org.jinterop.dcom.impls.automation
Interface IJIDispatch

All Superinterfaces:
IJIComObject, java.io.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
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 java.lang.String IID
          IID representing the COM IDispatch.
 
Method Summary
 void callMethod(int dispId)
          Performs a method call for the method identified by the dispId parameter.
 void callMethod(int dispId, java.lang.Object[] inparams)
          Performs a method call for the method identified by the dispId parameter.
 void callMethod(int dispId, java.lang.Object[] inparams, int[] dispIds)
          Performs a method call for the method identified by the dispId parameter.
 void callMethod(java.lang.String name)
          Performs a method call for the method identified by the name parameter.
 void callMethod(java.lang.String name, java.lang.Object[] inparams)
          Performs a method call for the method identified by the name parameter.
 void callMethod(java.lang.String name, java.lang.Object[] inparams, int[] dispIds)
          Performs a method call for the method identified by the name parameter.
 void callMethod(java.lang.String name, java.lang.Object[] inparams, java.lang.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, java.lang.Object[] inparams)
          Performs a method call for the method identified by the dispId parameter.
 JIVariant[] callMethodA(int dispId, java.lang.Object[] inparams, int[] dispIds)
          Performs a method call for the method identified by the dispId parameter.
 JIVariant callMethodA(java.lang.String name)
          Performs a method call for the method identified by the name parameter.
 JIVariant[] callMethodA(java.lang.String name, java.lang.Object[] inparams)
          Performs a method call for the method identified by the name parameter.
 JIVariant[] callMethodA(java.lang.String name, java.lang.Object[] inparams, int[] dispIds)
          Performs a method call for the method identified by the name parameter.
 JIVariant[] callMethodA(java.lang.String name, java.lang.Object[] inparams, java.lang.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, java.lang.Object[] inparams)
          Performs a propget for the method identified by the dispId parameter.
 JIVariant get(java.lang.String name)
          Performs a propget for the method identified by the name parameter.
 JIVariant[] get(java.lang.String name, java.lang.Object[] inparams)
          Performs a propget for the method identified by the name parameter.
 int getIDsOfNames(java.lang.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(java.lang.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, java.lang.Object[] params)
          Performs a propput for the method identified by the dispId
 void put(java.lang.String name, JIVariant inparam)
          Performs a propput for the method identified by the name parameter.
 void put(java.lang.String name, java.lang.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, java.lang.Object[] params)
          Performs a propputref for the method identified by the dispId.
 void putRef(java.lang.String name, JIVariant inparam)
          Performs a propput for the method identified by the name parameter.
 void putRef(java.lang.String name, java.lang.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 java.lang.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(java.lang.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
java.lang.IllegalArgumentException - if the apiName is null or empty.

getIDsOfNames

int[] getIDsOfNames(java.lang.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
java.lang.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(java.lang.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
java.lang.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(java.lang.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
java.lang.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,
                java.lang.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(java.lang.String name,
                java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

get

JIVariant get(java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(java.lang.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
java.lang.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(java.lang.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
java.lang.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(java.lang.String name,
                java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(int dispId,
                java.lang.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(java.lang.String name,
                        java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(int dispId,
                        java.lang.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(java.lang.String name,
                java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethod

void callMethod(int dispId,
                java.lang.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(java.lang.String name,
                        java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(int dispId,
                        java.lang.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(java.lang.String name,
                java.lang.Object[] inparams,
                java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

callMethodA

JIVariant[] callMethodA(java.lang.String name,
                        java.lang.Object[] inparams,
                        java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

put

void put(int dispId,
         java.lang.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(java.lang.String name,
         java.lang.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
java.lang.IllegalArgumentException - if the name is null or empty.

putRef

void putRef(int dispId,
            java.lang.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(java.lang.String name,
            java.lang.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
java.lang.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: