Função AllocateNtmsMedia (ntmsapi.h)
[O Gerenciador de Armazenamento Removível não está mais disponível para uso a partir do Windows 7 e do Windows Server 2008 R2.]
A função AllocateNtmsMedia aloca uma parte da mídia disponível.
Sintaxe
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
Manipule para a sessão retornada pela função OpenNtmsSession .
[in] lpMediaPool
Identificador exclusivo do pool de mídia do qual a mídia deve ser alocada. Somente pools de aplicativos podem ser especificados para alocação.
[in] lpPartition
Identificador de parte de um lado a ser usado como um LMID (identificador de mídia lógica). O lado deve estar no estado Disponível ou Importar. Esse recurso pode ser usado para alocar um lado específico ou importar mídia. Esse parâmetro é opcional.
[out] lpMediaId
LMID do meio alocado. Esse parâmetro será NULL se o meio não puder ser alocado.
[in] dwOptions
Opções. Esse parâmetro pode usar um dos valores a seguir.
[in] dwTimeout
Tempo máximo permitido para alocar a mídia especificada, em milissegundos. Se esse parâmetro for INFINITE, a função não atingirá o tempo limite. Se esse parâmetro for zero, ele aguardará a mídia. Observe que essa função não enfileira uma solicitação para mais mídia se o parâmetro dwOptions especificar NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE.
[out] lpAllocateInformation
Ponteiro para uma estrutura NTMS_ALLOCATION_INFORMATION que recebe o pool de mídia de origem do qual o meio foi obtido. Este parâmetro pode ser NULL.
Valor retornado
Essa função retorna um dos valores a seguir.
| Valor | Significado |
|---|---|
|
NTMS_CONTROL_ACCESS para o pool de mídia da mídia é negado. Outros erros de segurança também são possíveis, mas indicam um erro de subsistema de segurança.
Windows XP: NTMS_MODIFY_ACCESS para o pool de mídia da mídia é negado. |
|
O operador cancelou a solicitação de nova mídia. |
|
O banco de dados está inacessível ou danificado. |
|
O banco de dados está cheio. |
|
Um recurso intermediário não está disponível; por exemplo, o pool de mídia gratuito não está disponível. |
|
O identificador de sessão está ausente ou não é válido. |
|
A ID de partição ou LMID não era válida na entrada ao usar o sinalizador NTMS_ALLOCATE_NEXT. |
|
A ID do pool de mídia não é válida. |
|
A ID do pool de mídia ou mídia está ausente. |
|
A mídia especificada está offline e não pode ser alocada. |
|
Nenhuma mídia foi alocada dentro do evento de tempo limite especificado. |
|
Houve uma falha de alocação durante o processamento. |
|
A função foi bem-sucedida. |
|
O evento de tempo limite expirou antes da mídia estar disponível. |
Comentários
A função AllocateNtmsMedia retorna um LMID. Dependendo da política do pool de mídia, se o pool de mídia especificado não contiver nenhuma mídia disponível online, AllocateNtmsMedia poderá pesquisar o pool de mídia gratuito para que o meio especificado se mova para o pool de mídia especificado. A mídia do pool de mídia designado é alocada primeiro e, em seguida, a mídia gratuita é movida e alocada.
Se o pool de mídia contiver qualquer mídia disponível online, um meio do pool será alocado.
Se o pool de mídia estiver configurado para alocar mídia do pool gratuito automaticamente e o pool gratuito contiver mídia disponível online, um meio será movido para o pool especificado e alocado.
Windows Server 2003: Se a mídia estiver sendo alocada do pool gratuito, será necessário NTMS_USE_ACCESS para o pool gratuito e NTMS_CONTROL_ACCESS para o pool de destino. Se o pool gratuito não for o pool de mídia de origem, NTMS_CONTROL_ACCESS será necessário nos pools de origem e de destino.
Quando o valor de NTMS_ALLOCATE_NEXT é especificado, o parâmetro lpMediaId deve apontar para uma ID de mídia válida no momento da invocação. Nesse caso, lpMediaId é usado como um parâmetro IN e OUT. O próximo lado do meio lateral múltiplo especificado por lpMediaId é alocado e a nova ID de partição é retornada por meio de lpMediaId (substituindo a ID de mídia original passada).
Se NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE for especificado, ERROR_MEDIA_ UNAVAILABLE será retornado se nenhuma mídia estiver disponível.
Quando necessário, o RSM gera uma solicitação de operador para inserir mídia nova ou disponível. Se o tempo especificado no parâmetro dwTimeout passar antes que a solicitação do operador seja tratada, o RSM retornará ERROR_TIMEOUT e excluirá a solicitação do operador.
Se o usuário cancelar a solicitação de alocação, o RSM retornará ERROR_CANCELLED.
Se um usuário indicar que a solicitação do operador foi atendida, a solicitação será excluída e o RSM repetirá o processo.
Quando um aplicativo requer novas mídias que contêm dados, um usuário ou administrador coloca a mídia em uma biblioteca ou unidade. O RSM identifica a mídia e a coloca no pool de importação. O aplicativo pesquisa o pool de importação, move a mídia para seu pool de aplicativos e a aloca. Esse processo de rotina pode ser simplificado e tornado atômico por meio de uma única chamada para AllocateNtmsMedia. Depois de pesquisar o pool de importação, o aplicativo pode chamar AllocateNtmsMedia, passando a ID de partição do lado como o valor do parâmetro lpPartId . RSM, em seguida:
- move o meio para o pool de mídia especificado.
- altera o estado da mídia para alocado.
- retorna um LMID.
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ntmsapi.h |
| Biblioteca | Ntmsapi.lib |
| DLL | Ntmsapi.dll |