Programming Guide: Annotating the IDL

# Programming Guide

## Annotating the IDL

Scripting components must have a mechanism for discovering the methods, properties, and events exposed for scripting by a part. The information describing the methods, properties, and events exposed by a part is collectively referred to as the scripting meta data of the part. The direct scripting implementation of OpenDoc employs the IDL to specify the scripting meta data associated with scriptable parts. The part developer must annotate the IDL of the scriptable part with special IDL modifiers which identify the properties, methods, and events to be exposed to the script writer.

IDL modifiers are used to identify the class as an event class. The event class declares the method signatures for the routines that will be invoked as event handling routines. IDL modifiers are also used to indicate which classes in the IDL describes the events that can be triggered by the scriptable class.

Scripting-enabled parts must have the modifiers attached to the corresponding IDL definitions. Different modifiers apply to different part definitions as follows:

I | The modifier applies to an interface.
A | The modifier applies to an attribute.
O | The modifier applies to an operation.

### IDL Modifiers for OpenDoc

The modifiers and their semantics are described in the following sections.

#### ODdefault (A O)

This modifier identifies the SOM attribute or method as the default for incoming or outgoing interfaces. This modifier is used in Visual Basic scripts when the script refers to an instance without specifying an attribute or method.

#### ODdual (I)

This modifier indicates that the associated SOM interface has been coded to conform to the OLE rules for a dual interface. All parameters and return types specified for members of a dual interface must be OLE automation-compatible types. All members of a dual interface must pass an HRESULT as the function return value. Members that need to return other values should specify an output parameter as the last parameter and indicate another output parameter to receive the value of the function. For a dual interface, the scripting controller can use either the VTBL or IDispatch mode for invoking the method.

The supported OLE automation-compatible types are:

- Boolean
- Unsigned char
- Double
- Float
- Int
- Long
- Short
- BSTR
- CURRENCY
- DATE
- SCODE
- Enum
- IDispatch
- IUnknown

#### ODevent (I)

This modifier may be specified with or without a value string. When it is used on the eventclass, it should be specified without a value to indicate that the class is an event class. The eventclasss defines the signature for the event calls but does not describe an implemented class. When this modifier is used on a class that may generate events, its value is a comma-separated list of eventclass names. Each name specifies an eventclass that defines event method signatures that can be invoked by this class.

For additional information on ODevent, see "OpenDoc Event Notification"

#### ODGuid (I)

This modifier give the globally unique identifier of the class. This modifier is used by Visual Basic scripts in part registration. The format of this modifier should be:

    ODGuid = '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}';

where `X` is a hexadecimal number.

#### ODhelpcontext (I A O)

This modifier associates a help context value with the SOM construct. It is used with the value of ODhelpfile to provide context-sensitive help.

#### ODhelpfile (I A O)

This modifier associates a help file with a SOM definition. It is typically associated with a module or an interface.

#### ODhelpstring (I A O)

This modifier associates a help string with a SOM definition and is used to provide context-sensitive help.

#### ODid (O)

This modifier applies to a SOM operation or an attribute that is a member of the interface to be dispatched. It specifies the dispatch member ID that identifies the method or attribute methods. Values that are less than 1 are reserved in OLE for standard attributes and methods.

For additional information on the OLE standards for attributes and methods, see the OLE2 Programmers Reference by MicroSoft Press.

Note:

> Because a SOM class may be inherited from one or more base classes, the user-defined dispatch ID of a derived class may collide with the dispatch member ID of one of the base classes. If there is a collision, the derived classes member will override the base class member ID.

You can specify the ODid as an empty string. and the OpenDoc support code will supply an identifier that does not conflict with any inherited values.

If ODid is not specified for a method or attribute, that method or attribute is not presented as accessible to the scripting environment. Not specifying an ODid hides a method. Inherited methods with no ODid value will not be exposed to the scripting programmer.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]