LocateCatalogs

[This is preliminary documentation and subject to change.]

LocateCatalogs finds indexes that can be used to process queries for a files in a specified path. The machine and catalog parameter values returned by LocateCatalogs can be used to create an OLE DB ICommand object for issuing queries over a given scope.

STDAPI LocateCatalogs(
  WCHAR const * pwszScope,
  ULONG iBmk,
  WCHAR * pwszMachine,
  ULONG * pcMachine,
  WCHAR * pwszCatalog,
  ULONG * pcCatalog
);
 

Parameters

pwszScope

[in] Points to a null-terminated string that specifies the scope for an Index Server query. The scope can be local (e.g., C:\directory) or a remote UNC (e.g., \\MACHINE\SHARE\directory). The scope cannot be a redirected drive letter, that is, a drive letter that refers to a drive on a remote machine. Scopes must be physical, not Internet Information Server virtual scopes.

iBmk

[in] Specifies the 0-based bookmark of the result to be retrieved. Pass 0 to retrieve the first machine and catalog that index pwszScope, 1 to retrieve the second machine and catalog that index pwszScope, and so on. If no index for the bookmark is available, LocateCatalogs returns S_FALSE.

pwszMachine

[out] Points to a buffer where a null-terminated string is written if the function is successful. The result string is the machine name on which a query over the scope pwszScope can be executed.

pcMachine

[in/out] On input, points to a wide character count that specifies the size of pwszMachine. On output, specifies the count of characters used in pwszMachine if the function is successful, or the count of characters needed to store the name of the machine if the buffer is too small. If the buffer is too small, LocateCatalogs returns S_OK.

pwszCatalog

[out] Points to a buffer where a null-terminated string is written if the function is successful. The result string is the machine name on which a query over the scope pwszScope can be executed.

pcCatalog

[in/out] On input, points to a wide character count that specifies the size of pwszCatalog. On output, specifies the count of characters used in pwszCatalog if the function is successful, or the count of characters needed to store the name of the catalog if the buffer is too small. If the buffer is too small, LocateCatalogs returns S_OK.

Return Values

An HRESULT, S_OK if successful. If no machine and catalog can be found that index the scope, or iBmk is beyond the count of machines and catalogs that index the scope, the function returns S_FALSE. If there is an error, LocateCatalogs returns E_FAIL.

If a machine and catalog match is found but the machine and catalog buffers aren't big enough, LocateCatalogs returns S_OK, and fills pcCatalog and pcMachine with the wide character required. Callers of LocateCatalogs must check the return code, pcMachine, and pcCatalog to determine if the call was successful.

Remarks

LocateCatalogs is useful when it is not known what machine and catalog index a scope. If the machine and catalog are known, it's more efficient to execute a query without calling LocateCatalogs.

LocateCatalogs does not verify that the machine and catalog returned are available. If an application fails to issue a query with the machine and catalog returned, it should increment iBmk and call LocateCatalogs again to get the next machine and catalog that index the scope.

Example

This example enumerates all machines and catalogs capable of resolving queries over the scope "C:\directory".

HRESULT hr = S_OK;
 
for ( ULONG iBmk = 0; S_OK == hr; iBmk++ )
{
    WCHAR awcMachine[ MAX_COMPUTERNAME_LENGTH + 1 ];
    const ULONG cwcMachineBuffer = sizeof awcMachine / sizeof WCHAR;
    ULONG cwcMachine = cwcMachineBuffer;
    WCHAR awcCatalog[ MAX_PATH + 1 ];
    const ULONG cwcCatalogBuffer = sizeof awcCatalog / sizeof WCHAR;
    ULONG cwcCatalog = cwcCatalogBuffer;
 
    hr = LocateCatalogs( L"c:\\directory",
                         iBmk,
                         awcMachine,
                         &cwcMachine,
                         awcCatalog,
                         &cwcCatalog );
    if ( ( hr == S_OK ) &&
         ( cwcMachine <= cwcMachineBuffer ) &&
         ( cwcCatalog <= cwcCatalogBuffer ) )
    {
        wprintf( L"matching machine and catalog: '%s', '%s'\n", 
                awcMachine, awcCatalog );
    }
}