1.1 C3PO Functionality

One way to run a C3PO is to select the menu item or toolbar button that was added by the C3PO. A C3PO can also be registered to run when an existing menu item or toolbar button is selected, thus allowing the C3PO to enhance or replace the normal functionality. In addition, you can trigger a C3PO to run when GroupWise starts, when GroupWise ends, or when a new item arrives in the mailbox.

Each object in the GroupWise data store (mail message, appointment, task) is theoretically a C3PO. By installing a C3PO against the default message class names, customized C3PO behavior can be invoked. For example, arrival of all items in the GroupWise data store can be monitored by installing a C3PO under the root item message class. Multiple handlers for a given message class are allowed. However, the order of execution is dependent on the order of handler installation in the Windows registry.

This section covers the following topics:

1.1.1 C3PO Functionality and the Object API

A C3PO accesses and manipulates the GroupWise data store through the GroupWise Object API. The combination provides a powerful framework to open the GroupWise system to third-party development.

C3PO classes are expressed in the GroupWise Object API as the MessageClass property on the message object and its derivatives. Every object in the GroupWise data store has a message class field, which is a string. The object class ties an instance of a C3PO back to the associated object handler hierarchy.

1.1.2 Empty Objects

A C3PO does not need to generate any data records in the GroupWise data store. This allows the C3PO to fully participate in menu modifications, toolbar negotiations, chaining of command extensions, and so forth, without requiring the overhead of managing instance data. Hence, a single set of extensions (the C3PO specification) can be used for client extensions. Although it is legal to register C3PO implementations that do not generate instance records under other headings, they are typically registered under GW.CLIENT.

1.1.3 C3PO Interfaces

A C3PO is a COM Server that implements the appropriate interfaces to achieve a desired purpose. The C3PO specification defines the prototypes of functions and methods. The C3PO writer must write the code to implement these methods. This is distinct from other APIs, which supply a library of functions that may be called by the user.

The C3PO specification defines the interfaces that a C3PO can choose to support. A C3PO is required to support only those interfaces that are necessary to implement the desired behavior. The GroupWise client determines which interfaces a C3PO supports by calling the Query interface. Minimizing the set of supported interfaces can improve performance. Because excessive processing while adding items to the GroupWise menus can hinder the perceived performance, the C3PO writer should take care not to disturb system processing beyond reasonable limits.

The C3PO interfaces are applicable to remote applications. However, the menu and toolbar modifications cannot be made from a remote application unless the C3PO writer performs custom marshalling using the raw menu and toolbar handles which will be exposed.

1.1.4 Inheritance

C3PO software supports the notion of inheritance. That is, if class Msg.Foobar exists (along with the requisite object handler), the message class Msg.Foobar.Bif represents specialized behavior of Msg.Foobar. For example, when an action is attempted against a database record of type Msg.Foobar.Bif, the associated handler is passed contextual information (COM interfaces) that allow it to delegate behavior to ancestor classes. Individual C3POServers are responsible for delegation semantics. The C3POManager code (C3POManager) allows the C3POServer to build various enumerators for proper aggregation and delegation semantics.

The inheritance scheme is substantially (though not fully) realized. Each C3PO component can navigate the tree of data types and use the C3PO facilities. This is achieved through use of the C3POManager interfaces coupled with appropriate aggregation and delegation.

1.1.5 C3PO Instance Management

Each object in the GroupWise data store has a message class field, which is a string. The Object Class ties a C3PO instance to the associated object handler hierarchy. The C3PO system supports the multi-server concept, which allows multiple C3POServers to register under a single C3PO name. However, certain C3PO operations can only operate on a single server, in which case the first server registered under the C3PO name is invoked.

1.1.6 Languages

This optional key represents a series of language designations. The languages are precisely those supported by the component, which implies that multilingual support is accomplished by mapping from a single originating component into multiple languages. Presence of this section implies that the component can operate only in the target languages. Because Language Context ID (LCID) of 0 means any language, the restriction can be released by adding this key.

Each language is specified by a subkey, which is the LCID that is supported.

1.1.7 Thread Storage Architecture

When you are loading multiple C3POs as in-process servers (DLLs, rather than EXEs), you should be aware of an architectural limitation that is imposed by the operating system on the number of Thread Local Storage (TLS) indexes that are available. Since both the GroupWise Client and C3POs draw upon the same TLC pool and the GroupWise Client already uses a large number of these indexes (depending on what is being activated in the client), the TLS index limit might be exceeded when too many C3POs are added to the client.

The exact number of TLS indexes that are required by a C3PO can vary widely, depending on the language that is used to create the C3PO, what operations the C3PO performs, and other factors.

The following are TLS index limits for various operating systems:

Operating System

TLS Index Limit

Windows 95 and Windows NT 4.0

64

Windows 98 and Windows ME

80

Windows 2000 and Windows XP

1088

Because of the larger limit, TLS indexes are never a problem for Windows 2000 or Windows XP. Note also that the GroupWise 6.0 client uses slightly less indexes than GroupWise 5.5.EP.

If the TLS limit is exceeded, you might see a number of different runtime error messages.