Implementing the IDispatch Interface

ActiveX or OLE objects can implement the IDispatch interface for access by ActiveX clients, such as Visual Basic. The object's properties and methods can be accessed using IDispatch::GetIDsOfNames and IDispatch::Invoke.

The following examples show how to access an ActiveX or OLE object through the IDispatch interface. Portions of the code are omitted for brevity, including handling any errors returned by function calls.

// Declarations of variables used.
   DEFINE_GUID(CLSID_Hello,      // Portions omitted for brevity.

   HRESULT hresult;
   IUnknown * punk;
   IDispatch * pdisp;
   OLECHAR * szMember = "SayHello";
   DISPID dispid;
   DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};
   EXCEPINFO excepinfo;
   UINT nArgErr;

In the following code, the OleInitialize function loads the OLE dynamic-link libraries (DLLs), and the CoCreateInstance function initializes the ActiveX or OLE object's class factory. For more information on these two functions, see the COM Programmer's Reference.

// Initialize OLE DLLs.
hresult = OleInitialize(NULL);

// OLE function CoCreateInstance starts application using GUID.
hresult = CoCreateInstance(CLSID_Hello, NULL, CLSCTX_SERVER, IID_IUnknown, (void **)&punk);

QueryInterface checks whether the object supports IDispatch. (As with any call to QueryInterface, the returned pointer must be released when it is no longer needed.)

// Call QueryInterface to see if object supports IDispatch.
hresult = punk->QueryInterface(IID_IDispatch, &pdisp);

GetIDsOfNames retrieves the DISPID for the indicated method or property, in this case, szMember.

// Retrieve the dispatch identifier for the SayHello method.
// Use defaults where possible.
hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1,
   LOCALE_USER_DEFAULT,
   &dispid);

In the following call to Invoke, the DISPID indicates the property or method to invoke. The SayHello method does not take any parameters, so the fifth argument (&dispparamsNoArgs), contains a Null and 0, as initialized at declaration.

To invoke a property or method that requires parameters, supply the parameters in the DISPPARAMS structure.

// Invoke the method. Use defaults where possible.
hresult = pdisp->Invoke(
   dispid,
   IID_NULL,
   LOCALE_SYSTEM_DEFAULT,
   DISPATCH_METHOD,
   &dispparamsNoArgs,
   NULL,
   NULL,
   NULL);