Metodo IVdsSubSystem::CreateLun (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.]

Il metodo CreateLun crea un numero di unità logica (LUN).

Sintassi

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

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, è necessario specificare uno o più hint automagic nel parametro pHints .

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

[in] ullSizeInBytes

Dimensione, in byte, del nuovo LUN. Il provider può arrotondare le dimensioni verso l'alto o verso il basso per soddisfare i requisiti di allineamento o altre restrizioni. Nella maggior parte dei casi, il provider arrotonda, assicurandosi che, con eccezioni rare, il LUN sia almeno grande quanto 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 che contiene 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, utilizzando tutti gli extent in un'unità prima di passare alla successiva e interrompendo quando il LUN ha raggiunto le dimensioni richieste.

In alternativa, il chiamante può indirizzare il provider a selezionare automaticamente le unità passando NULL in questo parametro e 0 in lNumberOfDrives. Passa 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 a cui concedere l'accesso al LUN. L'elenco è una stringa leggibile con terminazione NULL delimitata da punto e virgola.

Se il valore è "", a tutti i computer con una porta HBA collegata al sottosistema di archiviazione verrà concesso l'accesso al LUN. Se il valore è "", nessun computer deve avere 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 l'accesso al LUN.

Se si specifica "*" o "", non è possibile specificare alcun altro valore.

Per le reti Fibre Channel e le reti SCSI (SAS) collegate serialmente, ogni voce è un nome a livello globale (WWN) a 64 bit di ogni porta in cui il LUN non viene mascherato, formattato come stringa esadecimale (16 caratteri long), byte più significativo per primo. Ad esempio, un indirizzo WWN di 01:23:45:67:89:AB:CD:EF è 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 non viene mascherato. Un LUN non mascherato a un particolare iniziatore viene considerato associato a tale iniziatore.

Nota L'elenco di annullamento del mascheramento può contenere più volte lo stesso WWN o IQN. Il chiamante non dovrebbe 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 annullamento del mascheramento effettivo chiamando il metodo IVdsLun::GetProperties .

[in] pHints

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

Dopo aver creato il LUN, il chiamante può determinare gli hint applicati dal provider chiamando il metodo IVdsLun::QueryHints o il metodo IVdsLunPlex::QueryHints .

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

[out] ppAsync

Indirizzo di un puntatore all'interfaccia IVdsAsync , che il VDS inizializza al momento della restituzione. I chiamanti devono rilasciare l'interfaccia. Usare questa interfaccia per annullare, attendere o eseguire una query sullo stato dell'operazione.

Se viene chiamato IVdsAsync::Wait sul puntatore di 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 su ogni puntatore di interfaccia. Tuttavia, se Wait restituisce un valore HRESULT non riuscito o se il parametro pHrResult di Wait riceve un valore HRESULT non riuscito, i puntatori di interfaccia nella struttura VDS_ASYNC_OUTPUT sono NULL e non devono essere rilasciati. È possibile verificare l'esito positivo o negativo dei valori HRESULT usando le macro SUCCEEDED 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 provenire dal VDS stesso o dal provider VDS sottostante in uso. I valori restituiti possibili includono quanto segue.

Codice/valore restituito	Descrizione
VDS_E_PROVIDER_CACHE_CORRUPT 0x8004241FL	Questo valore restituito segnala 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 di errore 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	Può essere restituito da qualsiasi metodo che accetta una costante VDS_OBJECT_ID . Questo valore restituito indica che l'identificatore non fa riferimento a un oggetto esistente.
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	Nel sottosistema sono presenti troppe unità gratuite per completare questa operazione.

Commenti

Scegliendo i valori appropriati per i parametri type e pHints , 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_HINTS a cui punta il parametro pHints .

Se il provider VDS supporta solo configurazioni di destinazione semplici, il sottosistema deve associare automaticamente l'oggetto LUN appena creato a un oggetto di destinazione iSCSI. Vedere il valore VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG dell'enumerazione VDS_SUB_SYSTEM_FLAG .

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.

Il provider hardware è responsabile della rimozione delle informazioni sulla partizione del LUN in modo che il LUN possa essere riutilizzato. Se il LUN è un disco MBR, questa operazione viene eseguita scrivendo zeri nel primo e negli ultimi 1 MB del disco. Per un disco GPT, gli zeri devono essere scritti nel primo e negli ultimi 16 KB del disco.

Esiste una differenza sottile tra i valori restituiti E_INVALIDARG e VDS_E_NOT_SUPPORTED . Non è previsto che i provider implementino tutte le funzionalità che l'API VDS può presentare a un client. Ad esempio, il metodo CreateLun espone la possibilità di creare molti tipi diversi di LUN, ad esempio semplici, mirror, con striping 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 che non è un valore di enumerazione VDS_LUN_TYPE valido, 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.

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

Requisiti

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