|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.isis.jaut.ApartmentObject
org.isis.jaut.Dispatch
The Dispatch
class enables Java programs to invoke methods
and access properties of an Automation object.
Embedded in the class, there is an IDispatch
interface pointer.
The methods of this class should be called always from the same thread (or from the same Apartment).
Field Summary | |
static int |
CLSCTX_INPROC_HANDLER
A class context allowing in-process handlers. |
static int |
CLSCTX_INPROC_SERVER
A class context allowing in-process servers. |
static int |
CLSCTX_LOCAL_SERVER
A class context allowing local servers. |
static int |
DISPATCH_METHOD
The member is invoked as a method. |
static int |
DISPATCH_PROPERTYGET
The member is retrived as a property or data member. |
static int |
DISPATCH_PROPERTYPUT
The member is changed as a property or data member. |
static int |
DISPATCH_PROPERTYPUTREF
The member is changed by a reference assignment. |
static int |
DISPID_EVALUATE
The dispatch ID of the standard "Evaluate" property. |
static int |
DISPID_PROPERTYPUT
The dispatch ID of the return value named argument. |
static int |
DISPID_VALUE
The dispatch ID of the standard "Value" property. |
int |
pDispatch
This holds an IDispatch interface pointer. |
Fields inherited from class org.isis.jaut.ApartmentObject |
apartment |
Constructor Summary | |
Dispatch()
Creates a NULL Dispatch object. |
|
Dispatch(int target)
Creates a Dispatch object pointing to the given target interface pointer. |
|
Dispatch(Variant target)
Creates a Dispatch object from a Variant . |
Method Summary | |
void |
attach(Dispatch target)
Sets the interface pointer of the Dispatch object to the interface pointer stored in target . |
void |
attach(int target)
Sets the interface pointer of the given interface pointer stored in target . |
void |
attach(Variant target)
Sets the interface pointer of the Dispatch object to the interface pointer stored in the Variant. |
void |
attachActiveObject(java.lang.String progID)
Sets the interface pointer of the Dispatch object to a running object. |
void |
attachNewInstance(java.lang.String progID,
int context)
Creates an Automation object of a given program ID, and attaches this Dispatch object to it. |
java.lang.Object |
call(java.lang.String dispName)
Invokes an Automation method with no argument. |
java.lang.Object |
call(java.lang.String dispName,
java.lang.Object arg0)
Invokes an Automation method with one argument. |
java.lang.Object |
call(java.lang.String dispName,
java.lang.Object[] args)
Invokes an Automation method with a list of arguments. |
java.lang.Object |
call(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object arg1)
Invokes an Automation method with two arguments. |
java.lang.Object |
call(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object arg1,
java.lang.Object arg2)
Invokes an Automation method with three arguments. |
java.lang.Object |
call(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object arg1,
java.lang.Object arg2,
java.lang.Object arg3)
Invokes an Automation method with four arguments. |
void |
callSub(java.lang.String dispName)
Invokes an Automation subrutine with no argument. |
void |
callSub(java.lang.String dispName,
java.lang.Object arg0)
Invokes an Automation subrutine with one argument. |
void |
callSub(java.lang.String dispName,
java.lang.Object[] args)
Invokes an Automation subrutine with a list of arguments. |
void |
callSub(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object arg1)
Invokes an Automation subrutine with two arguments. |
void |
callSub(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object arg1,
java.lang.Object arg2)
Invokes an Automation subrutine with three arguments. |
void |
changeInterface(java.lang.String iID)
Changes the embedded interface pointer to another interface pointer on the same Automation object. |
java.lang.Object |
clone()
Returns a clone of this object. |
static Dispatch |
createInstance(java.lang.String progID,
int context)
Creates an Automation object of a given program ID and returns the new Dispatch object. |
boolean |
equals(java.lang.Object target)
Tests if target is a Dispatch object referring to the same Automation object as this object. |
void |
finalize()
Clears and releases the Dispatch object, can be called from any Thread. |
java.lang.Object |
get(java.lang.String dispName)
Retrives an Automation property. |
java.lang.Object |
get(java.lang.String dispName,
java.lang.Object arg0)
Retrives an Automation property with one argument. |
int |
getIDOfName(java.lang.String name)
Maps a member name to a dispatch ID. |
int[] |
getIDsOfNames(java.lang.String[] names)
Maps a single member and an optional set of argument names to the corresponding list of integer dispatch IDs. |
int |
hashCode()
Returns a hash code value for the object. |
void |
invoke(int dispID,
int dispFlags,
Variant[] arguments,
int[] namedArgDispIDs,
Variant retval)
Invokes a method, or sets or retrives a property of an Automation object. |
java.lang.Object |
invoke(java.lang.String dispName,
int dispFlags,
java.lang.Object[] arguments,
int[] namedArgDispIDs)
Invokes a method, or retrives a property of an Automation object. |
void |
invokeSub(java.lang.String dispName,
int dispFlags,
java.lang.Object[] arguments,
int[] namedArgDispIDs)
Invokes a subrutine, or sets a property of an Automation object. |
boolean |
isNull()
Tests if the embedded IDispatch interface pointer is NULL . |
void |
put(java.lang.String dispName,
java.lang.Object value)
Sets an Automation property. |
void |
put(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object value)
Sets an Automation property with one argument. |
void |
putRef(java.lang.String dispName,
java.lang.Object value)
Sets an Automation property by reference. |
void |
putRef(java.lang.String dispName,
java.lang.Object arg0,
java.lang.Object value)
Sets an Automation property with one argument by reference. |
Dispatch |
queryInterface(java.lang.String iID)
Returns a new Dispatch object with another interface pointer to the same Automation object. |
void |
release()
Releases the interface pointer of the Dispatch object. |
Methods inherited from class org.isis.jaut.ApartmentObject |
finalizeInApartment, getApartment |
Methods inherited from class java.lang.Object |
getClass, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public int pDispatch
IDispatch
interface pointer.
public static final int CLSCTX_INPROC_SERVER
attachNewInstance(java.lang.String, int)
,
Constant Field Valuespublic static final int CLSCTX_INPROC_HANDLER
attachNewInstance(java.lang.String, int)
,
Constant Field Valuespublic static final int CLSCTX_LOCAL_SERVER
attachNewInstance(java.lang.String, int)
,
Constant Field Valuespublic static final int DISPID_VALUE
public static final int DISPID_PROPERTYPUT
public static final int DISPID_EVALUATE
public static final int DISPATCH_METHOD
DISPATCH_PROPERTYGET
flag may be set.
invoke
,
Constant Field Valuespublic static final int DISPATCH_PROPERTYGET
DISPATCH_METHOD
flag may be set.
invoke
,
Constant Field Valuespublic static final int DISPATCH_PROPERTYPUT
invoke
,
Constant Field Valuespublic static final int DISPATCH_PROPERTYPUTREF
invoke
,
Constant Field ValuesConstructor Detail |
public Dispatch()
NULL
Dispatch object. The interface pointer of the Dispatch object
must be set to a non-NULL
value before any other method can be invoked.
attach(Variant)
,
attach(Dispatch)
public Dispatch(int target)
public Dispatch(Variant target) throws ComException
Variant
.
target
- a Variant holding an interface pointer to an Automation object.Variant.getDispatch()
,
attach(Variant)
Method Detail |
public boolean isNull()
IDispatch
interface pointer is NULL
.
true
if the embedded IDispatch
interface pointer is NULL
,
false
otherwise.attach(Variant)
,
attach(Dispatch)
public void attach(Variant target) throws ComException
IUnknown
interface pointer, the
IUnknown::QueryInterface
method is used to get the IDispatch
pointer.
COM object references are managed according to the COM rules
using the IUnknown::AddRef
and IUnknown::Release
methods.
target
- a Variant of type VT_DISPATCH
, VT_DISPATCH|VT_BYREF
,
VT_UNKNOWN
or VT_UNKNOWN|VT_BYREF
holding the new interface pointer.
ComException
- is the IUnknown::QueryInterface
method fails.
JAutException
- if the target Variant does not have its underlying VARIANT
created,
or it is not of the porper type.public void attach(Dispatch target)
target
.
COM object references are managed according to the COM rules
using the IUnknown::AddRef
and IUnknown::Release
methods.
target
- a Dispatch object holding the new interface pointer.public void attach(int target)
target
.
COM object references are managed according to the COM rules
using the IUnknown::AddRef
and IUnknown::Release
methods.
target
- an integer representation if the new interface pointer.public void release()
NULL
,
it is released using the IDispatch::Release
method. Then the embedded interface pointer
is set to NULL
.
release
in class ApartmentObject
public void finalize()
#releaseInApartment
method if the underlying interface
pointer is not NULL
.
public java.lang.Object clone()
IDispatch
interface pointer,
and the reference count is incremented using the IDispatch::AddRef
method.
Dispatch
.public int hashCode()
IUnknown
interface pointer of this Dispatch object, obtained by using the IUnknow::QueryInterface
method.
public boolean equals(java.lang.Object target)
target
is a Dispatch object referring to the same Automation object as this object.
true
if target
is a Dispatch object referring to the same Automation
object as this object, false
otherwise.public void changeInterface(java.lang.String iID) throws ComException
IIDFromString
and IUnknown::QueryInterface
Automation
functions.
iID
- the interface ID of the new interface, in the format of "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
The retrived interface must be derived from IDispatch
.
JAutException
- if the current interface pointer of this object is NULL
.
ComException
- if either IIDFromString
or IUnknown::QueryInterface
fails.public Dispatch queryInterface(java.lang.String iID) throws ComException
iID
- the interface ID of the new interface, in the format of "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
The retrived interface must be derived from IDispatch
.
JAutException
- if the current interface pointer of this object is NULL
.
ComException
- if either IIDFromString
or IUnknown::QueryInterface
fails.changeInterface(java.lang.String)
public void attachNewInstance(java.lang.String progID, int context) throws ComException
CLSID
) of the COM class that will create
the Automation object using the CLSIDFromProgID
Automation function. Finally,
the CoCreateInstance
Automation function is invoked.
progID
- the program ID of the Automation object to be created.context
- the in which the code that manages the newly created object will run.
Acceptable values are combined from the CLSCTX_XXX
constants.
ComException
- if either CLSIDFromProgID
or CoCreateInstance
fails.createInstance(java.lang.String, int)
public static Dispatch createInstance(java.lang.String progID, int context) throws ComException
progID
- the program ID of the Automation object to be created.context
- the in which the code that manages the newly created object will run.
Acceptable values are combined from the CLSCTX_XXX
constants.
ComException
attachNewInstance(java.lang.String, int)
public void attachActiveObject(java.lang.String progID) throws ComException
CLSIDFromProgID
Automation function. Then the GetActiveObject
and IUnknown::QueryInterface
methods are called to retrive the IDispatch
interface pointer of the active object.
progID
- the program ID of the active object that has been registered.
ComException
- if one of the Automation functions fails.public int[] getIDsOfNames(java.lang.String[] names)
IDispatch::GetIDsOfNames
Automation function.
names
- a list of names, the first is the name of an interface member (property or method),
and the rest are parameters names.
JAutException
- if the current interface pointer of this object is NULL
.
ComException
- if IDispatch::GetIDsOfNames
fails.getIDOfName(java.lang.String)
public int getIDOfName(java.lang.String name)
IDispatch::GetIDsOfNames
Automation function.
name
- the name of an interface member (property or method).
JAutException
- if the current interface pointer of this object is NULL
.
ComException
- if IDispatch::GetIDsOfNames
fails.getIDsOfNames(java.lang.String[])
public void invoke(int dispID, int dispFlags, Variant[] arguments, int[] namedArgDispIDs, Variant retval)
IDispatch::Invoke
Automation function.
dispID
- the dispatch ID of the method or property to be invoked.dispFlags
- flags selecting the type of access. Acceptable values are
DISPATCH_METHOD
, DISPATCH_PROPERTYGET
, DISPATCH_PROPERTYPUT
and DISPATCH_PROPERTYPUTREF
.arguments
- the arguments of the method or property. This can be null
if there are no arguments. If an element of the arguements
list is
null, or its underlying VARIANT
is not created, then that parameter
will be passed as an DISP_E_PARAMNOTFOUND
value of type VT_ERROR
.namedArgDispIDs
- a list of dispatch IDs for named arguments. This can be null
indicating that there are no named arguments.retval
- the Variant where the result is to be stored. This can be null
if there is no return value, or the caller is not interested in the return value.
JAutException
- if the current interface pointer of this object is NULL
.
ComException
- if IDispatch::Invoke
fails.
Note, that when the COM error code is DISP_E_PARAMNOTFOUND
or DISP_E_TYPEMISMATCH
,
then the index of the illegal argument is not returned to the invoker.getIDsOfNames(java.lang.String[])
public java.lang.Object invoke(java.lang.String dispName, int dispFlags, java.lang.Object[] arguments, int[] namedArgDispIDs) throws ComException
null
arguments are converted to Variants
with the Variant.Variant(Object)
constructor,
then invoke(int, int, Variant[], int[], Variant)
is called.
Note, that if an argument is of type Variant
, then
the invoked method will receive a reference created by Variant.Variant(Variant)
.
dispName
- the name of the method or property.dispFlags
- the type of access.arguments
- the list of arguments.namedArgDispIDs
- a list of dispatch IDs for named arguments.
ComException
public void invokeSub(java.lang.String dispName, int dispFlags, java.lang.Object[] arguments, int[] namedArgDispIDs)
null
arguments are converted to Variants
with the Variant.Variant(Object)
constructor,
then invoke(int, int, Variant[], int[], Variant)
is called.
Note, that if an argument is of type Variant
, then
the invoked method will receive a reference created by Variant.Variant(Variant)
.
dispName
- the name of the method or property.dispFlags
- the type of access.arguments
- the list of arguments.namedArgDispIDs
- a list of dispatch IDs for named arguments.public java.lang.Object call(java.lang.String dispName)
invoke(String, int, Object[], int[])
public java.lang.Object call(java.lang.String dispName, java.lang.Object arg0)
invoke(String, int, Object[], int[])
public java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1)
invoke(String, int, Object[], int[])
public java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2)
invoke(String, int, Object[], int[])
public java.lang.Object call(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3)
invoke(String, int, Object[], int[])
public java.lang.Object call(java.lang.String dispName, java.lang.Object[] args)
invoke(String, int, Object[], int[])
public void callSub(java.lang.String dispName)
invokeSub(String, int, Object[], int[])
public void callSub(java.lang.String dispName, java.lang.Object arg0)
invokeSub(String, int, Object[], int[])
public void callSub(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1)
invokeSub(String, int, Object[], int[])
public void callSub(java.lang.String dispName, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2)
invokeSub(String, int, Object[], int[])
public void callSub(java.lang.String dispName, java.lang.Object[] args)
invokeSub(String, int, Object[], int[])
public java.lang.Object get(java.lang.String dispName)
invoke(String, int, Object[], int[])
public java.lang.Object get(java.lang.String dispName, java.lang.Object arg0)
invoke(String, int, Object[], int[])
public void put(java.lang.String dispName, java.lang.Object value)
invokeSub(String, int, Object[], int[])
public void put(java.lang.String dispName, java.lang.Object arg0, java.lang.Object value)
invokeSub(String, int, Object[], int[])
public void putRef(java.lang.String dispName, java.lang.Object value)
invokeSub(String, int, Object[], int[])
public void putRef(java.lang.String dispName, java.lang.Object arg0, java.lang.Object value)
invokeSub(String, int, Object[], int[])
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |