EjectNtmsMedia

[This is preliminary documentation and subject to change.]

The EjectNtmsMedia function ejects the specified medium from the port of the current library. If the library is busy, RSM queues EjectNtmsMedia and returns success.

DWORD WINAPI EjectNtmsMedia(
  HANDLE hSession, 
  LPNTMS_GUID lpMediaId,
  LPNTMS_GUID lpEjectOperation,
  DWORD dwAction
);
 

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpMediaId

Specifies the unique identifier of a piece of physical media (PMID).

lpEjectOperation

Specifies the GUID of the eject process. This must be used with the dwAction parameter set to the NTMS_EJECT_STOP flag.

dwAction

This parameter can be one of the following values.

Value	Meaning
NTMS_EJECT_START	Start the eject operation with a port. The specified medium is ejected until the time-out event occurs or until NTMS_EJECT_STOP is issued. The time-out value is specified in the library object and is applied to all ejects in the library.
NTMS_EJECT_STOP	Terminate the ejection process before the time-out event lapses.
NTMS_EJECT_QUEUE	Queue the specified media for ejection. Used to group media for multi-slot NTMS_IEPORT objects.

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_BUSY

More media was queued than slots available in the NTMS_IEPORT object.

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

A stop was performed on an invalid operation ID.

ERROR_INVALID_PARAMETER

A library ID or operation ID pointer is missing.

ERROR_LIBRARY_OFFLINE

The library ID refers to an offline library that cannot eject media.

ERROR_MEDIA_NOT_AVAILABLE

The media is disabled.

ERROR_NOT_ENOUGH_MEMORY

There was an allocation failure during processing.

ERROR_SUCCESS

The eject is queued.

Remarks

Media ejected using the EjectNtmsMedia function is moved to the offline library or deleted from the database. Cleaner cartridges, foreign media, and incompatible media are deleted when ejected.

If the NTMS_EJECT_STOP flag is specified for dwAction, the EjectNtmsMedia function stops the eject operation specified by the lpEjectOperation parameter. The lpEjectOperation GUID is returned when the NTMS_EJECT_START flag is used.

The NTMS_EJECT_QUEUE flag is used to bundle or batch media marked for ejection into a multi-slot library. You can queue media for ejection using the queue action when the application has queued all the necessary media. The application uses the start command to begin the physical eject operation. If more media is queued than slots in the NTMS_IEPORT object, EjectNtmsMedia returns ERROR_BUSY. To begin the physical eject operation, the application can use the START action on the last media or use a NULL media ID with the Start Operation

The QUEUE action does not return a GUID that can be used for the STOP action. However, when the queued requests are started with the START action, a GUID returns that can be used to cancel the entire operation with the STOP action.

If the media is currently in use (mounted or opened), this function returns an error.

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

Eject works only with online libraries.

The EjectNtmsMedia function returns to the application as soon as the eject request is queued.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in ntmsapi.h.
  Import Library: Use ntmsapi.lib.

See Also

Library Control Functions, InjectNtmsMedia