org.jinterop.dcom.impls.automation.IJIDispatch Maven / Gradle / Ivy
/** j-Interop (Pure Java implementation of DCOM protocol)
* Copyright (C) 2006 Vikram Roopchand
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 3.0 of the License, or (at your option) any later version.
*
* Though a sincere effort has been made to deliver a professional,
* quality product,the library itself is distributed WITHOUT ANY WARRANTY;
* See the GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA
*/
package org.jinterop.dcom.impls.automation;
import org.jinterop.dcom.common.JIException;
import org.jinterop.dcom.core.IJIComObject;
import org.jinterop.dcom.core.JIVariant;
/**
* < p>
* 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
* {@link 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
*/
public interface IJIDispatch extends IJIComObject {
/**
* Flag for selecting a method.
*/
public final int DISPATCH_METHOD = 0xFFFFFFF1;
/**
* Flag for selecting a Property propget.
*/
public final int DISPATCH_PROPERTYGET = 0xFFFFFFF2; //(0x2 );
/**
* Flag for selecting a Property propput.
*/
public final int DISPATCH_PROPERTYPUT = 0xFFFFFFF4; //& (0x4 );
/**
* COM DISPID for property "put" or "putRef".
*/
public final int DISPATCH_DISPID_PUTPUTREF = 0xFFFFFFFD; //(0x4 | 0x8 | DISPATCH_METHOD);
/**
* Flag for selecting a Property propputref.
*/
public final int DISPATCH_PROPERTYPUTREF = 0xFFFFFFF8; //0x8
/**
* IID representing the COM IDispatch.
*/
public final String IID = "00020400-0000-0000-c000-000000000046";
/**
* Definition from MSDN:
* Determines whether there is type information available for the dual
* interface.
*
*
* @return 1 if the object provides type information, otherwise 0.
* @throws JIException
*/
public int getTypeInfoCount() 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.
*
* @param apiName Method name.
* @return DISPID of the method.
* @throws JIException
* @throws IllegalArgumentException if the apiName is
* null or empty.
*/
public 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.
*
* @param apiName String[] with first index depicting method name and the
* rest depicting parameters.
* @return int[] DISPIDs in the same order as the
* method[argument] set.
* @throws JIException
* @throws IllegalArgumentException if the apiName is
* null or empty.
*/
public int[] getIDsOfNames(String[] apiName) throws JIException;
/**
* Returns an implementation of COM ITypeInfo interface based
* on the typeInfo.
*
*
* @param typeInfo the type information to return. Pass 0 to retrieve type
* information for the IDispatch implementation.
* @return
* @throws JIException
*/
public IJITypeInfo getTypeInfo(int typeInfo) throws JIException;
/**
* Performs a propput for the method identified by the
* dispId.
*
* @param dispId DISPID of the method to invoke.
* @param inparam parameter for that method.
* @throws JIException
*/
public void put(int dispId, JIVariant inparam) throws JIException;
/**
* Performs a propput for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #put(int, JIVariant)}.
*
* @param name name of the method to invoke.
* @param inparam parameter for that method.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public void put(String name, JIVariant inparam) throws JIException;
/**
* Performs a propputref for the method identified by the
* dispId.
*
* @param dispId DISPID of the method to invoke.
* @param inparam parameter for that method.
* @throws JIException
*/
public void putRef(int dispId, JIVariant inparam) throws JIException;
/**
* Performs a propput for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #putRef(int, JIVariant)}.
*
* @param name name of the method to invoke.
* @param inparam parameter for that method.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public void putRef(String name, JIVariant inparam) throws JIException;
/**
* Performs a propget for the method identified by the
* dispId.
*
* @param dispId DISPID of the method to invoke.
* @return JIVariant result of the call
* @throws JIException
*/
public JIVariant get(int dispId) throws JIException;
/**
* Performs a propget for the method identified by the
* dispId parameter. inparams defines the
* parameters for the get operation.
*
* @param dispId DISPID of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @return array of JIVariants
* @throws JIException
*/
public JIVariant[] get(int dispId, Object[] inparams) throws JIException;
/**
* Performs a propget for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #get(int, Object[])}.
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @return array of JIVariants
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public 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
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #get(int)}
*
* @param name name of the method to invoke.
* @return JIVariant result of the call.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public JIVariant get(String name) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #callMethod(int)}.
*
*
* @param name name of the method to invoke.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public void callMethod(String name) throws JIException;
/**
* Performs a method call for the method identified by the
* dispId parameter.
*
* @param dispId DISPID of the method to invoke.
* @throws JIException
*/
public void callMethod(int dispId) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #callMethodA(int)}.
*
*
* @param name name of the method to invoke.
* @return JIVariant result.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public JIVariant callMethodA(String name) throws JIException;
/**
* Performs a method call for the method identified by the
* dispId parameter.
*
* @param dispId DISPID of the method to invoke.
* @return JIVariant result.
* @throws JIException
*/
public JIVariant callMethodA(int dispId) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #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.
*
* @param name name of the method to invoke.
* @param 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
* @throws IllegalArgumentException if the name is
* null or empty.
*/
//sequential dispIds for params are used 0,1,2,3...
public void callMethod(String name, Object[] inparams) throws JIException;
//sequential dispIds for params are used 0,1,2,3...
/**
* 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.
*
* @param dispId DISPID of the method to invoke.
* @param 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
*/
public void callMethod(int dispId, Object[] inparams) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #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.
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @return JIVariant[] result.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
//sequential dispIds for params are used 0,1,2,3...
public JIVariant[] callMethodA(String name, 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.
*
* @param dispId DISPID of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @return JIVariant[] result.
* @throws JIException
*/
//sequential dispIds for params are used 0,1,2,3...
public JIVariant[] callMethodA(int dispId, Object[] inparams) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #callMethod(int, Object[], int[])}. For the inparams
* array, the corresponding DISPIDs are present in the
* dispIds array. The size of both arrays should match.
*
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param dispIds array of DISPIDs , matching by index to those
* in inparams array.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
//inparams.length == dispIds.length.
public void callMethod(String name, 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.
*
*
* @param dispId DISPID of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param dispIds array of DISPIDs , matching by index to those
* in inparams array.
* @throws JIException
*/
//inparams.length == dispIds.length.
public void callMethod(int dispId, Object[] inparams, int[] dispIds) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #callMethodA(int, Object[], int[])}.For the inparams
* array, the corresponding DISPIDs are present in the
* dispId array. The size of both arrays should match.
*
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param dispIds array of DISPIDs , matching by index to those
* in inparams array.
* @return JIVariant[] result.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
//inparams.length == dispIds.length.
public JIVariant[] callMethodA(String name, 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.
*
* @param dispId DISPID of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param dispIds array of DISPIDs , matching by index to those
* in inparams array.
* @return JIVariant[] result.
* @throws JIException
*/
//inparams.length == dispIds.length.
public JIVariant[] callMethodA(int dispId, Object[] inparams, int[] dispIds) throws JIException;
/**
* Performs a method call for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String[])} by forming
* name + paramNames [], and then delegates the call to
* {@link #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.
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param paramNames Array of parameter names, matching by index to those in
* inparams array.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
// inparams.length == paramNames.length.
public 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
* {@link #getIDsOfNames(String[])} by forming
* name + paramNames [], and then delegates the call to
* {@link #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.
*
* @param name name of the method to invoke.
* @param inparams members of this array are implicitly converted to
* JIVariants before performing the actual call to the COM
* server, via the IJIDispatch interface.
* @param paramNames Array of parameter names, matching by index to those in
* inparams array.
* @return JIVariant result.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
//inparams.length == paramNames.length.
public JIVariant[] callMethodA(String name, Object[] inparams, String[] paramNames) throws JIException;
/**
* Performs a propput for the method identified by the
* dispId
*
* @param dispId DISPID of the method to invoke.
* @param params parameters for that method.
* @throws JIException
*/
public void put(int dispId, Object[] params) throws JIException;
/**
* Performs a propput for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #put(int, Object[])}.
*
* @param name name of the method to invoke.
* @param params parameters for that method.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public void put(String name, Object[] params) throws JIException;
/**
* Performs a propputref for the method identified by the
* dispId.
*
* @param dispId DISPID of the method to invoke.
* @param params parameters for that method.
* @throws JIException
*/
public void putRef(int dispId, Object[] params) throws JIException;
/**
* Performs a propput for the method identified by the
* name parameter. Internally it will first do a
* {@link #getIDsOfNames(String)} and then delegates the call to
* {@link #putRef(int, Object[])}.
*
* @param name name of the method to invoke.
* @param params parameters for that method.
* @throws JIException
* @throws IllegalArgumentException if the name is
* null or empty.
*/
public void putRef(String name, Object[] params) throws JIException;
/**
* Returns the COM EXCEPINFO structure wrapped as a data object
* for the
* last operation. Note this will only be valid if a
* {@link JIException} has been raised in the last call.
*
* @return
*/
public JIExcepInfo getLastExcepInfo();
}