Interface

# IDispatch

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

<span class="title-ref">IDispatch</span> is the common interface exposed by automation servers (like Internet Explorer, Word, Excel, etc.). For automation servers that support dual interfaces you can use the `OLEObject</api/windows/oleobject>` class to automate them.

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                 | Parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Returns                            | Shared |
|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|--------|
| `GetIDofName<idispatch.getidofname>` | name As `String</api/data_types/string>`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `Integer</api/data_types/integer>` |        |
| `Invoke<idispatch.invoke>`           | dispIdMember As `Integer</api/data_types/integer>`, riid As `Ptr</api/data_types/additional_types/ptr>`, lcid As `UInt32</api/data_types/additional_types/uint32>`, wFlags As `UInt16</api/data_types/additional_types/uint16>`, `ByRef</api/language/byref>` pDispParams As COM.DISPPARAMS, pVarResult As `Ptr</api/data_types/additional_types/ptr>`, pExcepInfo As `Ptr</api/data_types/additional_types/ptr>`, `ByRef</api/language/byref>` puArgErr As `UInt32</api/data_types/additional_types/uint32>` | `Integer</api/data_types/integer>` |        |

## Method descriptions

<div id="idispatch.getidofname">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

IDispatch.GetIDofName

**GetIDofName**(name As `String</api/data_types/string>`) As `Integer</api/data_types/integer>`

> Gets a single DISPID (which can be used on calls to Invoke) from the specified name. If the name cannot be found this function returns -1.

<div id="idispatch.invoke">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

IDispatch.Invoke

**Invoke**(dispIdMember As `Integer</api/data_types/integer>`, riid As `Ptr</api/data_types/additional_types/ptr>`, lcid As `UInt32</api/data_types/additional_types/uint32>`, wFlags As `UInt16</api/data_types/additional_types/uint16>`, `ByRef</api/language/byref>` pDispParams As COM.DISPPARAMS, pVarResult As `Ptr</api/data_types/additional_types/ptr>`, pExcepInfo As `Ptr</api/data_types/additional_types/ptr>`, `ByRef</api/language/byref>` puArgErr As `UInt32</api/data_types/additional_types/uint32>`) As `Integer</api/data_types/integer>`

> Access properties and methods by ID.
>
> Details on COM.DISPPARAMS can be found [here](https://msdn.microsoft.com/en-us/library/windows/desktop/ms221416(v=vs.85).aspx).

## Sample code

The following automates Internet Explorer, queries for a specific interface (each interface is identified by a unique IID), and invokes a method on the interface

``` xojo
Var ie As New OLEObject("InternetExplorer.Application")
ie.Visible = True
ie.Navigate("google.com")

Var unk As New COM.IUnknown(ie.Handle)

' Query for the IID_IWebBrowser2 interface
Var iid As MemoryBlock = COM.IIDFromString("{D30C1661-CDAF-11D0-8A3E-00C04FC9E26E}")
Var out As Ptr
If COM.S_OK = unk.QueryInterface(iid, out) Then
  Var disp As New COM.IDispatch(out)
  Var id As Integer = disp.GetIDofName("FullName")

  ' If id = -1 Then the method doesn't exist
  ' This method has no parameters but we still have to pass in an empty structure
  Var params As COM.DISPPARAMS

  ' This method returns a BSTR which is stored in an OLE VARIANT
  Var result As New MemoryBlock(COM.SIZEOF_VARIANT)

  Var err As UInt32
  Var resultCode As Integer
  resultCode = disp.Invoke(id, COM.IID_NULL, COM.LOCALE_USER_DEFAULT, _
      COM.DISPATCH_METHOD + COM.DISPATCH_PROPERTYGET, params, result, Nil, err)

  If resultCode = COM.S_OK Then
    Var retVal As Variant = COM.VARIANTToRBVariant(result)
    MessageBox("Path to IE: " + retVal)

    ' Remember to free the OLE VARIANT
    COM.FreeVARIANT(result)
  End If
End If
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | Windows               |

<div id="windows.idispatch/see_also">

<div class="seealso">

`COM</api/windows/com>` module; `IUnknown</api/windows/iunknown>`, `IEnumVARIANT</api/windows/ienumvariant>`, `IPicture</api/windows/ipicture>`.

</div>

</div>