Metode IVdsSubSystem::CreateLun (vdshwprv.h)

Artikel
08/03/2023

[Dimulai dengan Windows 8 dan Windows Server 2012, antarmuka COM Layanan Disk Virtual digantikan oleh WINDOWS Storage Management API.]

Metode CreateLun membuat nomor unit logis (LUN).

Sintaks

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

Nilai enumerasi VDS_LUN_TYPE yang menentukan jenis LUN. LUN baru dapat menjadi jenis automagic atau jenis RAID tertentu, tetapi tidak keduanya. Jika penelepon menentukan jenis automagic, satu atau beberapa petunjuk otomatis harus ditentukan dalam parameter pHints .

Penunjuk antarmuka untuk objek LUN baru dapat diambil dengan memanggil metode IVdsAsync::Wait pada pointer antarmuka yang dikembalikan dalam parameter ppAsync . Struktur VDS_ASYNC_OUTPUT yang dikembalikan oleh Wait berisi penunjuk antarmuka objek LUN di anggota cl.pLunUnk .

[in] ullSizeInBytes

Ukuran, dalam byte, dari LUN baru. Penyedia dapat membulatkan ukuran ke atas atau ke bawah untuk memenuhi persyaratan penyelarasan atau pembatasan lainnya. (Dalam kebanyakan kasus, penyedia membulatkan ke atas, memastikan bahwa, dengan pengecualian langka, LUN setidaknya sebesar yang diminta.)

Setelah LUN dibuat, pemanggil dapat menentukan ukuran LUN yang sebenarnya dengan memanggil metode IVdsLun::GetProperties .

[in] pDriveIdArray

Penunjuk ke array yang berisi VDS_OBJECT_ID untuk setiap drive yang akan digunakan untuk membuat LUN. Dengan menentukan nilai non-NULL untuk parameter ini, pemanggil meminta agar penyedia menggunakan semua drive, dalam urutan yang disediakan, menggunakan semua jangkauan pada satu drive sebelum melanjutkan ke drive berikutnya, dan berhenti ketika LUN telah mencapai ukuran yang diminta.

Atau, penelepon dapat mengarahkan penyedia untuk memilih drive secara otomatis dengan melewati NULL dalam parameter ini dan 0 di lNumberOfDrives. (Teruskan NULL jika dan hanya jika lNumberOfDrives adalah 0.)

Jika parameter jenis menentukan jenis automagic, parameter ini harus NULL.

[in] lNumberOfDrives

Jumlah drive yang ditentukan dalam pDriveIdArray. Jika penelepon melewati 0, penyedia akan memilih drive.

Jika parameter jenis menentukan jenis automagic, parameter ini harus 0.

Setelah LUN dibuat, pemanggil dapat menentukan drive mana yang digunakan dengan memanggil metode IVdsLunPlex::QueryExtents .

[in] pwszUnmaskingList

Daftar yang menentukan komputer yang akan diberikan akses LUN. Daftar ini adalah string yang dibatasi titik koma, dihentikan NULL, dan dapat dibaca manusia.

Jika nilainya adalah "", semua komputer yang memiliki port HBA yang terpasang pada subsistem penyimpanan akan diberikan akses ke LUN. Jika nilainya adalah "", tidak ada komputer yang akan diberikan akses ke LUN.

Catatan Dalam praktiknya, jika nilainya adalah "", sebagian besar penyedia perangkat keras hanya memberikan port dan inisiator pada akses komputer lokal ke LUN.

Jika "*" atau "" ditentukan, tidak ada nilai lain yang dapat ditentukan.

Untuk jaringan Fibre Channel dan jaringan SCSI (SAS) yang terpasang serial, setiap entri adalah World-Wide Name (WWN) 64-bit dari setiap port tempat LUN dibuka kedoknya, diformat sebagai string heksadesimal (panjang 16 karakter), byte paling signifikan terlebih dahulu. Misalnya, alamat WWN 01:23:45:67:89:AB:CD:EF diwakili sebagai "0123456789ABCDEF". Untuk informasi selengkapnya, lihat spesifikasi T10 untuk Fibre Channel dan SAS.

Untuk jaringan iSCSI, setiap entri adalah nama yang memenuhi syarat iSCSI (IQN) dari setiap inisiator tempat LUN dibongkar. LUN yang tidak dimasuki ke inisiator tertentu dianggap terkait dengan inisiator tersebut.

Catatan Daftar membuka kemasan dapat berisi WWN atau IQN yang sama lebih dari sekali. Pemanggil tidak diharapkan untuk menghapus duplikat dari daftar atau untuk memvalidasi format WWN atau IQN.

Setelah LUN dibuat, pemanggil dapat menentukan daftar membuka kemasan aktual dengan memanggil metode IVdsLun::GetProperties .

[in] pHints

Penunjuk ke struktur VDS_HINTS yang menentukan petunjuk yang akan digunakan dalam membuat LUN. Penyedia tidak diperlukan untuk menerapkan petunjuk ke LUN. Petunjuk yang ditentukan dalam struktur VDS_HINTS hanya permintaan ke penyedia.

Setelah LUN dibuat, pemanggil dapat menentukan petunjuk yang diterapkan penyedia dengan memanggil metode IVdsLun::QueryHints atau metode IVdsLunPlex::QueryHints .

Jika parameter jenis menentukan jenis non-otomatis, parameter ini harus NULL.

[out] ppAsync

Alamat penunjuk antarmuka IVdsAsync , yang diinisialisasi VDS saat dikembalikan. Penelepon harus merilis antarmuka. Gunakan antarmuka ini untuk membatalkan, menunggu, atau mengkueri status operasi.

Jika IVdsAsync::Wait dipanggil pada penunjuk antarmuka yang dikembalikan dan nilai HRESULT yang berhasil dikembalikan, antarmuka yang dikembalikan dalam struktur VDS_ASYNC_OUTPUT harus dirilis dengan memanggil metode IUnknown::Release pada setiap pointer antarmuka. Namun, jika Wait mengembalikan nilai HRESULT kegagalan, atau jika parameter pHrResultWait menerima nilai HRESULT kegagalan, penunjuk antarmuka dalam struktur VDS_ASYNC_OUTPUT adalah NULL dan tidak perlu dirilis. Anda dapat menguji keberhasilan atau kegagalan nilai HRESULT dengan menggunakan makro BERHASIL dan GAGAL yang ditentukan dalam Winerror.h.

Nilai kembali

Metode ini dapat mengembalikan nilai HRESULT standar, seperti E_INVALIDARG atau E_OUTOFMEMORY, dan nilai pengembalian khusus VDS. Ini juga dapat mengembalikan kode kesalahan sistem yang dikonversi menggunakan makro HRESULT_FROM_WIN32 . Kesalahan dapat berasal dari VDS itu sendiri atau dari penyedia VDS yang mendasar yang sedang digunakan. Kemungkinan nilai yang dikembalikan termasuk yang berikut ini.

Mengembalikan kode/nilai	Deskripsi
VDS_E_PROVIDER_CACHE_CORRUPT 0x8004241FL	Nilai pengembalian ini menandakan perangkat lunak atau masalah komunikasi di dalam penyedia yang menyimpan informasi tentang array. Gunakan metode IVdsHwProvider::Reenumerate diikuti dengan metode IVdsHwProvider::Refresh untuk memulihkan cache.
VDS_E_OBJECT_DELETED 0x8004240BL	Objek subsistem tidak ada lagi.
VDS_E_OBJECT_STATUS_FAILED 0x80042431L	Subsistem dalam status gagal dan tidak dapat melakukan operasi yang diminta.
VDS_E_ANOTHER_CALL_IN_PROGRESS 0x80042404L	Operasi lain sedang berlangsung; operasi ini tidak dapat dilanjutkan sampai operasi atau operasi sebelumnya selesai.
VDS_E_OBJECT_NOT_FOUND 0x80042405L	Dapat dikembalikan dari metode apa pun yang mengambil konstanta VDS_OBJECT_ID . Nilai pengembalian ini menunjukkan bahwa pengidentifikasi tidak merujuk ke objek yang ada.
VDS_E_NOT_SUPPORTED 0x80042400L	Operasi atau kombinasi parameter ini tidak didukung oleh penyedia ini.
VDS_E_NOT_ENOUGH_SPACE 0x8004240FL	Tidak cukup ruang yang dapat digunakan untuk operasi ini.
VDS_E_NOT_ENOUGH_DRIVE 0x80042410L	Terlalu sedikit drive gratis yang ada di subsistem untuk menyelesaikan operasi ini.

Keterangan

Dengan memilih nilai yang sesuai untuk parameter jenis dan pHints , pemanggil dapat menentukan atribut LUN sepenuhnya, sebagian, atau minimal. Penyedia dapat secara otomatis menyertakan atribut yang tidak ditentukan, berdasarkan petunjuk otomatis yang ditentukan dalam struktur VDS_HINTS yang dituju parameter pHints .

Jika penyedia VDS hanya mendukung konfigurasi target sederhana, subsistem harus secara otomatis mengaitkan objek LUN yang baru dibuat dengan objek target iSCSI. Lihat nilai VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG enumerasi VDS_SUB_SYSTEM_FLAG .

Daftar WWN dan IQN dalam parameter pwszUnmaskingList mungkin berisi nama duplikat. Penyedia bertanggung jawab untuk memvalidasi semua nama dalam daftar dan menghapus duplikat jika perlu.

Penyedia perangkat keras bertanggung jawab untuk menghapus informasi partisi LUN sehingga LUN dapat digunakan kembali. Jika LUN adalah disk MBR, ini dicapai dengan menulis nol ke 1 MB pertama dan terakhir disk. Untuk disk GPT, nol harus ditulis ke disk pertama dan terakhir 16 KB.

Ada perbedaan halang antara nilai E_INVALIDARG dan pengembalian VDS_E_NOT_SUPPORTED . Penyedia tidak diharapkan untuk mengimplementasikan setiap fitur yang dapat disajikan API VDS kepada klien. Misalnya, metode CreateLun memaparkan kemampuan untuk membuat berbagai jenis LUN (misalnya, sederhana, cermin, bergaris, dan paritas). Namun, penyedia tidak diharuskan untuk mendukung semua jenis LUN. Jika penelepon menentukan nilai untuk parameter jenis yang bukan nilai enumerasi VDS_LUN_TYPE yang valid, penyedia harus mengembalikan E_INVALIDARG. Jika penelepon menentukan nilai jenis valid yang tidak didukung penyedia, penyedia harus mengembalikan VDS_E_NOT_SUPPORTED.

Catatan untuk pelaksana: Penyedia harus mengembalikan penunjuk antarmuka IVdsAsync dalam parameter ppAsync , bahkan jika panggilan ke metode ini tidak memulai operasi asinkron.

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	vdshwprv.h
Pustaka	Uuid.lib