Edit

Share via

SetCatalogState function (ntquery.h)

  • Article

Note

Indexing Service is no longer supported as of Windows XP and is unavailable for use as of Windows 8. Instead, use Windows Search for client side search and Microsoft Search Server Express for server side search.

Sets the catalog state for backup or other purposes.

Syntax

HRESULT SetCatalogState(
  WCHAR const *pwcsCat,
  WCHAR const *pwcsMachine,
  DWORD       dwNewState,
  DWORD       *pdwOldState
);

Parameters

pwcsCat

A pointer to the name of the catalog, for example, L"system" or L"Web".

pwcsMachine

A pointer to the name of the computer where the catalog exists; for example, L"." for the local computer.

dwNewState

The state of the catalog. See CICAT_* Constants.

pdwOldState

A pointer to a value that receives one of the CICAT_* constants that reflects the current state of the catalog.

Return value

This function can return one of these values.

Return code Description
S_OK
 The operation was completed successfully.
E_INVALIDARG
 The function received an invalid parameter.
CI_E_NOT_FOUND
 The function failed because either the catalog or the computer was not found.
CI_E_NOT_RUNNING
 The function failed because Indexing Service is not running.
CI_E_TIMEOUT
 The function failed because Indexing Service is too busy.

Remarks

A catalog can be read-only if any of the following conditions exist:

  • The value of the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ContentIndex\Catalogs\<catalog name>\IsReadOnly registry entry is set to 1.
  • The catalog is on a write-protected volume.
  • The catalog, specifically the file cicat.hsh, is read-only.

If any of the preceding conditions exist and the CICAT_WRITABLE bit is set, it does not have the desired effect and the catalog is opened read-only.

If the dwNewState parameter contains CICAT_NO_QUERY, the system checks to see whether the catalog can be set to a writable state. If any of the preceding conditions exist that prevent the catalog from being writable, the catalog remains read-only and the pdwOldState parameter returns CICAT_READONLY. However, because the intention of the flag is to halt querying, the catalog stops accepting queries even though it is in this read-only state.

Specifically, if you make the call:

SetCatalogState("System", ".", CICAT_NO_QUERY, &OldState);

the value of the pdwOldState parameter on return will contain CICAT_NO_QUERY in addition to CI_CAT_WRITABLE or CI_CAT_READONLY values, depending on the READONLY/WRITABLE attributes of the volume or file.

If you make the call to SetCatalogState, where the dwNewState parameter is any value other than CICAT_NO_QUERY, then the value of the pdwOldState parameter on return will contain one of the mutually exclusive CICAT_ constants (excluding CICAT_NO_QUERY and CICAT_GET_STATE) which reflects the current state of the catalog.

Note  If you issue a net pause command or a net continue command for Indexing Service, the state changes that were set by the SetCatalogState function are not preserved.
 
For examples of changes in a catalog's state, see the ChgState sample in the Platform SDK directory mssdk\samples\winbase\indexing\chgstate.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header ntquery.h
Library Ntquery.lib
DLL Ntquery.dll

See also

LocateCatalogs