3.2.5.2.1.1 INtmsLibraryControl1::EjectNtmsMedia (Opnum 3)

  • Article

The EjectNtmsMedia method ejects media from theport of a library.

 HRESULT EjectNtmsMedia(
   [in, unique] LPNTMS_GUID lpMediaId,
   [in, out] LPNTMS_GUID lpEjectOperation,
   [in] DWORD dwAction
 );

lpMediaId: A pointer to the media identifier of the media to eject.

lpEjectOperation: A pointer to the identifier of the eject process; MUST be used with dwAction set to NTMS_EJECT_STOP.

dwAction: A value from the NtmsEjectOperation enumeration that specifies the action to perform.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070057

ERROR_INVALID_PARAMETER

A parameter is not valid.

0x800700AA

ERROR_BUSY

The media or drives are busy.

0x800710D1

ERROR_LIBRARY_OFFLINE

The library identifier refers to an offline library.

0x800710D5

ERROR_RESOURCE_DISABLED

A resource required for this operation is disabled.

0x800710DD

ERROR_INVALID_OPERATION

A stop was performed on an invalid operation.

Upon receiving this message, the server MUST:

  • Verify that lpMediaId is not NULL.

  • Verify that lpEjectOperation is not NULL.

  • Verify that the value of dwAction is not greater than the value of NTMS_EJECT_FORCE.

If parameter validation fails, the server MUST fail the operation immediately and return the corresponding invalid argument error as its response to the client. If parameter validation succeeds, the server MUST do the following:

  • If the library is not busy, or if dwAction specifies NTMS_EJECT_FORCE, eject the specified medium from the port of the current library. If the library is busy and dwAction does not specify NTMS_EJECT_FORCE, the server MUST queue the EjectNtmsMedia message and return S_OK (0x00000000) indicating that the eject is queued.

  • Move media that are ejected to the offline library by using the EjectNtmsMedia method, or delete them from the database. Cleaner cartridge, import media, unrecognized media, and incompatible media MUST be deleted when ejected.

  • Return an ERROR_BUSY (0x800700AA) if the media are currently in use (mounted or opened).

The EjectNtmsMedia method does not work with the offline library. If the library identifier refers to an offline library that cannot eject media, the server MUST return ERROR_LIBRARY_OFFLINE (0x800710D1) indicating that the media cannot be ejected. Also, if either the library or the drive is disabled, the server MUST return ERROR_RESOURCE_DISABLED (0x800710D5).

If the NTMS_EJECT_STOP flag is specified for dwAction, the eject operation specified by the lpEjectOperation parameter MUST be stopped. The lpEjectOperation GUID MUST be 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 multislot library. Media can be queued for ejection by 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. To do this, the application can use the NTMS_EJECT_START action on the last medium or a medium identified by all zeros. If the library 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 lpEjectOperation.