3.2.5.2.2.3 INtmsMediaServices1::AllocateNtmsMedia (Opnum 6)

  • Article

The AllocateNtmsMedia method allocates a piece of available media.

 HRESULT AllocateNtmsMedia(
   [in] LPNTMS_GUID lpMediaPool,
   [in, unique] LPNTMS_GUID lpPartition,
   [in, out] LPNTMS_GUID lpMediaId,
   [in] DWORD dwOptions,
   [in] DWORD dwTimeout,
   [in, out] LPNTMS_ALLOCATION_INFORMATION lpAllocateInformation
 );

lpMediaPool: A pointer to the identifier of the media pool from which the media is allocated.

lpPartition: A pointer to the partition identifier of the side that MUST be used for a logical media identifier. This feature MUST be used to allocate a particular side or to import media.

lpMediaId: A pointer to the identifier of the allocated medium.

dwOptions: A bitmap of allocation options from the NtmsAllocateOptions (section 2.2.3.1) enumeration.

dwTimeout: The maximum time, in milliseconds, allowed to allocate the specified media. If this parameter is -1, the function MUST NOT time out. If this parameter is 0, it MUST NOT wait for media.

lpAllocateInformation: A pointer to an NTMS_ALLOCATION_INFORMATION (section 2.2.3.6) structure that MUST be filled with the source media pool from which the medium was taken. A NULL pointer MUST be passed if this information is not needed.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070005

ERROR_ACCESS_DENIED

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

0x80070008

ERROR_NOT_ENOUGH_MEMORY

An allocation error occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

The media or media pool identifiers are missing.

0x800704C7

ERROR_CANCELLED

The operator canceled the request for new media.

0x800705B4

ERROR_TIMEOUT

The time-out event expired before the medium was available.

0x800710CC

ERROR_INVALID_MEDIA

The partition identifier or logical media identifier was invalid when combined with the NTMS_ALLOCATE_NEXT flag.

0x800710CE

ERROR_INVALID_MEDIA_POOL

The media pool identifier is invalid.

0x800710D0

ERROR_MEDIA_OFFLINE

The specified media are offline and cannot be allocated.

0x800710D4

ERROR_MEDIA_UNAVAILABLE

No media have been allocated in the specified time-out.

0x800710D9

ERROR_DATABASE_FAILURE

The database is inaccessible or damaged.

0x800710DA

ERROR_DATABASE_FULL

The database is full.

0x800710DF

ERROR_DEVICE_NOT_AVAILABLE

An intermediate resource is not available.

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

If parameter validation succeeds, the server MUST perform the following actions:

  • Verify that the caller has permission to control the media pool specified in the call. If the client does not have the required access rights, the server MUST immediately fail the operation and return ERROR_ACCESS_DENIED (0x80070005).

  • If no errors were found while checking the partition but the partition was not suitable, the reason for its unsuitability (ReasonCode) MUST be passed back as the error code.

  • If the NTMS_ALLOCATE_NEXT option is specified, the server attempts to allocate the next partition, which MUST be on the same media as the partition (that is, pointed by lpPartition).

  • The server looks for an available partition in all the available drives. If none is found, the server asks the operator to add one before repeating the search.

The AllocateNtmsMedia method returns an LMID. If the partition identifier or logical media identifier was invalid when combined with the NTMS_ALLOCATE_NEXT flag, the server MUST return ERROR_INVALID_MEDIA (0x800710CC).

If the specified media pool does not contain any available online media, AllocateNtmsMedia might, depending upon the policy of the media pool, search the free media pool for the specified medium to move to the specified media pool. Media from the designated media pool are allocated first, and then free media are moved and allocated.

If the media pool contains any available online media, a medium from the pool is allocated.

If the media pool is automatically configured to allocate media from the free pool, and the free pool contains available online media, a medium is moved to the specified pool and allocated.<30>

When the NTMS_ALLOCATE_NEXT value is specified, the lpMediaId parameter MUST point to a valid media ID at the time of invocation. In this case, lpMediaId is used as an IN and OUT parameter. The next side of the multiple-sided medium specified by lpMediaId MUST be allocated, and the new partition ID is returned through lpMediaId (overwriting the original media ID that was passed in).

If NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE is specified, ERROR_MEDIA_UNAVAILABLE MUST be returned if no media are available.

When necessary, the server generates an operator request to insert new or available media. If the time specified in the dwTimeout parameter elapses before the operator request is handled, RSM MUST return ERROR_TIMEOUT and delete the operator request.

If the user cancels the allocation request, the server MUST return ERROR_CANCELLED (0x800704C7).

When an application requires new media that contain data, a user or administrator places the media in a library or drive. The server identifies the media and places it in the import pool. The application searches the import pool, moves the media to its application pool, and allocates it. This routine process can be streamlined and made atomic through a single call to AllocateNtmsMedia. After searching the import pool the application can call AllocateNtmsMedia, passing the partition ID of the side as the value of the lpPartition parameter. The server then moves the media to the specified media pool, changes the media state to allocated, and returns an LMID.

For two-sided media, the flip side MUST remain in the Import state and is not available for use until imported.

Only application pools can be specified for allocation by using the AllocateNtmsMedia method.

On completion of an asynchronous operation, notification is sent with the identifier lpMediaId.