ホーム › System.Ole › IRecordInfo

IRecordInfo

COM

📘 Microsoft Learn (日本語) · English

IID0000002f-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

特定のUDTの構造を記述します。

メソッド 16

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

vtbl 3 HRESULT RecordInit(void* pvNew)

レコードの新しいインスタンスを初期化します。

pvNew

void*

out

レコードのインスタンス。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

呼び出し元は、GetSizeメソッドを使用して適切なサイズでレコードのメモリを割り当てる必要があります。

RecordInitはレコードのすべての内容を0に設定し、レコードはリソースを保持しない状態になります。

vtbl 4 HRESULT RecordClear(void* pvExisting)

レコードを解放せずに、レコードのオブジェクト参照およびその他の値を解放します。

pvExisting

void*

クリアするレコード。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

RecordClearは、VT_PTRまたはVT_SAFEARRAYのインスタンスフィールドが保持するメモリブロックを解放します。呼び出し元はインスタンスフィールドのメモリを解放する必要があります。保持しているリソースがない場合、RecordClearは何も行いません。

vtbl 5 HRESULT RecordCopy(void* pvExisting, void* pvNew)

既存のレコードを、渡されたバッファーにコピーします。

pvExisting	void*	in	現在のレコードインスタンス。
pvNew	void*	out	レコードのコピー先。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

RecordCopyは、最初にコピー先のリソースを解放します。呼び出し元は、GetSizeまたはRecordCreateを呼び出して、コピー先に十分なメモリを割り当てる責任があります。RecordCopyがいずれかのフィールドのコピーに失敗した場合、RecordClearが呼び出されたかのように、すべてのフィールドがクリアされます。

vtbl 6 HRESULT GetGuid(GUID* pguid)

レコード型のGUIDを取得します。

pguid

GUID*

out

UDTを記述するTypeInfoのクラスGUID。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
TYPE_E_INVALIDSTATE	タイプライブラリの状態がこの操作に対して無効です。
E_INVALIDARG	1つ以上の引数が無効です。

vtbl 7 HRESULT GetName(LPWSTR* pbstrName)

レコード型の名前を取得します。

pbstrName

LPWSTR*

out

名前。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_OUT_OFMEMORY	メモリが不足しています。
E_INVALIDARG	1つ以上の引数が無効です。
TYPE_E_INVALIDSTATE	タイプライブラリの状態がこの操作に対して無効です。

解説(Remarks)

呼び出し元は、SysFreeStringを呼び出してBSTRを解放する必要があります。

vtbl 8 HRESULT GetSize(DWORD* pcbSize)

レコードインスタンスを保持するために必要なメモリのバイト数を取得します。

pcbSize

DWORD*

out

レコードインスタンスのサイズ(バイト単位)。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

vtbl 9 HRESULT GetTypeInfo(ITypeInfo** ppTypeInfo)

UDTまたはUDTのsafearrayを記述する型情報を取得します。

ppTypeInfo

ITypeInfo**

out

レコードの型情報。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。
TYPE_E_INVALIDSTATE	タイプライブラリの状態がこの操作に対して無効です。

解説(Remarks)

ポインターppTypeInfoに対してAddRefが呼び出されます。

vtbl 10 HRESULT GetField(void* pvData, LPWSTR szFieldName, VARIANT* pvarField)

指定されたフィールド名の値を含むVARIANTへのポインターを返します。

pvData	void*	in	レコードのインスタンス。
szFieldName	LPWSTR	in	フィールド名。
pvarField	VARIANT*	out	フィールド名szFieldNameの値を保持するVARIANT。戻り時に、フィールドの値のコピーがバリアントに格納されます。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

渡したVARIANTには、戻り時にフィールドの値のコピーが格納されます。VARIANTを変更しても、元となるレコードフィールドは変化しません。

呼び出し元がVARIANTのメモリを割り当てます。

コピーの前に、pvarFieldに対してVariantClearメソッドが呼び出されます。

vtbl 11 HRESULT GetFieldNoCopy(void* pvData, LPWSTR szFieldName, VARIANT* pvarField, void** ppvDataCArray)

値をコピーしたりリソースを割り当てたりせずに、指定されたフィールド名の値へのポインターを返します。

pvData	void*	in	レコードのインスタンス。
szFieldName	LPWSTR	in	フィールドの名前。
pvarField	VARIANT*	out	戻り時にUDTを含むVARIANT。
ppvDataCArray	void**	out	戻り時にフィールドの値を受け取ります。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

戻り時に、渡したVARIANTにはレコードのフィールドppvDataCArrayへの直接のポインターが格納されます。VARIANTを変更すると、元となるレコードフィールドも変化します。

呼び出し元はVARIANTのメモリを割り当てますが、そのメモリを所有しないため、pvarFieldを解放することはできません。このメソッドは、要求されたフィールドを設定する前に、pvarFieldに対してVariantClearを呼び出します。

vtbl 12 HRESULT PutField(DWORD wFlags, void* pvData, LPWSTR szFieldName, VARIANT* pvarField)

バリアントをフィールドに格納します。

wFlags	DWORD	in	wFlagsパラメーターに指定できる有効な値は、INVOKE_PROPERTYPUTまたはINVOKE_PROPERTYPUTREFのみです。 INVOKE_PROPERTYPUTREFが渡された場合、PutFieldは通常の型変換規則を用いて、渡されたバリアントの値をフィールドに割り当てるだけです。 INVOKE_PROPERTYPUTが渡された場合は、特定の規則が適用されます。フィールドがIDispatchから派生したクラスとして宣言されていて、フィールドの値がNULLの場合、エラーが返されます。フィールドの値がNULLでない場合、バリアントはそのフィールドが参照するオブジェクトがサポートする既定のプロパティに渡されます。フィールドがIDispatchから派生したクラスとして宣言されていない場合、エラーが返されます。フィールドがVT_Dispatch型のバリアントとして宣言されている場合、オブジェクトの既定値がフィールドに割り当てられます。それ以外の場合、バリアントの値がフィールドに割り当てられます。
pvData	void*	inout	レコードのインスタンスへのポインター。
szFieldName	LPWSTR	in	レコードのフィールドの名前。
pvarField	VARIANT*	in	バリアントへのポインター。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

vtbl 13 HRESULT PutFieldNoCopy(DWORD wFlags, void* pvData, LPWSTR szFieldName, VARIANT* pvarField)

実際のデータをフィールドに格納することで、データの所有権を割り当て先のフィールドに渡します。

wFlags	DWORD	in	wFlagsパラメーターに指定できる有効な値は、INVOKE_PROPERTYPUTまたはINVOKE_PROPERTYPUTREFのみです。
pvData	void*	inout	IRecordInfoによって記述されるレコードのインスタンス。
szFieldName	LPWSTR	in	レコードのフィールドの名前。
pvarField	VARIANT*	in	フィールドに格納するバリアント。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

vtbl 14 HRESULT GetFieldNames(DWORD* pcNames, LPWSTR* rgBstrNames)

レコードのフィールドの名前を取得します。

pcNames

DWORD*

inout

返す名前の数。

rgBstrNames

LPWSTR*

out

BSTR型の配列の名前。

rgBstrNamesパラメーターがNULLの場合、フィールド名の数がpcNamesに返されます。

rgBstrNamesパラメーターがNULLでない場合、rgBstrNamesに含まれる文字列名が返されます。pcNamesとrgBstrNamesの名前の数が等しくない場合、両者のうち少ない方の数が返されるフィールド名の数になります。呼び出し元は、rgBstrNamesで返された配列内のBSTRを解放する必要があります。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_OUT_OFMEMORY	メモリが不足しています。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

呼び出し元は、BSTRの配列用のメモリを割り当てる必要があります。配列が必要以上に大きい場合は、未使用の部分を0に設定してください。

戻り時に、呼び出し元は、含まれる各BSTRをSysFreeStringを使用して解放する必要があります。

メモリ不足の場合、pcNamesはエラーコードを指します。

vtbl 15 BOOL IsMatchingType(IRecordInfo* pRecordInfo)

渡されたレコードが、現在のレコード情報と一致するかどうかを判定します。

pRecordInfo

IRecordInfo*

レコードの情報。

戻り値

戻り値	説明
TRUE	渡されたレコードは現在のレコード情報と一致します。
FALSE	渡されたレコードは現在のレコード情報と一致しません。

vtbl 16 void* RecordCreate()

新しいレコードのためのメモリを割り当て、インスタンスを初期化し、レコードへのポインターを返します。

戻り値

このメソッドは、作成されたレコードへのポインターを返します。

解説(Remarks)

メモリは、返される前にゼロで初期化されます。

作成されたレコードは、RecordDestroyを呼び出して解放する必要があります。

vtbl 17 HRESULT RecordCreateCopy(void* pvSource, void** ppvDest)

レコードのインスタンスのコピーを、指定された場所に作成します。

pvSource	void*	in	コピーするレコードのインスタンス。
ppvDest	void**	out	pvSourceからデータをコピーした新しいレコード。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_OUT_OFMEMORY	メモリが不足しています。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

作成されたレコードは、RecordDestroyを呼び出して解放する必要があります。

vtbl 18 HRESULT RecordDestroy(void* pvRecord)

レコードのリソースを解放し、メモリを解放します。

pvRecord

void*

破棄するレコードのインスタンス。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値	説明
S_OK	成功しました。
E_INVALIDARG	1つ以上の引数が無効です。

解説(Remarks)

メモリを解放せずにレコードのインスタンスが保持するリソースを解放するため、RecordClearが呼び出されます。

注意このメソッドは、RecordCreateおよびRecordCreateCopyを通じて割り当てられたレコードに対してのみ呼び出すことができます。自分でレコードを割り当てた場合、このメソッドを呼び出すことはできません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IRecordInfo "{0000002F-0000-0000-C000-000000000046}"
#usecom global IRecordInfo IID_IRecordInfo "{}"
#comfunc global IRecordInfo_RecordInit        3 sptr
#comfunc global IRecordInfo_RecordClear       4 sptr
#comfunc global IRecordInfo_RecordCopy        5 sptr,sptr
#comfunc global IRecordInfo_GetGuid           6 var
#comfunc global IRecordInfo_GetName           7 var
#comfunc global IRecordInfo_GetSize           8 var
#comfunc global IRecordInfo_GetTypeInfo       9 sptr
#comfunc global IRecordInfo_GetField          10 sptr,wstr,var
#comfunc global IRecordInfo_GetFieldNoCopy    11 sptr,wstr,var,sptr
#comfunc global IRecordInfo_PutField          12 int,sptr,wstr,var
#comfunc global IRecordInfo_PutFieldNoCopy    13 int,sptr,wstr,var
#comfunc global IRecordInfo_GetFieldNames     14 var,var
#comfunc global IRecordInfo_IsMatchingType    15 sptr
#comfunc global IRecordInfo_RecordCreate      16
#comfunc global IRecordInfo_RecordCreateCopy  17 sptr,sptr
#comfunc global IRecordInfo_RecordDestroy     18 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IRecordInfo "{0000002F-0000-0000-C000-000000000046}"
#usecom global IRecordInfo IID_IRecordInfo "{}"
#comfunc global IRecordInfo_RecordInit        3 sptr
#comfunc global IRecordInfo_RecordClear       4 sptr
#comfunc global IRecordInfo_RecordCopy        5 sptr,sptr
#comfunc global IRecordInfo_GetGuid           6 sptr
#comfunc global IRecordInfo_GetName           7 sptr
#comfunc global IRecordInfo_GetSize           8 sptr
#comfunc global IRecordInfo_GetTypeInfo       9 sptr
#comfunc global IRecordInfo_GetField          10 sptr,wstr,sptr
#comfunc global IRecordInfo_GetFieldNoCopy    11 sptr,wstr,sptr,sptr
#comfunc global IRecordInfo_PutField          12 int,sptr,wstr,sptr
#comfunc global IRecordInfo_PutFieldNoCopy    13 int,sptr,wstr,sptr
#comfunc global IRecordInfo_GetFieldNames     14 sptr,sptr
#comfunc global IRecordInfo_IsMatchingType    15 sptr
#comfunc global IRecordInfo_RecordCreate      16
#comfunc global IRecordInfo_RecordCreateCopy  17 sptr,sptr
#comfunc global IRecordInfo_RecordDestroy     18 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。