forked from kohsuke/com4j
-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathCom4jObject.java
More file actions
142 lines (130 loc) · 4.64 KB
/
Com4jObject.java
File metadata and controls
142 lines (130 loc) · 4.64 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
package com4j;
/**
* Root of all the com4j interfaces.
*
* <p>
* Java interfaces mapped from COM interfaces always derive from this
* interface directly/indirectly. This interface provides methods
* that are common to all the COM interfaces.
*
* @author Kohsuke Kawaguchi (kk@kohsuke.org)
*/
@IID("{00000000-0000-0000-C000-000000000046}")
public interface Com4jObject {
/**
* Tests the identity of two COM objects.
*
* <p>
* This consists of doing <tt>IUnknown::QueryInterface</tt> on
* two interfaces and test the bit image of the resulting <tt>IUnknown*</tt>.
*
* <p>
* If one COM object implements two interfaces, in Java
* you see them as two different objects. Thus you
* cannot rely on <tt>==</tt> to check if they represent
* the same COM object.
*
* @param o the other {@link Com4jObject}
* @return true if the IUnknown pointer of the two objects are equal
*/
boolean equals(Object o);
/**
* Hash code consistent with {@link #equals(java.lang.Object)} }.
*
* <p>
* This method queries the <tt>IUnknown*</tt> value to the wrapped
* COM object and returns its pointer bit image as integer.
*
* <p>
* The net result is that the identity of {@link Com4jObject} is based
* on the identity of the underlying COM objects. Two {@link Com4jObject}
* that are holding different interfaces of the same COM object is
* considered "equal".
*
* @return The hash coded for this {@link Com4jObject}
*/
int hashCode();
/**
* Returns the interface pointer as an integer
* @return the interface pointer of this object.
*
* @deprecated 64bit unasfe.
*/
int getPtr();
/**
* Returns the interface pointer as an integer
*/
long getPointer();
/**
* QueryInterface to IUnknown and return its raw pointer value.
* This is the object identity in COM.
*/
long getIUnknownPointer();
/**
* Every Com4jObject has a ComThread that is running handling all the calls to this object. This method has to return that thread.
* @return the ComThread handling all the calls to this object.
*/
ComThread getComThread();
/**
* Prints the raw interface pointer that this object represents.
*
* @return a String representation of this object.
*/
String toString();
/**
* Releases a reference to the wrapped COM object.
*
* <p>
* Since Java objects tend to live longer in memory until it's GC-ed,
* and applications have generally no control over when it's GC-ed,
* calling the dispose method earlier enables applications to dispose
* the COM objects deterministically.
*/
void dispose();
/**
* Checks if this COM object implements a given interface.
*
* <p>
* This is just a convenience method that behaves as follows:
* <pre>
* return queryInterface(comInterface)!=null;
* </pre>
*
* @param comInterface The class object of the Com4J interface
* @param <T> the type of the interface class object
* @return true if the wrapped COM object implements a given interface.
*/
<T extends Com4jObject> boolean is( Class<T> comInterface );
/**
* Invokes the queryInterface of the wrapped COM object and attempts
* to obtain a different interface of the same object.
*
* @param <T> the type of the interface class object
* @param comInterface the class object of the requested Com4J interface
* @return a reference to the requested interface or null if the queryInterface fails.
*/
<T extends Com4jObject> T queryInterface( Class<T> comInterface );
/**
* Subscribes to the given event interface of this object.
*
* @param eventInterface The event interface definition. This interface/class
* has to have an {@link IID} annotation that designates
* the event interface GUID, and also methods annotated with
* {@link DISPID} that designates what methods are event methods.
* Must not be null.
*
* @param receiver The object that receives events.
*
* @param <T> the type of the eventInterface class object.
* @throws ComException if a subscription fails.
*
* @return Always non-null. Call {@link EventCookie#close()} to shut down
* the event subscription.
*/
<T> EventCookie advise( Class<T> eventInterface, T receiver );
/**
* You can use this function to set a name to an object. This is only for debug purposes.
* @param name the new name of the object.
*/
void setName(String name);
}