org.jinterop.dcom.win32
Interface IJIDispatch

All Superinterfaces:
IJIComObject, IJIUnknown

public interface IJIDispatch
extends IJIComObject

j-Interop class corresponding to COM IDispatch Interface.
Sample Usage:-
//Assume comStub is the reference to JIComServer, obtained earlier...
IJIUnknown unknown = comStub.createInstance();
// This call will result into a QueryInterface for the IDispatch
IJIDispatch dispatch = (IJIDispatch)JIComFactory.createCOMInstance(JIComFactory.IID_IDispatch,unknown);

Another example:-
//From MSWord example
JIVariant variant = dispatch.get("Documents");
JIInterfacePointer ptr = variant.getObjectAsInterfacePointer();
IJIDispatch documents = (IJIDispatch)JIComFactory.createCOMInstance(unknown,ptr);
JIString filePath = new JIString("c:/temp/test.doc");
JIVariant variant2[] = documents.callMethodA("open",new Object[]{new JIVariant(filePath,true),JIVariant.OPTIONAL_PARAM ,JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,
JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,
JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,
JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM,
JIVariant.OPTIONAL_PARAM,JIVariant.OPTIONAL_PARAM});
IJIDispatch document = (IJIDispatch)JIComFactory.createCOMInstance(unknown,variant2[0].getObjectAsInterfacePointer());

Please note that the behaviour of all APIs in this class accepting parameters is such that all inparams are converted to JIVariants before being sent to the COM server through the IJIDispatch interface. If the inparam is already a JIVariant , it is left as it is.
for example:-
//From MSADO example.
dispatch = (IJIDispatch)JIComFactory.createCOMInstance(JIComFactory.IID_IDispatch,unknown);
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...
}

This implicit conversion to JIVariant is NOT byReference. If the developer wishes to send that then he\she must put in a JIVariant with byRef flag set in the inparam array itself. Also, 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
          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.
 IJITypeInfo getTypeInfo(int typeInfo)
          Returns an j-Interop implementation of COM ITypeInfo interface based on the typeInfo .
 int getTypeInfoCount()
          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
call, call, getAssociatedSession, getInstanceLevelSocketTimeout, getInterfaceIdentifier, getInterfacePointer, getIpid, getUnreferencedHandler, isDispatchSupported, registerUnreferencedHandler, removeConnectionInfo, setInstanceLevelSocketTimeout, unregisterUnreferencedHandler
 
Methods inherited from interface org.jinterop.dcom.core.IJIUnknown
addRef, queryInterface, release
 

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
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
From MSDN:
Determines whether there is type information available for the dual interface.

Returns:
If the object provides type information, this number is 1; otherwise the number is 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:
int representing the DISPID.
Throws:
JIException

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

getTypeInfo

IJITypeInfo getTypeInfo(int typeInfo)
                        throws JIException
Returns an j-Interop implementation of COM ITypeInfo interface based on the typeInfo .

Parameters:
typeInfo -
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 getIdOfNames(name) and then delegates the call to put(int,JIVariant).

Parameters:
name - name of the method to invoke.
inparam - parameter for that method.
Throws:
JIException

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 getIdOfNames(name) and then delegates the call to putRef(int,JIVariant).

Parameters:
name - name of the method to invoke.
inparam - parameter for that method.
Throws:
JIException

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.
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 getIdOfNames(name) and then delegates the call to get(int,Object[]).inparams defines the parameters for the get operation.

Parameters:
name -
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)
              throws JIException
Performs a propget for the method identified by the name parameter. Internally it will first do a getIdOfNames(name) and then delegates the call to get(int).

Parameters:
name - name of the method to invoke.
Returns:
JIVariant result.
Throws:
JIException

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 getIdOfNames(name) and then delegates the call to callMethod(int).

Parameters:
name - name of the method to invoke.
Throws:
JIException

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 getIdOfNames(name) and then delegates the call to
callMethodA(int).

Parameters:
name - name of the method to invoke.
Returns:
JIVariant result.
Throws:
JIException

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 getIdOfNames(name) 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

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 getIdOfNames(name) 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

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 getIdOfNames(name) 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

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 getIdOfNames(name) 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:
JMeoVariant result.
Throws:
JIException

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:
JMeoVariant 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 getIdOfNames(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

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 getIdOfNames(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

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 getIdOfNames(name) and then delegates the call to put(int,Object[]).

Parameters:
name - name of the method to invoke.
params - parameters for that method.
Throws:
JIException

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 getIdOfNames(name) and then delegates the call to putRef(int,Object[]).

Parameters:
name - name of the method to invoke.
params - parameters for that method.
Throws:
JIException