AllocateNtmsMedia-Funktion (ntmsapi.h)

  • Artikel

[Wechselmedien-Manager ist ab Windows 7 und Windows Server 2008 R2 nicht mehr verfügbar.]

Die AllocateNtmsMedia-Funktion ordnet einen Teil der verfügbaren Medien zu.

Syntax

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

Parameter

[in] hSession

Handle für die von der OpenNtmsSession-Funktion zurückgegebene Sitzung.

[in] lpMediaPool

Eindeutiger Bezeichner des Medienpools, aus dem die Medien zugeordnet werden sollen. Für die Zuordnung können nur Anwendungspools angegeben werden.

[in] lpPartition

Teilbezeichner einer Seite, die als logische Medienbezeichner (LMID) verwendet werden soll. Die Seite muss den Status Verfügbar oder Import aufweisen. Dieses Feature kann zum Zuordnen einer bestimmten Seite oder zum Importieren von Medien verwendet werden. Dieser Parameter ist optional.

[out] lpMediaId

LMID des zugeordneten Mediums. Dieser Parameter ist NULL , wenn das Medium nicht zugeordnet werden kann.

[in] dwOptions

Optionen. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert Bedeutung
NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE
 Verhindert die Übermittlung einer Operatoranforderung für neue Medien, wenn keines mit den angegebenen Einschränkungen zugeordnet werden kann.
NTMS_ALLOCATE_NEW
 Weist eine Seite des angegebenen Mediums zu, die nicht für die logischen Medien einer anderen Anwendung freigegeben werden kann. Dieser Wert reserviert beispielsweise die zweite Seite von zweiseitigen optischen Medien.
NTMS_ALLOCATE_NEXT
 Ordnen Sie die nächste Seite des mehrseitigen Mediums zu, die zuvor mit dem wert NTMS_ALLOCATE_NEW zugeordnet wurde. Dadurch kann eine einzelne Anwendung beide Seiten eines beidseitigen Mediums verwenden und sicherstellen, dass die Anwendung alle Daten auf dem physischen Medium besitzt.

Wenn alle Seiten des Mediums bereits zugeordnet sind, schlägt die Zuordnungsanforderung fehl.

[in] dwTimeout

Maximal zulässige Zeit zum Zuordnen der angegebenen Medien in Millisekunden. Wenn dieser Parameter INFINITE ist, tritt für die Funktion kein Timeout auf. Wenn dieser Parameter null ist, wartet er auf Medien. Beachten Sie, dass diese Funktion keine Anforderung für weitere Medien in die Warteschlange stellt, wenn der dwOptions-Parameter NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE angibt.

[out] lpAllocateInformation

Zeiger auf eine NTMS_ALLOCATION_INFORMATION Struktur, die den Quellmedienpool empfängt, aus dem das Medium entnommen wurde. Dieser Parameter kann NULL sein.

Rückgabewert

Diese Funktion gibt einen der folgenden Werte zurück.

Wert Bedeutung
ERROR_ACCESS_DENIED
 NTMS_CONTROL_ACCESS zum Medienpool der Medien wird verweigert. Es sind auch andere Sicherheitsfehler möglich, die jedoch auf einen Sicherheitssubsystemfehler hinweisen.

Windows XP: NTMS_MODIFY_ACCESS zum Medienpool von Medien wird verweigert.
ERROR_CANCELLED
 Der Operator hat die Anforderung für neue Medien abgebrochen.
ERROR_DATABASE_FAILURE
 Auf die Datenbank kann nicht zugegriffen werden oder beschädigt werden.
ERROR_DATABASE_FULL
 Die Datenbank ist voll.
ERROR_DEVICE_NOT_AVAILABLE
 Eine Zwischenressource ist nicht verfügbar. beispielsweise ist der kostenlose Medienpool nicht verfügbar.
ERROR_INVALID_HANDLE
 Das Sitzungshandle fehlt oder ist ungültig.
ERROR_INVALID_MEDIA
 Die Partitions-ID oder LMID war bei der Eingabe bei Verwendung des NTMS_ALLOCATE_NEXT-Flags ungültig.
ERROR_INVALID_MEDIA_POOL
 Die Medienpool-ID ist ungültig.
ERROR_INVALID_PARAMETER
 Die Id des Medien- oder Medienpools fehlt.
ERROR_MEDIA_OFFLINE
 Die angegebenen Medien sind offline und können nicht zugeordnet werden.
ERROR_MEDIA_UNAVAILABLE
 Innerhalb des angegebenen Timeoutereignisses wurden keine Medien zugeordnet.
ERROR_NOT_ENOUGH_MEMORY
 Während der Verarbeitung ist ein Zuordnungsfehler aufgetreten.
ERROR_SUCCESS
 Die Funktion war erfolgreich.
ERROR_TIMEOUT
 Das Timeoutereignis ist abgelaufen, bevor Medien verfügbar waren.

Hinweise

Die AllocateNtmsMedia-Funktion gibt eine LMID zurück. Wenn der angegebene Medienpool keine online verfügbaren Medien enthält, kann AllocateNtmsMedia je nach Richtlinie des Medienpools den kostenlosen Medienpool nach dem angegebenen Medium durchsuchen, um in den angegebenen Medienpool zu wechseln. Medien aus dem angegebenen Medienpool werden zuerst zugeordnet, und dann werden die kostenlosen Medien verschoben und zugeordnet.

Wenn der Medienpool online verfügbare Medien enthält, wird ein Medium aus dem Pool zugeordnet.

Wenn der Medienpool für die automatische Zuweisung von Medien aus dem kostenlosen Pool konfiguriert ist und der kostenlose Pool online verfügbare Medien enthält, wird ein Medium in den angegebenen Pool verschoben und zugeordnet.

Windows Server 2003: Wenn Medien aus dem kostenlosen Pool zugeordnet werden, ist NTMS_USE_ACCESS zum kostenlosen Pool und NTMS_CONTROL_ACCESS zum Zielpool erforderlich. Wenn der kostenlose Pool nicht der Quellmedienpool ist, ist NTMS_CONTROL_ACCESS sowohl für Quell- als auch für Zielpools erforderlich.

Wenn der NTMS_ALLOCATE_NEXT Wert angegeben wird, muss der lpMediaId-Parameter zum Zeitpunkt des Aufrufs auf eine gültige Medien-ID verweisen. In diesem Fall wird lpMediaId als IN- und OUT-Parameter verwendet. Die nächste Seite des mehrseitigen Mediums, das von lpMediaId angegeben wird, wird zugeordnet, und die neue Partitions-ID wird über lpMediaId zurückgegeben (überschreiben die ursprüngliche Medien-ID übergeben).

Wenn NTMS_ALLOCATE_ERROR_IF_UNAVAILABLE angegeben ist, wird ERROR_MEDIA_ UNAVAILABLE zurückgegeben, wenn keine Medien verfügbar sind.

Bei Bedarf generiert RSM eine Operatoranforderung zum Einfügen neuer oder Verfügbarer Medien. Wenn die im dwTimeout-Parameter angegebene Zeit verstrichen ist, bevor die Operatoranforderung verarbeitet wird, gibt RSM ERROR_TIMEOUT zurück und löscht die Operatoranforderung.

Wenn der Benutzer die Zuordnungsanforderung abbricht, gibt RSM ERROR_CANCELLED zurück.

Wenn ein Benutzer angibt, dass die Operatoranforderung erfüllt wurde, wird die Anforderung gelöscht, und RSM wiederholt den Prozess.

Wenn eine Anwendung neue Medien mit Daten benötigt, platziert ein Benutzer oder Administrator die Medien in einer Bibliothek oder einem Laufwerk. RSM identifiziert die Medien und platziert es im Importpool. Die Anwendung durchsucht den Importpool, verschiebt die Medien in ihren Anwendungspool und ordnet sie zu. Dieser Routineprozess kann durch einen einzelnen Aufruf von AllocateNtmsMedia optimiert und atomar gestaltet werden. Nach dem Durchsuchen des Importpools kann die Anwendung AllocateNtmsMedia aufrufen und die Partitions-ID der Seite als Wert des lpPartId-Parameters übergeben. RSM dann:

  1. verschiebt das Medium in den angegebenen Medienpool.
  2. ändert den Zustand des Mediums in zugeordnet.
  3. gibt eine LMID zurück.
Hinweis Bei zweiseitigen Medien verbleibt die Kehrseite im Importzustand und steht erst nach dem Import zur Verwendung zur Verfügung.
 

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile ntmsapi.h
Bibliothek Ntmsapi.lib
DLL Ntmsapi.dll

Weitere Informationen

DeallocateNtmsMedia

Media Services-Funktionen

NTMS_ALLOCATION_INFORMATION