CryptCATAdminEnumCatalogFromHash function (mscat.h)

[The CryptCATAdminEnumCatalogFromHash function is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]

The CryptCATAdminEnumCatalogFromHash function enumerates the catalogs that contain a specified hash. The hash is typically returned from the CryptCATAdminCalcHashFromFileHandle function. After the final call to this function, call CryptCATAdminReleaseCatalogContext to release allocated memory.

Syntax

HCATINFO CryptCATAdminEnumCatalogFromHash(
  [in] HCATADMIN hCatAdmin,
  [in] BYTE      *pbHash,
  [in] DWORD     cbHash,
  [in] DWORD     dwFlags,
  [in] HCATINFO  *phPrevCatInfo
);

Parameters

[in] hCatAdmin

A handle to a catalog administrator context previously assigned by the CryptCATAdminAcquireContext function.

[in] pbHash

A pointer to the buffer that contains the hash retrieved by calling CryptCATAdminCalcHashFromFileHandle.

[in] cbHash

Number of bytes in the buffer allocated for pbHash.

[in] dwFlags

This parameter is reserved for future use and must be set to zero.

[in] phPrevCatInfo

A pointer to the handle to the previous catalog context or NULL. To get the first catalog that contains the hash, or to start an enumeration of all catalogs, pass NULL for this parameter. To continue the enumeration, pass the previous call's return value until no more catalogs are found.

Return value

The return value is a handle to the catalog context, or NULL if there are no more catalogs to enumerate.

Note: The type HCATINFO is simply a typedef for HANDLE, which makes it easy to accidentally use the HCATINFO in the wrong context. In particular, this is NOT the same as a HANDLE returned from CryptCATOpen, even though the compiler will not prevent you from using the HCATINFO in any function that expects a catalog handle. To acquire a catalog handle from this function, first call CryptCATCatalogInfoFromContext to get the filename of the catalog, and then call CryptCATOpen with that filename.

For extended error information, call the GetLastError function. For a complete list of error codes provided by the operating system, see System Error Codes.

Note: The function returns a value of type HCATINFO, but this is simply a typedef for HANDLE. Because of this, it is easy to accidentally use the HCATINFO when calling a function that expects a different kind of HANDLE. In particular, this is not the same as a HANDLE returned from CryptCATOpen, even though the compiler will not prevent you from using the HCATINFO in any function that expects a catalog handle.

To acquire a catalog handle from this function, first call CryptCATCatalogInfoFromContext to get the filename of the catalog, and then call CryptCATOpen with that filename to open the catalog.

Requirements