IVdsSubSystem::CreateLun-Methode (vds.h)

Artikel
03/06/2024

[Ab Windows 8 und Windows Server 2012 wird die COM-Schnittstelle des Virtuellen Datenträgerdiensts durch die Windows Storage Management-API abgelöst.]

Die CreateLun-Methode erstellt eine logische Einheitsnummer (Logical Unit Number, LUN).

Syntax

HRESULT CreateLun(
  [in]  VDS_LUN_TYPE  type,
  [in]  ULONGLONG     ullSizeInBytes,
  [in]  VDS_OBJECT_ID *pDriveIdArray,
  [in]  LONG          lNumberOfDrives,
  [in]  LPWSTR        pwszUnmaskingList,
  [in]  VDS_HINTS     *pHints,
  [out] IVdsAsync     **ppAsync
);

Parameter

[in] type

Ein VDS_LUN_TYPE Enumerationswert, der den LUN-Typ angibt. Die neue LUN kann ein automagischer Typ oder ein bestimmter RAID-Typ sein, aber nicht beides. Wenn der Aufrufer einen automagischen Typ angibt, sollten mindestens ein automagic-Hinweis im pHints-Parameter angegeben werden.

Der Schnittstellenzeiger für das neue LUN-Objekt kann durch Aufrufen der IVdsAsync::Wait-Methode für den im ppAsync-Parameter zurückgegebenen Schnittstellenzeiger abgerufen werden. Die vonWait zurückgegebene VDS_ASYNC_OUTPUT-Struktur enthält den LUN-Objektschnittstellenzeiger im cl.pLunUnk-Element .

[in] ullSizeInBytes

Die Größe der neuen LUN in Bytes. Der Anbieter kann die Größe auf- oder herunterrunden, um Ausrichtungsanforderungen oder andere Einschränkungen zu erfüllen. (In den meisten Fällen rundet der Anbieter auf und stellt sicher, dass die LUN mit seltenen Ausnahmen mindestens so groß wie angefordert ist.)

Nachdem die LUN erstellt wurde, kann der Aufrufer die tatsächliche Größe der LUN durch Aufrufen der IVdsLun::GetProperties-Methode ermitteln.

[in] pDriveIdArray

Ein Zeiger auf ein Array, das eine VDS_OBJECT_ID für jedes der Laufwerke enthält, die zum Erstellen der LUN verwendet werden sollen. Durch Angabe eines Werts ungleich NULL für diesen Parameter fordert der Aufrufer an, dass der Anbieter alle Laufwerke in der angegebenen Reihenfolge verwendet, wobei alle Blöcke auf einem Laufwerk verwendet werden, bevor er zum nächsten wechselt, und beendet, wenn die LUN die angeforderte Größe erreicht hat.

Alternativ kann der Aufrufer den Anbieter anweisen, die Laufwerke automatisch auszuwählen, indem er NULL in diesem Parameter und 0 in lNumberOfDrives übergibt. (Übergeben Sie NULL nur, wenn lNumberOfDrives 0 ist.)

Wenn der Type-Parameter einen automagischen Typ angibt, sollte dieser Parameter NULL sein.

[in] lNumberOfDrives

Die Anzahl der in pDriveIdArray angegebenen Laufwerke. Wenn der Aufrufer 0 übergibt, wählt der Anbieter die Laufwerke aus.

Wenn der Type-Parameter einen automagischen Typ angibt, sollte dieser Parameter 0 sein.

Nachdem die LUN erstellt wurde, kann der Aufrufer ermitteln, welche Laufwerke verwendet werden, indem er die IVdsLunPlex::QueryExtents-Methode aufruft .

[in] pwszUnmaskingList

Eine Liste, die die Computer angibt, denen Zugriff auf die LUN gewährt werden soll. Die Liste ist eine durch Semikolons getrennte, NULL-endende, für Menschen lesbare Zeichenfolge.

Wenn der Wert "" ist, muss allen Computern, die über einen HBA-Port verfügen, der an das Speichersubsystem angefügt ist, Zugriff auf die LUN gewährt werden. Wenn der Wert "" ist, soll keinem Computer Zugriff auf die LUN gewährt werden.

Hinweis Wenn der Wert "" lautet, gewähren die meisten Hardwareanbieter in der Praxis nur den Ports und Initiatoren auf dem lokalen Computer Zugriff auf die LUN.

Wenn "*" oder "" angegeben ist, kann kein anderer Wert angegeben werden.

Bei Fibre Channel-Netzwerken und serial angefügten SCSI-Netzwerken (SAS) ist jeder Eintrag ein 64-Bit World Wide Name (WWN) jedes Ports, an den die LUN entmasket ist, formatiert als hexadezimale Zeichenfolge (16 Zeichen lang), wobei zuerst das wichtigste Byte vorhanden ist. Beispielsweise wird eine WWN-Adresse von 01:23:45:67:89:AB:CD:EF als "0123456789ABCDEF" dargestellt. Weitere Informationen finden Sie in den T10-Spezifikationen für Fibre Channel und SAS.

Bei iSCSI-Netzwerken ist jeder Eintrag ein iSCSI-qualifizierter Name (IQN) jedes Initiators, für den die LUN entmasket ist. Eine LUN, die einem bestimmten Initiator entlarvt wurde, gilt als mit diesem Initiator verknüpft.

Hinweis Die Entlarmungsliste kann mehrmals denselben WWN oder IQN enthalten. Es wird nicht erwartet, dass der Aufrufer Duplikate aus der Liste entfernt oder das Format des WWN oder IQN überprüft.

Nachdem die LUN erstellt wurde, kann der Aufrufer die tatsächliche Aufhebungsliste ermitteln, indem er die IVdsLun::GetProperties-Methode aufruft .

[in] pHints

Zeiger auf eine VDS_HINTS-Struktur , die die Hinweise angibt, die beim Erstellen der LUN verwendet werden sollen. Der Anbieter muss die Hinweise nicht auf die LUN anwenden. Die in der VDS_HINTS-Struktur angegebenen Hinweise sind nur eine Anforderung an den Anbieter.

Nachdem die LUN erstellt wurde, kann der Aufrufer die Vom Anbieter angewendeten Hinweise ermitteln, indem er entweder die IVdsLun::QueryHints-Methode oder die IVdsLunPlex::QueryHints-Methode aufruft .

Wenn der Type-Parameter einen nicht automagischen Typ angibt, sollte dieser Parameter NULL sein.

[out] ppAsync

Die Adresse eines IVdsAsync-Schnittstellenzeigers , der von VDS bei der Rückgabe initialisiert wird. Aufrufer müssen die Schnittstelle freigeben. Verwenden Sie diese Schnittstelle, um die status des Vorgangs abzubrechen, abzuwarten oder abzufragen.

Wenn IVdsAsync::Wait für den zurückgegebenen Schnittstellenzeiger aufgerufen wird und ein erfolgreicher HRESULT-Wert zurückgegeben wird, müssen die in der VDS_ASYNC_OUTPUT-Struktur zurückgegebenen Schnittstellen durch Aufrufen der IUnknown::Release-Methode für jeden Schnittstellenzeiger freigegeben werden. Wenn Wait jedoch einen HRESULT-Fehlerwert zurückgibt oder der pHrResult-Parameter von Wait einen HRESULT-Fehlerwert empfängt, sind die Schnittstellenzeiger in der VDS_ASYNC_OUTPUT-StrukturNULL und müssen nicht freigegeben werden. Sie können HRESULT-Werte für Erfolg oder Fehler testen, indem Sie die in Winerror.h definierten Makros SUCCEEDED und FAILED verwenden.

Rückgabewert

Diese Methode kann HRESULT-Standardwerte wie E_INVALIDARG oder E_OUTOFMEMORY und VDS-spezifische Rückgabewerte zurückgeben. Es kann auch konvertierte Systemfehlercodes mithilfe des makros HRESULT_FROM_WIN32 zurückgeben. Fehler können vom VDS selbst oder vom zugrunde liegenden VDS-Anbieter stammen, der verwendet wird. Folgende Rückgabewerte sind möglich.

Rückgabecode/-wert	BESCHREIBUNG
VDS_E_PROVIDER_CACHE_CORRUPT 0x8004241FL	Dieser Rückgabewert signalisiert ein Software- oder Kommunikationsproblem innerhalb eines Anbieters, der Informationen über das Array zwischenspeichert. Verwenden Sie die IVdsHwProvider::Reenumerate-Methode gefolgt von der IVdsHwProvider::Refresh-Methode , um den Cache wiederherzustellen.
VDS_E_OBJECT_DELETED 0x8004240BL	Das Subsystemobjekt ist nicht mehr vorhanden.
VDS_E_OBJECT_STATUS_FAILED 0x80042431L	Das Subsystem weist einen Fehlerstatus auf und kann den angeforderten Vorgang nicht ausführen.
VDS_E_ANOTHER_CALL_IN_PROGRESS 0x80042404L	Ein weiterer Vorgang wird ausgeführt; Dieser Vorgang kann erst fortgesetzt werden, wenn der vorherige Vorgang abgeschlossen ist.
VDS_E_OBJECT_NOT_FOUND 0x80042405L	Kann von jeder Methode zurückgegeben werden, die eine VDS_OBJECT_ID Konstante akzeptiert. Dieser Rückgabewert gibt an, dass der Bezeichner nicht auf ein vorhandenes Objekt verweist.
VDS_E_NOT_SUPPORTED 0x80042400L	Dieser Vorgang oder eine Kombination von Parametern wird von diesem Anbieter nicht unterstützt.
VDS_E_NOT_ENOUGH_SPACE 0x8004240FL	Für diesen Vorgang ist nicht genügend nutzbarer Speicherplatz vorhanden.
VDS_E_NOT_ENOUGH_DRIVE 0x80042410L	Es sind zu wenige freie Laufwerke im Subsystem vorhanden, um diesen Vorgang abzuschließen.

Hinweise

Durch Auswahl geeigneter Werte für die Parameter type und pHints kann der Aufrufer die Attribute der LUN vollständig, teilweise oder minimal angeben. Der Anbieter kann automatisch nicht angegebene Attribute einschließen, basierend auf den automagischen Hinweisen, die in der VDS_HINTS-Struktur angegeben sind, auf die der pHints-Parameter verweist.

Wenn der VDS-Anbieter nur einfache Zielkonfigurationen unterstützt, sollte das Subsystem das neu erstellte LUN-Objekt automatisch einem iSCSI-Zielobjekt zuordnen. Sehen Sie sich den VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG Wert der VDS_SUB_SYSTEM_FLAG-Enumeration an.

Die Liste der WWNs und IQNs im parameter pwszUnmaskingList kann doppelte Namen enthalten. Es liegt in der Verantwortung des Anbieters, alle Namen in der Liste zu überprüfen und bei Bedarf Duplikate zu entfernen.

Der Hardwareanbieter ist dafür verantwortlich, die Partitionsinformationen der LUN zu entfernen, damit die LUN wiederverwendet werden kann. Wenn es sich bei der LUN um einen MBR-Datenträger handelt, wird dies erreicht, indem Nullen auf die ersten und letzten 1 MB des Datenträgers geschrieben werden. Bei einem GPT-Datenträger müssen Nullen auf die ersten und letzten 16 KB des Datenträgers geschrieben werden.

Es gibt einen geringfügigen Unterschied zwischen den E_INVALIDARG und VDS_E_NOT_SUPPORTED Rückgabewerten. Von Anbietern wird nicht erwartet, dass sie jedes Feature implementieren, das die VDS-API einem Client präsentieren kann. Die CreateLun-Methode macht beispielsweise die Möglichkeit verfügbar, viele verschiedene Arten von LUNs zu erstellen (z. B. einfache, Spiegel, Gestreifte und Parität). Anbieter müssen jedoch nicht alle Arten von LUNs unterstützen. Wenn der Aufrufer einen Wert für den Typparameter angibt, der kein gültiger VDS_LUN_TYPE Enumerationswert ist, sollte der Anbieter E_INVALIDARG zurückgeben. Wenn der Aufrufer einen gültigen Typwert angibt, den der Anbieter nicht unterstützt, sollte der Anbieter VDS_E_NOT_SUPPORTED zurückgeben.

Hinweise für Implementierer: Der Anbieter muss einen IVdsAsync-Schnittstellenzeiger im ppAsync-Parameter zurückgeben, auch wenn der Aufruf dieser Methode keinen asynchronen Vorgang initiiert.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	vds.h
Bibliothek	Uuid.lib