org.eclipse.swt.ole.win32.OleAutomation

public final class OleAutomation extends Object

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

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 (getProperty), to set property values (setProperty) or to invoke a method (invoke or invokeNoReply). Arguments are passed around in the form of Variant objects.

Here is a sample IDL fragment:

        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);
        };

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


        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 != 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 == null || pVarResult.getInt() != OLE.S_OK){
                System.out.println("Failed to add file "+fileName);
        }

        automation.dispose();

See Also:

Constructor Summary

Constructors

Constructor

Description

OleAutomation(String progId)

Creates an OleAutomation object for the specified progID.

OleAutomation(OleClientSite clientSite)

Creates an OleAutomation object for the specified client.
Method Summary

Modifier and Type

Method

Description

void

dispose()

Disposes the automation object.

boolean

equals(Object object)

String

getDocumentation(int dispId)

Returns the documentation string for the given member ID.

OleFunctionDescription

getFunctionDescription(int index)

Returns the description of a function at the given index.

String

getHelpFile(int dispId)

Returns the fully qualified name of the Help file for the given member ID.

int[]

getIDsOfNames(String[] names)

Returns the positive integer values (IDs) that are associated with the specified names by the IDispatch implementor.

String

getLastError()

Returns a description of the last error encountered.

String

getName(int dispId)

Returns the name of the given member ID.

String[]

getNames(int dispId, int maxSize)

Returns the name of a function and parameter names for the specified function ID.

Variant

getProperty(int dispIdMember)

Returns the value of the property specified by the dispIdMember.

Variant

getProperty(int dispIdMember, Variant[] rgvarg)

Returns the value of the property specified by the dispIdMember.

Variant

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

Returns the value of the property specified by the dispIdMember.

OlePropertyDescription

getPropertyDescription(int index)

Returns the property description of a variable at the given index.

org.eclipse.swt.internal.ole.win32.TYPEATTR

getTypeInfoAttributes()

Returns the type info of the current object referenced by the automation.

Variant

invoke(int dispIdMember)

Invokes a method on the OLE Object; the method has no parameters.

Variant

invoke(int dispIdMember, Variant[] rgvarg)

Invokes a method on the OLE Object; the method has no optional parameters.

Variant

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

Invokes a method on the OLE Object; the method has optional parameters.

void

invokeNoReply(int dispIdMember)

Invokes a method on the OLE Object; the method has no parameters.

void

invokeNoReply(int dispIdMember, Variant[] rgvarg)

Invokes a method on the OLE Object; the method has no optional parameters.

void

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

Invokes a method on the OLE Object; the method has optional parameters.

boolean

setProperty(int dispIdMember, Variant rgvarg)

Sets the property specified by the dispIdMember to a new value.

boolean

setProperty(int dispIdMember, Variant[] rgvarg)

Sets the property specified by the dispIdMember to a new value.

Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- OleAutomation
  
  public OleAutomation(OleClientSite clientSite)
  
  Creates an OleAutomation object for the specified client.
  Parameters:
  
  clientSite - the site for the OLE Document or ActiveX Control whose additional functionality you need to access
  
  Throws:
  
  IllegalArgumentException -
  
  ERROR_INVALID_INTERFACE_ADDRESS when called with an invalid client site
- OleAutomation
  
  public OleAutomation(String progId)
  
  Creates an OleAutomation object for the specified progID.
  Parameters:
  
  progId - the unique program identifier of an OLE Document application; the value of the ProgID key or the value of the VersionIndependentProgID key specified in the registry for the desired OLE Document (for example, the VersionIndependentProgID for Word is Word.Document)
  
  Throws:
  
  SWTException -
  ERROR_INVALID_CLASSID when the progId does not map to a registered CLSID
  ERROR_CANNOT_CREATE_OBJECT when failed to create OLE Object
  ERROR_INTERFACE_NOT_FOUND when the OLE object specified does not implement IDispatch
  
  Since:
  
  3.6
Method Details
- dispose
  
  public void dispose()
  
  Disposes the automation object.
  This method releases the IDispatch interface on the OLE Document or ActiveX Control. Do not use the OleAutomation object after it has been disposed.
- getHelpFile
  
  public String getHelpFile(int dispId)
  
  Returns the fully qualified name of the Help file for the given member ID.
  
  Parameters:
  
  dispId - the member ID whose Help file is being retrieved.
  
  Returns:
  
  a string representing the fully qualified name of a Help file or null.
- getDocumentation
  
  public String getDocumentation(int dispId)
  
  Returns the documentation string for the given member ID.
  
  Parameters:
  
  dispId - the member ID in which the documentation is being retrieved.
  
  Returns:
  
  the documentation string if it exists; otherwise return null.
- getPropertyDescription
  
  public OlePropertyDescription getPropertyDescription(int index)
  
  Returns the property description of a variable at the given index.
  
  Parameters:
  
  index - the index of a variable whose property is being retrieved.
  
  Returns:
  
  an OlePropertyDescription for a variable at the given index.
- getFunctionDescription
  
  public OleFunctionDescription getFunctionDescription(int index)
  
  Returns the description of a function at the given index.
  
  Parameters:
  
  index - the index of a function whose property is being retrieved.
  
  Returns:
  
  an OleFunctionDescription for a function at the given index.
- getTypeInfoAttributes
  
  public org.eclipse.swt.internal.ole.win32.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.
  
  Returns:
  
  the type info of the receiver
- getName
  
  public String getName(int dispId)
  
  Returns the name of the given member ID.
  
  Parameters:
  
  dispId - the member ID in which the name is being retrieved.
  
  Returns:
  
  the name if it exists; otherwise return null.
- getNames
  
  public String[] getNames(int dispId, int maxSize)
  
  Returns the name of a function and parameter names for the specified function ID.
  
  Parameters:
  
  dispId - the function ID in which the name and parameters are being retrieved.
  
  maxSize - the maximum number of names to retrieve.
  
  Returns:
  
  an array of name containing the function name and the parameter names
- getIDsOfNames
  
  public 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.
  
  Parameters:
  
  names - an array of names for which you require the identifiers
  
  Returns:
  
  positive integer values that are associated with the specified names in the same order as the names where provided; or null if the names are unknown
- getLastError
  
  public String getLastError()
  
  Returns a description of the last error encountered.
  
  Returns:
  
  a description of the last error encountered
- getProperty
  
  public Variant getProperty(int dispIdMember)
  
  Returns the value of the property specified by the dispIdMember.
  
  Parameters:
  
  dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  Returns:
  
  the value of the property specified by the dispIdMember or null
- getProperty
  
  public Variant getProperty(int dispIdMember, Variant[] rgvarg)
  
  Returns the value of the property specified by the dispIdMember.
  
  Parameters:
  
  dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  Returns:
  
  the value of the property specified by the dispIdMember or null
  
  Since:
  
  2.0
- getProperty
  
  public Variant getProperty(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs)
  
  Returns the value of the property specified by the dispIdMember.
  
  Parameters:
  
  dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
  
  Returns:
  
  the value of the property specified by the dispIdMember or null
  
  Since:
  
  2.0
- equals
  
  public boolean equals(Object object)
  
  Overrides:
  
  equals in class Object
- invoke
  
  public Variant invoke(int dispIdMember)
  
  Invokes a method on the OLE Object; the method has no parameters.
  
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  Returns:
  
  the result of the method or null if the method failed to give result information
- invoke
  
  public Variant invoke(int dispIdMember, Variant[] rgvarg)
  
  Invokes a method on the OLE Object; the method has no optional parameters.
  
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  Returns:
  
  the result of the method or null if the method failed to give result information
- invoke
  
  public 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.
  
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
  
  Returns:
  
  the result of the method or null if the method failed to give result information
- invokeNoReply
  
  public 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 public void invoke(int dispIdMember).
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  Throws:
  
  SWTException -
  
  ERROR_ACTION_NOT_PERFORMED when method invocation fails
- invokeNoReply
  
  public 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 public void invoke(int dispIdMember, Variant[] rgvarg).
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  Throws:
  
  SWTException -
  
  ERROR_ACTION_NOT_PERFORMED when method invocation fails
- invokeNoReply
  
  public 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 public void invoke(int dispIdMember, Variant[] rgvarg, int[] rgdispidNamedArgs).
  Parameters:
  
  dispIdMember - the ID of the method as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  rgdispidNamedArgs - an array of identifiers for the arguments specified in rgvarg; the parameter IDs must be in the same order as their corresponding values; all arguments must have an identifier - identifiers can be obtained using OleAutomation.getIDsOfNames
  
  Throws:
  
  SWTException -
  
  ERROR_ACTION_NOT_PERFORMED when method invocation fails
- setProperty
  
  public boolean setProperty(int dispIdMember, Variant rgvarg)
  
  Sets the property specified by the dispIdMember to a new value.
  
  Parameters:
  
  dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - the new value of the property
  
  Returns:
  
  true if the operation was successful
- setProperty
  
  public boolean setProperty(int dispIdMember, Variant[] rgvarg)
  
  Sets the property specified by the dispIdMember to a new value.
  
  Parameters:
  
  dispIdMember - the ID of the property as specified by the IDL of the ActiveX Control; the value for the ID can be obtained using OleAutomation.getIDsOfNames
  
  rgvarg - an array of arguments for the method. All arguments are considered to be read only unless the Variant is a By Reference Variant type.
  
  Returns:
  
  true if the operation was successful
  
  Since:
  
  2.0

Class OleAutomation

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

OleAutomation

OleAutomation

Method Details

dispose

getHelpFile

getDocumentation

getPropertyDescription

getFunctionDescription

getTypeInfoAttributes

getName

getNames

getIDsOfNames

getLastError

getProperty

getProperty

getProperty

equals

invoke

invoke

invoke

invokeNoReply

invokeNoReply

invokeNoReply

setProperty

setProperty