org.jinterop.dcom.core
Class JICallObject

java.lang.Object
  extended by NdrObject
      extended by org.jinterop.dcom.core.JICallObject
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
JIUserCallObject

public class JICallObject
extends NdrObject
implements java.io.Serializable

This class is used to setup all the parameters (in and out) for the call to the COM server to be successfully executed.
Sample Usage:-
JICallObject obj = new JICallObject(handle.getIpid());
obj.reInit();
obj.setOpnum(94); //This needs to be obtained via IDL, Other wise use IJIDispatch if COM IDispatch
//interface is supported by the underlying COM Object.
obj.addInParamAsPointer(new JIPointer(new JIString("j-Interop Rocks",JIFlags.FLAG_REPRESENTATION_STRING_LPCTSTR)), JIFlags.FLAG_NULL);
obj.addInParamAsPointer(new JIPointer(new JIString("Pretty simple ;)",JIFlags.FLAG_REPRESENTATION_STRING_LPCTSTR)), JIFlags.FLAG_NULL);

//handle is previously obtained IJIComObject
Object[] result = handle.call(obj);

Please note that if values are expected back from the call, they should be added as outParams before the call(...) api is used.
obj.addOutParamAsType(JIVariant.class,JIFlags.FLAG_NULL);
obj.addOutParamAsObject(new JIPointer(Short.class,true),JIFlags.FLAG_NULL);

Note: Something odd that I have noticed, BSTR* and any second level Interface Pointer like IDispatch** , are always returned back to the callee. So when they are being used in inParams, please use them in outParams as well.

Since:
1.0

Constructor Summary
JICallObject(java.lang.String IPIDofParent)
           Creates a JICallObject associated with an Interface Identifier.
JICallObject(java.lang.String IPIDofParent, boolean dispatchNotSupported)
          Creates a JICallObject associated with an Interface Identifier.
 
Method Summary
 void addInParamAsArray(JIArray value, int FLAGS)
          Add IN parameter as JIArray at the end of the Parameter list.
 void addInParamAsBoolean(boolean value, int FLAGS)
          Add IN parameter as boolean at the end of the Parameter list.
 void addInParamAsCharacter(char value, int FLAGS)
          Add IN parameter as char at the end of the Parameter list.
 void addInParamAsDouble(double value, int FLAGS)
          Add IN parameter as double at the end of the Parameter list.
 void addInParamAsFloat(float value, int FLAGS)
          Add IN parameter as float at the end of the Parameter list.
 void addInParamAsInt(int value, int FLAGS)
          Add IN parameter as int at the end of the Parameter list.
 void addInParamAsInterfacePointer(JIInterfacePointer interfacePointer, int FLAGS)
          Add IN parameter as JIInterfacePointer at the end of the Parameter list.
 void addInParamAsObject(java.lang.Object value, int FLAGS)
          Add IN parameter as Object at the end of the Parameter list.
 void addInParamAsPointer(JIPointer value, int FLAGS)
          Add IN parameter as JIPointer at the end of the Parameter list.
 void addInParamAsShort(short value, int FLAGS)
          Add IN parameter as short at the end of the Parameter list.
 void addInParamAsString(java.lang.String value, int FLAGS)
          Add IN parameter as String at the end of the Parameter list.
 void addInParamAsStruct(JIStruct value, int FLAGS)
          Add IN parameter as JIStruct at the end of the Parameter list.
 void addInParamAsUnsigned(IJIUnsigned value, int FLAGS)
          Add IN parameter as IJIUnsigned at the end of the Parameter list.
 void addInParamAsUUID(java.lang.String value, int FLAGS)
          Add IN parameter as String representation of UUID at the end of the Parameter list.
 void addInParamAsVariant(JIVariant value, int FLAGS)
          Add IN parameter as JIVariant at the end of the Parameter list.
 void addOutParamAsObject(java.lang.Object outparam, int FLAGS)
          Add OUT parameter at the end of the out parameter list.
 void addOutParamAsType(java.lang.Class clazz, int FLAGS)
          Add OUT parameter of the type clazz at the end of the out parameter list.
 int getHRESULT()
          Returns the HRESULT of this operation.
 java.lang.Object getInParamAt(int index)
          Returns IN parameter at the specified index from the Parameter list.
 int getInparamFlags()
          Returns the In Param flag.
 java.lang.Object[] getInParams()
          Returns the entire IN parameters list.
 int getOpnum()
          Returns the opnum of the API which will be invoked at the COM server.
 java.lang.Object getOutParamAt(int index)
          Retrieves the OUT param at the index in the out parameters list.
 int getOutparamFlags()
          Returns the Out Param flag.
 java.lang.Object[] getOutParams()
          Returns the entire OUT parameters list.
 JIArray getResultAsArrayAt(int index)
          Returns the value as JIArray at the index from the result list.
 boolean getResultAsBooleanAt(int index)
          Returns the value as boolean at the index from the result list.
 char getResultAsCharacterAt(int index)
          Returns the value as char at the index from the result list.
 double getResultAsDoubleAt(int index)
          Returns the value as double at the index from the result list.
 float getResultAsFloatAt(int index)
          Returns the value as float at the index from the result list.
 int getResultAsIntAt(int index)
          Returns the value as int at the index from the result list.
 JIPointer getResultAsPointerAt(int index)
          Returns the value as JIPointer at the index from the result list.
 short getResultAsShortAt(int index)
          Returns the value as short at the index from the result list.
 JIString getResultAsStringAt(int index)
          Returns the value as JIString at the index from the result list.
 JIStruct getResultAsStructAt(int index)
          Returns the value as JIStruct at the index from the result list.
 java.lang.String getResultAsUUIDStrAt(int index)
          Returns the value as String representation of the UUID at the index from the result list.
 JIVariant getResultAsVariantAt(int index)
          Returns the value as JIVariant at the index from the result list.
 java.lang.Object[] getResults()
          Returns the results as an Object[].
 java.lang.Object[] getResultsInCaseOfException()
          Returns the results incase an exception occured.
 void insertInParamAsArrayAt(int index, JIArray value, int FLAGS)
          Add IN parameter as JIArray at the specified index in the Parameter list.
 void insertInParamAsBooleanAt(int index, boolean value, int FLAGS)
          Add IN parameter as boolean at the specified index in the Parameter list.
 void insertInParamAsCharacterAt(int index, char value, int FLAGS)
          Add IN parameter as char at the specified index in the Parameter list.
 void insertInParamAsDoubleAt(int index, double value, int FLAGS)
          Add IN parameter as double at the specified index in the Parameter list.
 void insertInParamAsFloatAt(int index, float value, int FLAGS)
          Add IN parameter as float at the specified index in the Parameter list.
 void insertInParamAsIntAt(int index, int value, int FLAGS)
          Add IN parameter as int at the specified index in the Parameter list.
 void insertInParamAsInterfacePointerAt(int index, JIInterfacePointer value, int FLAGS)
          Add IN parameter as JIInterfacePointer at the specified index in the Parameter list.
 void insertInParamAsObjectAt(int index, java.lang.Object value, int FLAGS)
          Add IN parameter as Object at the specified index in the Parameter list.
 void insertInParamAsPointerAt(int index, JIPointer value, int FLAGS)
          Add IN parameter as JIPointer at the specified index in the Parameter list.
 void insertInParamAsShortAt(int index, short value, int FLAGS)
          Add IN parameter as short at the specified index in the Parameter list.
 void insertInParamAsStringAt(int index, java.lang.String value, int FLAGS)
          Add IN parameter as String at the specified index in the Parameter list.
 void insertInParamAsStructAt(int index, JIStruct value, int FLAGS)
          Add IN parameter as JIStruct at the specified index in the Parameter list.
 void insertInParamAsUnsignedAt(int index, IJIUnsigned value, int FLAGS)
          Add IN parameter as IJIUnsigned at the specified index in the Parameter list.
 void insertInParamAsUUIDAt(int index, java.lang.String value, int FLAGS)
          Add IN parameter as String representation of UUID at the specified index in the Parameter list.
 void insertInParamAsVariantAt(int index, JIVariant value, int FLAGS)
          Add IN parameter as JIVariant at the specified index in the Parameter list.
 void insertOutParamAt(int index, java.lang.Object classOrInstance, int FLAGS)
          insert an OUT parameter at the specified index in the out parameter list.
 boolean isError()
          Returns true incase the Call resulted in an exception, use getHRESULT to get the error code.
 void reInit()
          Reinitialises all members of this object except the parent's IPID.
 void removeInParamAt(int index, int FLAGS)
          Removes IN parameter at the specified index from the Parameter list.
 void removeOutParamAt(int index, int FLAGS)
          Removes OUT parameter at the specified index from the out parameters list.
 void setInParams(java.lang.Object[] values, int FLAGS)
          Add IN parameter as Object[] at the end of the Parameter list.The array is iterated and all members appended to the list.
 void setOpnum(int num)
          Sets the opnum of the API which will be invoked at the COM server.
 void setOutParams(java.lang.Object[] values, int FLAGS)
          Add OUT parameter as Object[] at the end of the Parameter list.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JICallObject

public JICallObject(java.lang.String IPIDofParent,
                    boolean dispatchNotSupported)
Creates a JICallObject associated with an Interface Identifier.

Parameters:
IPIDofParent - Please use IJIComObject.getIpid() for this.
dispatchNotSupported - true if dispatch is not supported by the Interface, please use IJIComObject.isDispatchSupported()
to find out whether dispatch is supported on the parent or not.

JICallObject

public JICallObject(java.lang.String IPIDofParent)

Creates a JICallObject associated with an Interface Identifier. This ctor assumes that Dispatch is supported by the Interface.
Sample Usage:-
//handle is an IJIComObject obtained before
JICallObject obj = new JICallObject(handle.getIpid());

Parameters:
IPIDofParent - Please use IJIComObject.getIpid() for this.
Method Detail

reInit

public void reInit()
Reinitialises all members of this object except the parent's IPID. The Object is ready to be used again on a fresh IJIComObject.call(...) after this step.


addInParamAsInterfacePointer

public void addInParamAsInterfacePointer(JIInterfacePointer interfacePointer,
                                         int FLAGS)
Add IN parameter as JIInterfacePointer at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsInt

public void addInParamAsInt(int value,
                            int FLAGS)
Add IN parameter as int at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsUnsigned

public void addInParamAsUnsigned(IJIUnsigned value,
                                 int FLAGS)
Add IN parameter as IJIUnsigned at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsFloat

public void addInParamAsFloat(float value,
                              int FLAGS)
Add IN parameter as float at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsBoolean

public void addInParamAsBoolean(boolean value,
                                int FLAGS)
Add IN parameter as boolean at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsShort

public void addInParamAsShort(short value,
                              int FLAGS)
Add IN parameter as short at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsDouble

public void addInParamAsDouble(double value,
                               int FLAGS)
Add IN parameter as double at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsCharacter

public void addInParamAsCharacter(char value,
                                  int FLAGS)
Add IN parameter as char at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be)

addInParamAsString

public void addInParamAsString(java.lang.String value,
                               int FLAGS)
Add IN parameter as String at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (These HAVE to be the String Flags).

addInParamAsVariant

public void addInParamAsVariant(JIVariant value,
                                int FLAGS)
Add IN parameter as JIVariant at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

addInParamAsObject

public void addInParamAsObject(java.lang.Object value,
                               int FLAGS)
Add IN parameter as Object at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

addInParamAsUUID

public void addInParamAsUUID(java.lang.String value,
                             int FLAGS)
Add IN parameter as String representation of UUID at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

addInParamAsPointer

public void addInParamAsPointer(JIPointer value,
                                int FLAGS)
Add IN parameter as JIPointer at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

addInParamAsStruct

public void addInParamAsStruct(JIStruct value,
                               int FLAGS)
Add IN parameter as JIStruct at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

addInParamAsArray

public void addInParamAsArray(JIArray value,
                              int FLAGS)
Add IN parameter as JIArray at the end of the Parameter list.

Parameters:
value -
FLAGS - from JIFlags (if need be).

setInParams

public void setInParams(java.lang.Object[] values,
                        int FLAGS)
Add IN parameter as Object[] at the end of the Parameter list.The array is iterated and all members appended to the list.

Parameters:
values -
FLAGS - from JIFlags (if need be).

insertInParamAsInterfacePointerAt

public void insertInParamAsInterfacePointerAt(int index,
                                              JIInterfacePointer value,
                                              int FLAGS)
Add IN parameter as JIInterfacePointer at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsIntAt

public void insertInParamAsIntAt(int index,
                                 int value,
                                 int FLAGS)
Add IN parameter as int at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsUnsignedAt

public void insertInParamAsUnsignedAt(int index,
                                      IJIUnsigned value,
                                      int FLAGS)
Add IN parameter as IJIUnsigned at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsFloatAt

public void insertInParamAsFloatAt(int index,
                                   float value,
                                   int FLAGS)
Add IN parameter as float at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsBooleanAt

public void insertInParamAsBooleanAt(int index,
                                     boolean value,
                                     int FLAGS)
Add IN parameter as boolean at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsShortAt

public void insertInParamAsShortAt(int index,
                                   short value,
                                   int FLAGS)
Add IN parameter as short at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsDoubleAt

public void insertInParamAsDoubleAt(int index,
                                    double value,
                                    int FLAGS)
Add IN parameter as double at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsCharacterAt

public void insertInParamAsCharacterAt(int index,
                                       char value,
                                       int FLAGS)
Add IN parameter as char at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsStringAt

public void insertInParamAsStringAt(int index,
                                    java.lang.String value,
                                    int FLAGS)
Add IN parameter as String at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (These HAVE to be the String Flags).

insertInParamAsVariantAt

public void insertInParamAsVariantAt(int index,
                                     JIVariant value,
                                     int FLAGS)
Add IN parameter as JIVariant at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsObjectAt

public void insertInParamAsObjectAt(int index,
                                    java.lang.Object value,
                                    int FLAGS)
Add IN parameter as Object at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsUUIDAt

public void insertInParamAsUUIDAt(int index,
                                  java.lang.String value,
                                  int FLAGS)
Add IN parameter as String representation of UUID at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsPointerAt

public void insertInParamAsPointerAt(int index,
                                     JIPointer value,
                                     int FLAGS)
Add IN parameter as JIPointer at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsStructAt

public void insertInParamAsStructAt(int index,
                                    JIStruct value,
                                    int FLAGS)
Add IN parameter as JIStruct at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

insertInParamAsArrayAt

public void insertInParamAsArrayAt(int index,
                                   JIArray value,
                                   int FLAGS)
Add IN parameter as JIArray at the specified index in the Parameter list.

Parameters:
index - 0 based index
value -
FLAGS - from JIFlags (if need be).

removeInParamAt

public void removeInParamAt(int index,
                            int FLAGS)
Removes IN parameter at the specified index from the Parameter list.

Parameters:
index - 0 based index
FLAGS - from JIFlags (if need be).

getInParamAt

public java.lang.Object getInParamAt(int index)
Returns IN parameter at the specified index from the Parameter list.

Parameters:
index - 0 based index
Returns:
Primitives are returned as there Derieved types.

addOutParamAsType

public void addOutParamAsType(java.lang.Class clazz,
                              int FLAGS)
Add OUT parameter of the type clazz at the end of the out parameter list.

Parameters:
clazz -
FLAGS -

addOutParamAsObject

public void addOutParamAsObject(java.lang.Object outparam,
                                int FLAGS)
Add OUT parameter at the end of the out parameter list. Typically callers are
composite in nature JIStruct, JIUnions, JIPointer and JIString .

Parameters:
outparam -
FLAGS -

insertOutParamAt

public void insertOutParamAt(int index,
                             java.lang.Object classOrInstance,
                             int FLAGS)
insert an OUT parameter at the specified index in the out parameter list.

Parameters:
index - 0 based index
classOrInstance - can be either a Class or an Object
FLAGS -

getOutParamAt

public java.lang.Object getOutParamAt(int index)
Retrieves the OUT param at the index in the out parameters list.

Parameters:
index - 0 based index
Returns:

removeOutParamAt

public void removeOutParamAt(int index,
                             int FLAGS)
Removes OUT parameter at the specified index from the out parameters list.

Parameters:
index - 0 based index
FLAGS - from JIFlags (if need be).

setOutParams

public void setOutParams(java.lang.Object[] values,
                         int FLAGS)
Add OUT parameter as Object[] at the end of the Parameter list. The array is iterated and all members appended to the list.

Parameters:
values -
FLAGS - from JIFlags (if need be).

getResults

public java.lang.Object[] getResults()
Returns the results as an Object[]. This array has to be iterated over to get the individual values.


getResultAsIntAt

public int getResultAsIntAt(int index)
Returns the value as int at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsFloatAt

public float getResultAsFloatAt(int index)
Returns the value as float at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsBooleanAt

public boolean getResultAsBooleanAt(int index)
Returns the value as boolean at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsShortAt

public short getResultAsShortAt(int index)
Returns the value as short at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsDoubleAt

public double getResultAsDoubleAt(int index)
Returns the value as double at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsCharacterAt

public char getResultAsCharacterAt(int index)
Returns the value as char at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsStringAt

public JIString getResultAsStringAt(int index)
Returns the value as JIString at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsVariantAt

public JIVariant getResultAsVariantAt(int index)
Returns the value as JIVariant at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsUUIDStrAt

public java.lang.String getResultAsUUIDStrAt(int index)
Returns the value as String representation of the UUID at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsPointerAt

public JIPointer getResultAsPointerAt(int index)
Returns the value as JIPointer at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsStructAt

public JIStruct getResultAsStructAt(int index)
Returns the value as JIStruct at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultAsArrayAt

public JIArray getResultAsArrayAt(int index)
Returns the value as JIArray at the index from the result list.

Parameters:
index - 0 based index
Returns:

getResultsInCaseOfException

public java.lang.Object[] getResultsInCaseOfException()
Returns the results incase an exception occured.

Returns:

getHRESULT

public int getHRESULT()
Returns the HRESULT of this operation. This should be zero for successful calls and non-zero for failures.

Returns:

getInParams

public java.lang.Object[] getInParams()
Returns the entire IN parameters list.

Returns:

getOutParams

public java.lang.Object[] getOutParams()
Returns the entire OUT parameters list.

Returns:

getInparamFlags

public int getInparamFlags()
Returns the In Param flag.

Returns:

getOutparamFlags

public int getOutparamFlags()
Returns the Out Param flag.

Returns:

getOpnum

public int getOpnum()
Returns the opnum of the API which will be invoked at the COM server.


setOpnum

public void setOpnum(int num)
Sets the opnum of the API which will be invoked at the COM server. This is a 0 based index. Refer to the IDL of the COM server for this, all APIs are listed in a sequential order starting from 0. Please ignore the "Id" they might be having and count the index of the API being called here from the beginning of the interface starting from 0 as the first index. Also note that if this interface derieves from anything other than IUnknown or IDispatch, your start index will change from 0 to the cumulative(if that interface is also a derieved one) count of the super interface. For e.g if A(3 apis) derieves from B (10 apis), then first API of A is at Opnum of 3, second at 4 and so on. Alternatively, you can use the IJIDispatch interface, if the object supports it.


isError

public boolean isError()
Returns true incase the Call resulted in an exception, use getHRESULT to get the error code.

Returns: