2.2.49.2 IDL Automation Scope

  • Article

An IDL automation scope is defined by the library keyword, as in the following.

 oa-scope = 
      oa-library-header LWSP "{" oa-library-body "}" LWSP [";"]
 oa-library-header = 
      "[" LWSP library-attributes LWSP "]" 
           LWSP kw-library LWSP Identifier
 oa-library-body = *oa-library-declarator
     
 library-attributes = 
      library-attribute *( "," LWSP library-attribute LWSP )
 library-attribute  = uuid-attr / 
             version-attr / 
             lcid-attr / 
             help-attr /
             custom-attr /
             kw-control /
             kw-hidden /
             kw-restricted
  
 uuid-attr = kw-uuid LWSP "(" LWSP uuid-rep LWSP ")"
 version-attr = 
      kw-version LWSP "(" LWSP 1*DIGIT *( "." 1*DIGIT ) LWSP ")"
 lcid-attr = kw-lcid LWSP "(" LWSP integer-const-exp LWSP ")"
 help-attr = helpcontext-attr  / 
             helpfile-attr  / 
             helpstring-attr  / 
             helpstringcontext-attr / 
             helpstringdll-attr
 helpcontext-attr = 
      kw-helpcontext LWSP "(" LWSP integer-const-exp LWSP ")"
 helpfile-attr = kw-helpfile LWSP "(" LWSP string LWSP ")"
 helpstring-attr = kw-helpstring LWSP "(" LWSP string LWSP ")"
 helpstringcontext-attr = kw-helpstringcontext LWSP "(" 
            LWSP integer-const-exp LWSP ")"
 helpstringdll-attr = kw-helpstringdll LWSP "(" LWSP string LWSP ")"
 custom-attr = kw-custom LWSP 
             "(" uuid-rep LWSP "," LWSP const-exp LWSP ")"
  
 oa-library-declarator = interface / 
        import / 
        export /
        oa-importlib /
        oa-module /
        oa-dispinterface /
        oa-coclass
  
  
  
 

  • oa-scope: Specifies a new automation scope. There MUST be, at most, one automation scope defined in an IDL file.

  • uuid-attr: Specifies a GUID that MUST identify the automation scope. This attribute MUST be present in the library scope.

  • version-attr: Specifies the version of the automation scope. If this attribute is not specified, a version of 0.0 MUST be assumed for the automation scope. Otherwise, it MUST contain a major version that MUST be a decimal number between 0 and 65535 inclusive. If the minor version is missing, it MUST be treated as 0. Otherwise, it MUST be a decimal number between 0 and 65535 inclusive.

lcid-attr: Specifies the locale ID of the automation scope. If this attribute is not specified, the locale ID of 0x0409 MUST be used for the automation scope. Otherwise, this value MUST resolve to a valid locale ID.

The combination (<guid>, <vMajor>, <vMinor>, <lcidValue>) MUST uniquely identify an automation scope.

 The <guid> value is the main component of the automation scope identity. Scopes with identical <guid> values MUST belong to the same automation scope family.

The <vMajor> and <vMinor> values MUST be used to specify different versions of an automation scope. automation scopes from the same automation scope family that also share the same version numbers MUST belong to the same automation scope generation.

The <lcidValue> MUST be used to define multiple automation scopes within an automation scope generation. Two such automation scopes MUST define the same automation interfaces, and the interfaces MUST differ only in the names that are used for methods, properties, and parameter names (see sections 2.2.49.5 and 2.2.49.6). The equivalent names from the two automation scopes MUST map to the same DISPIDs. This enables an automation server to define multiple mappings from method/property names to a determined set of DISPIDs, with one mapping for each supported locale ID.

helpcontext-attr: Specifies an implementation-specific integer.<31> The value of this attribute MUST be a 32-bit integer. When used on nonlibrary elements, the language element it decorates MUST belong to an automation scope that is declared with the helpfile attribute.

helpfile-attr: Specifies an implementation-specific string.<32>

helpstring-attr: Specifies an implementation-specific string.<33>

helpstringcontext-attr: Specifies an implementation-specific integer.<34> The value of this attribute MUST be a 32-bit integer.

helpstringdll-attr: Specifies an implementation-specific string.<35>

uuid-attr: Specifies a GUID that MUST identify the type. Any Automation-compatible constructed types (enums, structs, or unions) that are not declared with a specifying GUID cannot be retrieved by using ITypeLib::GetTypeInfoOfGuid.

kw-control: Specifies that all COM servers in the automation scope are visual controls. A type browser client can limit the visibility of elements that have this attribute.

kw-hidden: Specifies that the automation scope elements are not intended to be displayed to users. Type browser clients SHOULD NOT expose the functionality of elements with this attribute.

kw-restricted: Specifies that the element is not intended to be used under all conditions. Type browser clients MAY<36> place restrictions on the visibility or usability of elements that have this attribute. Elements that have the [restricted] attribute MUST NOT also have the [default] attribute.

help-attr: Specifies information associated with language elements that can be retrieved by using ITypeLib::GetDocumentation or ITypeInfo::GetDocumentation (as specified in section 3.11.4.7).

custom-attr: Specifies that the attribute is user-defined, and that its meaning depends on its associated GUID.

Custom attributes are optional. If there is more than one custom attribute decorating an automation scope, each one MUST have a different identifying GUID.

The constant value associated with a [custom] attribute MUST be a value that can be stored in a _wireVARIANT, as specified in section 2.2.29.2.