3.2.5.2.2.1 INtmsMediaServices1::MountNtmsMedia (Opnum 3)

The MountNtmsMedia method mounts one or more pieces of media.

 HRESULT MountNtmsMedia(
   [in, size_is(dwCount)] LPNTMS_GUID lpMediaId,
   [in, out, size_is(dwCount)] LPNTMS_GUID lpDriveId,
   [in] DWORD dwCount,
   [in] DWORD dwOptions,
   [in] int dwPriority,
   [in] DWORD dwTimeout,
   [in, out] LPNTMS_MOUNT_INFORMATION lpMountInformation
 );

lpMediaId: An array of logical media identifiers or media side identifiers. Each entry in the array MUST be unique.

lpDriveId: An array of drive identifiers that correspond to the media listed in the lpMediaId parameter. This array MUST either specify a list of drives into which media will be mounted or receive the list of drives into which media will be mounted when the operation completes.

dwCount: The number of elements in the lpMediaId and lpDriveId arrays.

dwOptions: A bitmap of mount options from the NtmsMountOptions (section 2.2.3.3) enumeration.

dwPriority: A value from the NtmsMountPriority (section 2.2.3.4) enumeration specifying the priority of the mount request.

dwTimeout: The maximum time, in milliseconds, allowed for mounting of the specified media. To wait as long as the mount takes, this parameter MUST be set to 0xFFFFFFFF. If dwOptions is specified as NTMS_MOUNT_NOWAIT, ignore this value.

Value	Meaning
0xFFFFFFFF	Use this value to wait as long as required for the mount to occur.

lpMountInformation: This parameter is currently unused. It MUST be sent as NULL and ignored on receipt.

Return value/code	Description
0x00000000 S_OK	The call was successful.
0x80070005 ERROR_ACCESS_DENIED	Access to an object was denied.
0x80070008 ERROR_NOT_ENOUGH_MEMORY	A allocation failure occurred during processing.
0x8007000F ERROR_INVALID_DRIVE	The drive identifier is not valid.
0x80070013 ERROR_WRITE_PROTECT	The media state is set to NTMS_PARTSTATE_COMPLETE, from the NtmsPartitionState enumeration, and the NTMS_MOUNT_WRITE value was specified.
0x80070057 ERROR_INVALID_PARAMETER	A parameter is not valid.
0x800700AA ERROR_BUSY	The media or drives are busy.
0x800705B4 ERROR_TIMEOUT	The time-out event expired before the medium was available.
0x800710CC ERROR_INVALID_MEDIA	The media identifier is not valid.
0x800710CD ERROR_INVALID_LIBRARY	The library identifier is not valid.
0x800710CF ERROR_DRIVE_MEDIA_MISMATCH	The specified media and drive are not in the same library.
0x800710D0 ERROR_MEDIA_OFFLINE	The specified media is offline and cannot be allocated.
0x800710D5 ERROR_RESOURCE_DISABLED	A resource required for this operation is disabled.
0x800710D9 ERROR_DATABASE_FAILURE	The database query or update failed.
0x800710DA ERROR_DATABASE_FULL	The database is full.
0x800710E0 ERROR_REQUEST_REFUSED	The request is refused as a user canceled the request through the user interface.
0x8007139E ERROR_RESOURCE_NOT_AVAILABLE	The specified resource is not available.
0x8007139F ERROR_INVALID_STATE	An unexpected state was encountered.
0x800704C7 ERROR_CANCELLED	The request was cancelled.

Upon receiving this message, the server MUST verify that dwCount is not 0, verify that lpMediaId is not NULL, and verify that lpDriveId is not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

The server MUST check the physical media that are specified to verify that the mount request can be fulfilled. It MUST also check the validity of the physical media to ensure that they are in valid libraries, and verify that the drive IDs passed in are valid.

If the media state is set to NTMS_PARTSTATE_COMPLETE from the NtmsPartitionState enumeration, and the NTMS_MOUNT_WRITE value was specified, the server MUST return ERROR_WRITE_PROTECT (0x80070013).

The MountNtmsMedia method queues a request to mount the specified media, then waits the number of milliseconds specified in the dwTimeout parameter for the mount to complete or for an error to be detected. If the server cannot complete the mount operation before dwTimeout expires, the server MUST cancel the request and return an error. If the specified media are in an offline library, the server MUST return ERROR_MEDIA_OFFLINE (0x800710D0). If the specified medium is in use or a drive is not available, the process blocks up to the time-out value and returns ERROR_BUSY (0x800700AA). If the NTMS_MOUNT_ERROR_NOT_AVAILABLE value is specified, the method MUST return an immediate error when a resource (medium or drive) is unavailable.

The time-out value of 0xFFFFFFFF can be used to make the method wait without timing out. When a nonzero time-out value is specified in the dwTimeout parameter, the server MUST wait for all the media that are specified in lpMediaId to become mounted. If the specified time elapses before all the media are mounted, the MountNtmsMedia method MUST return an error and cancels the request. The application can examine the status that is returned and resubmit the request, if desired.

When multiple media to be mounted are specified with a single call, all the specified media MUST be in a single library. If any of the specified media are offline, none of the media will be mounted until all the media are online.

If the specified medium is offline, the server MUST post an operator request to mount the media and the MountNtmsMedia method waits for the period of time that is specified in the dwTimeout parameter. If the wait period exceeds the parameter, the mount request is canceled, and the server MUST return ERROR_TIMEOUT (0x800705B4).

If the media cannot be mounted because either the library or media is offline and the client has specified NTMS_MOUNT_ERROR_OFFLINE in dwOptions, then the server MUST return ERROR_MEDIA_OFFLINE (0x800710D0).

If the specified medium is offline and the client has not specified NTMS_MOUNT_ERROR_OFFLINE in dwOptions, the server MUST post an operator request to mount the media and then wait for the period of time specified by the dwTimeout parameter.

If the specified medium is online, the server requests the mount.

If a drive or medium is unavailable, the server MUST send the request, and the MountNtmsMedia method waits for the period of time that is specified in the dwTimeout parameter. If the wait period exceeds the parameter, the mount request is canceled, and the server MUST return ERROR_TIMEOUT (0x800705B4).