ホーム › Security.Cryptography.Certificates › IAlternativeName

IAlternativeName

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID728ab313-217d-11da-b2a4-000e7bbb2b09継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

IX509ExtensionAlternativeNames オブジェクトによって、AlternativeNames 拡張のインスタンスを表すために使用されます。

メソッド 7

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT InitializeFromString(AlternativeNameType Type, LPWSTR strValue)

電子メールアドレス、Domain Name System (DNS) 名、URL、登録済みのオブジェクト識別子 (OID)、またはユーザープリンシパル名 (UPN) を含む文字列からオブジェクトを初期化します。

Type

AlternativeNameType

strValue パラメーターに含まれる入力文字列が表す名前の種類を識別する AlternativeNameType 列挙値です。次のいずれかの値である必要があります。

値	意味
XCN_CERT_ALT_NAME_RFC822_NAME	名前は電子メールアドレスです。
XCN_CERT_ALT_NAME_DNS_NAME	名前は DNS 名です。
XCN_CERT_ALT_NAME_URL	名前は URL です。
XCN_CERT_ALT_NAME_REGISTERED_ID	名前は登録済みの OID です。
XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME	名前は UPN です。

strValue

LPWSTR

名前を格納する BSTR 変数です。

戻り値

関数が成功した場合、S_OK を返します。

関数が失敗した場合、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

解説(Remarks)

このメソッドを使用して UPN を指定すると、UPN は XCN_OID_NT_PRINCIPAL_NAME (1.3.6.1.4.1.311.20.2.3) OID に関連付けられ、Distinguished Encoding Rules (DER) でエンコードされます。RawData プロパティを呼び出すと、エンコードされたバイト配列を取得できます。OID は ObjectId プロパティを呼び出して取得できます。

このメソッドを使用して次のいずれかの名前の種類を指定すると、メソッドは E_INVALIDARG を返します。

値	説明
XCN_CERT_ALT_NAME_UNKNOWN	名前の種類が識別されていません。
XCN_CERT_ALT_NAME_OTHER_NAME	名前は OID とバイト配列で構成されます。
XCN_CERT_ALT_NAME_DIRECTORY_NAME	名前は X.500 ディレクトリ名です。
XCN_CERT_ALT_NAME_IP_ADDRESS	名前は IP アドレスです。
XCN_CERT_ALT_NAME_GUID	名前は GUID です。

InitializeFromOtherName メソッドを使用すると OID と対応する名前文字列を指定でき、InitializeFromRawData メソッドを使用すると GUID、IP アドレス、または X.500 ディレクトリ名を指定できます。

vtbl 8 HRESULT InitializeFromRawData(AlternativeNameType Type, EncodingType Encoding, LPWSTR strRawData)

Distinguished Encoding Rules (DER) でエンコードされたバイト配列に含まれる、Digital Signature Algorithm (DSA) GUID、X.500 ディレクトリ名、または Internet Protocol (IP) アドレスからオブジェクトを初期化します。

Type

AlternativeNameType

入力文字列が表す名前の種類を識別する AlternativeNameType 列挙値です。次のいずれかの値である必要があります。

値	意味
XCN_CERT_ALT_NAME_DIRECTORY_NAME	名前は X.500 ディレクトリ名です。
XCN_CERT_ALT_NAME_IP_ADDRESS	名前は IP アドレスです。
XCN_CERT_ALT_NAME_GUID	名前は GUID です。

Encoding

EncodingType

strRawData パラメーターに適用される Unicode エンコードの種類を識別する EncodingType 列挙値です。

strRawData

LPWSTR

DER エンコードされたデータを格納する BSTR 変数です。

戻り値

関数が成功した場合、S_OK を返します。

関数が失敗した場合、エラーを示す HRESULT 値を返します。取り得る値には次の表のものが含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

リターンコード	説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED)	オブジェクトはすでに初期化されています。

解説(Remarks)

生データは、Distinguished Encoding Rules (DER) を使用してエンコードされたバイト配列です。バイト配列は Unicode エンコードされた文字列として指定する必要があります。

このメソッドを使用して DSA GUID (XCN_CERT_ALT_NAME_GUID) を指定すると、GUID は XCN_OID_NTDS_REPLICATION (1.3.6.1.4.1.311.25.1) オブジェクト識別子 (OID) に関連付けられ、オクテット文字列 (バイト配列) としてエンコードされます。OID は ObjectId プロパティを呼び出して取得できます。RawData プロパティを呼び出すと、エンコードされたバイト配列を取得できます。

このメソッドを使用して次のいずれかの名前の種類を指定すると、メソッドは E_INVALIDARG を返します。

値	説明
XCN_CERT_ALT_NAME_UNKNOWN	名前の種類が識別されていません。
XCN_CERT_ALT_NAME_RFC822_NAME	名前は電子メールアドレスです。
XCN_CERT_ALT_NAME_DNS_NAME	名前は DNS 名です。
XCN_CERT_ALT_NAME_URL	名前は URL です。
XCN_CERT_ALT_NAME_REGISTERED_ID	名前は登録済みの OID です。
XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME	名前はユーザープリンシパル名 (UPN) です。
XCN_CERT_ALT_NAME_OTHER_NAME	名前は OID とバイト配列で構成されます。

InitializeFromOtherName メソッドを使用すると OID と対応する名前文字列を指定でき、InitializeFromString メソッドを使用すると電子メールアドレス、DNS 名、URL、登録済みの OID、またはユーザープリンシパル名 (UPN) を指定できます。

vtbl 9 HRESULT InitializeFromOtherName(IObjectId* pObjectId, EncodingType Encoding, LPWSTR strRawData, VARIANT_BOOL ToBeWrapped)

オブジェクト識別子 (OID) と、それに関連付けられた生データ (バイト配列) からオブジェクトを初期化します。

pObjectId	IObjectId*	inoptional	OID を表す IObjectId インターフェイスへのポインターです。
Encoding	EncodingType	in	strRawData パラメーターに適用される Unicode エンコードの種類を識別する EncodingType 列挙値です。
strRawData	LPWSTR	in	OID に関連付けられた名前を格納する BSTR 変数です。
ToBeWrapped	VARIANT_BOOL	in	strRawData パラメーターに含まれる入力文字列を、オクテット文字列 (バイト配列) としてエンコードして保存するかどうかを示す VARIANT_BOOL 変数です。

戻り値

関数が成功した場合、S_OK を返します。

リターンコード/値	説明
HRESULT_FROM_WIN32(ERROR_ALREADY_INITIALIZED)	オブジェクトはすでに初期化されています。

解説(Remarks)

この関数を使用すると、OID とそれに関連付けられた文字列値から IAlternativeName オブジェクトを初期化できます。文字列は Unicode エンコードされます。ToBeWrapped パラメーターに true を指定すると、文字列は Distinguished Encoding Rules (DER) を使用してエンコードされます。OID は ObjectId プロパティを呼び出して取得できます。エンコードされた文字列、または ToBeWrapped が true の場合は DER エンコードされたバイト配列を、RawData プロパティを呼び出して取得できます。

vtbl 10 HRESULT get_Type(AlternativeNameType* pValue)

代替名の種類を取得します。

pValue

AlternativeNameType*

out

別名の種類を受け取る AlternativeNameType へのポインタである。

解説(Remarks)

AlternativeNameType 列挙型から次の値が返される可能性があります。XCN_CERT_ALT_NAME_UNKNOWN 値が返されることはありません。

値	説明
XCN_CERT_ALT_NAME_OTHER_NAME	名前はオブジェクト識別子 (OID) とバイト配列で構成されます。
XCN_CERT_ALT_NAME_RFC822_NAME	名前は電子メールアドレスです。
XCN_CERT_ALT_NAME_DNS_NAME	名前は DNS 名です。
XCN_CERT_ALT_NAME_DIRECTORY_NAME	名前は X.500 ディレクトリ名です。
XCN_CERT_ALT_NAME_URL	名前は URL です。
XCN_CERT_ALT_NAME_IP_ADDRESS	名前は IP アドレスです。
XCN_CERT_ALT_NAME_REGISTERED_ID	名前は登録済みの OID です。
XCN_CERT_ALT_NAME_GUID	名前は GUID です。
XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME	名前はユーザープリンシパル名 (UPN) です。

vtbl 11 HRESULT get_StrValue(LPWSTR* pValue)

電子メールアドレス、Domain Name System (DNS) 名、URL、登録済みのオブジェクト識別子 (OID)、またはユーザープリンシパル名 (UPN) を含む文字列を取得します。

pValue

LPWSTR*

out

別名の値 (文字列表現) を受け取る文字列ポインタである。

解説(Remarks)

InitializeFromString メソッドを呼び出し、次のいずれかの AlternativeNameType 値を指定して IAlternativeName オブジェクトを初期化した場合、このプロパティを呼び出して文字列を取得できます。

値	説明
XCN_CERT_ALT_NAME_RFC822_NAME	名前は電子メールアドレスです。
XCN_CERT_ALT_NAME_DNS_NAME	名前は DNS 名です。
XCN_CERT_ALT_NAME_URL	名前は URL です。
XCN_CERT_ALT_NAME_REGISTERED_ID	名前は登録済みの OID です。
XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME	名前は UPN です。

vtbl 12 HRESULT get_ObjectId(IObjectId** ppValue)

名前に関連付けられているオブジェクト識別子 (OID) がある場合は、それを取得します。

ppValue

IObjectId**

out

OtherName 形式の別名の OID を表す IObjectId オブジェクトを受け取るインターフェイスポインタへのポインタである。

解説(Remarks)

次のいずれかの方法で IAlternativeName オブジェクトを初期化した場合、このプロパティの値を取得できます。

InitializeFromOtherName を呼び出して OID を指定する。
InitializeFromRawData を呼び出して XCN_CERT_ALT_NAME_GUID 型を指定する。
InitializeFromString を呼び出して XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME 型を指定する。

vtbl 13 HRESULT get_RawData(EncodingType Encoding, LPWSTR* pValue)

名前を格納する、Distinguished Encoding Rules (DER) でエンコードされたバイト配列を取得します。

Encoding	EncodingType	in	出力データのエンコード形式を指定する EncodingType である。
pValue	LPWSTR*	out	別名の生データ (エンコード済み) を受け取る文字列ポインタである。

解説(Remarks)

次のいずれかの方法で IAlternativeName オブジェクトを初期化した場合、このプロパティの値を取得できます。

InitializeFromOtherName を呼び出してオブジェクト識別子 (OID) を指定する。
InitializeFromRawData を呼び出して XCN_CERT_ALT_NAME_GUID、XCN_CERT_ALT_NAME_DIRECTORY_NAME、または XCN_CERT_ALT_NAME_IP_ADDRESS 型を指定する。
InitializeFromString を呼び出して XCN_CERT_ALT_NAME_USER_PRINCIPLE_NAME 型を指定する。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IAlternativeName "{728AB313-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IAlternativeName IID_IAlternativeName "{}"
#comfunc global IAlternativeName_InitializeFromString     7 int,wstr
#comfunc global IAlternativeName_InitializeFromRawData    8 int,int,wstr
#comfunc global IAlternativeName_InitializeFromOtherName  9 sptr,int,wstr,int
#comfunc global IAlternativeName_get_Type                 10 var
#comfunc global IAlternativeName_get_StrValue             11 var
#comfunc global IAlternativeName_get_ObjectId             12 sptr
#comfunc global IAlternativeName_get_RawData              13 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IAlternativeName "{728AB313-217D-11DA-B2A4-000E7BBB2B09}"
#usecom global IAlternativeName IID_IAlternativeName "{}"
#comfunc global IAlternativeName_InitializeFromString     7 int,wstr
#comfunc global IAlternativeName_InitializeFromRawData    8 int,int,wstr
#comfunc global IAlternativeName_InitializeFromOtherName  9 sptr,int,wstr,int
#comfunc global IAlternativeName_get_Type                 10 sptr
#comfunc global IAlternativeName_get_StrValue             11 sptr
#comfunc global IAlternativeName_get_ObjectId             12 sptr
#comfunc global IAlternativeName_get_RawData              13 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。