Passing Structures in OLE Automation

• Microsoft OLE Libraries for Windows and Win32s, version 2.02
• Microsoft Visual Basic for Windows, version 3.0

SUMMARY

OLE Automation does not allow structures to be passed as parameters. Automation servers that work with standard controllers like Visual Basic can model a structure as an automation object or pass simple structures as a safearray of VT_UI1. Automation servers that work with custom controllers can pass structures as a safearray of VT_UI1 or by passing a data transfer object that supports IDataObject.

MORE INFORMATION

OLE Automation does not support passing structures as parameters to automation methods and properties. Here are some ways to work around this:

NOTE: Standard controllers are products such as Visual Basic that can control any automation server. A custom controller is written to control a specific automation server.

If the Automation server is designed to work with standard controllers such as Visual Basic, the structure could be modeled as an automation object. For example, consider this structure:

struct point {

    short x;
    short y;

This could modeled as an automation object with two properties, x and y. Visual Basic code such as the following could be used to get and set the values of the properties. Note how the CreateLine method, which required two points as parameters, is implemented as taking references to two automation objects.

Dim Application As Object Dim P1 As Object Dim P2 As Object Dim Line As Object : Set P1 = Application.CreatePoint() P1.x = 3 P1.y = 4 Set P2 = Application.CreatePoint() P2.x = 20 P2.y = 21 Set Line = Application.CreateLine(P1, P2)

The CreatePoint method returns a Point automation object whose x & y properties are set. The type of the value returned by CreatePoint is IDispatch* or a pointer to an object that supports automation. The CreateLine method takes two parameters of type IDispatch* or a pointer to an object that supports automation.

The disadvantage of this solution is that if the automation server is not an inproc server, each property access will result in the overhead of an LRPC/RPC call.

If the automation server is designed to work with custom controllers, the structure could be serialized into a safearray of VT_UI1 and the resultant binary data could be passed as a parameter of type SAFEARRAY(unsigned char). Another solution is to create a data transfer object that supports IDataObject. The IUnknown of this data transfer object could be passed in a parameter of type IUnknown*. The server could then use IDataObject::GetData with a private clipboard format to get the storage medium in which the structure was serialized. Simple structures can be passed from Visual Basic using a safearray of VT_UI1 as described in Don Box's OLE column in the June 1996 issue of the Microsoft Systems Journal.

NOTE: Serializing the structure into a BSTR will not work because the Unicode-ANSI conversions done by OLE's 16:32 bit interoperablity layer assumes that BSTRs contain strings and not binary data. Consequently, binary data passed in BSTRs can be corrupted by such conversions. However, serializing binary data into BSTRs will work if both controller and server are 16-bit. It will also work if both the controller and server are 32-bit and both support Unicode. This is because 32-bit OLE supports only Unicode, not ANSI. A safearray of VT_UI is preferred because of these limitations of passing binary data through BSTRs.