The @com.method directive specifies how a COM object method is mapped between Java and COM. It supplies a set of directive parameters that indicate the mapping to the equivalent Microsoft Interface Definition Language (MIDL) form.
@com.method([vtoffset=integer | long], [dispid=integer | long], [name=string], [name2=string], [type=METHOD | PROPGET | PROPPUT | PROPPUTREF], [thread=AUTO | NO], [nodispatch], [returntype=VOID | HRESULT], [addFlagsVtable=integer], [addFlagsDispatch=integer])
vtoffset=integer | long | Specifies the vtable offset for this method, not counting the methods in IUnknown. Thus, the first method in an interface has an offset of zero, the second method has an offset of one, and so on.
Dependency: Used only for custom (vtable) and dual interfaces. Default: The method's index within the COM methods in the Java interface (that is, those methods with @com.method directives). |
dispid=integer | long | Indicates the dispatch ID (DISPID) for this method
Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: The method’s index within the COM methods in the Java interface (that is, those methods with @com.method directives). |
name=string | Specifies how to expose this Java method to COM by means of IDispatch. The Microsoft VM implements a dispatch interface that maps the name given by this parameter to the dispatch ID given by the dispid parameter.
Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: The method's name. |
name2=string | Specifies a secondary mapping from this Java method to COM by means of IDispatch. The Microsoft VM implements a dispatch interface that maps the name given by this parameter to the dispatch ID given by the dispid parameter.
Dependency: Used only for methods that will be members of a dispatch or dual interface. |
type=METHOD | PROPGET | PROPPUT | PROPPUTREF | Indicates the dispatch invocation type of the Java method. It can be for manipulating COM object properties or an actual COM object method. The semantics of each possible value are directly related to those of the corresponding DISPATCH_* flag used in calls to IDispatch::Invoke.
Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: METHOD. |
thread=AUTO | NO | Specifies the default Microsoft VM marshaling behavior to be applied to any COM object parameters (type=DISPATCH or type=OBJECT in the @com.parameters directive) in this method. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on these objects to the thread that the object was created in, which is the thread that originally received the object. This is the safest option, and the default.
If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread. Default: AUTO. |
nodispatch | Specifies that this method should not be accessible from a dispatch interface. |
returntype=VOID | HRESULT | Specifies the return type for this method. Generally, the default, HRESULT, is used. If specified, the COM method associated with this Java method returns an HRESULT. The Microsoft VM hides this fact by mapping HRESULT values other than S_OK to instances of com.ms.com.ComException, and vice versa. If the Java method returns a value, it is mapped to the last parameter in the COM method, which is assumed to be a return value.
If VOID is specified, the Java and COM method return values are directly related. For instance, if the COM method returns an integer value, the Java method will return this same integer value. Dependency: Used only for methods that will be members of a vtable or dual interface. Default: HRESULT. |
addFlagsDispatch=integer | A low-level parameter that allows direct modification of created class attributes. The value is truncated to a WORD (2 bytes) and then combined with the Flags field of the MCFuncDesc attribute that will get created for the dispatch method.
Dependency: Used only for methods that will be members of a dispatch or dual interface. |
addFlagsVtable=integer
Example: addFlagsVtable=4 |
A low-level parameter that allows direct modification of created class attributes. The value is truncated to a WORD (2 bytes) and then combined with the Flags field of the MCFuncDesc attribute that will get created for the vtable method. Specify the value 4 to cause the Microsoft VM to ignore non-failing HRESULT values. The VM will still throw a ComFailException for failing HRESULT values, but will not throw a ComSuccessException for successful HRESULT values.
Dependency: Used only for methods that will be members of a vtable or dual interface. |
COM_ProxiesTo | Method scope. |
COM_ExposedAs_Group | Method scope. |
COM_GuidPool | Class scope. |
COM_MethodPool | Class scope. |
To express iid_is and size_is from an @com directive, declare methods as follows:
/** @com.method(...) @com.parameters([in,type=PTR] riid, [customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] return) */ public IUnknown BindToObject(_Guid riid); /** @com.method(...) @com.parameters([in,type=U4] length, [in,out,customMarshal="com.ms.com.SizeIsMarshaler",type=CUSTOM] items) */ public void GetItems(int length, int[] items);
See the sample in Samples\com\iidis_sizeis for more information.
A good way to learn how IDL descriptions are mapped to @com directives is to look at the generated Java wrappers from Jactivex and the IDL notation from oleview and compare the outputs. This is easily accomplished by picking a COM dynamic-link library (DLL), like Shdocvw.dll, and generating wrappers as follows:
jactivex shdocvw.dll
Use oleview to view the IDL representation of the COM objects and interfaces within Shdocvw.dll:
oleview shdocvw.dll
This is a representation of IDL and Java code that illustrates how a property from a dual interface is mapped to @com.method directives.
Here is how the Count method of the IShellWindows interface looks in the OLE/COM Object Viewer:
[id(0x60020000), propget, helpstring("Get count of open Shell windows")] HRESULT Count([out, retval] long* Count);
Here is how jactivex maps IShellWindows.Count to @com.method and @com.parameters directives:
/** @com.method(vtoffset=4, dispid=1610743808, type=PROPGET, name="Count", addFlagsVtable=4) */ /**@com.parameters([type=I4] return) */ public int getCount();
iid_is and size_is Support
%SDKDIR%\Samples\com\iid_is_size_is