Fonction AllocateNtmsMedia (ntmsapi.h)

  • Article

[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.

Valeur Signification
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE
 Empêche la soumission d’une demande d’opérateur pour un nouveau média si aucun ne peut être alloué avec les contraintes spécifiées.
NTMS_ALLOCATE_NEW
 Alloue un côté du support spécifié qui ne peut pas être partagé avec le média logique d’une autre application. Par exemple, cette valeur réserve la deuxième face du support optique double face.
NTMS_ALLOCATE_NEXT
 Allouez le côté suivant du support multi-face précédemment alloué avec la valeur NTMS_ALLOCATE_NEW. Cela permet à une application unique d’utiliser les deux côtés d’un média double face et de s’assurer que l’application possède toutes les données sur le support physique.

Si tous les côtés du support sont déjà alloués, la demande d’allocation échoue.

[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
ERROR_ACCESS_DENIED
 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é.
ERROR_CANCELLED
 L’opérateur a annulé la demande de nouveau média.
ERROR_DATABASE_FAILURE
 La base de données est inaccessible ou endommagée.
ERROR_DATABASE_FULL
 La base de données est pleine.
ERROR_DEVICE_NOT_AVAILABLE
 Une ressource intermédiaire n’est pas disponible ; par exemple, le pool multimédia gratuit n’est pas disponible.
ERROR_INVALID_HANDLE
 Le handle de session est manquant ou n’est pas valide.
ERROR_INVALID_MEDIA
 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.
ERROR_INVALID_MEDIA_POOL
 L’ID du pool de médias n’est pas valide.
ERROR_INVALID_PARAMETER
 L’ID du média ou du pool de médias est manquant.
ERROR_MEDIA_OFFLINE
 Le média spécifié est hors connexion et ne peut pas être alloué.
ERROR_MEDIA_UNAVAILABLE
 Aucun média n’a été alloué dans l’événement de délai d’attente spécifié.
ERROR_NOT_ENOUGH_MEMORY
 Il y a eu un échec d’allocation pendant le traitement.
ERROR_SUCCESS
 La fonction a réussi.
ERROR_TIMEOUT
 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 :

  1. déplace le support vers le pool de médias spécifié.
  2. modifie l’état du média en lui permettant d’être alloué.
  3. retourne un LMID.
Note Pour les médias à deux côtés, le revers reste à l’état Importer et n’est pas disponible pour une utilisation tant qu’il n’est pas importé.
 

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

Voir aussi

DeallocateNtmsMedia

Fonctions Media Services

NTMS_ALLOCATION_INFORMATION