Implementing the IDispatch Interface

IDispatch is located in the Oleauto.h header file on 32-bit systems, and in Dispatch.h on 16-bit systems.

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. The code is abbreviated for brevity, and omits error handling.

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

    HRESULT hresult;
    IUnknown * punk;
    IDispatch * pdisp;
    OLECHAR FAR* 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 OLE Programmer's Reference in the Win32 Software Development Kit (SDK).

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

// OLE function CoCreateInstance starts application using GUID.
hresult = CoCreateInstance(CLSID_Hello, NULL, CLSCTX_SERVER, IID_IUnknown, (void FAR* FAR*)&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);