3.1.2 Custom COM Interfaces

A "custom" COM interface is one defined by a developer, as opposed to "standard" COM interfaces that are defined by COM. A custom COM interface is the recommended way of exposing functionality. In order to support legacy controllers that use IDispatch as the primary automation mechanism, custom defined interfaces should be derived from IDispatch. By convention, interfaces of this type are called dual interfaces. Using dual interfaces allows legacy controllers to handle custom interfaces as if they were IDispatch interfaces.

A custom COM interface is used to access the properties and methods on an object. A read-only property maps to an interface entry of the form get_<PropertyName>. A read/write property maps to two interface entries of the form get_<PropertyName> and put_<PropertyName>. All methods on an interface return an HRESULT value to indicate success or failure. The HRESULT type is discussed in the COM specification.

To retain compatibility with Automation–enabled controllers, all parameters and return types should be within the subset of those defined by the Automation VARIANT data type. For more information consult the COM documentation. A list for informational purposes appears in Appendix A, "COM Automation Data Types." An object can also expose interfaces that use data types other than those in the VARIANT subset; however, those interfaces will not be callable from Automation controllers like Visual Basic. Since all Active Directory custom interfaces are derived from IDispatch, they can be used as IDispatch interface pointers.

A custom COM interface definition in IDL format would look like this example:

[ object, uuid(IID_IADsXYZ), oleautomation, dual ]

interface IADsXYZ: IDispatch

{

// Read-only properties.

[propget]

HRESULT AReadOnlyProp ([out, retval]BSTR *pbstrAReadOnlyProp);

// Read/write properties.

[propget]

HRESULT AReadWriteProp ([out, retval]long *plAReadWriteProp);

[propput]

HRESULT AReadWriteProp ([in]long lAReadWriteProp);

// Methods.

HRESULT AMethod ([in]DATE dateInParameter,

[out, retval]BSTR *pbstrReturnValue);

};

The following table describes each member of the interface. The Active Directory syntax of each member is also noted. Syntax definitions can be found in Chapter 6, "Object Extensions."