Carapace

Carapace Class Declaration

The class of an object defines the capabilities of the object. For an example of class declaration, see the Trumpet class.

In the following, items in square brackets [ ... ] are optional. Items within curly braces { ... } may be repeated zero or more times. 

<classDeclaration> ::= 

    ( class <className>

        [ ( guid <guidString> ) ]

        [ ( major <majorVersionNo> ) ]

        [ ( minor <minorVersionNo> ) ]

        { <interfaceDeclaration> }
    )

<interfaceDeclaration> ::= 

    ( interface [ <interfaceName> ]

        [ ( progId <progIdString> ) ]

        [ ( library <guidString> <majorVersionNo> <minorVersionNo> ) ]

        [ ( guid <guidString> ) ]

        [ ( major <majorVersionNo> ) ]

        [ ( minor <minorVersionNo> ) ]

        [ ( creatable <yesNo> ) ]

        [ ( direction <inOut> ) ]

        [ ( properties  { <propertyDeclaration> } ) ]

        [ ( methods  { <methodDeclaration> } ) ]
    )

<propertyDeclaration> ::= 

    ( [ public | private ] <propertyName>  <className> [ ( id <dispatchId> ) ] [ readOnly ] ) 

<methodDeclaration> ::= 

    ( [ public | private ] <returnType>  <methodName> ( { <argSpec> } ) [ ( id <dispatchId> ) ] )

    <argSpec> ::= ( <argumentName> <argumentType> )    |
                  <argumentName>                       |
                  ...
Basic definitions are as follows:

<className> a token ie. a sequence of characters
<progIdString> a String name - a convention within COM is to have this as "Company.SpecificName"
<guidString> String form of a COM guid (globally unique identifier) eg. "{EF6699E0-893F-11D3-868D-963F97CCFE2F}"
<majorVersionNo> an Integer version no. : default = 1
<minorVersionNo> an Integer version no. : default = 0
<interfaceName> a String name - for Carapace, only the primary (initial) interface for an object does not require a name
<dispatchId> an Integer or Binary which, if supplied, defines the value for the Dispatch identifier for the method
<yesNo> a Symbol which takes the value yes or no -- a creatable interface (which must be an inbound interface) is one which can be used to create the object
<inOut> a Symbol which takes the value in or out -- an inbound interface is one where an external client invokes methods on this object; an external (or events) interface is one where this object invokes methods on a connected external object

Class Declaration

The class declaration gives the name, COM identifier and version numbers of the given class. All the detail is contained within the interface declaration sections.

Interface Declaration

The set of interface declarations forms the bulk of any class declaration.

Most of an interface declaration is formed from the method and property declarations. Apart from the name and version information for an interface, the following parts of an interface declaration require further explanation:

direction An interface is either inbound (where methods are initiated by the COM client) or outbound (where this is an events interface and methods are initiated by the object itself without waiting to be prodded by a client).
library The definition of this interface might be held in a different COM type library as identified by the supplied GUID and major/minor versions

This is most often used when an inbound interface on this object implements an outbound (events) interface on another COM object. In this case, the COM type library containing the COM definition of this interface is given.

creatable A creatable interface is one which is registered with COM so that, if a COM client requests this interface to be made, COM will create this object and return the requested interface.

A creatable interface must be an inbound interface.

By default, the first inbound interface of an object defined as creatable and all other interfaces are defined as non-creatable.

Property Declaration

A property declaration determines the following:

In addition, the dispatch id for the property -- ie. the integer which identifies this property when using COM -- can be set. This is particularly useful when implementing interfaces defined in other type libraries.

Method Declaration

The declaration for a method is very similar to the function declaration. The declaration defines determines:

To be usable, the method must also be defined.

Method Definition

The method declaration determines the return type, name and arguments of a method. The method definition states exactly what the method does when invoked.

Carapace methods are defined in the same way as are functions. The one thing extra to remember is that the name is extended to include the class name and, if the interface has a name, the interface name.

For example, on the primary interface of the Trumpet object, the play method is defined as: 

    (defun NIL Trumpet::play ( (m String) ) 

       ...
    )
For named methods on named interfaces the interface name is also included within the method definition e.g. 
    (defun NIL Trumpet:Volume::setVolume ( (max Integer) ) 

       ...
    )

Contents Index Current topic: objects Related topics: functions