org.jinterop.dcom.impls.automation

Interface IJIDispatch

All Superinterfaces:

IJIComObject, Serializable

public interface IJIDispatch
extends IJIComObject

Represents the Windows COM IDispatch Interface.

Sample Usage :-
//Assume comServer is the reference to JIComServer, obtained earlier...
IJIComObject comObject = comServer.createInstance();
// This call will result into a QueryInterface for the IDispatch
IJIDispatch dispatch = (IJIDispatch)JIObjectFactory.narrowObject(comObject.queryInterface(IJIDispatch.IID));


Another example :-
int dispId = dispatch.getIDsOfNames("Workbooks");
JIVariant outVal = dispatch.get(dispId);
IJIDispatch dispatchOfWorkBooks =(IJIDispatch)JIObjectFactory.narrowObject(outVal.getObjectAsComObject());
JIVariant[] outVal2 = dispatchOfWorkBooks.callMethodA("Add",new Object[]{JIVariant.OPTIONAL_PARAM()});
dispatchOfWorkBook =(IJIDispatch)JIObjectFactory.narrowObject(outVal2[0].getObjectAsComObject());
outVal = dispatchOfWorkBook.get("Worksheets");
dispatchOfWorkSheets = (IJIDispatch)JIObjectFactory.narrowObject(outVal.getObjectAsComObject());


Please note that all [in] parameters are converted to JIVariant before being sent to the COM server through the IJIDispatch interface. If any [in] parameter is already a JIVariant , it is left as it is.

for example:-
//From MSADO example.
dispatch = (IJIDispatch)JIObjectFactory.narrowObject(comObject.queryInterface(IJIDispatch.IID));
dispatch.callMethod("Open",new Object[]{new JIString("driver=Microsoft Access Driver (*.mdb);dbq=C:\\temp\\products.mdb"),
JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,new Integer(-1)});
JIVariant variant[] = dispatch.callMethodA("Execute",new Object[]{new JIString("SELECT * FROM Products"),new Integer(-1)});
if (variant[0].isNull())
{
System.out.println("Recordset is empty.");
}
else
{
//Do something...
}


Where ever the corresponding COM interface API requires an [optional] parameter, the developer can use JIVariant.OPTIONAL_PARAM() , like in the example above.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field and Description
static int	DISPATCH_DISPID_PUTPUTREF COM DISPID for property "put" or "putRef".
static int	DISPATCH_METHOD Flag for selecting a method.
static int	DISPATCH_PROPERTYGET Flag for selecting a Property propget.
static int	DISPATCH_PROPERTYPUT Flag for selecting a Property propput.
static int	DISPATCH_PROPERTYPUTREF Flag for selecting a Property propputref.
static String	IID IID representing the COM IDispatch.

Method Summary

Modifier and Type	Method and Description
void	callMethod(int dispId) Performs a method call for the method identified by the dispId parameter.
void	callMethod(int dispId, Object[] inparams) Performs a method call for the method identified by the dispId parameter.
void	callMethod(int dispId, Object[] inparams, int[] dispIds) Performs a method call for the method identified by the dispId parameter.
void	callMethod(String name) Performs a method call for the method identified by the name parameter.
void	callMethod(String name, Object[] inparams) Performs a method call for the method identified by the name parameter.
void	callMethod(String name, Object[] inparams, int[] dispIds) Performs a method call for the method identified by the name parameter.
void	callMethod(String name, Object[] inparams, String[] paramNames) Performs a method call for the method identified by the name parameter.
JIVariant	callMethodA(int dispId) Performs a method call for the method identified by the dispId parameter.
JIVariant[]	callMethodA(int dispId, Object[] inparams) Performs a method call for the method identified by the dispId parameter.
JIVariant[]	callMethodA(int dispId, Object[] inparams, int[] dispIds) Performs a method call for the method identified by the dispId parameter.
JIVariant	callMethodA(String name) Performs a method call for the method identified by the name parameter.
JIVariant[]	callMethodA(String name, Object[] inparams) Performs a method call for the method identified by the name parameter.
JIVariant[]	callMethodA(String name, Object[] inparams, int[] dispIds) Performs a method call for the method identified by the name parameter.
JIVariant[]	callMethodA(String name, Object[] inparams, String[] paramNames) Performs a method call for the method identified by the name parameter.
JIVariant	get(int dispId) Performs a propget for the method identified by the dispId.
JIVariant[]	get(int dispId, Object[] inparams) Performs a propget for the method identified by the dispId parameter.
JIVariant	get(String name) Performs a propget for the method identified by the name parameter.
JIVariant[]	get(String name, Object[] inparams) Performs a propget for the method identified by the name parameter.
int	getIDsOfNames(String apiName) Maps a method name to its corresponding DISPID.The result of this call is cached for further usage and no network call is performed again for the same method name.
int[]	getIDsOfNames(String[] apiName) Maps a single method name and an optional set of it's argument names to a corresponding set of DISPIDs.
JIExcepInfo	getLastExcepInfo() Returns the COM EXCEPINFO structure wrapped as a data object for the last operation.
IJITypeInfo	getTypeInfo(int typeInfo) Returns an implementation of COM ITypeInfo interface based on the typeInfo.
int	getTypeInfoCount() Definition from MSDN: Determines whether there is type information available for the dual interface.
void	put(int dispId, JIVariant inparam) Performs a propput for the method identified by the dispId.
void	put(int dispId, Object[] params) Performs a propput for the method identified by the dispId
void	put(String name, JIVariant inparam) Performs a propput for the method identified by the name parameter.
void	put(String name, Object[] params) Performs a propput for the method identified by the name parameter.
void	putRef(int dispId, JIVariant inparam) Performs a propputref for the method identified by the dispId.
void	putRef(int dispId, Object[] params) Performs a propputref for the method identified by the dispId.
void	putRef(String name, JIVariant inparam) Performs a propput for the method identified by the name parameter.
void	putRef(String name, Object[] params) Performs a propput for the method identified by the name parameter.

Methods inherited from interface org.jinterop.dcom.core.IJIComObject

addRef, call, call, getAssociatedSession, getInstanceLevelSocketTimeout, getInterfaceIdentifier, getIpid, getUnreferencedHandler, internal_getConnectionInfo, internal_getInterfacePointer, internal_removeConnectionInfo, internal_setConnectionInfo, internal_setDeffered, isDispatchSupported, isLocalReference, queryInterface, registerUnreferencedHandler, release, setInstanceLevelSocketTimeout, unregisterUnreferencedHandler

Field Detail

DISPATCH_METHOD

static final int DISPATCH_METHOD

Flag for selecting a method.

See Also:

Constant Field Values

DISPATCH_PROPERTYGET

static final int DISPATCH_PROPERTYGET

Flag for selecting a Property propget.

See Also:

Constant Field Values

DISPATCH_PROPERTYPUT

static final int DISPATCH_PROPERTYPUT

Flag for selecting a Property propput.

See Also:

Constant Field Values

DISPATCH_DISPID_PUTPUTREF

static final int DISPATCH_DISPID_PUTPUTREF

COM DISPID for property "put" or "putRef".

See Also:

Constant Field Values

DISPATCH_PROPERTYPUTREF

static final int DISPATCH_PROPERTYPUTREF

Flag for selecting a Property propputref.

See Also:

Constant Field Values

IID

static final String IID

IID representing the COM IDispatch.

See Also:

Constant Field Values

Method Detail

getTypeInfoCount

int getTypeInfoCount()
              throws JIException

Definition from MSDN: Determines whether there is type information available for the dual interface.

Returns:

1 if the object provides type information, otherwise 0.

Throws:

JIException

getIDsOfNames

int getIDsOfNames(String apiName)
           throws JIException

Maps a method name to its corresponding DISPID.The result of this call is cached for further usage and no network call is performed again for the same method name.

Parameters:

apiName - Method name.

Returns:

DISPID of the method.

Throws:

JIException

IllegalArgumentException - if the apiName is null or empty.

getIDsOfNames

int[] getIDsOfNames(String[] apiName)
             throws JIException

Maps a single method name and an optional set of it's argument names to a corresponding set of DISPIDs. The result of this call is cached for further usage and no network call is performed again for the same method[argument] set.

Parameters:

apiName - String[] with first index depicting method name and the rest depicting parameters.

Returns:

int[] DISPIDs in the same order as the method[argument] set.

Throws:

JIException

IllegalArgumentException - if the apiName is null or empty.

getTypeInfo

IJITypeInfo getTypeInfo(int typeInfo)
                 throws JIException

Returns an implementation of COM ITypeInfo interface based on the typeInfo.

Parameters:

typeInfo - the type information to return. Pass 0 to retrieve type information for the IDispatch implementation.

Returns:

Throws:

JIException

put

void put(int dispId,
         JIVariant inparam)
  throws JIException

Performs a propput for the method identified by the dispId.

Parameters:

dispId - DISPID of the method to invoke.

inparam - parameter for that method.

Throws:

JIException

put

void put(String name,
         JIVariant inparam)
  throws JIException

Performs a propput for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to put(int, JIVariant).

Parameters:

name - name of the method to invoke.

inparam - parameter for that method.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

putRef

void putRef(int dispId,
            JIVariant inparam)
     throws JIException

Performs a propputref for the method identified by the dispId.

Parameters:

dispId - DISPID of the method to invoke.

inparam - parameter for that method.

Throws:

JIException

putRef

void putRef(String name,
            JIVariant inparam)
     throws JIException

Performs a propput for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to putRef(int, JIVariant).

Parameters:

name - name of the method to invoke.

inparam - parameter for that method.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

get

JIVariant get(int dispId)
       throws JIException

Performs a propget for the method identified by the dispId.

Parameters:

dispId - DISPID of the method to invoke.

Returns:

JIVariant result of the call

Throws:

JIException

get

JIVariant[] get(int dispId,
                Object[] inparams)
         throws JIException

Performs a propget for the method identified by the dispId parameter. inparams defines the parameters for the get operation.

Parameters:

dispId - DISPID of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Returns:

array of JIVariants

Throws:

JIException

get

JIVariant[] get(String name,
                Object[] inparams)
         throws JIException

Performs a propget for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to get(int, Object[]).

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Returns:

array of JIVariants

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

get

JIVariant get(String name)
       throws JIException

Performs a propget for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to get(int)

Parameters:

name - name of the method to invoke.

Returns:

JIVariant result of the call.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(String name)
         throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethod(int).

Parameters:

name - name of the method to invoke.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(int dispId)
         throws JIException

Performs a method call for the method identified by the dispId parameter.

Parameters:

dispId - DISPID of the method to invoke.

Throws:

JIException

callMethodA

JIVariant callMethodA(String name)
               throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethodA(int).

Parameters:

name - name of the method to invoke.

Returns:

JIVariant result.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant callMethodA(int dispId)
               throws JIException

Performs a method call for the method identified by the dispId parameter.

Parameters:

dispId - DISPID of the method to invoke.

Returns:

JIVariant result.

Throws:

JIException

callMethod

void callMethod(String name,
                Object[] inparams)
         throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethod(int, Object[]). For the inparams array, sequential DISPIDs (zero based index) will be used. For inparam[0] , DISPID will be 0, for inparam[1] it will be 1 and so on.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(int dispId,
                Object[] inparams)
         throws JIException

Performs a method call for the method identified by the dispId parameter. For the inparams array, sequential DISPIDs (zero based index) will be used. For inparam[0] , DISPID will be 0, for inparam[1] it will be 1 and so on.

Parameters:

dispId - DISPID of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Throws:

JIException

callMethodA

JIVariant[] callMethodA(String name,
                        Object[] inparams)
                 throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethodA(int, Object[]). For the inparams array, sequential DISPIDs (zero based index) will be used. For inparam[0] , DISPID will be 0, for inparam[1] it will be 1 and so on.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Returns:

JIVariant[] result.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(int dispId,
                        Object[] inparams)
                 throws JIException

Performs a method call for the method identified by the dispId parameter. For the inparams array, sequential DISPIDs (zero based index) will be used. For inparam[0] , DISPID will be 0, for inparam[1] it will be 1 and so on.

Parameters:

dispId - DISPID of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

Returns:

JIVariant[] result.

Throws:

JIException

callMethod

void callMethod(String name,
                Object[] inparams,
                int[] dispIds)
         throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethod(int, Object[], int[]). For the inparams array, the corresponding DISPIDs are present in the dispIds array. The size of both arrays should match.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

dispIds - array of DISPIDs , matching by index to those in inparams array.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(int dispId,
                Object[] inparams,
                int[] dispIds)
         throws JIException

Performs a method call for the method identified by the dispId parameter. For the inparams array, the corresponding DISPIDs are present in the dispIds array. The size of both arrays should match.

Parameters:

dispId - DISPID of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

dispIds - array of DISPIDs , matching by index to those in inparams array.

Throws:

JIException

callMethodA

JIVariant[] callMethodA(String name,
                        Object[] inparams,
                        int[] dispIds)
                 throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to callMethodA(int, Object[], int[]).For the inparams array, the corresponding DISPIDs are present in the dispId array. The size of both arrays should match.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

dispIds - array of DISPIDs , matching by index to those in inparams array.

Returns:

JIVariant[] result.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(int dispId,
                        Object[] inparams,
                        int[] dispIds)
                 throws JIException

Performs a method call for the method identified by the dispId parameter. For the inparams array, the corresponding DISPIDs are present in the dispIds array. The size of both arrays should match.

Parameters:

dispId - DISPID of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

dispIds - array of DISPIDs , matching by index to those in inparams array.

Returns:

JIVariant[] result.

Throws:

JIException

callMethod

void callMethod(String name,
                Object[] inparams,
                String[] paramNames)
         throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String[]) by forming name + paramNames [], and then delegates the call to callMethod(int, Object[], int[]). For the inparams array, the corresponding parameter names are present in the paramNames array. The size of both arrays should match.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

paramNames - Array of parameter names, matching by index to those in inparams array.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(String name,
                        Object[] inparams,
                        String[] paramNames)
                 throws JIException

Performs a method call for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String[]) by forming name + paramNames [], and then delegates the call to callMethodA(int, Object[], int[]). For the inparams array, the corresponding parameter names are present in the paramNames array. The size of both arrays should match.

Parameters:

name - name of the method to invoke.

inparams - members of this array are implicitly converted to JIVariants before performing the actual call to the COM server, via the IJIDispatch interface.

paramNames - Array of parameter names, matching by index to those in inparams array.

Returns:

JIVariant result.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

put

void put(int dispId,
         Object[] params)
  throws JIException

Performs a propput for the method identified by the dispId

Parameters:

dispId - DISPID of the method to invoke.

params - parameters for that method.

Throws:

JIException

put

void put(String name,
         Object[] params)
  throws JIException

Performs a propput for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to put(int, Object[]).

Parameters:

name - name of the method to invoke.

params - parameters for that method.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

putRef

void putRef(int dispId,
            Object[] params)
     throws JIException

Performs a propputref for the method identified by the dispId.

Parameters:

dispId - DISPID of the method to invoke.

params - parameters for that method.

Throws:

JIException

putRef

void putRef(String name,
            Object[] params)
     throws JIException

Performs a propput for the method identified by the name parameter. Internally it will first do a getIDsOfNames(String) and then delegates the call to putRef(int, Object[]).

Parameters:

name - name of the method to invoke.

params - parameters for that method.

Throws:

JIException

IllegalArgumentException - if the name is null or empty.

getLastExcepInfo

JIExcepInfo getLastExcepInfo()

Returns the COM EXCEPINFO structure wrapped as a data object for the last operation. Note this will only be valid if a JIException has been raised in the last call.

Returns: