Funzione AllocateNtmsMedia (ntmsapi.h)

Articolo
08/25/2023

[Gestione archiviazione rimovibile non è più disponibile per l'uso a partire da Windows 7 e Windows Server 2008 R2.]

La funzione AllocateNtmsMedia alloca un elemento multimediale disponibile.

Sintassi

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
);

Parametri

[in] hSession

Handle per la sessione restituita dalla funzione OpenNtmsSession .

[in] lpMediaPool

Identificatore univoco del pool di supporti da cui deve essere allocato il supporto. Solo i pool di applicazioni possono essere specificati per l'allocazione.

[in] lpPartition

Identificatore parte di un lato da usare come identificatore di supporti logici (LMID). Il lato deve essere nello stato Disponibile o Importa. Questa funzionalità può essere usata per allocare un lato specifico o per importare supporti. Questo parametro è facoltativo e,

[out] lpMediaId

LMID del supporto allocato. Questo parametro è NULL se il supporto non può essere allocato.

[in] dwOptions

Opzioni. Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE	Impedisce l'invio di una richiesta di operatore per nuovi supporti se nessuno può essere allocato con i vincoli specificati.
NTMS_ALLOCATE_NEW	Alloca un lato del supporto specificato che non può essere condiviso con i supporti logici di un'altra applicazione. Ad esempio, questo valore riserva il secondo lato di supporti ottici a due lati.
NTMS_ALLOCATE_NEXT	Allocare il lato successivo del supporto multi-side allocato in precedenza con il valore NTMS_ALLOCATE_NEW. In questo modo, una singola applicazione può usare entrambi i lati di un supporto a due lati e assicurarsi che l'applicazione sia proprietaria di tutti i dati presenti nel supporto fisico. Se tutti i lati del supporto sono già allocati, la richiesta di allocazione ha esito negativo.

[in] dwTimeout

Tempo massimo consentito per allocare il supporto specificato, espresso in millisecondi. Se questo parametro è INFINITE, la funzione non si verifica il timeout. Se questo parametro è zero, attenderà i supporti. Si noti che questa funzione non accoda una richiesta per più supporti se il parametro dwOptions specifica NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE.

[out] lpAllocateInformation

Puntatore a una struttura NTMS_ALLOCATION_INFORMATION che riceve il pool di supporti di origine da cui è stato acquisito il supporto. Questo parametro può essere NULL.

Valore restituito

Questa funzione restituisce uno dei valori seguenti.

Valore	Significato
ERROR_ACCESS_DENIED	NTMS_CONTROL_ACCESS al pool di supporti del supporto viene negato. Sono possibili anche altri errori di sicurezza, ma indicano un errore del sottosistema di sicurezza. Windows XP: NTMS_MODIFY_ACCESS al pool di contenuti multimediali viene negato.
ERROR_CANCELLED	L'operatore ha annullato la richiesta di nuovi supporti.
ERROR_DATABASE_FAILURE	Il database non è accessibile o danneggiato.
ERROR_DATABASE_FULL	Il database è pieno.
ERROR_DEVICE_NOT_AVAILABLE	Una risorsa intermedia non è disponibile; ad esempio, il pool di supporti gratuiti non è disponibile.
ERROR_INVALID_HANDLE	L'handle di sessione è mancante o non è valido.
ERROR_INVALID_MEDIA	L'ID di partizione o LMID non è valido all'input quando si usa il flag di NTMS_ALLOCATE_NEXT.
ERROR_INVALID_MEDIA_POOL	L'ID del pool multimediale non è valido.
ERROR_INVALID_PARAMETER	L'ID del pool multimediale o multimediale è mancante.
ERROR_MEDIA_OFFLINE	Il supporto specificato è offline e non può essere allocato.
ERROR_MEDIA_UNAVAILABLE	Nessun supporto allocato nell'evento di timeout specificato.
ERROR_NOT_ENOUGH_MEMORY	Si è verificato un errore di allocazione durante l'elaborazione.
ERROR_SUCCESS	La funzione ha avuto esito positivo.
ERROR_TIMEOUT	L'evento di timeout è scaduto prima che il supporto fosse disponibile.

Commenti

La funzione AllocateNtmsMedia restituisce un LMID. A seconda dei criteri del pool di supporti, se il pool di supporti specificato non contiene supporti disponibili online, AllocateNtmsMedia potrebbe cercare nel pool multimediale gratuito il supporto specificato per spostarsi nel pool di supporti specificato. Il supporto dal pool di supporti designato viene allocato per primo e quindi il supporto libero viene spostato e allocato.

Se il pool di supporti contiene supporti disponibili online, viene allocato un supporto dal pool.

Se il pool di supporti è configurato per allocare automaticamente i supporti dal pool gratuito e il pool gratuito contiene supporti disponibili online, un supporto viene spostato nel pool specificato e allocato.

Windows Server 2003: Se i supporti vengono allocati dal pool gratuito, è necessario NTMS_USE_ACCESS al pool gratuito e NTMS_CONTROL_ACCESS al pool di destinazione. Se il pool gratuito non è il pool di supporti di origine, NTMS_CONTROL_ACCESS è necessario nei pool di origine e di destinazione.

Quando viene specificato il valore NTMS_ALLOCATE_NEXT, il parametro lpMediaId deve puntare a un ID supporto valido al momento della chiamata. In questo caso, lpMediaId viene usato come parametro IN e OUT. Il lato successivo del supporto lato multiplo specificato da lpMediaId viene allocato e il nuovo ID di partizione viene restituito tramite lpMediaId (sovrascrivendo l'ID multimediale originale passato).

Se si specifica NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE, ERROR_MEDIA_ NON DISPONIBILE viene restituito se non è disponibile alcun supporto.

Quando necessario, RSM genera una richiesta di operatore per inserire supporti nuovi o disponibili. Se il tempo specificato nel parametro dwTimeout è trascorso prima che la richiesta dell'operatore venga gestita, RSM restituisce ERROR_TIMEOUT ed elimina la richiesta dell'operatore.

Se l'utente annulla la richiesta di allocazione, RSM restituisce ERROR_CANCELLED.

Se un utente indica che la richiesta dell'operatore è stata soddisfatta, la richiesta viene eliminata e RSM ritenta il processo.

Quando un'applicazione richiede nuovi supporti contenenti dati, un utente o un amministratore inserisce il supporto in una libreria o in un'unità. RSM identifica il supporto e lo inserisce nel pool di importazione. L'applicazione cerca nel pool di importazione, sposta il supporto nel pool di applicazioni e lo alloca. Questo processo di routine può essere semplificato e reso atomico tramite una singola chiamata a AllocateNtmsMedia. Dopo aver eseguito una ricerca nel pool di importazione, l'applicazione può chiamare AllocateNtmsMedia, passando l'ID partizione del lato come valore del parametro lpPartId . RSM quindi:

sposta il supporto nel pool di supporti specificato.
modifica lo stato del supporto in allocato.
restituisce un LMID.

Nota Per i supporti a due lati, il lato capovolgimento rimane nello stato Di importazione e non è disponibile per l'uso fino all'importazione.

Requisiti


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ntmsapi.h
Libreria	Ntmsapi.lib
DLL	Ntmsapi.dll

Vedi anche

DeallocateNtmsMedia

Funzioni di Servizi multimediali

NTMS_ALLOCATION_INFORMATION

Condividi tramite