Função MountNtmsMedia (ntmsapi.h)

  • Artigo

[O Gerenciador de Armazenamento Removível não está mais disponível desde o Windows 7 e o Windows Server 2008 R2.]

A função MountNtmsMedia monta de forma síncrona uma ou mais partes de mídia.

Sintaxe

DWORD MountNtmsMedia(
  [in]      HANDLE                   hSession,
  [in]      LPNTMS_GUID              lpMediaId,
  [in, out] LPNTMS_GUID              lpDriveId,
  [in]      DWORD                    dwCount,
  [in]      DWORD                    dwOptions,
  [in]      int                      dwPriority,
  [in]      DWORD                    dwTimeout,
            LPNTMS_MOUNT_INFORMATION lpMountInformation
);

Parâmetros

[in] hSession

Identificador para a sessão retornada pela função OpenNtmsSession .

[in] lpMediaId

Matriz de identificadores exclusivos de mídia lógica ou lados.

[in, out] lpDriveId

Matriz de identificadores de unidade que corresponde à lista de mídias no parâmetro lpMediaId . Essa matriz especifica uma lista de unidades para montar mídia ou recebe a lista de unidades em que a mídia é montada na conclusão da operação. Veja o valor de NTMS_MOUNT_SPECIFIC_DRIVE abaixo. Se a função MountNtmsMedia atingir o tempo limite antes da conclusão da montagem, o RSM não retornará a lista de unidades.

[in] dwCount

Número de identificadores de mídia e identificadores de unidade passados nos parâmetros lpMediaId e lpDriveId . Observe que lpMediaId e lpDriveId devem apontar para o primeiro elemento de matrizes de comprimento igual.

[in] dwOptions

Opções. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
NTMS_MOUNT_SPECIFIC_DRIVE
 Monte a mídia nas unidades específicas fornecidas no parâmetro lpDriveId .
NTMS_MOUNT_READ
 Monte a mídia para acesso de leitura. Use esse valor para montar mídia somente leitura.
NTMS_MOUNT_WRITE
 Monte a mídia para acesso de gravação. Use esse sinalizador para impedir que o RSM monte a mídia Concluída. Esse valor pode ser combinado com NTMS_MOUNT_READ para acesso de leitura/gravação.

O RSM não poderá montar a mídia Concluída se esse sinalizador estiver selecionado.
NTMS_MOUNT_ERROR_NOT_AVAILABLE
 Esse valor retornará um erro se a mídia ou uma unidade não estiver disponível.
NTMS_MOUNT_ERROR_OFFLINE
 Não emita uma solicitação de operador para montar mídia offline. Retornará um erro se a mídia especificada não estiver atualmente em uma biblioteca.

[in] dwPriority

Prioridade da montagem usada pelo RSM para permitir o acesso a unidades. As prioridades variam de -15 a 15, com 15 a prioridade mais alta e 0 é o padrão. Esse parâmetro também pode ter uma das seguintes constantes. Um aplicativo deve passar NTMS_PRIORITY_NORMAL, a menos que uma prioridade de montagem especial seja necessária.

Valor Significado
NTMS_PRIORITY_NORMAL
 Montagens que não são críticas ao tempo.
NTMS_PRIORITY_LOW
 Montagens executadas como uma atividade em segundo plano.
NTMS_PRIORITY_HIGH
 Montagens que são críticas ao tempo.
NTMS_PRIORITY_LOWEST
 Montagem de prioridade mais baixa.
NTMS_PRIORITY_HIGHEST
 Montagem de prioridade mais alta.

[in] dwTimeout

Tempo máximo permitido para montar a mídia especificada, em milissegundos. Defina esse parâmetro como INFINITE para aguardar até que a montagem seja concluída.

lpMountInformation

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Essa função retorna um dos valores a seguir.

Valor Significado
ERROR_ACCESS_DENIED
 NTMS_USE_ACCESS ao pool de mídia ou à biblioteca que contém a mídia é negada; outros erros de segurança também são possíveis, mas indicam um erro de subsistema de segurança.
ERROR_BUSY
 A mídia ou as unidades estão ocupadas.
ERROR_CANCELLED
 A solicitação foi cancelada pela função CloseNtmsSession .
ERROR_DATABASE_FAILURE
 O banco de dados está inacessível ou danificado.
ERROR_DATABASE_FULL
 O banco de dados está cheio.
ERROR_DRIVE_MEDIA_MISMATCH
 A mídia e a unidade especificadas não estão na mesma biblioteca.
ERROR_INVALID_DRIVE
 Pelo menos uma das unidades especificadas não é válida.
ERROR_INVALID_LIBRARY
 A biblioteca que contém as unidades ou mídia não é válida.
ERROR_INVALID_MEDIA
 Uma ou mais das mídias especificadas não são válidas ou há IDs de mídia duplicadas na lista de mídias.
ERROR_INVALID_STATE
 Ocorreu um estado inesperado de mídia ou dispositivo durante a montagem.
ERROR_MEDIA_OFFLINE
 A mídia está offline e não pode ser montada.
ERROR_NOT_ENOUGH_MEMORY
 Ocorreu uma falha de alocação de memória durante o processamento.
ERROR_REQUEST_REFUSED
 O usuário cancelou a solicitação por meio da interface do usuário.
ERROR_RESOURCE_DISABLED
 Um ou mais recursos necessários para executar a montagem estão desabilitados.
ERROR_SUCCESS
 A mídia foi montada e está pronta para uso.
ERROR_TIMEOUT
 O evento de tempo limite expirou ao tentar adquirir um ou mais recursos necessários. A solicitação de montagem foi cancelada.
ERROR_WRITE_PROTECT
 O estado da mídia é definido como Concluído e o valor de NTMS_MOUNT_WRITE foi especificado.

Comentários

A função MountNtmsMedia enfileira uma solicitação para montar a mídia especificada e aguarda o número de milissegundos especificado no parâmetro dwTimeout para que a montagem seja concluída ou que um erro seja detectado. Se o RSM não puder concluir a operação de montagem antes que dwTimeout expire, o NTMS cancelará a solicitação e retornará um erro. Se a mídia especificada estiver em uma biblioteca offline, o aplicativo poderá ser bloqueado por um longo período de tempo. Você pode usar a função GetNtmsObjectInformation para determinar o local atual do meio especificado. Você também pode usar o valor NTMS_MOUNT_ERROR_OFFLINE para gerar um erro imediato em vez de uma solicitação de operador quando a mídia estiver offline.

Se o meio especificado estiver em uso ou uma unidade não estiver disponível, o processo bloqueará até o valor de tempo limite e retornará ERROR_BUSY. Se o valor NTMS_MOUNT_ERROR_NOT_AVAILABLE for especificado, a função retornará um erro imediato quando um recurso (mídia ou unidade) não estiver disponível.

O valor de tempo limite de INFINITE pode ser usado para fazer com que a função aguarde sem atingir o tempo limite. Quando um valor de tempo limite diferente de zero é especificado no parâmetro dwTimeout , o RSM aguarda que toda a mídia especificada em lpMediaId seja montada. Se o tempo especificado passar antes de toda a mídia ser montada, a função MountNtmsMedia retornará um erro e cancelará a solicitação. O aplicativo pode examinar o status retornado e reenviar a solicitação, se desejado.

Quando várias mídias a serem montadas são especificadas com uma única chamada, toda a mídia especificada deve estar em uma única biblioteca. Se qualquer uma das mídias especificadas estiver offline, nenhuma mídia será montada até que toda a mídia esteja online.

Na conclusão da montagem, o estado da unidade (por exemplo, correção ou modo variável) não está definido. O aplicativo deve configurar a unidade.

A função CloseNtmsSession pode ser usada para cancelar uma montagem pendente. O comportamento padrão é:

  • Se o meio especificado estiver offline, o RSM postará uma solicitação de operador para montar a mídia e a função MountNtmsMedia aguardará o período de tempo especificado no parâmetro dwTimeout .
  • Se o meio especificado estiver online, o RSM solicitará a montagem.
  • Se uma unidade ou mídia não estiver disponível, o RSM enviará a solicitação e a função MountNtmsMedia aguardará o período de tempo especificado no parâmetro dwTimeout .

Requisitos

Requisito Valor
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

Confira também

Funções dos Serviços de Mídia