INtmsLibraryControl1::InjectNtmsMedia (Opnum 4)

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




The insert is queued.



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



An allocation failure occurred during processing.



A parameter is missing.



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



The database is inaccessible or damaged.



The database is full.



The NTMS_INJECT_STOP action was performed on an invalid operation identifier.



The library is disabled.



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.