com.jacob.com

## Class Dispatch

- java.lang.Object
- - com.jacob.com.JacobObject
  - - com.jacob.com.Dispatch

- Direct Known Subclasses:
    ActiveXComponent

      public class Dispatch
      extends JacobObject

  Object represents MS level dispatch object. Each instance of this points at some data structure on the MS windows side.

  You're going to live here a lot

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `fdexNameCaseSensitive` One of legal values for GetDispId.
    `static int` | `Get` used by callN() and callSubN()
    `static int` | `LOCALE_SYSTEM_DEFAULT` Used to set the locale in a call.
    `long` | `m_pDispatch` This is public because Dispatch.cpp knows its name and accesses it directly to get the dispatch id.
    `static int` | `Method` used by callN() and callSubN()
    `static int` | `Put` used by put()
    `static int` | `PutRef` not used, probably intended for putRef()

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Dispatch()` zero argument constructor that sets the dispatch pointer to 0 This is the only way to create a Dispatch without a value in the pointer field.
    `` | `Dispatch(Dispatch dispatchToBeDisplaced)` Constructor to be used by subclass that want to swap themselves in for the default Dispatch class.
    `protected` | `Dispatch(long pDisp)` Constructor that only gets called from JNI QueryInterface calls JNI code that looks up the object for the key passed in.
    `` | `Dispatch(java.lang.String requestedProgramId)` This constructor calls createInstance with progid.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Variant` | `call(Dispatch dispatchTarget, int dispid)`
    `static Variant` | `call(Dispatch dispatchTarget, int dispid, java.lang.Object... attributes)`
    `static Variant` | `call(Dispatch dispatchTarget, java.lang.String name)`
    `static Variant` | `call(Dispatch dispatchTarget, java.lang.String name, java.lang.Object... attributes)`
    `static Variant` | `callN_CaseSensitive(Dispatch dispatchTarget, java.lang.String name, java.lang.Object[] values)` not implemented yet
    `static Variant` | `callN(Dispatch dispatchTarget, int dispID, java.lang.Object... args)`
    `static Variant` | `callN(Dispatch dispatchTarget, java.lang.String name, java.lang.Object... args)`
    `static void` | `callSub(Dispatch dispatchTarget, int dispid)` makes call to native callSubN
    `static void` | `callSub(Dispatch dispatchTarget, int dispid, java.lang.Object... attributes)` makes call to native callSubN
    `static void` | `callSub(Dispatch dispatchTarget, java.lang.String name)` makes call to native callSubN
    `static void` | `callSub(Dispatch dispatchTarget, java.lang.String name, java.lang.Object... attributes)` makes call to native callSubN
    `static void` | `callSubN(Dispatch dispatchTarget, int dispID, java.lang.Object... args)`
    `static void` | `callSubN(Dispatch dispatchTarget, java.lang.String name, java.lang.Object... args)`
    `protected void` | `coCreateInstance(java.lang.String pProgramIdentifier)` Wrapper around the native method
    `protected void` | `finalize()`
    `static Variant` | `get_CaseSensitive(Dispatch dispatchTarget, java.lang.String name)` not implemented yet
    `static Variant` | `get(Dispatch dispatchTarget, int dispid)` Cover for call to underlying invokev()
    `static Variant` | `get(Dispatch dispatchTarget, java.lang.String name)` Cover for call to underlying invokev()
    `protected void` | `getActiveInstance(java.lang.String pProgramIdentifier)` Wrapper around the native method
    `static int` | `getIDOfName(Dispatch dispatchTarget, java.lang.String name)`
    `static int[]` | `getIDsOfNames(Dispatch dispatchTarget, int lcid, java.lang.String[] names)`
    `static int[]` | `getIDsOfNames(Dispatch dispatchTarget, java.lang.String[] names)`
    `java.lang.String` | `getProgramId()` returns the program id if an activeX component created this otherwise it returns null.
    `static int` | `hasExited(Dispatch dispatchTarget)` The method is used to poll until it returns 1, indicating that the COM server in gone.
    `static int` | `hasExited(Dispatch disp, int dispid, int lcid)` Cover for native method
    `static Variant` | `invoke(Dispatch dispatchTarget, int dispID, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static Variant` | `invoke(Dispatch dispatchTarget, java.lang.String name, int dispID, int lcid, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static Variant` | `invoke(Dispatch dispatchTarget, java.lang.String name, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static void` | `invokeSub(Dispatch dispatchTarget, int dispid, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static void` | `invokeSub(Dispatch dispatchTarget, java.lang.String name, int dispid, int lcid, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static void` | `invokeSub(Dispatch dispatchTarget, java.lang.String name, int wFlags, java.lang.Object[] oArg, int[] uArgErr)`
    `static void` | `invokeSubv(Dispatch dispatchTarget, int dispID, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static void` | `invokeSubv(Dispatch dispatchTarget, java.lang.String name, int dispID, int lcid, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static void` | `invokeSubv(Dispatch dispatchTarget, java.lang.String name, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static Variant` | `invokev(Dispatch dispatchTarget, int dispID, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static Variant` | `invokev(Dispatch dispatchTarget, java.lang.String name, int dispID, int lcid, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static Variant` | `invokev(Dispatch dispatchTarget, java.lang.String name, int wFlags, Variant[] vArg, int[] uArgErr)`
    `static Variant` | `invokev(Dispatch dispatchTarget, java.lang.String name, int wFlags, Variant[] vArg, int[] uArgErr, int wFlagsEx)`
    `protected boolean` | `isAttached()`
    `static void` | `put_Casesensitive(Dispatch dispatchTarget, java.lang.String name, java.lang.Object val)` not implemented yet
    `static void` | `put(Dispatch dispatchTarget, int dispid, java.lang.Object val)`
    `static void` | `put(Dispatch dispatchTarget, java.lang.String name, java.lang.Object val)`
    `static void` | `putRef(Dispatch dispatchTarget, int dispid, java.lang.Object val)` cover for underlying call to invoke
    `static void` | `putRef(Dispatch dispatchTarget, java.lang.String name, java.lang.Object val)` cover for underlying call to invoke
    `Dispatch` | `QueryInterface(java.lang.String iid)` Return a different interface by IID string.
    `void` | `safeRelease()` Finalizers call this method.

    - ### Methods inherited from class com.jacob.com.JacobObject

      `debug, getBuildDate, getBuildVersion, isDebugEnabled`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LOCALE_SYSTEM_DEFAULT

          public static final int LOCALE_SYSTEM_DEFAULT

      Used to set the locale in a call. The user locale is another option
      See Also:
        Constant Field Values

    - #### Method

          public static final int Method

      used by callN() and callSubN()
      See Also:
        Constant Field Values

    - #### Get

          public static final int Get

      used by callN() and callSubN()
      See Also:
        Constant Field Values

    - #### Put

          public static final int Put

      used by put()
      See Also:
        Constant Field Values

    - #### PutRef

          public static final int PutRef

      not used, probably intended for putRef()
      See Also:
        Constant Field Values

    - #### fdexNameCaseSensitive

          public static final int fdexNameCaseSensitive

      One of legal values for GetDispId. Not used in this layer and probably not needed.
      See Also:
        Constant Field Values

    - #### m_pDispatch

          public long m_pDispatch

      This is public because Dispatch.cpp knows its name and accesses it directly to get the dispatch id. You really can't rename it or make it private

  - ### Constructor Detail

    - #### Dispatch

          public Dispatch()

      zero argument constructor that sets the dispatch pointer to 0 This is the only way to create a Dispatch without a value in the pointer field.

    - #### Dispatch

          public Dispatch(java.lang.String requestedProgramId)

      This constructor calls createInstance with progid. This is the constructor used by the ActiveXComponent or by programs that don't like the activeX interface but wish to create new connections to windows programs.

      This constructor always creates a new windows/program object because it is based on the CoCreate() windows function.

      Parameters:
        `requestedProgramId` -
      Throws:
        `java.lang.IllegalArgumentException` - if null is passed in as the program id

    - #### Dispatch

          protected Dispatch(long pDisp)

      Constructor that only gets called from JNI QueryInterface calls JNI code that looks up the object for the key passed in. The JNI CODE then creates a new dispatch object using this constructor
      Parameters:
        `pDisp` -

    - #### Dispatch

          public Dispatch(Dispatch dispatchToBeDisplaced)

      Constructor to be used by subclass that want to swap themselves in for the default Dispatch class. Usually you will have a class like WordDocument that is a subclass of Dispatch and it will have a constructor public WordDocument(Dispatch). That constructor should just call this constructor as super(Dispatch)
      Parameters:
        `dispatchToBeDisplaced` -

  - ### Method Detail

    - #### getActiveInstance

          protected void getActiveInstance(java.lang.String pProgramIdentifier)

      Wrapper around the native method
      Parameters:
        `pProgramIdentifier` - name of the program you wish to connect to

    - #### coCreateInstance

          protected void coCreateInstance(java.lang.String pProgramIdentifier)

      Wrapper around the native method
      Parameters:
        `pProgramIdentifier` -

    - #### QueryInterface

          public Dispatch QueryInterface(java.lang.String iid)

      Return a different interface by IID string.

      Once you have a Dispatch object, you can navigate to the other interfaces of a COM object by calling QueryInterafce. The argument is an IID string in the format: "{9BF24410-B2E0-11D4-A695-00104BFF3241}". You typically get this string from the idl file (it's called uuid in there). Any interface you try to use must be derived from IDispatch. T The atl example uses this.

      The Dispatch instance resulting from this query is instanciated in the JNI code.

      Parameters:
        `iid` -
      Returns:
        Dispatch a disptach that matches ??

    - #### getProgramId

          public java.lang.String getProgramId()

      returns the program id if an activeX component created this otherwise it returns null. This was added to aid in debugging
      Returns:
        the program id an activeX component was created against

    - #### finalize

          protected void finalize()

      Overrides:
        `finalize` in class `java.lang.Object`

    - #### safeRelease

          public void safeRelease()

      Description copied from class: `JacobObject`
      Finalizers call this method. This method should release any COM data structures in a way that it can be called multiple times. This can happen if someone manually calls this and then a finalizer calls it.
      Overrides:
        `safeRelease` in class `JacobObject`

    - #### isAttached

          protected boolean isAttached()

      Returns:
        true if there is an underlying windows dispatch object

    - #### put_Casesensitive

          public static void put_Casesensitive(Dispatch dispatchTarget,
                                               java.lang.String name,
                                               java.lang.Object val)

      not implemented yet
      Parameters:
        `dispatchTarget` -
        `name` -
        `val` -
      Throws:
        `NotImplementedException`

    - #### invokeSubv

          public static void invokeSubv(Dispatch dispatchTarget,
                                        java.lang.String name,
                                        int dispID,
                                        int lcid,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `dispID` -
        `lcid` -
        `wFlags` -
        `vArg` -
        `uArgErr` -

    - #### invokeSubv

          public static void invokeSubv(Dispatch dispatchTarget,
                                        java.lang.String name,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `wFlags` -
        `vArg` -
        `uArgErr` -

    - #### invokeSubv

          public static void invokeSubv(Dispatch dispatchTarget,
                                        int dispID,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `dispID` -
        `wFlags` -
        `vArg` -
        `uArgErr` -

    - #### callN_CaseSensitive

          public static Variant callN_CaseSensitive(Dispatch dispatchTarget,
                                                    java.lang.String name,
                                                    java.lang.Object[] values)

      not implemented yet
      Parameters:
        `dispatchTarget` -
        `name` -
        `values` -
      Returns:
        never returns anything because
      Throws:
        `NotImplementedException`

    - #### callSubN

          public static void callSubN(Dispatch dispatchTarget,
                                      java.lang.String name,
                                      java.lang.Object... args)

      Parameters:
        `dispatchTarget` -
        `name` -
        `args` - an array of argument objects

    - #### callSubN

          public static void callSubN(Dispatch dispatchTarget,
                                      int dispID,
                                      java.lang.Object... args)

      Parameters:
        `dispatchTarget` -
        `dispID` -
        `args` - an array of argument objects

    - #### getIDOfName

          public static int getIDOfName(Dispatch dispatchTarget,
                                        java.lang.String name)

      Parameters:
        `dispatchTarget` -
        `name` -
      Returns:
        int id for the passed in name

    - #### getIDsOfNames

          public static int[] getIDsOfNames(Dispatch dispatchTarget,
                                            int lcid,
                                            java.lang.String[] names)

      Parameters:
        `dispatchTarget` -
        `lcid` -
        `names` -
      Returns:
        int[] in id array for passed in names

    - #### getIDsOfNames

          public static int[] getIDsOfNames(Dispatch dispatchTarget,
                                            java.lang.String[] names)

      Parameters:
        `dispatchTarget` -
        `names` -
      Returns:
        int[] int id array for passed in names

    - #### callN

          public static Variant callN(Dispatch dispatchTarget,
                                      java.lang.String name,
                                      java.lang.Object... args)

      Parameters:
        `dispatchTarget` -
        `name` -
        `args` -
      Returns:
        Variant returned by call

    - #### callN

          public static Variant callN(Dispatch dispatchTarget,
                                      int dispID,
                                      java.lang.Object... args)

      Parameters:
        `dispatchTarget` -
        `dispID` -
        `args` -
      Returns:
        Variant returned by call

    - #### invoke

          public static Variant invoke(Dispatch dispatchTarget,
                                       java.lang.String name,
                                       int dispID,
                                       int lcid,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `dispID` -
        `lcid` -
        `wFlags` -
        `oArg` -
        `uArgErr` -
      Returns:
        Variant returned by invoke

    - #### invoke

          public static Variant invoke(Dispatch dispatchTarget,
                                       java.lang.String name,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `wFlags` -
        `oArg` -
        `uArgErr` -
      Returns:
        Variant returned by invoke

    - #### invoke

          public static Variant invoke(Dispatch dispatchTarget,
                                       int dispID,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `dispID` -
        `wFlags` -
        `oArg` -
        `uArgErr` -
      Returns:
        Variant returned by invoke

    - #### call

          public static Variant call(Dispatch dispatchTarget,
                                     java.lang.String name)

      Parameters:
        `dispatchTarget` -
        `name` -
      Returns:
        Variant returned by underlying callN

    - #### call

          public static Variant call(Dispatch dispatchTarget,
                                     java.lang.String name,
                                     java.lang.Object... attributes)

      Parameters:
        `dispatchTarget` -
        `name` -
        `attributes` -
      Returns:
        Variant returned by underlying callN

    - #### call

          public static Variant call(Dispatch dispatchTarget,
                                     int dispid)

      Parameters:
        `dispatchTarget` -
        `dispid` -
      Returns:
        Variant returned by underlying callN

    - #### call

          public static Variant call(Dispatch dispatchTarget,
                                     int dispid,
                                     java.lang.Object... attributes)

      Parameters:
        `dispatchTarget` -
        `dispid` -
        `attributes` - var arg list of attributes that will be passed to the underlying function
      Returns:
        Variant returned by underlying callN

    - #### put

          public static void put(Dispatch dispatchTarget,
                                 java.lang.String name,
                                 java.lang.Object val)

      Parameters:
        `dispatchTarget` -
        `name` -
        `val` -

    - #### put

          public static void put(Dispatch dispatchTarget,
                                 int dispid,
                                 java.lang.Object val)

      Parameters:
        `dispatchTarget` -
        `dispid` -
        `val` -

    - #### invokev

          public static Variant invokev(Dispatch dispatchTarget,
                                        java.lang.String name,
                                        int dispID,
                                        int lcid,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `dispID` -
        `lcid` -
        `wFlags` -
        `vArg` -
        `uArgErr` -
      Returns:
        Variant returned by underlying invokev

    - #### invokev

          public static Variant invokev(Dispatch dispatchTarget,
                                        java.lang.String name,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `wFlags` -
        `vArg` -
        `uArgErr` -
      Returns:
        Variant returned by underlying invokev

    - #### invokev

          public static Variant invokev(Dispatch dispatchTarget,
                                        java.lang.String name,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr,
                                        int wFlagsEx)

      Parameters:
        `dispatchTarget` -
        `name` -
        `wFlags` -
        `vArg` -
        `uArgErr` -
        `wFlagsEx` -
      Returns:
        Variant returned by underlying invokev

    - #### invokev

          public static Variant invokev(Dispatch dispatchTarget,
                                        int dispID,
                                        int wFlags,
                                        Variant[] vArg,
                                        int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `dispID` -
        `wFlags` -
        `vArg` -
        `uArgErr` -
      Returns:
        Variant returned by underlying invokev

    - #### invokeSub

          public static void invokeSub(Dispatch dispatchTarget,
                                       java.lang.String name,
                                       int dispid,
                                       int lcid,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `dispid` -
        `lcid` -
        `wFlags` -
        `oArg` -
        `uArgErr` -

    - #### invokeSub

          public static void invokeSub(Dispatch dispatchTarget,
                                       java.lang.String name,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `name` -
        `wFlags` -
        `oArg` -
        `uArgErr` -

    - #### invokeSub

          public static void invokeSub(Dispatch dispatchTarget,
                                       int dispid,
                                       int wFlags,
                                       java.lang.Object[] oArg,
                                       int[] uArgErr)

      Parameters:
        `dispatchTarget` -
        `dispid` -
        `wFlags` -
        `oArg` -
        `uArgErr` -

    - #### callSub

          public static void callSub(Dispatch dispatchTarget,
                                     java.lang.String name)

      makes call to native callSubN
      Parameters:
        `dispatchTarget` -
        `name` -

    - #### callSub

          public static void callSub(Dispatch dispatchTarget,
                                     java.lang.String name,
                                     java.lang.Object... attributes)

      makes call to native callSubN
      Parameters:
        `dispatchTarget` -
        `name` -
        `attributes` - var args list of attributes to be passed to underlying functions

    - #### callSub

          public static void callSub(Dispatch dispatchTarget,
                                     int dispid)

      makes call to native callSubN
      Parameters:
        `dispatchTarget` -
        `dispid` -

    - #### callSub

          public static void callSub(Dispatch dispatchTarget,
                                     int dispid,
                                     java.lang.Object... attributes)

      makes call to native callSubN
      Parameters:
        `dispatchTarget` -
        `dispid` -
        `attributes` - var args list of attributes to be passed to underlying function

    - #### get

          public static Variant get(Dispatch dispatchTarget,
                                    java.lang.String name)

      Cover for call to underlying invokev()
      Parameters:
        `dispatchTarget` -
        `name` -
      Returns:
        Variant returned by the request for retrieval of parameter

    - #### get

          public static Variant get(Dispatch dispatchTarget,
                                    int dispid)

      Cover for call to underlying invokev()
      Parameters:
        `dispatchTarget` -
        `dispid` -
      Returns:
        Variant returned by the request for retrieval of parameter

    - #### putRef

          public static void putRef(Dispatch dispatchTarget,
                                    java.lang.String name,
                                    java.lang.Object val)

      cover for underlying call to invoke
      Parameters:
        `dispatchTarget` -
        `name` -
        `val` -

    - #### putRef

          public static void putRef(Dispatch dispatchTarget,
                                    int dispid,
                                    java.lang.Object val)

      cover for underlying call to invoke
      Parameters:
        `dispatchTarget` -
        `dispid` -
        `val` -

    - #### get_CaseSensitive

          public static Variant get_CaseSensitive(Dispatch dispatchTarget,
                                                  java.lang.String name)

      not implemented yet
      Parameters:
        `dispatchTarget` -
        `name` -
      Returns:
        Variant never returned
      Throws:
        `NotImplementedException`

    - #### hasExited

          public static int hasExited(Dispatch disp,
                                      int dispid,
                                      int lcid)

      Cover for native method
      Parameters:
        `disp` -
        `dispid` -
        `lcid` -
      Returns:
        0 if the dispatch is still active and 1 if it has exited

    - #### hasExited

          public static int hasExited(Dispatch dispatchTarget)

      The method is used to poll until it returns 1, indicating that the COM server in gone.

      Sourceforge feature request 2927058

      Parameters:
        `dispatchTarget` -
      Returns:
        0 if the dispatch is still active and 1 if it has exited

http://jacob-project.sourceforge.net