OleAutomation

OleAutomation provides a generic mechanism for accessing functionality that is specific to a particular ActiveX Control or OLE Document.

<p>The OLE Document or ActiveX Control must support the IDispatch interface in order to provide OleAutomation support. The additional functionality provided by the OLE Object is specified in its IDL file. The additional methods can either be to get property values (<code>getProperty</code>), to set property values (<code>setProperty</code>) or to invoke a method (<code>invoke</code> or <code>invokeNoReply</code>). Arguments are passed around in the form of <code>Variant</code> objects.

<p>Here is a sample IDL fragment:

<pre> interface IMyControl : IDispatch { [propget, id(0)] HRESULT maxFileCount([retval, out] int *c); [propput, id(0)] HRESULT maxFileCount(in int c); [id(1)] HRESULT AddFile(in BSTR fileName); }; </pre>

<p>An example of how to interact with this extended functionality is shown below:

<code><pre> OleAutomation automation = new OleAutomation(myControlSite);

// Look up the ID of the maxFileCount parameter int[] rgdispid = automation.getIDsOfNames(new String[]{"maxFileCount"}); int maxFileCountID = rgdispid[0];

// Set the property maxFileCount to 100: if (automation.setProperty(maxFileCountID, new Variant(100))) { System.out.println("Max File Count was successfully set."); }

// Get the new value of the maxFileCount parameter: Variant pVarResult = automation.getProperty(maxFileCountID); if (pVarResult !is null) { System.out.println("Max File Count is "+pVarResult.getInt()); }

// Invoke the AddFile method // Look up the IDs of the AddFile method and its parameter rgdispid = automation.getIDsOfNames(new String[]{"AddFile", "fileName"}); int dispIdMember = rgdispid[0]; int[] rgdispidNamedArgs = new int[] {rgdispid[1]};

// Convert arguments to Variant objects Variant[] rgvarg = new Variant[1]; String fileName = "C:\\testfile"; rgvarg[0] = new Variant(fileName);

// Call the method Variant pVarResult = automation.invoke(dispIdMember, rgvarg, rgdispidNamedArgs);

// Check the return value if (pVarResult is null || pVarResult.getInt() !is OLE.S_OK){ System.out.println("Failed to add file "+fileName); }

automation.dispose();

</pre></code>

@see <a href="http://www.eclipse.org/swt/snippets/#ole">OLE and ActiveX snippets</a> @see <a href="http://www.eclipse.org/swt/examples.php">SWT Examples: OLEExample, OleWebBrowser</a>

final

class OleAutomation {

this(OleClientSite clientSite);

void dispose();

String getHelpFile(int dispId);

String getDocumentation(int dispId);

OlePropertyDescription getPropertyDescription(int index);

OleFunctionDescription getFunctionDescription(int index);

TYPEATTR* getTypeInfoAttributes();

String getName(int dispId);

String[] getNames(int dispId, int maxSize);

int[] getIDsOfNames(String[] names);

String getLastError();

Variant getProperty(int dispIdMember);

Variant getProperty(int dispIdMember, Variant[] rgvarg);

Variant getProperty(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs);

Variant invoke(int dispIdMember);

Variant invoke(int dispIdMember, Variant[] rgvarg);

Variant invoke(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs);

void invokeNoReply(int dispIdMember);

void invokeNoReply(int dispIdMember, Variant[] rgvarg);

void invokeNoReply(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs);

bool setProperty(int dispIdMember, Variant rgvarg);

bool setProperty(int dispIdMember, Variant[] rgvarg);

}

Constructors

this this(OleClientSite clientSite): Creates an OleAutomation object for the specified client.

Members

Functions

dispose void dispose(): Disposes the automation object. <p> This method releases the IDispatch interface on the OLE Document or ActiveX Control. Do not use the OleAutomation object after it has been disposed.
getDocumentation String getDocumentation(int dispId): Returns the documentation string for the given member ID.
getFunctionDescription OleFunctionDescription getFunctionDescription(int index): Returns the description of a function at the given index.
getHelpFile String getHelpFile(int dispId): Returns the fully qualified name of the Help file for the given member ID.
getIDsOfNames int[] getIDsOfNames(String[] names): Returns the positive integer values (IDs) that are associated with the specified names by the IDispatch implementor. If you are trying to get the names of the parameters in a method, the first String in the names array must be the name of the method followed by the names of the parameters.
getLastError String getLastError(): Returns a description of the last error encountered.
getName String getName(int dispId): Returns the name of the given member ID.
getNames String[] getNames(int dispId, int maxSize): Returns the name of a function and parameter names for the specified function ID.
getProperty Variant getProperty(int dispIdMember): Returns the value of the property specified by the dispIdMember.
getProperty Variant getProperty(int dispIdMember, Variant[] rgvarg): Returns the value of the property specified by the dispIdMember.
getProperty Variant getProperty(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs): Returns the value of the property specified by the dispIdMember.
getPropertyDescription OlePropertyDescription getPropertyDescription(int index): Returns the property description of a variable at the given index.
getTypeInfoAttributes TYPEATTR* getTypeInfoAttributes(): Returns the type info of the current object referenced by the automation. The type info contains information about the object such as the function descriptions, the member descriptions and attributes of the type.
invoke Variant invoke(int dispIdMember): Invokes a method on the OLE Object; the method has no parameters.
invoke Variant invoke(int dispIdMember, Variant[] rgvarg): Invokes a method on the OLE Object; the method has no optional parameters.
invoke Variant invoke(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs): Invokes a method on the OLE Object; the method has optional parameters. It is not necessary to specify all the optional parameters, only include the parameters for which you are providing values.
invokeNoReply void invokeNoReply(int dispIdMember): Invokes a method on the OLE Object; the method has no parameters. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling <code>public void invoke(int dispIdMember)</code>.
invokeNoReply void invokeNoReply(int dispIdMember, Variant[] rgvarg): Invokes a method on the OLE Object; the method has no optional parameters. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling <code>public void invoke(int dispIdMember, Variant[] rgvarg)</code>.
invokeNoReply void invokeNoReply(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs): Invokes a method on the OLE Object; the method has optional parameters. It is not necessary to specify all the optional parameters, only include the parameters for which you are providing values. In the early days of OLE, the IDispatch interface was not well defined and some applications (mainly Word) did not support a return value. For these applications, call this method instead of calling <code>public void invoke(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs)</code>.
setProperty bool setProperty(int dispIdMember, Variant rgvarg): Sets the property specified by the dispIdMember to a new value.
setProperty bool setProperty(int dispIdMember, Variant[] rgvarg): Sets the property specified by the dispIdMember to a new value.

OleAutomation

Constructors

Members

Functions

Meta

Source