3.2.5.2.1.18 INtmsLibraryControl1::SetNtmsDeviceChangeDetection (Opnum 21)

  • Article

The SetNtmsDeviceChangeDetection method sets one or more target devices for change detection. Implementation of this method is optional.<25> The server MAY return a non-implemented error (ERROR_CALL_NOT_IMPLEMENTED, 0x80070078). <26>

 HRESULT SetNtmsDeviceChangeDetection(
   [in] NTMS_HANDLE DetectHandle,
   [in, size_is(dwCount)] LPNTMS_GUID lpObjectId,
   [in] DWORD dwType,
   [in] DWORD dwCount
 );

DetectHandle: The device change detection handle, or NULL for a single poll of the objects in lpObjectId. The handle MUST have come from a prior BeginNtmsDeviceChangeDetection method invocation.

lpObjectId: An array of media library, physical media, or media type identifiers, used to specify the target devices for change detection. All identifiers MUST be of the same type.

dwType: One of the NTMS_LIBRARY, NTMS_PHYSICAL_MEDIA, or NTMS_MEDIA_TYPE values defined in the NtmsObjectsTypes (section 2.2.1.6) enumeration, specifying the type of the objects in lpObjectId.

dwCount: The number of elements in the lpObjectId array.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070006

ERROR_INVALID_HANDLE

The session handle is not valid.

0x80070057

ERROR_INVALID_PARAMETER

A parameter is not valid.

0x80070078

ERROR_CALL_NOT_IMPLEMENTED

This function is not supported on this system.

0x800710CC

ERROR_INVALID_MEDIA

The media identifier is not valid.

0x800710CD

ERROR_INVALID_LIBRARY

The library identifier is not valid.

If the method is implemented, the server MUST verify that both DetectHandle and lpObjectId are not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

If parameter validation succeeds and dwCount is greater than one, the server MUST verify that the type of objects specified in the lpObjectId array are all of the same object type. If the objects specified in the lpObjectId array are not of the same object type, the server MUST return ERROR_INVALID_PARAMETER (0x80070057).

The SetNtmsDeviceChangeDetection method sets one or more target devices for change detection.

The device can be specified directly by passing library GUIDs, or indirectly by passing physical media or media type GUIDs. When using indirect specification, only stand-alone libraries that could contain the media or media type are detected. All devices that are specified, either directly or indirectly, continue to be detected until the device change detection handle is closed using the EndNtmsDeviceChangeDetection method.

This method can also be used to poll for changed media in the specified devices. This feature is typically used by a UI when opening a leaf node or implementing a refresh option.