AllocateNtmsMedia

The AllocateNtmsMedia function allocates a piece of available media.

DWORD WINAPI AllocateNtmsMedia(
  HANDLE hSession,
  LPNTMS_GUID lpMediaPool,
  LPNTMS_GUID lpPartId,
  LPNTMS_GUID lpMediaId,
  DWORD dwOptions,
  DWORD dwTimeout
  LPNTMS_ALLOCATION_INFORMATION lpAllocateInformation
);

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.

lpPartId

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

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 can 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 side 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 side of the multi-sideed medium previously allocated with the NTMS_ALLOCATE_NEW value. This allows a single application to use both sides 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 sides 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.

lpAllocateInformation

Pointer to a structure that returns the source media pool from which the medium was taken. If this information is not needed, pass a NULL pointer.

Return Values

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 free 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 free 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 free pool automatically, and the free 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 side of the multiple 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.

When an application requires new media containing data, a user or administrator places the media in a library or drive. RSM 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 lpPartId argument. RSM then:

1. moves the medium to the specified media pool.
2. changes the media's state to allocated.
3. returns an LMID.

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntmsapi.h.
  Library: Use Ntmsapi.lib.

See Also

Media Services Functions, DeallocateNtmsMedia