126.96.36.199.2.3 INtmsMediaServices1::AllocateNtmsMedia (Opnum 6)
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.
lpMediaId: A pointer to the identifier of the allocated medium.
dwOptions: A bitmap of allocation options from the NtmsAllocateOptions (section 188.8.131.52) 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 184.108.40.206) 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.
The call was successful.
NTMS_MODIFY_ACCESS to the library is denied; other security errors are possible, but indicate a security subsystem error.
An allocation error occurred during processing.
The media or media pool identifiers are missing.
The operator canceled the request for new media.
The time-out event expired before the medium was available.
The partition identifier or logical media identifier was invalid when combined with the NTMS_ALLOCATE_NEXT flag.
The media pool identifier is invalid.
The specified media are offline and cannot be allocated.
No media have been allocated in the specified time-out.
The database is inaccessible or damaged.
The database is full.
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.
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.