2.2.49.6 Automation Parameters

  • Article

The OLE Automation Protocol provides a number of attributes, specified in this section, that extend the IDL syntax specified by the <param-attribute> production from [C706] chapter 4. When these attributes are used, they specify how the client MUST pack the arguments when calling IDispatch::Invoke (section 3.1.4.4).

The automation extensions to IDL expand the definition for the <param_attribute> production in [C706]:

 param-attribute = rpcidl-defined /
   kw-defaultvalue LWSP "(" LWSP integer-const-exp LWSP ")" /
   kw-optional /
   kw-lcid     /
   kw-retval/
   custom-attr
 

The defaultvalue attribute is valid only if the parameter is a scalar type, an enum, or a BSTR (section 2.2.23). The expression specified with defaultvalue MUST be a constant, or an expression resolving to a constant, that can be represented by a VARIANT. The defaultvalue attribute MUST NOT be used on a parameter of a method declared with the vararg attribute.

The optional attribute is valid only if the parameter is of type VARIANT or VARIANT*. The optional attribute MUST NOT be used on a parameter of a method declared with the vararg attribute. For information on handling optional arguments, see section 3.1.4.4.3.

When applied to a parameter, the lcid attribute lets you pass a locale identifier to a function. A function MUST have at most one [lcid] parameter, which MUST be [in] only, and MUST have a type of LONG.

The retval attribute designates the parameter that receives the return value of an interface member that describes a method or get property. The attribute MUST appear on the last parameter of a method that has the propget attribute. The parameter MUST have the [out] attribute, and MUST be a pointer type.

The following parameter ordering (from left to right) MUST be respected when defining an automation-compatible method.

  1. Required parameters (parameters that do not have the defaultvalue or optional attributes)

  2. Parameters with the defaultvalue attribute, if any

  3. Parameters with the optional attribute, if any

  4. lcid parameter, if present

  5. retval parameter, if present