com.jacob.com
Class Dispatch

java.lang.Object
  extended by com.jacob.com.JacobObject
      extended by 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
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.
 int 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
  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(int pDisp)
          Constructor that only gets called from JNI QueryInterface calls JNI code that looks up the object for the key passed in.
  Dispatch(String requestedProgramId)
          This constructor calls createInstance with progid.
 
Method Summary
static Variant call(Dispatch dispatchTarget, int dispid)
           
static Variant call(Dispatch dispatchTarget, int dispid, Object... attributes)
           
static Variant call(Dispatch dispatchTarget, String name)
           
static Variant call(Dispatch dispatchTarget, String name, Object... attributes)
           
static Variant callN_CaseSensitive(Dispatch dispatchTarget, String name, Object[] values)
          not implemented yet
static Variant callN(Dispatch dispatchTarget, int dispID, Object... args)
           
static Variant callN(Dispatch dispatchTarget, String name, Object... args)
           
static void callSub(Dispatch dispatchTarget, int dispid)
          makes call to native callSubN
static void callSub(Dispatch dispatchTarget, int dispid, Object... attributes)
          makes call to native callSubN
static void callSub(Dispatch dispatchTarget, String name)
          makes call to native callSubN
static void callSub(Dispatch dispatchTarget, String name, Object... attributes)
          makes call to native callSubN
static void callSubN(Dispatch dispatchTarget, int dispID, Object... args)
           
static void callSubN(Dispatch dispatchTarget, String name, Object... args)
           
protected  void coCreateInstance(String pProgramIdentifier)
          Wrapper around the native method
protected  void finalize()
           
static Variant get_CaseSensitive(Dispatch dispatchTarget, String name)
          not implemented yet
static Variant get(Dispatch dispatchTarget, int dispid)
          Cover for call to underlying invokev()
static Variant get(Dispatch dispatchTarget, String name)
          Cover for call to underlying invokev()
protected  void getActiveInstance(String pProgramIdentifier)
          Wrapper around the native method
static int getIDOfName(Dispatch dispatchTarget, String name)
           
static int[] getIDsOfNames(Dispatch dispatchTarget, int lcid, String[] names)
           
static int[] getIDsOfNames(Dispatch dispatchTarget, String[] names)
           
 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, Object[] oArg, int[] uArgErr)
           
static Variant invoke(Dispatch dispatchTarget, String name, int dispID, int lcid, int wFlags, Object[] oArg, int[] uArgErr)
           
static Variant invoke(Dispatch dispatchTarget, String name, int wFlags, Object[] oArg, int[] uArgErr)
           
static void invokeSub(Dispatch dispatchTarget, int dispid, int wFlags, Object[] oArg, int[] uArgErr)
           
static void invokeSub(Dispatch dispatchTarget, String name, int dispid, int lcid, int wFlags, Object[] oArg, int[] uArgErr)
           
static void invokeSub(Dispatch dispatchTarget, String name, int wFlags, Object[] oArg, int[] uArgErr)
           
static void invokeSubv(Dispatch dispatchTarget, int dispID, int wFlags, Variant[] vArg, int[] uArgErr)
           
static void invokeSubv(Dispatch dispatchTarget, String name, int dispID, int lcid, int wFlags, Variant[] vArg, int[] uArgErr)
           
static void invokeSubv(Dispatch dispatchTarget, 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, String name, int dispID, int lcid, int wFlags, Variant[] vArg, int[] uArgErr)
           
static Variant invokev(Dispatch dispatchTarget, String name, int wFlags, Variant[] vArg, int[] uArgErr)
           
static Variant invokev(Dispatch dispatchTarget, String name, int wFlags, Variant[] vArg, int[] uArgErr, int wFlagsEx)
           
protected  boolean isAttached()
           
static void put_Casesensitive(Dispatch dispatchTarget, String name, Object val)
          not implemented yet
static void put(Dispatch dispatchTarget, int dispid, Object val)
           
static void put(Dispatch dispatchTarget, String name, Object val)
           
static void putRef(Dispatch dispatchTarget, int dispid, Object val)
          cover for underlying call to invoke
static void putRef(Dispatch dispatchTarget, String name, Object val)
          cover for underlying call to invoke
 Dispatch QueryInterface(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 int 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(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:
IllegalArgumentException - if null is passed in as the program id


Dispatch

protected Dispatch(int 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(String pProgramIdentifier)
Wrapper around the native method

Parameters:
pProgramIdentifier - name of the program you wish to connect to

coCreateInstance

protected void coCreateInstance(String pProgramIdentifier)
Wrapper around the native method

Parameters:
pProgramIdentifier -

QueryInterface

public Dispatch QueryInterface(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 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 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,
                                     String name,
                                     Object val)
not implemented yet

Parameters:
dispatchTarget -
name -
val -
Throws:
NotImplementedException

invokeSubv

public static void invokeSubv(Dispatch dispatchTarget,
                              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,
                              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,
                                          String name,
                                          Object[] values)
not implemented yet

Parameters:
dispatchTarget -
name -
values -
Returns:
never returns anything because
Throws:
NotImplementedException

callSubN

public static void callSubN(Dispatch dispatchTarget,
                            String name,
                            Object... args)
Parameters:
dispatchTarget -
name -
args - an array of argument objects

callSubN

public static void callSubN(Dispatch dispatchTarget,
                            int dispID,
                            Object... args)
Parameters:
dispatchTarget -
dispID -
args - an array of argument objects

getIDOfName

public static int getIDOfName(Dispatch dispatchTarget,
                              String name)
Parameters:
dispatchTarget -
name -
Returns:
int id for the passed in name

getIDsOfNames

public static int[] getIDsOfNames(Dispatch dispatchTarget,
                                  int lcid,
                                  String[] names)
Parameters:
dispatchTarget -
lcid -
names -
Returns:
int[] in id array for passed in names

getIDsOfNames

public static int[] getIDsOfNames(Dispatch dispatchTarget,
                                  String[] names)
Parameters:
dispatchTarget -
names -
Returns:
int[] int id array for passed in names

callN

public static Variant callN(Dispatch dispatchTarget,
                            String name,
                            Object... args)
Parameters:
dispatchTarget -
name -
args -
Returns:
Variant returned by call

callN

public static Variant callN(Dispatch dispatchTarget,
                            int dispID,
                            Object... args)
Parameters:
dispatchTarget -
dispID -
args -
Returns:
Variant returned by call

invoke

public static Variant invoke(Dispatch dispatchTarget,
                             String name,
                             int dispID,
                             int lcid,
                             int wFlags,
                             Object[] oArg,
                             int[] uArgErr)
Parameters:
dispatchTarget -
name -
dispID -
lcid -
wFlags -
oArg -
uArgErr -
Returns:
Variant returned by invoke

invoke

public static Variant invoke(Dispatch dispatchTarget,
                             String name,
                             int wFlags,
                             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,
                             Object[] oArg,
                             int[] uArgErr)
Parameters:
dispatchTarget -
dispID -
wFlags -
oArg -
uArgErr -
Returns:
Variant returned by invoke

call

public static Variant call(Dispatch dispatchTarget,
                           String name)
Parameters:
dispatchTarget -
name -
Returns:
Variant returned by underlying callN

call

public static Variant call(Dispatch dispatchTarget,
                           String name,
                           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,
                           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,
                       String name,
                       Object val)
Parameters:
dispatchTarget -
name -
val -

put

public static void put(Dispatch dispatchTarget,
                       int dispid,
                       Object val)
Parameters:
dispatchTarget -
dispid -
val -

invokev

public static Variant invokev(Dispatch dispatchTarget,
                              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,
                              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,
                              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,
                             String name,
                             int dispid,
                             int lcid,
                             int wFlags,
                             Object[] oArg,
                             int[] uArgErr)
Parameters:
dispatchTarget -
name -
dispid -
lcid -
wFlags -
oArg -
uArgErr -

invokeSub

public static void invokeSub(Dispatch dispatchTarget,
                             String name,
                             int wFlags,
                             Object[] oArg,
                             int[] uArgErr)
Parameters:
dispatchTarget -
name -
wFlags -
oArg -
uArgErr -

invokeSub

public static void invokeSub(Dispatch dispatchTarget,
                             int dispid,
                             int wFlags,
                             Object[] oArg,
                             int[] uArgErr)
Parameters:
dispatchTarget -
dispid -
wFlags -
oArg -
uArgErr -

callSub

public static void callSub(Dispatch dispatchTarget,
                           String name)
makes call to native callSubN

Parameters:
dispatchTarget -
name -

callSub

public static void callSub(Dispatch dispatchTarget,
                           String name,
                           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,
                           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,
                          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,
                          String name,
                          Object val)
cover for underlying call to invoke

Parameters:
dispatchTarget -
name -
val -

putRef

public static void putRef(Dispatch dispatchTarget,
                          int dispid,
                          Object val)
cover for underlying call to invoke

Parameters:
dispatchTarget -
dispid -
val -

get_CaseSensitive

public static Variant get_CaseSensitive(Dispatch dispatchTarget,
                                        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