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
`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
`` `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
`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