InjectNtmsMedia

[This is preliminary documentation and subject to change.]

The InjectNtmsMedia function allows media to be inserted into the port of the specified online library. If the library is busy, RSM queues InjectNtmsMedia and returns success.

DWORD WINAPI InjectNtmsMedia(
  HANDLE hSession, 
  LPNTMS_GUID lpLibraryId,
  LPNTMS_GUID lpInjectOperation,
  DWORD dwAction
);

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpLibraryId

Specifies the unique identifier of a library object.

lpInjectOperation

Specifies the GUID of the insert Libraryworkitem. This is returned for use with the Stop action code.

dwAction

This parameter can be one of the following values.

Value	Meaning
NTMS_INJECT_START	Start the insert operation with a port. Media is repeatedly inserted until the time-out event occurs or the NTMS_INJECT_STOP flag is issued.
NTMS_INJECT_STOP	Terminate the insertion process prior to the time-out event lapsing.

Return Values

ERROR_ACCESS_DENIED: NTMS_CONTROL_ACCESS to the library is denied. Other security errors are also possible, but they would indicate a security subsystem error.
ERROR_DATABASE_FAILURE: The database is inaccessible or damaged.
ERROR_DATABASE_FULL: The database is full.
ERROR_DEVICE_NOT_AVAILABLE: The library is disabled.
ERROR_INVALID_HANDLE: The session ID is invalid or missing.
ERROR_INVALID_OPERATION: There was a Stop action performed on an invalid operation ID.
ERROR_INVALID_PARAMETER: The library ID or operation ID pointer is missing.
ERROR_LIBRARY_OFFLINE: The library ID refers to an offline library that cannot eject media.
ERROR_NOT_ENOUGH_MEMORY: There was an allocation failure during processing.
ERROR_SUCCESS: The insert is queued.

Remarks

If the library specified by the InjectNtmsMedia function does not have a port, use the AccessNtmsLibraryDoor function to insert and eject media.

This function is valid only for online libraries.

This function returns to the application as soon as the insert request is queued.

Insert begins the process of inserting media into an online library. Because libraries vary on the functionality of the NTMS_IEPORT object, each device may operate slightly differently. The following steps describe how to insert media into a library:

To insert media into a library

Allow/unlock/extend the NTMS_IEPORT object.
Poll for a full NTMS_IEPORT object, a retracted NTMS_IEPORT object, a Stop Inject command, or a time-out value. If none of these have occurred, continue to wait. (Multi-cartridge IEports are not scanned for full status.)
When one of the preceding events occurs, the NTMS_IEPORT object is locked, each medium in the NTMS_IEPORT object 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 remains in the NTMS_IEPORT object and an Operator Request is posted to have media removed from the library.

If there are no free slots, the InjectNtmsMedia function receives an error.

QuickInfo