Share via

3.2.5.2.1.2 INtmsLibraryControl1::InjectNtmsMedia (Opnum 4)

  • Article

The InjectNtmsMedia method allows media to be inserted into the port of an online library.

 HRESULT InjectNtmsMedia(
   [in] LPNTMS_GUID lpLibraryId,
   [in, out] LPNTMS_GUID lpInjectOperation,
   [in] DWORD dwAction
 );

lpLibraryId: A pointer to the identifier of a media library.

lpInjectOperation: A pointer to the identifier of the insert process. In the case of a NTMS_INJECT_START or NTMS_INJECT_STARTMANY operation, this MUST be an out parameter, and the server will return the lpInjectOperation identifier immediately after starting the operation. In the case of a NTMS_INJECT_STOP or NTMS_INJECT_RETRACT operation, this MUST be an input parameter.

The lpInjectOperation identifier received in an NTMS_INJECT_START operation is used only in a NTMS_INJECT_STOP operation. The lpInjectOperation identifier received in a NTMS_INJECT_STARTMANY operation is used only in the NTMS_INJECT_STOP and NTMS_INJECT_RETRACT operations.

dwAction: A value from the NtmsInjectOperation enumeration, specifying the operation to perform.

Return value/code

Description

0x00000000

S_OK

The insert is queued.

0x80070005

ERROR_ACCESS_DENIED

NTMS_CONTROL_ACCESS to the library is denied; other security errors are possible but indicate a security subsystem error.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

An allocation failure occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

A parameter is missing.

0x800710D1

ERROR_LIBRARY_OFFLINE

The library identifier refers to an offline library that cannot inject media.

0x800710D9

ERROR_DATABASE_FAILURE

The database is inaccessible or damaged.

0x800710DA

ERROR_DATABASE_FULL

The database is full.

0x800710DD

ERROR_INVALID_OPERATION

The NTMS_INJECT_STOP action was performed on an invalid operation identifier.

0x800710DF

ERROR_DEVICE_NOT_AVAILABLE

The library is disabled.

0x800710E2

ERROR_LIBRARY_FULL

The library is full, and no slot is available for use.

Upon receiving this message, the server MUST:

  • Verify that lpLibraryId is not NULL.

  • Verify that lpInjectOperation is not NULL.

  • Verify that dwAction is not greater than NTMS_INJECT_STARTMANY.

If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057). If the library is offline, the method MUST return ERROR_LIBRARY_OFFLINE (0x800710D1).

Because libraries vary in functionality of the NTMS_IEPORT object, each device might operate slightly differently. The following steps specify how the RSM server generally handles a media inject request:

  1. The server allows, unlocks, or extends the NTMS_IEPORT.

  2. The server checks to see whether there is a full NTMS_IEPORT, a retracted NTMS_IEPORT, a Stop Inject command, or a time-out value. If none of these have occurred, the server MUST continue to wait. (Multicartridge IE ports are not scanned for full status.)

  3. When one of the preceding events occurs, the NTMS_IEPORT MUST be locked; each medium in the NTMS_IEPORT is moved to a slot; and an Identify Medium command is queued for each medium. If there are not enough slots for the media in the NTMS_IEPORT object, the media MUST remain in the NTMS_IEPORT object and an operator request is sent, requesting that media be removed from the library. If an NTMS_INJECT_STOP action was issued on an invalid operation identifier, the InjectNtmsMedia method MUST return ERROR_INVALID_OPERATION (0x800710DD). If there are no free slots, the InjectNtmsMedia method MUST return ERROR_LIBRARY_FULL (0x800710E2).

If the library specified by the InjectNtmsMedia method does not have a port, the AccessNtmsLibraryDoor method can be used to insert and eject media.

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