3.2.5.2.1.10 INtmsLibraryControl1::InjectNtmsCleaner (Opnum 13)
The InjectNtmsCleaner method allows a cleaner cartridge to be inserted into an online library unit.
-
HRESULT InjectNtmsCleaner( [in] LPNTMS_GUID lpLibrary, [in, out] LPNTMS_GUID lpInjectOperation, [in] DWORD dwNumberOfCleansLeft, [in] DWORD dwAction );
lpLibrary: A pointer to the identifier of the media library into which the cleaner will be inserted.
lpInjectOperation: A pointer to the GUID of the insert process library operation. If the value of dwAction is NTMS_INJECT_START, this parameter receives the GUID for the operation from server; if the value of dwAction is NTMS_INJECT_STOP, this parameter must be set to the GUID of the operation to be stopped.
dwNumberOfCleansLeft: The number of cleaning cycles remaining on the cleaning media.
dwAction: One of the NTMS_INJECT_START or NTMS_INJECT_STOP values from the NtmsInjectOperation enumeration, specifying the operation to perform.
-
Return value/code
Description
0x00000000
S_OK
The call was successful.
0x80070005
ERROR_ACCESS_DENIED
Access to at least one object is denied.
0x80070006
ERROR_INVALID_HANDLE
The session handle is invalid.
0x80070008
ERROR_NOT_ENOUGH_MEMORY
Not enough storage is available to process this command.
0x80070057
ERROR_INVALID_PARAMETER
The parameter is incorrect.
0x800710CD
ERROR_INVALID_LIBRARY
The library is not found in the database.
0x800710D1
ERROR_LIBRARY_OFFLINE
The library must be online for a cleaner cartridge to be inserted.
0x800710D5
ERROR_RESOURCE_DISABLED
A resource required for this operation is disabled.
0x800710DF
ERROR_DEVICE_NOT_AVAILABLE
The library is not connected.
0x800710EC
ERROR_CLEANER_SLOT_NOT_SET
A cleaner slot is not reserved.
0x8007138E
ERROR_RESOURCE_NOT_AVAILABLE
The reserved slot is not empty.
0x80070032
ERROR_NOT_SUPPORTED
The dwaction field is set to NTMS_INJECT_STOP, but there are no library ports.
Upon receiving this message, the server MUST verify that both lpLibrary and lpInjectOperation are not NULL. If parameter validation fails, the server MUST fail the operation immediately and return ERROR_INVALID_PARAMETER (0x80070057).
If parameter validation succeeds, the server MUST check access rights to the library and verify that the library is enabled and online before processing further. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005). If the library or drive is disabled, the server MUST return ERROR_RESOURCE_DISABLED (0x800710D5). If the library is offline, the server MUST return ERROR_LIBRARY_OFFLINE (0x800710D1).
The action taken by the server depends on the value of dwAction. The following table lists all possible values for dwAction.
Value |
Meaning |
---|---|
NTMS_INJECT_START |
Start the insertion with either the NTMS_IEPORT or the NTMS_IEDOOR object. A single cleaner cartridge MUST be inserted. If the NTMS_IEDOOR object is used, no inventory is performed on the library. |
NTMS_INJECT_STOP |
For libraries with NTMS_IEPORT objects, terminates the insertion process that is specified by lpEjectOperation prior to the time-out event lapsing. For libraries without NTMS_IEPORT objects, the server MUST return ERROR_INVALID_OPERATION. |
The InjectNtmsCleaner method inserts the cleaner cartridge in the reserved library slot. To use the InjectNtmsCleaner method, the number of cleaning cycles that remain on the cleaner cartridge MUST be specified so that the server can keep track of it.
On completion of an asynchronous operation, notification will be sent with the identifier lpInjectOperation.