COM Server

Any class defined in Carapace can be made available within a COM server.

Being a COM server is a little more involved than being a COM client, since the following steps must be performed:

• declare the class of object e.g. the Trumpet object in our example.
• implement the class - ie. define each method for each interface rather than simply declare them within the class.
• register the class - this makes it known to the COM system so the server can be started at the client's request.

Class Declaration

First, the class must be declared in Carapace.

The Trumpet example needs to be modified slightly so that it can be made into a COM object. We need to supply a few more details for COM.

A complete class declaration for the Trumpet follows:

(class "Trumpet"

    (guid "{B30204B1-8BB0-11d3-8180-0050048C7269}")

    (major 1)
    (minor 0)

    (interface 

        (progId "Carapace.Trumpet")
        (guid "{B30204B2-8BB0-11d3-8180-0050048C7269}")

        (major 1)
        (minor 0)

        (properties

            (mute String)
            (metal String readOnly)
        )

        (methods

            # initialise the object
            (NIL Trumpet ( (m String) ) )

            # play a piece of music
            (NIL play ( (m String) ) )
        )
    )

    (interface Volume

        (progId "Carapace.TrumpetVolume")

        (guid "{B30204B3-8BB0-11d3-8180-0050048C7269}")

        (major 1)
        (minor 0)

        (methods

            # set the maximum volume
            (NIL setVolume ( (max Integer) ) )

            # make it silent!
            (NIL silencer () )
        )
    )
)

Class Implementation

All methods need to be defined for a class -- that is, every method on every interface. For the Trumpet example above, this means the following methods require definition:

    #
    ## Methods on the primary interface:
    #

    # initialise the object
    (defun NIL Trumpet::Trumpet ( (m String) )

        ... stuff here

    )

    # play a piece of music
    (defun NIL Trumpet::play ( (m String) )

        ... stuff here

    )

    #
    ## Methods on secondary interface ie. interface no. 1
    #

    # set the maximum volume
    (defun NIL Trumpet:Volume::silencer ()

        ... stuff here

    )

    # make it silent!
    (defun NIL Trumpet:Volume::Trumpet ( (m String) )

        ... stuff here

    )

Class Registration

We can only register the class when we have created a type library, since this defines the classes and interfaces in a form COM can understand.

The following makes a type library to hold just our Trumpet class:

(defun NIL register ()

    (local (t TypeLibrary))
        
    # the absolute path of the type library - by convention, they
    # use a .tlb extension
    #
    (set t (create TypeLibrary (join (list ::InstallDir "/typelibs/trumpet.tlb"))))

    (t.name "Carapace Trumpet Example")
    (t.guid "{B30204B5-8BB0-11d3-8180-0050048C7269}")
    (t.major 1)
    (t.minor 0)
    (t.description "a Carapace example")

    (t.addType "Trumpet")

    # other .addType calls would go here to add further types

    # these are the two, generic Carapace servers which will load up
    # any scripted class and become a COM server for the class
    #
    (t.inprocServer "caracom.dll")
    (t.localServer "caracom.exe")

    # name the script which *defines* the Trumpet methods - 
    # this must also *declare* the Trumpet class
    #
    (t.script "trumpet.cpl")

    # since the script 'trumpet.cpl' lives in the standard
    # Carapace scripts directory there is no need to record 
    # any other path information -- if it lives in a different 
    # directory, set the path property for the TypeLibrary
    # accordingly

    # save the type library to disk
    (t.save)

    # register the type library - this updates the system registry
    (t.register)

    (load "cservgen.cpl")
    (makeComServer "caratrumpet.dll")
    (makeComServer "caratrumpet.exe")

    (t.inprocServer "caracom.dll")
    (t.localServer "caracom.exe")