The Dispach Class of the com.ms.com package enables Java programs to invoke methods and access the properties of any Microsoft® ActiveX® Automation object. (ActiveX Automation objects are ActiveX components that support the IDispatch interface.) Methods in the Dispatch class are static; it is never necessary to instantiate this class.
public class Dispatch { // Fields public static final int DISPID_ABOUTBOX; public static final int DISPID_AMBIENT_APPEARANCE; public static final int DISPID_AMBIENT_AUTOCLIP; public static final int DISPID_AMBIENT_BACKCOLOR; public static final int DISPID_AMBIENT_CHARSET; public static final int DISPID_AMBIENT_CODEPAGE; public static final int DISPID_AMBIENT_DISPLAYASDEFAULT; public static final int DISPID_AMBIENT_DISPLAYNAME; public static final int DISPID_AMBIENT_FONT; public static final int DISPID_AMBIENT_FORECOLOR; public static final int DISPID_AMBIENT_LOCALEID; public static final int DISPID_AMBIENT_MESSAGEREFLECT; public static final int DISPID_AMBIENT_PALETTE; public static final int DISPID_AMBIENT_SCALEUNITS; public static final int DISPID_AMBIENT_SHOWGRABHANDLES; public static final int DISPID_AMBIENT_SHOWHATCHING; public static final int DISPID_AMBIENT_SUPPORTSMNEMONICS; public static final int DISPID_AMBIENT_TEXTALIGN; public static final int DISPID_AMBIENT_TRANSFERPRIORITY; public static final int DISPID_AMBIENT_UIDEAD; public static final int DISPID_AMBIENT_USERMODE; public static final int DISPID_APPEARANCE; public static final int DISPID_AUTOSIZE; public static final int DISPID_BACKCOLOR; public static final int DISPID_BACKSTYLE; public static final int DISPID_BORDERCOLOR; public static final int DISPID_BORDERSTYLE; public static final int DISPID_BORDERVISIBLE; public static final int DISPID_BORDERWIDTH; public static final int DISPID_CAPTION; public static final int DISPID_CLICK; public static final int DISPID_COLLECT; public static final int DISPID_CONSTRUCTOR; public static final int DISPID_DBLCLICK; public static final int DISPID_DESTRUCTOR; public static final int DISPID_DOCLICK; public static final int DISPID_DRAWMODE; public static final int DISPID_DRAWSTYLE; public static final int DISPID_DRAWWIDTH; public static final int DISPID_ENABLED; public static final int DISPID_ERROREVENT; public static final int DISPID_EVALUATE; public static final int DISPID_FILLCOLOR; public static final int DISPID_FILLSTYLE; public static final int DISPID_FONT; public static final int DISPID_FORECOLOR; public static final int DISPID_HWND; public static final int DISPID_KEYDOWN; public static final int DISPID_KEYPRESS; public static final int DISPID_KEYUP; public static final int DISPID_MOUSEDOWN; public static final int DISPID_MOUSEICON; public static final int DISPID_MOUSEMOVE; public static final int DISPID_MOUSEPOINTER; public static final int DISPID_MOUSEUP; public static final int DISPID_NEWENUM; public static final int DISPID_PICTURE; public static final int DISPID_PROPERTYPUT; public static final int DISPID_READYSTATE; public static final int DISPID_READYSTATECHANGE; public static final int DISPID_REFRESH; public static final int DISPID_TABSTOP; public static final int DISPID_TEXT; public static final int DISPID_UNKNOWN; public static final int DISPID_VALID; public static final int DISPID_VALUE; public static final int fdexNameCaseSensitive; public static final int Get; public static final int LOCALE_SYSTEM_DEFAULT; public static final int Method; public static final int Put; public static final int PutRef; // Methods public static Variant call(Object pDispatch, String dispName); public static Variant call(Object pDispatch, String dispName, Object o0); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6); public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7); public static Variant call(Object pDispatch, int dispid); public static Variant call(Object pDispatch, int dispid, Object o0); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6); public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7); public static Variant callN(Object pDispatch, String dispName, Object oArg[]); public static Variant callN(Object pDispatch, int dispid, Object oArg[]); public static Variant callN_casesensitive(Object pDispatch, String dispName, Object oArg[]); public static void callSub(Object pDispatch, String dispName); public static void callSub(Object pDispatch, String dispName, Object o0); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6); public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7); public static void callSub(Object pDispatch, int dispid); public static void callSub(Object pDispatch, int dispid, Object o0); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6); public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7); public static void callSubN(Object pDispatch, String dispName, Object oArg[]); public static void callSubN(Object pDispatch, int dispid, Object oArg[]); public static Variant get(Object pDispatch, String dispName); public static Variant get(Object pDispatch, int dispid); public static Variant get_casesensitive(Object pDispatch, String dispName); public static int getIDOfName(Object pDispatch, String dispName); public static int[] getIDsOfNames(Object pDispatch, _Guid iid, int lcid, String dispNames[]); public static Variant invoke(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[]); public static Variant invoke(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[]); public static Variant invoke(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[]); public static void invokeSub(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[]); public static void invokeSub(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[]); public static void invokeSub(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[]); public static void invokeSubv(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[]); public static void invokeSubv(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[]); public static void invokeSubv(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[]); public static Variant invokev(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[]); public static Variant invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[], int wFlagsEx); public static Variant invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[]); public static Variant invokev(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[]); public static void put(Object pDispatch, String dispName, Object val); public static void put(Object pDispatch, int dispid, Object val); public static void put_casesensitive(Object pDispatch, String dispName, Object val); public static void putRef(Object pDispatch, String dispName, Object val); public static void putRef(Object pDispatch, int dispid, Object val); }
Although the Dispatch Class includes a large number of methods, three basic methods define its capabilities.
Maps methods or property names to dispids.
Invokes methods or accesses properties.
Invokes subroutines.
If one of these methods does not accomplish a given task, neither will any of the other methods in the Dispatch class. Each of the other methods in the class has the same function as one of the three basic methods; however, each of the other methods supplies (wraps) commonly used default parameters for ease of use.
The following table describes the parameters required by the invokev and invokeSubv methods and specifies default values that aren't mentioned in the wrapper method documentation.
Object pDispatch | Either a Java object that wraps an ActiveX Automation object or a Variant object that can be coerced to such an object by the Variant.toDispatch method. There is no default value for this parameter; every wrapper method requires it. |
_Guid iid | The IID of the interface that is invoked. (The interface must derive from IDispatch.) If the value is missing or null, the value of IID_IDispatch is used. |
String dispName | The name of the method or property that is invoked. If the value is null, dispID is used to determine the method or property. |
int dispID | Indicates the method or property that is invoked. This parameter is ignored if dispName is null. |
int lcid | Indicates the locale identifier. Wrapper methods automatically pass Dispatch.LOCALE_SYSTEM_DEFAULT for this value. |
int wFlags | Indicates the type of access: must be Dispatch.Method, Dispatch.Get, Dispatch.Put or Dispatch.PutRef. Most of the wrapper methods provide a fixed access that is indicated by the method name: Get methods default to DISPATCH_PROPERTYGET; Put methods default to DISPATCH_PROPERTYPUT; Call methods default to DISPATCH_METHOD. |
Variant vArg | The parameters of the method or property accessor. No default value. |
int uArgErr[] | If the Automation object rejects a parameter, this array receives the index of the offending parameter; it must be null or a one-element integer array. |
Most wrapper methods accept objects other than Variant objects. These objects are converted to the appropriate variant type according to the rules shown in the following table.
Original Type | Converted Type |
null | Converted to VT_EMPTY. |
Variant | Passed as is. |
Integer | Converted to VT_I4. |
String | Converted to VT_BSTR. |
Boolean | Converted to VT_BOOL. |
Double | Converted to VT_R8. |
Float | Converted to VT_R4. |
SafeArray | Converted to VT_BYREF|VT_ARRAY|*. |
other | Converted to VT_DISPATCH. |