Función AllocateNtmsMedia (ntmsapi.h)

  • Artículo

[El Administrador de almacenamiento extraíble ya no está disponible para su uso a partir de Windows 7 y Windows Server 2008 R2.]

La función AllocateNtmsMedia asigna un fragmento de medios disponibles.

Sintaxis

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

Parámetros

[in] hSession

Identificador de la sesión devuelta por la función OpenNtmsSession .

[in] lpMediaPool

Identificador único del grupo de medios desde el que se va a asignar el medio. Solo se pueden especificar grupos de aplicaciones para la asignación.

[in] lpPartition

Identificador de parte de un lado que se va a usar como identificador de medios lógicos (LMID). El lado debe estar en el estado Disponible o Importar. Esta característica se puede usar para asignar un lado determinado o para importar medios. Este parámetro es opcional.

[out] lpMediaId

LMID del medio asignado. Este parámetro es NULL si no se puede asignar el medio.

[in] dwOptions

Opciones. Este parámetro puede ser uno o más de los siguientes valores.

Valor Significado
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE
 Impide el envío de una solicitud de operador para los nuevos medios si no se puede asignar ninguno con las restricciones especificadas.
NTMS_ALLOCATE_NEW
 Asigna un lado del medio especificado que no se puede compartir con los medios lógicos de otra aplicación. Por ejemplo, este valor reserva el segundo lado de medios ópticos de dos lados.
NTMS_ALLOCATE_NEXT
 Asigne el lado siguiente del medio de varios lados asignado previamente con el valor de NTMS_ALLOCATE_NEW. Esto permite que una sola aplicación use ambos lados de un elemento de medio de dos lados y asegúrese de que la aplicación posee todos los datos del elemento físico.

Si ya se han asignado todos los lados del medio, se produce un error en la solicitud de asignación.

[in] dwTimeout

Tiempo máximo permitido para asignar el medio especificado, en milisegundos. Si este parámetro es INFINITE, la función no agotará el tiempo de espera. Si este parámetro es cero, esperará a medios. Tenga en cuenta que esta función no pone en cola una solicitud de más medios si el parámetro dwOptions especifica NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE.

[out] lpAllocateInformation

Puntero a una estructura de NTMS_ALLOCATION_INFORMATION que recibe el grupo de medios de origen del que se tomó el medio. Este parámetro puede ser NULL.

Valor devuelto

Esta función devuelve uno de los valores siguientes.

Valor Significado
ERROR_ACCESS_DENIED
 NTMS_CONTROL_ACCESS al grupo de medios de comunicación se deniega. También se pueden producir otros errores de seguridad, pero indicarían un error de subsistema de seguridad.

Windows XP: NTMS_MODIFY_ACCESS al grupo de medios se deniega.
ERROR_CANCELLED
 El operador canceló la solicitud de nuevos medios.
ERROR_DATABASE_FAILURE
 La base de datos no es accesible o está dañada.
ERROR_DATABASE_FULL
 La base de datos está llena.
ERROR_DEVICE_NOT_AVAILABLE
 Un recurso intermedio no está disponible; por ejemplo, el grupo de medios gratuito no está disponible.
ERROR_INVALID_HANDLE
 Falta el identificador de sesión o no es válido.
ERROR_INVALID_MEDIA
 El identificador de partición o LMID no era válido al escribir al usar la marca NTMS_ALLOCATE_NEXT.
ERROR_INVALID_MEDIA_POOL
 El identificador del grupo de medios no es válido.
ERROR_INVALID_PARAMETER
 Falta el identificador del grupo de medios o multimedia.
ERROR_MEDIA_OFFLINE
 El medio especificado está sin conexión y no se puede asignar.
ERROR_MEDIA_UNAVAILABLE
 No se ha asignado ningún medio dentro del evento de tiempo de espera especificado.
ERROR_NOT_ENOUGH_MEMORY
 Se produjo un error de asignación durante el procesamiento.
ERROR_SUCCESS
 La función se realizó correctamente.
ERROR_TIMEOUT
 El evento de tiempo de espera expiró antes de que los medios estuvieran disponibles.

Comentarios

La función AllocateNtmsMedia devuelve un LMID. Dependiendo de la directiva del grupo de medios, si el grupo de medios especificado no contiene ningún medio disponible en línea, AllocateNtmsMedia podría buscar el grupo de medios libre para el medio especificado para pasar al grupo de medios especificado. Los medios del grupo de medios designado se asignan primero y, a continuación, se mueven y asignan los medios gratuitos.

Si el grupo de medios contiene algún medio disponible en línea, se asigna un medio del grupo.

Si el grupo de medios está configurado para asignar medios del grupo gratuito automáticamente y el grupo gratuito contiene medios disponibles en línea, se mueve un medio al grupo especificado y se asigna.

Windows Server 2003: Si los medios se asignan desde el grupo gratuito, se requiere NTMS_USE_ACCESS al grupo gratuito y NTMS_CONTROL_ACCESS al grupo de destino. Si el grupo gratuito no es el grupo de medios de origen, se requiere NTMS_CONTROL_ACCESS en los grupos de origen y de destino.

Cuando se especifica el valor NTMS_ALLOCATE_NEXT, el parámetro lpMediaId debe apuntar a un identificador de medio válido en el momento de la invocación. En este caso, lpMediaId se usa como parámetro IN y OUT. Se asigna el siguiente lado del medio lateral múltiple especificado por lpMediaId y el nuevo identificador de partición se devuelve a través de lpMediaId (sobrescribiendo el identificador de medio original pasado).

Si se especifica NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE, se devuelve ERROR_MEDIA_ no disponible si no hay ningún medio disponible.

Cuando sea necesario, RSM genera una solicitud de operador para insertar medios nuevos o disponibles. Si la hora especificada en el parámetro dwTimeout transcurre antes de que se controle la solicitud del operador, RSM devuelve ERROR_TIMEOUT y elimina la solicitud del operador.

Si el usuario cancela la solicitud de asignación, RSM devuelve ERROR_CANCELLED.

Si un usuario indica que se ha cumplido la solicitud del operador, la solicitud se elimina y RSM vuelve a intentar el proceso.

Cuando una aplicación requiere nuevos medios que contengan datos, un usuario o administrador coloca los medios en una biblioteca o unidad. RSM identifica el medio y lo coloca en el grupo de importación. La aplicación busca en el grupo de importación, mueve los medios a su grupo de aplicaciones y los asigna. Este proceso rutinario se puede simplificar y realizar atómico a través de una sola llamada a AllocateNtmsMedia. Después de buscar en el grupo de importación, la aplicación puede llamar a AllocateNtmsMedia, pasando el identificador de partición del lado como el valor del parámetro lpPartId . Después, RSM:

  1. mueve el medio al grupo de medios especificado.
  2. cambia el estado del medio a asignado.
  3. devuelve un LMID.
Nota En el caso de los medios de dos lados, el lado inverso permanece en el estado Importar y no está disponible para su uso hasta que se importe.
 

Requisitos

   
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado ntmsapi.h
Library Ntmsapi.lib
Archivo DLL Ntmsapi.dll

Consulte también

DeallocateNtmsMedia

Funciones de Media Services

NTMS_ALLOCATION_INFORMATION