Share via

2.2.49.8 Coclass Specifications

  • Article

The automation IDL extensions allow a COM server to expose a rich set of attributes and behaviors, as specified below.

         
 oa-coclass = "[" LWSP oa-coclass-attrs LWSP "]"  LWSP 
              kw-coclass LWSP Identifier 
                LWSP "{" LWSP oa-coclass-body LWSP "}"
  
 oa-coclass-attrs = oa-coclass-attr *( LWSP ","LWSP oa-coclass-attr)
 oa-coclass-attr = uuid-attr / 
                   help-attr / 
                   version-attr / 
                   custom-attr / 
                   kw-aggregatable / 
                   kw-appobject / 
                   kw-control / 
                   kw-hidden / 
                   kw-licensed / 
                   kw-noncreatable / 
                   kw-predeclid
  
 oa-coclass-body = *( oa-coclass-itf-decl )
 oa-coclass-itf-decl = [ "[" LWSP oa-cid-attrs LWSP "]" LWSP ] 
      ( kw-interface / kw-dispinterface ) LWSP Identifier 
                                                   LWSP ";"
 oa-cid-attrs = oa-cid-attr *( LWSP "," LWSP oa-cid-attr )
 oa-cid-attr = kw-source / 
                   kw-default / 
                   kw-defaultvtable / 
                   kw-restricted
 

A coclass statement MUST specify a UUID using the uuid-attr production. The other attributes in the oa-coclass-attrs production are optional.

kw-aggregatable: Specifies that the COM server is aggregatable (see section 2.2.49.1.1).

kw-appobject: Specifies that the coclass is an "appobject coclass" and that its members MUST be included in the binding context of the automation type library (see section 3.5.4.1.1). It also specifies that ITypeInfo::CreateInstance MUST NOT create more than one instance of the coclass, and MUST return a reference to an existing instance of the coclass if one has already been created.

kw-control: Specifies that the COM server it describes is a visual control and is not intended to be used in a nonvisual environment. When applied to an automation scope, it specifies that all COM servers in the scope are visual controls. A Type browser client MAY limit the visibility of elements with this attribute<44>.

kw-hidden: Specifies that the coclass element is not intended to be displayed to users. Type browser clients SHOULD NOT expose the functionality of elements with this attribute<45>.

kw-licensed: Specifies that the COM server is licensed, and can be instantiated only by using a license-aware object creation method<46>. Calls to any object creation method requesting an object of this type MUST fail if the creation method cannot validate licensing requirements at run time.

kw-noncreatable: Specifies that the coclass can be instantiated only by using a custom object creation method. Calls to any generic object creation method, including ITypeInfo::CreateInstance (as specified in section 3.7.4.11), that request an object of this type MUST fail<47>.

kw-predeclid: Specifies that ITypeInfo::CreateInstance MUST NOT create more than one instance of the coclass, and MUST return a reference to an existing instance of the coclass if one has already been created.

kw-default: Specifies that the interface or dispinterface it decorates is a default interface, and can be used in a context where it is not specified by name. Elements with the default attribute MUST NOT also have the [restricted] attribute.

An interface with the [default] attribute and without the [source] attribute is a "default nonsource interface" and defines the binding context of its coclass. Clients, such as macro languages, that can refer to only one interface per coclass MUST use this interface. A coclass MUST NOT contain more than one default nonsource interface.

An interface with both the [default] and [source] attributes behaves as specified by the [source] and [defaultvtable] sections that follow.

kw-source: Specifies that the interface is a source interface for the COM server described by the oa-coclass production. Such a COM server is a connectable server (as specified in section 2.2.49.1.2). The interface MUST be implemented by a client in order to receive events raised by the connectable server.

When combined with the [default] attribute, this attribute specifies that the interface is the default source interface for clients that can refer to only one source interface per coclass. A coclass MUST NOT contain more than one interface with both the [source] and [default] attributes.

kw-defaultvtable: Specifies that the interface is the default source DCOM interface for clients that can refer to only one source DCOM interface per coclass. Interfaces with this attribute MUST also have the [source] attribute. A coclass MUST NOT contain more than one interface with the [defaultvtable] attribute.

An interface that is declared with the [dual], [source], [default], and [defaultvtable] attributes MUST be both the default dispinterface and the default DCOM interface of its coclass.

kw-restricted: Specifies that the element is not intended to be used under all conditions, as specified in section 2.2.49.3.