IVdsSubSystem2
COM公式ドキュメント
IVdsSubSystem2 インターフェースは、VDS_HINTS2 および VDS_SUB_SYSTEM_PROP2 構造体を使用して、サブシステムに対するクエリおよび構成操作を実行するためのメソッドを提供します。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
VdsSubSystem2::GetProperties2 (vdshwprv.h) メソッドは、サブシステムのプロパティを返します。
| pSubSystemProp2 | VDS_SUB_SYSTEM_PROP2* | out | 呼び出し元が割り当てて渡す VDS_SUB_SYSTEM_PROP2 構造体のアドレス。VDS は pwszFriendlyName および pwszIdentification メンバー文字列のメモリを割り当てます。 呼び出し元は、 CoTaskMemFree 関数を使用してこれらの文字列を解放する必要があります。 |
戻り値
このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値 を返すことができます。また、HRESULT_FROM_WIN32 マクロを使用して変換された システムエラーコード を返す場合もあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダー から発生する可能性があります。戻り値としては次のものが考えられます。
| リターンコード/値 | 説明 |
|---|---|
|
一部のプロパティは正常に取得されましたが、すべてではありません。デバイスの取り外しなど、すべてのプロパティの取得に失敗する原因は数多くあることに注意してください。 |
|
アレイに関する情報をキャッシュしているプロバイダーの内部で、ソフトウェアまたは通信の問題が発生しています。 IVdsHwProvider::Reenumerate メソッドに続けて IVdsHwProvider::Refresh メソッドを使用して、 キャッシュを復元してください。 |
|
サブシステムオブジェクトは既に存在しません。 |
IVdsSubSystem2::GetDrive2 (vdshwprv.h) メソッドは、指定されたドライブを返します。
| sBusNumber | SHORT | in | ドライブが接続されているバスの番号。 |
| sSlotNumber | SHORT | in | ドライブが占有しているスロットの番号。 |
| ulEnclosureNumber | DWORD | in | ドライブを格納しているエンクロージャの番号。このパラメーターは、VDS_DRIVE_PROP2 構造体の ulEnclosureNumber メンバーに対応します。 |
| ppDrive | IVdsDrive** | out | IVdsDrive インターフェースポインターのアドレス。呼び出し元は インターフェースを解放する必要があります。 |
戻り値
このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値 を返すことができます。また、HRESULT_FROM_WIN32 マクロを使用して変換された システムエラーコード を返す場合もあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダー から発生する可能性があります。戻り値としては次のものが考えられます。
| リターンコード/値 | 説明 |
|---|---|
|
アレイに関する情報をキャッシュしているプロバイダーの内部で、ソフトウェアまたは通信の問題が発生しています。IVdsHwProvider::Reenumerate メソッドに続けて IVdsHwProvider::Refresh メソッドを使用して、キャッシュを復元してください。 |
|
サブシステムオブジェクトは既に存在しません。 |
|
サブシステムは失敗した状態にあり、要求された操作を実行できません。 |
|
別の操作が進行中です。この操作は、先行する 1 つ以上の操作が完了するまで続行できません。 |
IVdsSubSystem2::CreateLun2 (vdshwprv.h) メソッドは LUN を作成します。IVdsSubSystem::CreateLun メソッドと同一です。
| type | VDS_LUN_TYPE | in | LUN の種類を指定する VDS_LUN_TYPE 列挙値。新しい LUN は automagic タイプまたは特定の RAID タイプのいずれかにできますが、両方を同時に指定することはできません。呼び出し元が automagic タイプを指定する場合は、1 つ以上の automagic ヒントを pHints パラメーターに指定する必要があります。 新しい LUN オブジェクト のインターフェースポインターは、 ppAsync パラメーターで返されたインターフェースポインターに対して IVdsAsync::Wait メソッドを呼び出すことで取得できます。 Wait が返す VDS_ASYNC_OUTPUT 構造体には、 cl.pLunUnk メンバーに LUN オブジェクトのインターフェースポインターが格納されます。 |
| ullSizeInBytes | ULONGLONG | in | 新しい LUN のサイズ (バイト単位)。プロバイダーは、アライメント要件やその他の制約を満たすために、サイズを切り上げまたは切り下げることができます。(ほとんどの場合、プロバイダーは切り上げを行い、まれな例外を除いて、 LUN が要求されたサイズ以上になるようにします。) LUN の作成後、呼び出し元は IVdsLun::GetProperties メソッドを呼び出すことで、LUN の実際のサイズを確認できます。 |
| pDriveIdArray | GUID* | in | LUN の作成に使用する各ドライブの VDS_OBJECT_ID を格納した配列へのポインター。このパラメーターに NULL 以外の値を指定すると、呼び出し元は、指定された順序ですべてのドライブを使用し、1 つのドライブ上のすべてのエクステントを使い切ってから次のドライブに進み、LUN が要求されたサイズに達した時点で停止するようプロバイダーに要求することになります。 あるいは、このパラメーターに NULL を、lNumberOfDrives に 0 を渡すことで、プロバイダーにドライブを自動的に選択させることもできます。(NULL を渡すのは、lNumberOfDrives が 0 の場合に限ります。) type パラメーターが automagic タイプを指定している場合、このパラメーターは NULL にする必要があります。 |
| lNumberOfDrives | INT | in | pDriveIdArray で指定されたドライブの数。呼び出し元が 0 を渡した場合、 プロバイダーがドライブを選択します。 type パラメーターが automagic タイプを指定している場合、このパラメーターは 0 にする必要があります。 LUN の作成後、呼び出し元は IVdsLunPlex::QueryExtents メソッドを呼び出すことで、どのドライブが使用されているかを確認できます。 |
| pwszUnmaskingList | LPWSTR | in | LUN へのアクセスを許可するコンピューターを指定するリスト。このリストは、 セミコロン区切りで NULL 終端の、人間が読める形式の文字列です。 値が "" の場合、ストレージサブシステムに接続された HBAポートを持つすべてのコンピューターに LUN へのアクセスが許可されます。値が "" の場合、どのコンピューターにも LUN へのアクセスは許可されません。 "*" または "" を指定した場合、他の値を指定することはできません。 ファイバーチャネルネットワークおよびシリアル接続 SCSI (SAS) ネットワークでは、各エントリは LUN がアンマスクされる各ポートの 64 ビットの World-Wide Name (WWN) であり、 16 進数の文字列 (16 文字) として、最上位バイトから順にフォーマットされます。たとえば、WWN アドレス 01:23:45:67:89:AB:CD:EF は "0123456789ABCDEF" と表されます。詳細については、ファイバーチャネル および SAS の T10 仕様を参照してください。 iSCSI ネットワークでは、各エントリは LUN がアンマスクされる各イニシエーターの iSCSI 修飾名 (IQN) です。特定のイニシエーターに対してアンマスクされた LUN は、そのイニシエーターに関連付けられているものとみなされます。 注意 アンマスキングリストには、同じ WWN または IQN が複数回含まれる場合があります。呼び出し元は、リストから重複を削除したり、WWN や IQN の形式を検証したりする
必要はありません。
|
| pHints2 | VDS_HINTS2* | in | LUN の作成に使用するヒントを指定する VDS_HINTS2 構造体へのポインター。プロバイダーは、ヒントを LUN に適用する必要はありません。VDS_HINTS2 構造体で指定されるヒントは、プロバイダーへの要求にすぎません。 LUN の作成後、呼び出し元は IVdsLun2::QueryHints2 メソッドを呼び出すことで、プロバイダーが適用したヒントを確認できます。 type パラメーターが automagic 以外のタイプを指定している場合、このパラメーターは NULL にする必要があります。 |
| ppAsync | IVdsAsync** | out | IVdsAsync インターフェースポインターのアドレス。 VDS は戻り時にこれを初期化します。呼び出し元はインターフェースを解放する必要があります。このインターフェースを使用して、操作の取り消し、完了待ち、または 状態の照会を行います。 返されたインターフェースポインターに対して IVdsAsync::Wait を呼び出し、成功を示す HRESULT 値が返された場合、 VDS_ASYNC_OUTPUT 構造体で返されるインターフェースは、各インターフェースポインターに対して IUnknown::Release メソッドを呼び出して解放する必要があります。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体のインターフェースポインターは NULL であり、解放する必要はありません。HRESULT 値が成功か失敗かは、Winerror.h で定義されている SUCCEEDED および FAILED マクロを使用して判定できます。 |
戻り値
このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値 を返すことができます。また、HRESULT_FROM_WIN32 マクロを使用して変換された システムエラーコード を返す場合もあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダー から発生する可能性があります。戻り値としては次のものが考えられます。
| リターンコード/値 | 説明 |
|---|---|
|
アレイに関する情報をキャッシュしているプロバイダーの内部で、ソフトウェアまたは通信の問題が発生しています。 IVdsHwProvider::Reenumerate メソッドに続けて IVdsHwProvider::Refresh メソッドを使用して、キャッシュを復元してください。 |
|
サブシステムオブジェクトは既に存在しません。 |
|
サブシステムは失敗した状態にあり、要求された操作を実行できません。 |
|
別の操作が進行中です。この操作は、先行する 1 つ以上の操作が完了するまで続行できません。 |
|
識別子が既存のオブジェクトを参照していません。この値は、VDS_OBJECT_ID 定数を受け取る任意のメソッドから返される可能性があります。 |
|
この操作またはパラメーターの組み合わせは、このプロバイダーではサポートされていません。 |
|
この操作に十分な使用可能領域がありません。 |
|
この操作を完了するには、サブシステム内の空きドライブが少なすぎます。 |
解説(Remarks)
type および pHints2 パラメーターに適切な値を選択することで、呼び出し元は LUN の属性を全面的に、部分的に、または最小限に指定できます。プロバイダーは、 pHints パラメーターが指す VDS_HINTS2 構造体で指定された automagic ヒントに基づいて、指定されていない属性を自動的に含めることができます。
実装者への注意: このメソッドの呼び出しが非同期操作を開始しない場合でも、プロバイダーは ppAsync パラメーターに IVdsAsync インターフェースポインターを返す必要があります。
pwszUnmaskingList パラメーター内の WWN および IQN のリストには、重複する名前が含まれる場合があります。リスト内のすべての名前を検証し、必要に応じて重複を削除するのはプロバイダーの責任です。
CreateLun2 メソッドに応答して、新しい LUN をいずれかのホストにアンマスクする前に、プロバイダーは先頭と末尾の 1 メガバイトをゼロで埋め、 LUN を未初期化のままにする必要があります。
E_INVALIDARG と VDS_E_NOT_SUPPORTED の戻り値には微妙な違いがあります。プロバイダーは、VDS API がクライアントに提供できるすべての機能を実装することを求められているわけではありません。たとえば、 CreateLun2 メソッドは、さまざまな種類の LUN (たとえば、simple、mirror、striped、parity) を作成する機能を公開します。しかし、プロバイダーはすべての 種類の LUN をサポートする必要はありません。呼び出し元が type パラメーターに有効な VDS_LUN_TYPE 列挙値ではない値を指定した場合、プロバイダーは E_INVALIDARG を返す必要があります。呼び出し元がプロバイダーのサポートしない有効な type 値を指定した場合、プロバイダーは VDS_E_NOT_SUPPORTED を返す必要があります。
IVdsSubSystem2::QueryMaxLunCreateSize2 (vdshwprv.h) メソッドは、指定された LUN の種類とヒントを使用して作成できる最大の LUN のサイズを返します。
| type | VDS_LUN_TYPE | in | LUN の種類を指定する VDS_LUN_TYPE 列挙値。 |
| pDriveIdArray | GUID* | in | LUN の作成に使用する各ドライブの VDS_OBJECT_ID を格納した配列へのポインター。プロバイダーは、 指定された順序でドライブを使用するよう試みる必要があります。lNumberOfDrives パラメーターが 0 の場合、このパラメーターは NULL にすることができ、その場合はプロバイダーが自動的にドライブを選択します。 |
| lNumberOfDrives | INT | in | pDriveIdArray 配列内のエントリ数。このパラメーターは省略可能で、0 にすることができます。 |
| pHints2 | VDS_HINTS2* | in | LUN の作成に使用する VDS_HINTS2 構造体へのポインター。 ヒントは常に、それ以前に列挙されたパラメーターよりも優先度が低くなります。このパラメーターは必須であり、NULL にすることはできません。 |
| pullMaxLunSize | ULONGLONG* | out | LUN の最大サイズ (バイト単位) を格納するバッファへのポインター。このパラメーターは必須であり、NULL にすることはできません。 |
戻り値
このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値 を返すことができます。また、HRESULT_FROM_WIN32 マクロを使用して変換された システムエラーコード を返す場合もあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダー から発生する可能性があります。戻り値としては次のものが考えられます。
| リターンコード/値 | 説明 |
|---|---|
|
アレイに関する情報をキャッシュしているプロバイダーの内部で、ソフトウェアまたは通信の問題が発生しています。 IVdsHwProvider::Reenumerate メソッドに続けて IVdsHwProvider::Refresh メソッドを使用して、 キャッシュを復元してください。 |
|
サブシステムオブジェクトは既に存在しません。 |
|
サブシステムは失敗した状態にあり、要求された操作を実行できません。 |
|
別の操作が進行中です。この操作は、先行する 1 つ以上の操作が完了するまで続行できません。 |
|
識別子が既存のオブジェクトを参照していません。この値は、VDS_OBJECT_ID 定数を受け取る任意のメソッドから返される可能性があります。 |
|
この操作またはパラメーターの組み合わせは、このプロバイダーではサポートされていません。 |
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IVdsSubSystem2 "{BE666735-7800-4A77-9D9C-40F85B87E292}" #usecom global IVdsSubSystem2 IID_IVdsSubSystem2 "{}" #comfunc global IVdsSubSystem2_GetProperties2 3 var #comfunc global IVdsSubSystem2_GetDrive2 4 int,int,int,sptr #comfunc global IVdsSubSystem2_CreateLun2 5 int,int64,var,int,wstr,var,sptr #comfunc global IVdsSubSystem2_QueryMaxLunCreateSize2 6 int,var,int,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IVdsSubSystem2 "{BE666735-7800-4A77-9D9C-40F85B87E292}" #usecom global IVdsSubSystem2 IID_IVdsSubSystem2 "{}" #comfunc global IVdsSubSystem2_GetProperties2 3 sptr #comfunc global IVdsSubSystem2_GetDrive2 4 int,int,int,sptr #comfunc global IVdsSubSystem2_CreateLun2 5 int,int64,sptr,int,wstr,sptr,sptr #comfunc global IVdsSubSystem2_QueryMaxLunCreateSize2 6 int,sptr,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。