Top Description Fields Constructors Methods
com.sun.jna.platform.win32.COM.util

public Class ProxyObject

extends Object
implements InvocationHandler, IDispatch, IRawDispatchHandle, IConnectionPoint
Class Inheritance
All Implemented Interfaces
com.sun.jna.platform.win32.COM.util.IConnectionPoint, com.sun.jna.platform.win32.COM.util.IRawDispatchHandle, com.sun.jna.platform.win32.COM.util.IDispatch, com.sun.jna.platform.win32.COM.util.IUnknown, java.lang.reflect.InvocationHandler
Imports
java.lang.reflect.InvocationHandler, .InvocationTargetException, .Proxy, com.sun.jna.Pointer, .WString, com.sun.jna.internal.ReflectionUtils, com.sun.jna.platform.win32.Guid, .Guid.IID, .Guid.REFIID, .Kernel32Util, .OaIdl, .OaIdl.DISPID, .OaIdl.DISPIDByReference, .OaIdl.EXCEPINFO, .OleAuto, .OleAuto.DISPPARAMS, .Variant, .Variant.VARIANT, .WinDef, .WinDef.DWORDByReference, .WinNT, .WinNT.HRESULT, com.sun.jna.platform.win32.COM.COMException, .COMUtils, .ConnectionPoint, .ConnectionPointContainer, .Dispatch, .IDispatch, .IDispatchCallback, com.sun.jna.platform.win32.COM.util.annotation.ComInterface, .ComMethod, .ComProperty, com.sun.jna.ptr.IntByReference, .PointerByReference

This object acts as the invocation handler for interfaces annotated with ComInterface. It wraps all (necessary) low level COM calls and dispatches them through the COM runtime.

The caller of the methods is responsible for correct initialization of the COM runtime and appropriate thread-handling - depending on the choosen handling model.

See Also
MSDN - Processes, Threads, and Apartments, MSDN - Understanding and Using COM Threading Models

Field Summary

Modifier and TypeField and Description
private final ObjectFactory
private final IDispatch
private final Class<?>
private long

Constructor Summary

AccessConstructor and Description
public
ProxyObject(Class<?> theInterface, IDispatch rawDispatch, ObjectFactory factory)

Method Summary

Modifier and TypeMethod and Description
public IComEventCallbackCookie
advise(Class<?>
- the COM interface that the listener will receive events from
comEventCallbackInterface
,
final IComEventCallbackListener
- and object that will receive the callback events
comEventCallbackListener
)

Implements com.sun.jna.platform.win32.COM.util.IConnectionPoint.advise.

Set up the comEventCallbackListener to receive callback events from the target COM object
public synchronized void
public boolean
equals(Object
the reference object with which to compare.
arg
)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.
private ConnectionPoint
protected void
finalize()

Overrides java.lang.Object.finalize.

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
private String
private Guid.IID
getIID(ComInterface annotation)

private String
private String
public <T> T
public <T> T
public IDispatch
private long
public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the object.
public Object
invoke(final Object
the proxy instance that the method was invoked on
proxy
,
final Method
the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.
method
,
final Object[]
an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.
args
)

Implements java.lang.reflect.InvocationHandler.invoke.

Processes a method invocation on a proxy instance and returns the result.
public <T> T
public <T> T
protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name, Variant.VARIANT pArg)

protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, OaIdl.DISPID dispId, Variant.VARIANT pArg)

protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name)

protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, OaIdl.DISPID dispId)

protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name, Variant.VARIANT[] pArgs)

protected WinNT.HRESULT
oleMethod(final int nType, final Variant.VARIANT.ByReference pvResult, final OaIdl.DISPID dispId, Variant.VARIANT[] pArgs)

protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, String name, Variant.VARIANT pArg)

Deprecated
protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, OaIdl.DISPID dispId, Variant.VARIANT pArg)

Deprecated
protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, String name)

Deprecated
protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, OaIdl.DISPID dispId)

Deprecated
protected WinNT.HRESULT
oleMethod(int nType, Variant.VARIANT.ByReference pvResult, final IDispatch pDisp, String name, Variant.VARIANT[] pArgs)

Deprecated
protected WinNT.HRESULT
oleMethod(final int nType, final Variant.VARIANT.ByReference pvResult, final IDispatch pDisp, final OaIdl.DISPID dispId, Variant.VARIANT[] pArgs)

Deprecated
public <T> T
queryInterface(Class<T> comInterface)

Implements com.sun.jna.platform.win32.COM.util.IUnknown.queryInterface.

Returns a proxy object for the given interface.
protected OaIdl.DISPID
protected OaIdl.DISPID
resolveDispId(final IDispatch pDisp, String name)

Deprecated
public <T> void
public <T> void
private void
private void
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public void
unadvise(Class<?>
- the interface that is being listened to
comEventCallbackInterface
,
final IComEventCallbackCookie
- the cookie that was returned when advise was called
cookie
)

Implements com.sun.jna.platform.win32.COM.util.IConnectionPoint.unadvise.

Stop listening for callback events
private Object[]
unfoldWhenVarargs(Method method, Object[] argParams)

Inherited from java.lang.Object:
clonegetClassnotifynotifyAllwaitwaitwait

Field Detail

factoryback to summary
private final ObjectFactory factory
rawDispatchback to summary
private final IDispatch rawDispatch
theInterfaceback to summary
private final Class<?> theInterface
unknownIdback to summary
private long unknownId

Constructor Detail

ProxyObjectback to summary
public ProxyObject(Class<?> theInterface, IDispatch rawDispatch, ObjectFactory factory)
Annotations
@SuppressWarnings:LeakingThisInConstructor

Method Detail

adviseback to summary
public IComEventCallbackCookie advise(Class<?> comEventCallbackInterface, final IComEventCallbackListener comEventCallbackListener) throws COMException

Implements com.sun.jna.platform.win32.COM.util.IConnectionPoint.advise.

Doc from com.sun.jna.platform.win32.COM.util.IConnectionPoint.advise.

Set up the comEventCallbackListener to receive callback events from the target COM object

Parameters
comEventCallbackInterface:Class<?>

- the COM interface that the listener will receive events from

comEventCallbackListener:IComEventCallbackListener

- and object that will receive the callback events

Returns:IComEventCallbackCookie

- a cookie that can be used to detach (unadvise) the event callback listener throws COMException if an error occurs trying to set up the listener on the target COM object, see exception cause for details.

Annotations
@Override
disposeback to summary
public synchronized void dispose()
equalsback to summary
public boolean equals(Object arg)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
arg:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
fetchRawConnectionPointback to summary
private ConnectionPoint fetchRawConnectionPoint(Guid.IID iid)
finalizeback to summary
protected void finalize() throws Throwable

Overrides java.lang.Object.finalize.

Doc from java.lang.Object.finalize.

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

When running in a Java virtual machine in which finalization has been disabled or removed, the garbage collector will never call finalize(). In a Java virtual machine in which finalization is enabled, the garbage collector might call finalize only after an indefinite delay.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Annotations
@Override
Exceptions
Throwable:
the Exception raised by this method
getAccessorNameback to summary
private String getAccessorName(Method method, ComProperty prop)
getIIDback to summary
private Guid.IID getIID(ComInterface annotation)
getMethodNameback to summary
private String getMethodName(Method method, ComMethod meth)
getMutatorNameback to summary
private String getMutatorName(Method method, ComProperty prop)
getPropertyback to summary
public <T> T getProperty(Class<T> returnType, String name, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.getProperty.

Annotations
@Override
getPropertyback to summary
public <T> T getProperty(Class<T> returnType, OaIdl.DISPID dispID, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.getProperty.

Annotations
@Override
getRawDispatchback to summary
public IDispatch getRawDispatch()

Implements com.sun.jna.platform.win32.COM.util.IRawDispatchHandle.getRawDispatch.

Annotations
@Override
getUnknownIdback to summary
private long getUnknownId()
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object.

Annotations
@Override
invokeback to summary
public Object invoke(final Object proxy, final Method method, final Object[] args) throws Throwable

Implements java.lang.reflect.InvocationHandler.invoke.

Doc from java.lang.reflect.InvocationHandler.invoke.

Processes a method invocation on a proxy instance and returns the result. This method will be invoked on an invocation handler when a method is invoked on a proxy instance that it is associated with.

Parameters
proxy:Object

the proxy instance that the method was invoked on

method:Method

the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

args:Object[]

an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.

Returns:Object

the value to return from the method invocation on the proxy instance. If the declared return type of the interface method is a primitive type, then the value returned by this method must be an instance of the corresponding primitive wrapper class; otherwise, it must be a type assignable to the declared return type. If the value returned by this method is null and the interface method's return type is primitive, then a NullPointerException will be thrown by the method invocation on the proxy instance. If the value returned by this method is otherwise not compatible with the interface method's declared return type as described above, a ClassCastException will be thrown by the method invocation on the proxy instance.

Annotations
@Override
Exceptions
Throwable:
the exception to throw from the method invocation on the proxy instance. The exception's type must be assignable either to any of the exception types declared in the throws clause of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error. If a checked exception is thrown by this method that is not assignable to any of the exception types declared in the throws clause of the interface method, then an UndeclaredThrowableException containing the exception that was thrown by this method will be thrown by the method invocation on the proxy instance.
invokeMethodback to summary
public <T> T invokeMethod(Class<T> returnType, String name, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.invokeMethod.

Annotations
@Override
invokeMethodback to summary
public <T> T invokeMethod(Class<T> returnType, OaIdl.DISPID dispID, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.invokeMethod.

Annotations
@Override
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name, Variant.VARIANT pArg) throws COMException
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, OaIdl.DISPID dispId, Variant.VARIANT pArg) throws COMException
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name) throws COMException
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, OaIdl.DISPID dispId) throws COMException
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, String name, Variant.VARIANT[] pArgs) throws COMException
oleMethodback to summary
protected WinNT.HRESULT oleMethod(final int nType, final Variant.VARIANT.ByReference pvResult, final OaIdl.DISPID dispId, Variant.VARIANT[] pArgs) throws COMException
Annotations
@SuppressWarnings:deprecation
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, String name, Variant.VARIANT pArg) throws COMException

Deprecated

Annotations
@Deprecated
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, OaIdl.DISPID dispId, Variant.VARIANT pArg) throws COMException

Deprecated

Annotations
@Deprecated
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, String name) throws COMException

Deprecated

Annotations
@Deprecated
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, IDispatch pDisp, OaIdl.DISPID dispId) throws COMException

Deprecated

Annotations
@Deprecated
oleMethodback to summary
protected WinNT.HRESULT oleMethod(int nType, Variant.VARIANT.ByReference pvResult, final IDispatch pDisp, String name, Variant.VARIANT[] pArgs) throws COMException

Deprecated

Annotations
@Deprecated
oleMethodback to summary
protected WinNT.HRESULT oleMethod(final int nType, final Variant.VARIANT.ByReference pvResult, final IDispatch pDisp, final OaIdl.DISPID dispId, Variant.VARIANT[] pArgs) throws COMException

Deprecated

Annotations
@Deprecated
queryInterfaceback to summary
public <T> T queryInterface(Class<T> comInterface) throws COMException

Implements com.sun.jna.platform.win32.COM.util.IUnknown.queryInterface.

Doc from com.sun.jna.platform.win32.COM.util.IUnknown.queryInterface.

Returns a proxy object for the given interface. Assuming that the interface is annotated with a ComInterface annotation that provides a valid iid.

Will throw COMException if an error occurs trying to retrieve the requested interface, see exception cause for details.

Annotations
@Override
resolveDispIdback to summary
protected OaIdl.DISPID resolveDispId(String name)
Annotations
@SuppressWarnings:deprecation
resolveDispIdback to summary
protected OaIdl.DISPID resolveDispId(final IDispatch pDisp, String name)

Deprecated

Annotations
@Deprecated
setPropertyback to summary
public <T> void setProperty(String name, T value)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.setProperty.

Annotations
@Override
setPropertyback to summary
public <T> void setProperty(OaIdl.DISPID dispId, T value)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.setProperty.

Annotations
@Override
setPropertyback to summary
private void setProperty(String name, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.setProperty.

setPropertyback to summary
private void setProperty(OaIdl.DISPID dispID, Object... args)

Implements com.sun.jna.platform.win32.COM.util.IDispatch.setProperty.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
unadviseback to summary
public void unadvise(Class<?> comEventCallbackInterface, final IComEventCallbackCookie cookie) throws COMException

Implements com.sun.jna.platform.win32.COM.util.IConnectionPoint.unadvise.

Doc from com.sun.jna.platform.win32.COM.util.IConnectionPoint.unadvise.

Stop listening for callback events

Parameters
comEventCallbackInterface:Class<?>

- the interface that is being listened to

cookie:IComEventCallbackCookie

- the cookie that was returned when advise was called

Annotations
@Override
unfoldWhenVarargsback to summary
private Object[] unfoldWhenVarargs(Method method, Object[] argParams)