Fonction AllocateNtmsMedia (ntmsapi.h)
[Le Gestionnaire de stockage amovible n’est plus disponible à partir de Windows 7 et Windows Server 2008 R2.]
La fonction AllocateNtmsMedia alloue un élément multimédia disponible.
Syntaxe
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
);
Paramètres
[in] hSession
Gérez la session retournée par la fonction OpenNtmsSession .
[in] lpMediaPool
Identificateur unique du pool de médias à partir duquel le média doit être alloué. Seuls les pools d’applications peuvent être spécifiés pour l’allocation.
[in] lpPartition
Identificateur de partie d’un côté à utiliser comme identificateur de média logique (LMID). Le côté doit être à l’état Disponible ou Importer. Cette fonctionnalité peut être utilisée pour allouer un côté particulier ou pour importer un média. Ce paramètre est facultatif.
[out] lpMediaId
LMID du support alloué. Ce paramètre a la valeur NULL si le support ne peut pas être alloué.
[in] dwOptions
Options. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
[in] dwTimeout
Durée maximale autorisée pour allouer le média spécifié, en millisecondes. Si ce paramètre est INFINITE, la fonction n’expirera pas. Si ce paramètre est égal à zéro, il attend le support. Notez que cette fonction ne met pas en file d’attente une demande de support supplémentaire si le paramètre dwOptions spécifie NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE.
[out] lpAllocateInformation
Pointeur vers une structure NTMS_ALLOCATION_INFORMATION qui reçoit le pool de médias source à partir duquel le support a été extrait. Ce paramètre peut être NULL.
Valeur retournée
Cette fonction retourne l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
NTMS_CONTROL_ACCESS au pool multimédia du média est refusé. D’autres erreurs de sécurité sont également possibles, mais elles indiquent une erreur de sous-système de sécurité.
Windows XP : NTMS_MODIFY_ACCESS au pool multimédia du média est refusé. |
|
L’opérateur a annulé la demande de nouveau média. |
|
La base de données est inaccessible ou endommagée. |
|
La base de données est pleine. |
|
Une ressource intermédiaire n’est pas disponible ; par exemple, le pool multimédia gratuit n’est pas disponible. |
|
Le handle de session est manquant ou n’est pas valide. |
|
L’ID de partition ou LMID n’était pas valide lors de l’entrée lors de l’utilisation de l’indicateur NTMS_ALLOCATE_NEXT. |
|
L’ID du pool de médias n’est pas valide. |
|
L’ID du média ou du pool de médias est manquant. |
|
Le média spécifié est hors connexion et ne peut pas être alloué. |
|
Aucun média n’a été alloué dans l’événement de délai d’attente spécifié. |
|
Il y a eu un échec d’allocation pendant le traitement. |
|
La fonction a réussi. |
|
L’événement de délai d’expiration a expiré avant que le média soit disponible. |
Notes
La fonction AllocateNtmsMedia retourne un LMID. En fonction de la stratégie du pool de médias, si le pool de médias spécifié ne contient aucun média disponible en ligne, AllocateNtmsMedia peut rechercher dans le pool multimédia gratuit le support spécifié pour passer au pool multimédia spécifié. Les médias du pool de médias désigné sont alloués en premier, puis le média gratuit est déplacé et alloué.
Si le pool de médias contient un média disponible en ligne, un support du pool est alloué.
Si le pool de médias est configuré pour allouer automatiquement le contenu multimédia à partir du pool gratuit et que le pool gratuit contient un média disponible en ligne, un support est déplacé vers le pool spécifié et alloué.
Windows Server 2003 : Si le média est alloué à partir du pool gratuit, NTMS_USE_ACCESS au pool gratuit et NTMS_CONTROL_ACCESS au pool de destination est requis. Si le pool gratuit n’est pas le pool de médias source, NTMS_CONTROL_ACCESS est requis sur les pools source et de destination.
Lorsque la valeur NTMS_ALLOCATE_NEXT est spécifiée, le paramètre lpMediaId doit pointer vers un ID multimédia valide au moment de l’appel. Dans ce cas, lpMediaId est utilisé comme paramètre IN et OUT. Le côté suivant du support recto-verso spécifié par lpMediaId est alloué, et le nouvel ID de partition est retourné via lpMediaId (en remplaçant l’ID multimédia d’origine transmis).
Si NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE est spécifié, ERROR_MEDIA_ INDISPONIBLE est retourné si aucun média n’est disponible.
Si nécessaire, RSM génère une demande d’opérateur pour insérer un média nouveau ou disponible. Si le temps spécifié dans le paramètre dwTimeout s’écoule avant que la demande d’opérateur soit gérée, RSM retourne ERROR_TIMEOUT et supprime la demande d’opérateur.
Si l’utilisateur annule la demande d’allocation, RSM retourne ERROR_CANCELLED.
Si un utilisateur indique que la demande d’opérateur a été satisfaite, la demande est supprimée et RSM réessaye le processus.
Lorsqu’une application a besoin d’un nouveau média contenant des données, un utilisateur ou un administrateur place le média dans une bibliothèque ou un lecteur. RSM identifie le média et le place dans le pool d’importation. L’application recherche le pool d’importation, déplace le média vers son pool d’applications et l’alloue. Ce processus de routine peut être simplifié et rendu atomique par un seul appel à AllocateNtmsMedia. Après avoir effectué une recherche dans le pool d’importation, l’application peut appeler AllocateNtmsMedia, en passant l’ID de partition du côté comme valeur du paramètre lpPartId . RSM ensuite :
- déplace le support vers le pool de médias spécifié.
- modifie l’état du média en lui permettant d’être alloué.
- retourne un LMID.
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ntmsapi.h |
| Bibliothèque | Ntmsapi.lib |
| DLL | Ntmsapi.dll |