Metodo IVdsSubSystem2::CreateLun2 (vds.h)

Articolo
03/03/2024

[A partire da Windows 8 e Windows Server 2012, l'interfaccia COM del servizio disco virtuale viene sostituita dall'API gestione archiviazione di Windows.

Crea un LUN. Questo metodo è identico al metodo IVdsSubSystem::CreateLun , ad eccezione del fatto che gli hint automagic vengono forniti usando una struttura VDS_HINTS2 anziché una struttura VDS_HINTS .

Sintassi

HRESULT CreateLun2(
  [in]  VDS_LUN_TYPE  type,
  [in]  ULONGLONG     ullSizeInBytes,
  [in]  VDS_OBJECT_ID *pDriveIdArray,
  [in]  LONG          lNumberOfDrives,
  [in]  LPWSTR        pwszUnmaskingList,
  [in]  VDS_HINTS2    *pHints2,
  [out] IVdsAsync     **ppAsync
);

Parametri

[in] type

Valore di enumerazione VDS_LUN_TYPE che specifica il tipo LUN. Il nuovo LUN può essere un tipo automagic o un tipo RAID specifico, ma non entrambi. Se il chiamante specifica un tipo automagic, uno o più hint automagic devono essere specificati nel parametro pHints .

Il puntatore dell'interfaccia per il nuovo oggetto LUN può essere recuperato chiamando il metodo IVdsAsync::Wait sul puntatore dell'interfaccia restituito nel parametro ppAsync . La struttura VDS_ASYNC_OUTPUT restituita da Wait contiene il puntatore dell'interfaccia dell'oggetto LUN nel membro cl.pLunUnk .

[in] ullSizeInBytes

Dimensioni, in byte, del nuovo LUN. Il provider può arrotondare le dimensioni fino o giù per soddisfare i requisiti di allineamento o altre restrizioni. Nella maggior parte dei casi, il provider esegue il round up, assicurandosi che, con eccezioni rare, il LUN sia almeno di grandi dimensioni richiesto.

Dopo aver creato il LUN, il chiamante può determinare le dimensioni effettive del LUN chiamando il metodo IVdsLun::GetProperties .

[in] pDriveIdArray

Puntatore a una matrice contenente un VDS_OBJECT_ID per ognuna delle unità da usare per creare il LUN. Specificando un valore non NULL per questo parametro, il chiamante richiede che il provider usi tutte le unità, nell'ordine specificato, usando tutti gli extent in un'unità prima di passare alla successiva e arrestarsi quando il LUN ha raggiunto le dimensioni richieste.

In alternativa, il chiamante può indirizzare il provider per selezionare automaticamente le unità passando NULL in questo parametro e 0 in lNumberOfDrives. Passare NULL se e solo se lNumberOfDrives è 0.)

Se il parametro di tipo specifica un tipo automagic, questo parametro deve essere NULL.

[in] lNumberOfDrives

Numero di unità specificate in pDriveIdArray. Se il chiamante passa 0, il provider seleziona le unità.

Se il parametro di tipo specifica un tipo automagic, questo parametro deve essere 0.

Dopo aver creato il LUN, il chiamante può determinare quali unità sono in uso chiamando il metodo IVdsLunPlex::QueryExtents .

[in] pwszUnmaskingList

Elenco che specifica i computer da concedere all'accesso al LUN. L'elenco è una stringa delimitata da punto e virgola, con terminazione NULL, leggibile.

Se il valore è "", tutti i computer con una porta HBA collegata al sottosistema di archiviazione devono essere concessi l'accesso al LUN. Se il valore è "", nessun computer deve essere concesso l'accesso al LUN.

Nota In pratica, se il valore è "", la maggior parte dei provider hardware concede solo le porte e gli iniziatori nel computer locale accesso al LUN.

Se viene specificato "*" o "", non è possibile specificare alcun altro valore.

Per le reti Fibre Channel e le reti SCSI associate seriali (SAS), ogni voce è un nome world-wide (WWN) a 64 bit di ogni porta a cui il LUN è smascherato, formattato come stringa esadecimale (16 caratteri long), primo byte significativo. Ad esempio, un indirizzo WWN di 01:23:45:67:89:AB:CD:EF viene rappresentato come "0123456789ABCDEF". Per altre informazioni, vedere le specifiche T10 per Fibre Channel e SAS.

Per le reti iSCSI, ogni voce è un nome qualificato iSCSI (IQN) di ogni iniziatore a cui il LUN è senza maschera. Un LUN non mascherato a un particolare iniziatore viene considerato associato a tale iniziatore.

Nota L'elenco di annullamento del mascheramento può contenere la stessa WWN o IQN più di una volta. Il chiamante non è previsto rimuovere duplicati dall'elenco o per convalidare il formato della WWN o dell'IQN.

Dopo aver creato il LUN, il chiamante può determinare l'elenco di smascheramento effettivo chiamando il metodo IVdsLun::GetProperties .

[in] pHints2

Puntatore a una struttura VDS_HINTS2 che specifica gli hint da usare nella creazione del LUN. Il provider non è necessario per applicare gli hint al LUN. Gli hint specificati nella struttura VDS_HINTS2 sono solo una richiesta al provider.

Dopo aver creato il LUN, il chiamante può determinare gli hint applicati dal provider chiamando il metodo IVdsLun2::QueryHints2 .

Se il parametro di tipo specifica un tipo non automagic, questo parametro deve essere NULL.

[out] ppAsync

Indirizzo di un puntatore dell'interfaccia IVdsAsync , che il VDS inizializza sul ritorno. I chiamanti devono rilasciare l'interfaccia. Usare questa interfaccia per annullare, attendere o eseguire query sullo stato dell'operazione.

Se viene chiamato IVdsAsync::Wait sul puntatore dell'interfaccia restituito e viene restituito un valore HRESULT riuscito, le interfacce restituite nella struttura VDS_ASYNC_OUTPUT devono essere rilasciate chiamando il metodo IUnknown::Release in ogni puntatore dell'interfaccia. Tuttavia, se Wait restituisce un valore HRESULT non riuscito o se il parametro pHrResultdiWait riceve un valore HRESULT non riuscito, i puntatori di interfaccia nella struttura VDS_ASYNC_OUTPUT sono NULL e non devono essere rilasciati. È possibile testare i valori HRESULT di esito positivo o negativo usando le macro SUCCESSED e FAILED definite in Winerror.h.

Valore restituito

Questo metodo può restituire valori HRESULT standard, ad esempio E_INVALIDARG o E_OUTOFMEMORY e valori restituiti specifici di VDS. Può anche restituire codici di errore di sistema convertiti usando la macro HRESULT_FROM_WIN32 . Gli errori possono derivare da VDS stesso o dal provider VDS sottostante usato. I valori restituiti possibili includono quanto segue.

Codice/valore restituito	Descrizione
VDS_E_PROVIDER_CACHE_CORRUPT 0x8004241FL	Si verifica un problema di comunicazione o software all'interno di un provider che memorizza nella cache le informazioni sulla matrice. Usare il metodo IVdsHwProvider::Reenumerate seguito dal metodo IVdsHwProvider ::Refresh per ripristinare la cache.
VDS_E_OBJECT_DELETED 0x8004240BL	L'oggetto sottosistema non è più presente.
VDS_E_OBJECT_STATUS_FAILED 0x80042431L	Il sottosistema si trova in uno stato non riuscito e non è in grado di eseguire l'operazione richiesta.
VDS_E_ANOTHER_CALL_IN_PROGRESS 0x80042404L	Un'altra operazione è in corso; questa operazione non può continuare fino al completamento dell'operazione o delle operazioni precedenti.
VDS_E_OBJECT_NOT_FOUND 0x80042405L	L'identificatore non fa riferimento a un oggetto esistente. Questo valore può essere restituito da qualsiasi metodo che accetta una costante VDS_OBJECT_ID .
VDS_E_NOT_SUPPORTED 0x80042400L	Questa operazione o combinazione di parametri non è supportata da questo provider.
VDS_E_NOT_ENOUGH_SPACE 0x8004240FL	Non è disponibile spazio utilizzabile sufficiente per questa operazione.
VDS_E_NOT_ENOUGH_DRIVE 0x80042410L	Troppo poche unità gratuite sono presenti nel sottosistema per completare questa operazione.

Commenti

Scegliendo i valori appropriati per i parametri di tipo e pHints2 , il chiamante può specificare gli attributi del LUN completamente, parzialmente o minimamente. Il provider può includere automaticamente attributi non specificati, in base agli hint automagic specificati nella struttura VDS_HINTS2 a cui punta il parametro pHints .

Note per gli implementatori: Il provider deve restituire un puntatore dell'interfaccia IVdsAsync nel parametro ppAsync , anche se la chiamata a questo metodo non avvia un'operazione asincrona.

L'elenco di WWN e IQN nel parametro pwszUnmaskingList può contenere nomi duplicati. È responsabilità del provider convalidare tutti i nomi nell'elenco e rimuovere duplicati se necessario.

In risposta al metodo CreateLun2 e prima di rimuovere il nuovo LUN in qualsiasi host, il provider deve riempire il primo e l'ultimo megabyte con zero, lasciando il LUN non inizializzato.

Esiste una differenza sottile tra i valori restituiti E_INVALIDARG e VDS_E_NOT_SUPPORTED . I provider non devono implementare tutte le funzionalità che l'API VDS può presentare a un client. Ad esempio, il metodo CreateLun2 espone la possibilità di creare molti tipi diversi di LUN(ad esempio, semplice, mirror, striped e parità). Tuttavia, i provider non sono necessari per supportare tutti i tipi di LUN. Se il chiamante specifica un valore per il parametro di tipo non valido VDS_LUN_TYPE valore di enumerazione, il provider deve restituire E_INVALIDARG. Se il chiamante specifica un valore di tipo valido che il provider non supporta, il provider deve restituire VDS_E_NOT_SUPPORTED.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	vds.h
Libreria	Uuid.lib