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(String requestedProgramId) This constructor calls createInstance with progid.

Method Summary

Methods

Modifier and Type	Method and Description
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 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(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(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(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