IDispatch

オブジェクト、メソッド、プロパティを、オートメーションをサポートするプログラミングツールやその他のアプリケーションに公開します。

オブジェクトが提供する型情報インターフェイスの数(0 または 1)を取得します。

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

このメソッドは 0 を返すことがあり、これはオブジェクトが型情報を一切提供しないことを示します。この場合でも、オブジェクトは IDispatch または VTBL を介してプログラム制御可能な場合がありますが、型情報にアクセスするブラウザー、コンパイラー、その他のプログラミングツールに対して実行時の型情報を提供しません。これは、ブラウザーからオブジェクトを隠す場合に有用です。

例

次の Lines サンプルファイル Lines.cpp のコードは、CLines クラス(ActiveX または OLE オブジェクト)の GetTypeInfoCount メンバー関数を実装しています。

STDMETHODIMP
CLines::GetTypeInfoCount(UINT * pctinfo)
{
   if (pctinfo == NULL) {
      return E_INVALIDARG;
}
   *pctinfo = 1;
   return NOERROR;
}

オブジェクトの型情報を取得します。これを使用してインターフェイスの型情報を取得できます。

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

単一のメンバーと、省略可能な引数名のセットを、対応する整数 DISPID のセットにマッピングします。これらの DISPID は、以降の Invoke 呼び出しで使用できます。

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

IDispatch の実装は、任意の正の整数 ID 値を特定の名前に関連付けることができます。0 は既定の Value プロパティ用に予約されており、–1 は不明な名前を示すために予約されています。その他の負の値は、別の目的のために定義されています。たとえば、GetIDsOfNames が呼び出され、実装が名前の 1 つ以上を認識しない場合、DISP_E_UNKNOWNNAME を返し、rgDispId 配列には不明な名前に対応するエントリに DISPID_UNKNOWN が格納されます。

メンバーおよびパラメーターの DISPID は、オブジェクトの存続期間中は一定に保たれる必要があります。これにより、クライアントは一度 DISPID を取得し、後で使用するためにキャッシュできます。

GetIDsOfNames が複数の名前で呼び出された場合、最初の名前(rgszNames[0])はメンバー名に対応し、以降の名前はメンバーのパラメーター名に対応します。

同じ名前でも、コンテキストによって異なる DISPID にマッピングされる場合があります。たとえば、ある名前が特定のインターフェイスのメンバー名として使用されるときには DISPID を持ち、別のインターフェイスのメンバーとしては別の ID を持ち、パラメーターとして現れるたびに異なるマッピングを持つことがあります。

GetIDsOfNames は、IDispatch クライアントが実行時に名前へバインドする際に使用されます。代わりにコンパイル時にバインドするには、IDispatch クライアントは Type Description Interfaces で説明されている型情報インターフェイスを使用して、名前を DISPID にマッピングできます。これにより、クライアントはコンパイル時にメンバーへバインドし、実行時に GetIDsOfNames を呼び出すことを回避できます。コンパイル時のバインドの説明については、Type Description Interfaces を参照してください。

GetIDsOfNames の実装は大文字と小文字を区別しません。大文字と小文字を区別する名前マッピングが必要なユーザーは、GetIDsOfNames を呼び出すのではなく、型情報インターフェイスを使用して名前を DISPID にマッピングする必要があります。

例

次の Lines サンプルファイル Lines.cpp のコードは、CLine クラスの GetIDsOfNames メンバー関数を実装しています。ActiveX または OLE オブジェクトは、標準の実装である DispGetIDsOfNames を使用します。この実装は、入力引数の検証を DispGetIdsOfNames に依存しています。セキュリティリスクを最小限に抑えるため、入力引数のより堅牢な検証を行うコードを含めてください。

STDMETHODIMP 
CLine::GetIDsOfNames(
      REFIID riid,
      OLECHAR ** rgszNames,
      UINT cNames,
      LCID lcid,
      DISPID * rgDispId)
{
      return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

次のコードは、CLine の Color プロパティの DISPID を取得するために GetIDsOfNames を呼び出す ActiveX クライアントに現れる可能性があります。

HRESULT hresult;
IDispatch * pdisp = (IDispatch *)NULL;
DISPID dispid;
OLECHAR * szMember = "color";

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1, LOCALE_SYSTEM_DEFAULT,
   &dispid);

オブジェクトが公開するプロパティおよびメソッドへのアクセスを提供します。

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

通常、Invoke を直接実装すべきではありません。代わりに、ディスパッチインターフェイスを使用して、CreateStdDispatch および DispInvoke 関数を作成してください。詳細については、CreateStdDispatch、DispInvoke、Creating the IDispatch Interface、および Exposing ActiveX Objects を参照してください。

メンバーを呼び出す前にアプリケーション固有の処理を行う必要がある場合、コードは必要なアクションを実行してから、ITypeInfo::Invoke を呼び出してメンバーを呼び出します。ITypeInfo::Invoke は Invoke とまったく同じように動作します。CreateStdDispatch および DispInvoke によって作成される Invoke の標準実装は、ITypeInfo::Invoke に処理を委譲します。

ActiveX クライアントでは、Invoke を使用してプロパティの値を取得および設定したり、ActiveX オブジェクトのメソッドを呼び出したりします。dispIdMember 引数は、呼び出すメンバーを識別します。メンバーを識別する DISPID は、オブジェクトの実装者によって定義され、オブジェクトのドキュメント、IDispatch::GetIDsOfNames 関数、または ITypeInfo インターフェイスを使用して判別できます。

IDispatch::Invoke() を DISPATCH_PROPERTYPUT または DISPATCH_PROPERTYPUTREF とともに使用する場合、DISPPARAMS 構造体の cNamedArgs および rgdispidNamedArgs 要素を次のように特別に初期化する必要があります。

DISPID dispidNamed = DISPID_PROPERTYPUT;
dispparams.cNamedArgs = 1;
dispparams.rgdispidNamedArgs = &dispidNamed;

以降の情報は、ActiveX クライアントの開発者、およびコードを使用して ActiveX オブジェクトを公開するその他の人を対象としています。公開されたオブジェクトの利用者が想定すべき動作について説明します。