3.2.5.2.6.1 INtmsLibraryControl2::IdentifyNtmsSlot (Opnum 23)

 The IdentifyNtmsSlot method identifies the media in a storage slot.

 HRESULT IdentifyNtmsSlot(
   [in] LPNTMS_GUID lpSlotId,
   [in] DWORD dwOption
 );

lpSlotId: A pointer to the identifier of the slot containing the media to identify

dwOption: A value from the NtmsDismountOptions (section 2.2.1.9) enumeration specifying what to do with the media after identification is complete. If dwOption does not contain a valid value, the default value NTMS_DISMOUNT_IMMEDIATE is taken.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070005

ERROR_ACCESS_DENIED

Access to an object was denied.

0x80070057

ERROR_INVALID_PARAMETER

A parameter is not valid.

0x800710D1

ERROR_LIBRARY_OFFLINE

The library identifier refers to an offline library.

0x800710D8

ERROR_OBJECT_NOT_FOUND

The object was not found.

Upon receiving this message, the server MUST verify that lpSlotId is not NULL and verify that dwOption is equal to either NTMS_DISMOUNT_DEFERRED, NTMS_DISMOUNT_IMMEDIATE, or 0. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057) as either the slot identifier or option is invalid.

If parameter validation succeeds, the server MUST check the access rights to the media, verify that the slot is valid, and determine the library that the slot belongs to. If the client does not have the required access rights, NTMS_CONTROL_ACCESS to the library is denied and the server MUST return ERROR_ACCESS_DENIED (0x80070005). Other security errors are possible, but they indicate a security subsystem error. If the slot is not valid, the server MUST return ERROR_OBJECT_NOT_FOUND (0x800710D8).

The library MUST be an online library to perform an inventory. If the library is offline, the server MUST return ERROR_LIBRARY_OFFLINE (0x800710D1.

The server then identifies the media in the specified slot. If the specified dwOption is equal to NTMS_DISMOUNT_DEFERRED, the server MUST leave the media in the drive and mark it for deferred dismount. If dwOption is set to NTMS_DISMOUNT_IMMEDIATE, the server MUST dismount the media immediately.

On completion of an asynchronous operation, notification will be sent with the identifier lpSlotId.