org.jinterop.dcom.impls.automation.IJIDispatch Maven / Gradle / Ivy
The newest version!
/** 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;
/** 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();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy