IVdsSubSystem::CreateLun-Methode (vdshwprv.h)
[Ab Windows 8 und Windows Server 2012 wird die COM-Schnittstelle des Virtuellen Datenträgerdiensts von der 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.
Wenn "*" oder "" angegeben ist, kann kein anderer Wert angegeben werden.
Für Fibre Channel-Netzwerke und sas-Netzwerke (Serial Attached SCSI) 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 das wichtigste Byte zuerst 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.
[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 den Status des Vorgangs abzubrechen, darauf zu warten oder den Status des Vorgangs 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 |
|---|---|
|
Dieser Rückgabewert signalisiert ein Software- oder Kommunikationsproblem innerhalb eines Anbieters, der Informationen zum Array zwischenspeichert. Verwenden Sie die IVdsHwProvider::Reenumerate-Methode gefolgt von der IVdsHwProvider::Refresh-Methode , um den Cache wiederherzustellen. |
|
Das Subsystemobjekt ist nicht mehr vorhanden. |
|
Das Subsystem weist einen Fehlerstatus auf und kann den angeforderten Vorgang nicht ausführen. |
|
Ein weiterer Vorgang wird ausgeführt; Dieser Vorgang kann erst fortgesetzt werden, wenn der vorherige Vorgang abgeschlossen ist. |
|
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. |
|
Dieser Vorgang oder eine Kombination von Parametern wird von diesem Anbieter nicht unterstützt. |
|
Für diesen Vorgang ist nicht genügend nutzbarer Speicherplatz vorhanden. |
|
Es sind zu wenige freie Laufwerke im Subsystem vorhanden, um diesen Vorgang abzuschließen. |
Bemerkungen
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 basierend auf den automagischen Hinweisen, die in der VDS_HINTS-Struktur angegeben sind, auf die der pHints-Parameter verweist, automatisch nicht angegebene Attribute einschließen.
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. einfach, spiegelungsfähig, gestreift und paritätisch). 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
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | vdshwprv.h |
| Bibliothek | Uuid.lib |