AllocateNtmsMedia

[This is preliminary documentation and subject to change.]

The AllocateNtmsMedia function allocates a piece of available media.

DWORD WINAPI AllocateNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaPool,
  LPNTMS_GUID lpPartition,
  LPNTMS_GUID lpMediaId,
  DWORD dwOptions,
  DWORD dwTimeout
);

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpMediaPool

Specifies the unique identifier of a media pool from which the media is to be allocated.

lpPartition

Specifies the part ID of a partition to use for LMID. The partition must be in the Available or Import state. This feature can be used to allocate a particular partition or to import media. This parameter is optional. A NULL pointer is normally used.

lpMediaId

Used to return the media ID of the allocated medium. The returned logical media ID is NULL if the medium cannot be allocated.

dwOptions

This parameter must be one or more of the following values.

Value	Meaning
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE	Prevents the submission of an operator request for new media if none can be allocated with the specified constraints.
NTMS_ALLOCATE_NEW	Allocates a partition of the specified medium that cannot be shared with another application's logical media. For example, this value reserves the second side of two-sided optical media.
NTMS_ALLOCATE_NEXT	Allocate the next partition of the multipartitioned medium previously allocated with the NTMS_ALLOCATE_NEW value. This allows a single application to use both partitions of a piece of two-sided media and ensure that the application owns all the data on the piece of physical media. If all the partitions of the medium are already allocated, the allocation request fails.

dwTimeout

Specifies the maximum time allowed, in milliseconds, to allocate the specified media. Set this parameter to INFINITE so the function will not time out. Set this parameter to zero to not wait for media. Note that this function does not queue a request for more media if the NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE value is specified.

Return Values

ERROR_ACCESS_DENIED: NTMS_MODIFY_ACCESS to media's media pool is denied.
ERROR_CANCELLED: The operator canceled the request for new media.
ERROR_DATABASE_FAILURE: The database is inaccessible or damaged.
ERROR_DATABASE_FULL: The database is full.
ERROR_DEVICE_NOT_AVAILABLE: An intermediate resource is not available; for example, the scratch media pool is not available.
ERROR_INVALID_HANDLE: The session handle is invalid or missing.
ERROR_INVALID_MEDIA: The partition ID or logical media ID was invalid upon input when using the NTMS_ALLOCATE_NEXT flag.
ERROR_INVALID_MEDIA_POOL: The media pool ID is invalid.
ERROR_INVALID_PARAMETER: The media or media pool ID is missing.
ERROR_MEDIA_OFFLINE: The specified media is offline and cannot be allocated.
ERROR_MEDIA_UNAVAILABLE: No media has been allocated within the specified time-out event.
ERROR_NOT_ENOUGH_MEMORY: There was an allocation failure during processing.
ERROR_SUCCESS: The function was successful.
ERROR_TIMEOUT: The time-out event expired before media was available.

Remarks

Only application pools may be specified for allocation using the AllocateNtmsMedia function.

The AllocateNtmsMedia function returns an LMID. Depending upon the media pool's policy, if the specified media pool does not contain any online Available media, AllocateNtmsMedia might search the scratch media pool for the specified medium to move to the specified media pool. Media from the designated media pool is allocated first, and then the scratch media is moved and allocated.

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

If the media pool is configured to allocate media from the scratch pool automatically, and the scratch pool contains online Available media, a medium is moved to the specified pool and 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 partition of the multiple partitioned (sided) medium specified by lpMediaId is allocated, and the new partition ID is returned through lpMediaId (overwriting the original media ID passed in).

If NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE is specified, ERROR_MEDIA_ UNAVAILABLE is returned if no media is available.

When necessary, RSM 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 returns ERROR_TIMEOUT and deletes the operator request.

If the user cancels the allocation request, RSM returns ERROR_CANCELLED.

If a user indicates that the operator request has been satisfied, the request is deleted and RSM retries the process. The following steps describe how to allow media to be imported into RSM:

To allow media to be imported into RSM

The AllocateNtmsMedia function specifies a partition in the Import Media pool or in the Import state.
RSM moves the medium to the specified media pool.
RSM changes the media's state to allocated.
RSM returns an LMID.

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

QuickInfo