Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.swt.ole.win32
Class OleAutomation

    java.lang.Object
      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();

Constructor Summary
`OleAutomation(OleClientSite clientSite)` Creates an OleAutomation object for the specified client.

Method Summary
`void` | `dispose()` Disposes the automation object.
`String` | `getDocumentation(int dispId)`
`OleFunctionDescription` | `getFunctionDescription(int index)`
`String` | `getHelpFile(int dispId)`
`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)`
`String[]` | `getNames(int dispId, int maxSize)`
`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)`
`org.eclipse.swt.internal.ole.win32.TYPEATTR` | `getTypeInfoAttributes()`
`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, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### 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:
  `SWTError` -
  - ERROR_INVALID_INTERFACE_ADDRESS when called with an invalid client site

Method Detail

### 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)

### getDocumentation

    public String getDocumentation(int dispId)

### getPropertyDescription

    public OlePropertyDescription getPropertyDescription(int index)

### getFunctionDescription

    public OleFunctionDescription getFunctionDescription(int index)

### getTypeInfoAttributes

    public org.eclipse.swt.internal.ole.win32.TYPEATTR getTypeInfoAttributes()

### getName

    public String getName(int dispId)

### getNames

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

### 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

### 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 neccessary 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:
    `SWTError` -
    - 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:
    `SWTError` -
    - 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 neccessary 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:
    `SWTError` -
    - 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.