ホーム › Storage.VirtualDiskService › IVdsHwProviderStoragePools

IVdsHwProviderStoragePools

COM

IIDd5b5937a-f188-4c79-b86c-11c920ad11b8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IVdsHwProviderStoragePools インターフェイス (vdshwprv.h) は、記憶域プール内に LUN を作成し、ハードウェアプロバイダーによって管理される記憶域プールを列挙するためのメソッドを提供します。

メソッド 3

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT QueryStoragePools(DWORD ulFlags, ULONGLONG ullRemainingFreeSpace, VDS_POOL_ATTRIBUTES* pPoolAttributes, IEnumVdsObject** ppEnum)

IVdsHwProviderStoragePools::QueryStoragePools (vdshwprv.h) メソッドは、ハードウェアプロバイダーによって管理される記憶域プールの一覧を含む IEnumVdsObject 列挙オブジェクトを返します。

ulFlags	DWORD	in	照会する記憶域プールの種類を指定する、1 つ以上の VDS_STORAGE_POOL_TYPE フラグのビットマスク。フラグの 1 つは VDS_SPT_CONCRETE または VDS_SPT_PRIMORDIAL のいずれかである必要があります。このパラメーターの既定値は 0 です。値が 0 の場合、すべての記憶域プールが照会されることを意味します。
ullRemainingFreeSpace	ULONGLONG	in	各記憶域プールが備えている必要のある空き領域の最小量 (バイト単位)。このパラメーターの既定値は 0 です。値が 0 の場合、記憶域プールは任意の量の空き領域を備えることができることを意味します。
pPoolAttributes	VDS_POOL_ATTRIBUTES*	in	返される記憶域プールが備えている必要のある属性値を指定する VDS_POOL_ATTRIBUTES 構造体へのポインター。このパラメーターの既定値は NULL です。値が NULL の場合、記憶域プールは任意の属性値を備えることができることを意味します。
ppEnum	IEnumVdsObject**	out	記憶域プールの列挙に使用できる IEnumVdsObject インターフェイスポインターのアドレス。詳細については、「Working with Enumeration Objects」を参照してください。呼び出し元は、インターフェイスおよび各記憶域プールオブジェクトが不要になったときに、IUnknown::Release メソッドを呼び出して解放する必要があります。このパラメーターは必須であり、NULL にすることはできません。

戻り値

このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値を返すことがあります。また、HRESULT_FROM_WIN32 マクロを使用して変換されたシステムエラーコードを返すこともあります。エラーは VDS 自体、または使用されている基盤の VDS プロバイダーから発生する可能性があります。返される可能性のある値には次のものが含まれます。

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

ハードウェアプロバイダーが記憶域プールを 1 つも管理していない場合、このメソッドは空の列挙オブジェクトを返します。

pPoolAttributes パラメーターに NULL 以外の値を指定した場合、このメソッドは VDS_POOL_ATTRIBUTES 構造体で指定されたすべての属性を満たす記憶域プールのみを返します。最小属性および最大属性が指定されている場合、返される記憶域プールはこれらの属性に厳密に一致する必要があります。ヒント属性は、指定されたすべての属性を満たす記憶域プールをさらに絞り込むためのヒントとして使用されます。指定された属性がいずれの記憶域プールにも該当しない場合、このメソッドは空の列挙オブジェクトとともに S_OK を返します。

vtbl 4 HRESULT CreateLunInStoragePool(VDS_LUN_TYPE type, ULONGLONG ullSizeInBytes, GUID StoragePoolId, LPWSTR pwszUnmaskingList, VDS_HINTS2* pHints2, IVdsAsync** ppAsync)

IVdsHwProviderStoragePools::CreateLunInStoragePool (vdshwprv.h) メソッドは、記憶域プール内に LUN を作成します。

type	VDS_LUN_TYPE	in	作成する LUN の種類を指定する VDS_LUN_TYPE 列挙値。新しい LUN は automagic 型または特定の RAID 型のいずれかにできますが、両方にすることはできません。呼び出し元が automagic 型を指定する場合は、pHints2 パラメーターに 1 つ以上の automagic ヒントを指定する必要があります。新しい LUN オブジェクトのインターフェイスポインターは、ppAsync パラメーターで返されたインターフェイスポインターに対して IVdsAsync::Wait メソッドを呼び出すことで取得できます。Wait によって返される VDS_ASYNC_OUTPUT 構造体は、cl.pLunUnk メンバーに LUN オブジェクトのインターフェイスポインターを含んでいます。
ullSizeInBytes	ULONGLONG	in	新しい LUN のサイズ (バイト単位)。プロバイダーは、アラインメント要件やその他の制約を満たすために、サイズを切り上げまたは切り下げることができます。(ほとんどの場合、プロバイダーは切り上げるため、まれな例外を除き、LUN は要求されたサイズ以上になります。) LUN の作成後、呼び出し元は IVdsLun::GetProperties メソッドを呼び出すことで、LUN の実際のサイズを確認できます。
StoragePoolId	GUID	in	LUN を作成する記憶域プールを識別する VDS_OBJECT_ID 値。このパラメーターは必須であり、GUID_NULL にすることはできません。
pwszUnmaskingList	LPWSTR	in	LUN へのアクセスを許可するコンピューターを指定する一覧。この一覧は、セミコロン区切りで NULL 終端の、人間が読める形式の文字列です。値が "" の場合、ストレージサブシステムに接続された HBAポートを持つすべてのコンピューターに LUN へのアクセスが許可されます。値が "" の場合、どのコンピューターにも LUN へのアクセスは許可されません。注実際には、値が "" の場合、ほとんどのハードウェアプロバイダーは、ローカルコンピューター上のポートおよびイニシエーターにのみ LUN へのアクセスを許可します。 "*" または "" を指定した場合、他の値を指定することはできません。ファイバーチャネルネットワークおよびシリアル接続 SCSI (SAS) ネットワークの場合、各エントリは、LUN のマスクが解除される各ポートの 64 ビットの World-Wide Name (WWN) であり、16 進数の文字列 (16 文字) として、最上位バイトを先頭にして表記されます。たとえば、WWN アドレス 01:23:45:67:89:AB:CD:EF は "0123456789ABCDEF" と表記されます。詳細については、Fibre Channel および SAS の T10 仕様を参照してください。 iSCSI ネットワークの場合、各エントリは、LUN のマスクが解除される各イニシエーターの iSCSI 修飾名 (IQN) です。特定のイニシエーターに対してマスクが解除された LUN は、そのイニシエーターに関連付けられているとみなされます。注マスク解除の一覧には、同じ WWN または IQN が複数回含まれる場合があります。呼び出し元は、一覧から重複を削除したり、WWN や IQN の形式を検証したりする必要はありません。 LUN の作成後、呼び出し元は IVdsLun::GetProperties メソッドを呼び出すことで、実際のマスク解除の一覧を確認できます。
pHints2	VDS_HINTS2*	in	LUN の作成時に使用するヒントを指定する VDS_HINTS2 構造体へのポインター。プロバイダーは、そのヒントを LUN に適用する必要はありません。VDS_HINTS2 構造体で指定されるヒントは、プロバイダーへの要求にすぎません。 LUN の作成後、呼び出し元は IVdsLun2::QueryHints2 メソッドを呼び出すことで、プロバイダーが適用したヒントを確認できます。 type パラメーターに automagic 型以外の型を指定する場合、このパラメーターは NULL にする必要があります。
ppAsync	IVdsAsync**	out	正常に完了した際に、この操作を監視および制御するための IVdsAsync インターフェイスを受け取る IVdsAsync インターフェイスへのポインター。呼び出し元は、受け取ったインターフェイスの使用が終わったら解放する必要があります。このインターフェイスに対して IVdsAsync::Wait メソッドを呼び出して成功を示す HRESULT 値が返された場合、VDS_ASYNC_OUTPUT 構造体で返されるインターフェイスは、各インターフェイスポインターに対して IUnknown::Release メソッドを呼び出して解放する必要があります。ただし、Wait が失敗を示す HRESULT 値を返した場合、または Wait の pHrResult パラメーターが失敗を示す HRESULT 値を受け取った場合、VDS_ASYNC_OUTPUT 構造体内のインターフェイスポインターは NULL であり、解放する必要はありません。成功または失敗を示す HRESULT 値は、Winerror.h で定義されている SUCCEEDED マクロおよび FAILED マクロを使用して検査できます。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

解説(Remarks)

type パラメーターと pHints2 パラメーターに適切な値を選択することで、呼び出し元は LUN の属性を完全に、部分的に、または最小限に指定できます。プロバイダーは、pHints2 パラメーターが指す VDS_HINTS2 構造体で指定された automagic ヒントに基づいて、指定されていない属性を自動的に含めることができます。

実装者への注意: プロバイダーは、このメソッドの呼び出しが非同期操作を開始しない場合であっても、ppAsync パラメーターに IVdsAsync インターフェイスポインターを返す必要があります。

pwszUnmaskingList パラメーター内の WWN と IQN の一覧には、重複した名前が含まれている場合があります。一覧内のすべての名前を検証し、必要に応じて重複を削除するのはプロバイダーの責任です。

CreateLunInStoragePool メソッドに応答して、新しい LUN をいずれかのホストに対してマスク解除する前に、プロバイダーは最初と最後の 1 メガバイトを 0 で埋め、LUN を初期化されていない状態のままにしておく必要があります。

E_INVALIDARG と VDS_E_NOT_SUPPORTED の戻り値の間には微妙な違いがあります。プロバイダーは、VDS API がクライアントに提示できるすべての機能を実装することを求められているわけではありません。たとえば、CreateLunInStoragePool メソッドは、多くの異なる種類の LUN (たとえば、シンプル、ミラー、ストライプ、パリティ) を作成する機能を公開しています。しかし、プロバイダーはすべての種類の LUN をサポートする必要はありません。呼び出し元が type パラメーターに、有効な VDS_LUN_TYPE 列挙値ではない値を指定した場合、プロバイダーは E_INVALIDARG を返す必要があります。呼び出し元が、プロバイダーがサポートしていない有効な type 値を指定した場合、プロバイダーは VDS_E_NOT_SUPPORTED を返す必要があります。

vtbl 5 HRESULT QueryMaxLunCreateSizeInStoragePool(VDS_LUN_TYPE type, GUID StoragePoolId, VDS_HINTS2* pHints2, ULONGLONG* pullMaxLunSize)

IVdsHwProviderStoragePools::QueryMaxLunCreateSizeInStoragePool (vdshwprv.h) メソッドは、指定された LUN の種類とヒントに基づいて、記憶域プール内に作成できる LUN の最大サイズを返します。

type	VDS_LUN_TYPE	in	LUN の種類を指定する VDS_LUN_TYPE 列挙値。このパラメーターは必須であり、有効な LUN の種類である必要があります。
StoragePoolId	GUID	in	新しい LUN の作成に使用する記憶域プールを識別する VDS_OBJECT_ID (GUID) 値。このパラメーターは必須であり、GUID_NULL にすることはできません。
pHints2	VDS_HINTS2*	in	LUN の作成時に使用するヒントを含む VDS_HINTS2 構造体へのポインター。
pullMaxLunSize	ULONGLONG*	out	LUN の最大サイズ (バイト単位) を受け取る ULONGLONG 値のアドレス。

戻り値

戻り値	説明
S_OK	メソッドは正常に完了しました。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IVdsHwProviderStoragePools "{D5B5937A-F188-4C79-B86C-11C920AD11B8}"
#usecom global IVdsHwProviderStoragePools IID_IVdsHwProviderStoragePools "{}"
#comfunc global IVdsHwProviderStoragePools_QueryStoragePools                   3 int,int64,var,sptr
#comfunc global IVdsHwProviderStoragePools_CreateLunInStoragePool              4 int,int64,int,wstr,var,sptr
#comfunc global IVdsHwProviderStoragePools_QueryMaxLunCreateSizeInStoragePool  5 int,int,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IVdsHwProviderStoragePools "{D5B5937A-F188-4C79-B86C-11C920AD11B8}"
#usecom global IVdsHwProviderStoragePools IID_IVdsHwProviderStoragePools "{}"
#comfunc global IVdsHwProviderStoragePools_QueryStoragePools                   3 int,int64,sptr,sptr
#comfunc global IVdsHwProviderStoragePools_CreateLunInStoragePool              4 int,int64,int,wstr,sptr,sptr
#comfunc global IVdsHwProviderStoragePools_QueryMaxLunCreateSizeInStoragePool  5 int,int,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。