The GroupWise XTD Object API

Articles and Tips: article

TIM STURDIVANT
GroupWare Technical Writer
GroupWare Division

KEN CIRCEO
GroupWare Technical Writer
GroupWare Division

JASON HUNTINGTON
GroupWare Technical Writer
GroupWare Division

CAROL OERTLI
GroupWare Technical Editor
GroupWare Division

RON NERDIN
GroupWare Technical Writer
GroupWare Division

01 Mar 1996

The GroupWise XTD Object API (GWOAPI) provides direct access to the GroupWise data store, so a developer can see, use, and manipulate the data store from outside GroupWise XTD. The GWOAPI provides access to the Address Book and document management capabilities of GroupWise XTD as well as to mail messages, appointments, tasks, notes, and phone messages. The initial release of GroupWise XTD (May 1996) will implement the GWOAPI only under Windows 95. The GWOAPI is accessible through object oriented languages such as C++. It also supports OLE Automation, which provides an industry standard for interfacing applications. The GroupWise XTD Object API design is based on the latest object oriented theory and techniques. GWOAPI objects provide an organized representation of the GroupWise data store. The GroupWise Object API does not replace any other API. However, other APIs can be used in conjunction with the GWOAPI.

RELATED DEVNOTES Feb 96 "GroupWise XTD APIs and Beyond: A BrainShare Preview"

Introduction
Overview
Using the GroupWise Object API
Custom 3rd-Party Objects

Introduction

Overview

To understand GWOAPI, it is valuable to discuss its user interface and object-oriented design, as well as how it relates to other APIs.

User Interface

Because the GWOAPI does not define a user interface, the application is free to define its own interface and use the GWOAPI to access the GroupWise data store. For applications which run under the GroupWise XTD Client, the Custom 3rd Party Object (C3PO) interface is provided to make it easier for third party developers to extend the functionality of GroupWise. The C3PO specification replaces custom messages and custom commands in the GroupWise XTD Client. C3POs use the GWOAPI to access and manipulate the GroupWise data store. C3POs must be registered in the Windows 95 system registry.

Object Oriented Design

The GroupWise XTD Object API design is based on the latest object oriented theory and techniques. GWOAPI objects provide an organized representation of the GroupWise data store. An object contains the relevant properties (data) and the methods (functions) which manipulate the properties. You can define new objects without affecting older applications that are not aware of the new objects. You can also add properties and methods to an existing object without changing its previous functionality. Thus, new versions of the GWOAPI are inherently backward compatible. Any development tools that can access OLE Automation objects can be used to develop applications and can get GroupWise XTD information.

OLE Automation can manage collection objects defined in the GWOAPI. A collection object is a special object that provides a uniform means of managing a number of objects of a given type.

GWOAPI Versus Other APIs

The GroupWise Object API does not replace any other API. However, other APIs can be used in conjunction with the GWOAPI. GroupWise XTD also supports the Microsoft Messaging API (MAPI), Dynamic Data Exchange (DDE), Open Document Management API (ODMA), and the Windows Open API.

MAPI is a standard set of messaging functions used to create mail enabled applications. However, since MAPI is focused on e mail, it is not general enough to handle other GroupWise functions such as appointments, tasks, and calendars. An application might use the GWOAPI to access the GroupWise data store and use MAPI to interface the application to another e mail system. GroupWise can act as a DDE server and will execute tokens or commands. GroupWise XTD will support ODMA, which is a standardized interface that fits between applications and document management systems.

GroupWise XTD also supports the Windows Open API, which provides the ability to trap and process tokens that are generated by GroupWise. However, the GWOAPI will provide all of the information and functionality to interface with GroupWise XTD that is required to implement many applications.

More than any other API, the GroupWise XTD Object API opens the GroupWise system to third party development. The GroupWise Object API is easier to use than APIs such as MAPI because it provides a higher level interface with GroupWise. It provides access to the GroupWise XTD data store free from the complexity of the underlying system and allows you to focus on using the information encapsulated in the objects.

Using the GroupWise Object API

The first step in using the GWOAPI in a third party application is to get a handle to the GroupWise Application object. In Visual Basic this is accomplished with the following statement.

Set objGroupWise = CreateObject ( "NovellGroupWiseSession" )

The variable objGroupWise must be of type variant or object.

The next step is to log in to GroupWise. This is done by invoking the Login method of the Application object. In Visual Basic this is done with the following statement.

vntReturnVal = objGroupWise.Login ( txtUserID, txtCommandLine )

The variable vntReturnVal is of type variant and must be present in the statement even if it is not used otherwise. The string txtUserID is the user ID name. The string txtCommandLine contains any valid command line parameters.

The application is now logged into GroupWise and the properties of the Application object are valid. The contents of the data store are accessible through the Application object.

In Delphi the statements to get a handle to the GroupWise Application object and to log in to GroupWise are similar to those in Visual Basic. However, OleAuto must be declared in the "Uses" section and objGroupWise must be declared variant in the "Var" section.

The handle to the GroupWise Application object is obtained with the statement:

OleInitialize(Nil); objGroupWise := CreateOleObject( 'NovellGroupWiseSession' );

Logging into GroupWise in Delphi is accomplished with the statement:

objGroupWise.Login( txtUserID, txtCommandLine );

The GroupWise XTD Object API Objects

The following objects are defined by the GroupWise XTD Object API. A simplified diagram showing the relationships of the various objects appears after the list of objects.

Object	Description
Account	Allowsaccess to objects and properties associatedwith one of the UserIDs which has been loggedin to or proxied for by the current Applicationobject.
Accounts	An Accountcollection object.
AccountRights	Providesaccess rights to an account.
AccountRightsCollection	An AccountRightsCollection object.
Address	Describesan address for use by a Recipient object.This object can be viewed as the base classfor the AddressBookEntry class. In caseswhere a parameter list calls for the useof an Address object, an AddressBookEntryobject may be used as well.
Addresses	An Addresscollection object.
AddressBook	Providesaccess to Address Book data. There may bemore than one Address Book and, therefore,more than one AddressBook object.
AddressBooks	An AddressBookcollection object.
AddressBookEntry	Describesan entry in an AddressBook.
AddressBookEntries	An AddressBookEntrycollection object.
Application	The rootApplication object. All other GroupWise XTDobjects are contained by the Application object.
Appointment	Providesappointment information and actions. Appointmentis a subtype of Message.
Attachment	Describesan attachment to a Message object.
Attachments	An Attachmentcollection object.
BusySearchElement	Containsthe Busy Search results for a user or resourcespecified in the To, CC, or BC field of aBusy Search request.
BusySearchElements	A BusySearchElementcollection object.
BusySearchRequest	Used toinitiate a Busy Search.
BusySearchResult	Containsthe results of a Busy Search. BusySearchResultis derived from Message, since this itemnow appears in the user's In Box in XTD.
DocElement	A DocumentManagement element.
DocElements	A DocElementcollection object.
DocLibrary	A DocumentManagement library.
DocLibraries	A DocLibrarycollection object.
DocReference	A referenceto a specific version of a Document Managementdocument. DocReference is a subtype of Message.
DocRights	Providesaccess rights to one or more versions of a document.
DocRightsCollection	A DocRightsCollection object.
DocType	A DocumentManagement document type.
Document	A DocumentManagement document.
Documents	A Documentcollection object.
DocVersion	A DocumentManagement version.
DocVersions	A DocVersioncollection object.
DocVersionEvent	A DocumentManagement version event.
DocVersionEvents	A DocVersionEventcollection object.
Field	Used torepresent user defined fields in Messageobjects, AddressBook objects, and Documentobjects.
Fields	A Fieldcollection object.
FieldDefinition	Definesa field.
FieldDefinitions	A FieldDefinitioncollection object.
Filter	Representssaved filter information. This object maybe used with the Find method in the Addresses,AddressBookEntries, Messages, and MessageListcollections to derive subsets of those collections.
Filters	A collectionrepresenting the saved filters associatedwith a particular Account.
Folder	Foldersare part of a hierarchical storage system.The contents of one folder can be viewedat any time.
Folders	A Foldercollection object.
FolderRights	Providesaccess rights to a folder.
FolderRightsCollection	A FolderRightscollection object.
Mail	Providesmail information and actions. Mail is a subtypeof Message.
Message	Base classcontaining common methods and propertiesfor any item that may be sent to anotheruser. No actual instance of this class willever be created.
Messages	A Messagecollection object.
MessageList	A temporaryMessage collection object that is not persistentin the message data store. A collection ofthis type may be created by applying a filterto another message collection object, suchas Message objects or another instance ofMessageList.
Note	Providesnote information and actions. Note is a subtypeof Message.
PhoneMessage	Providesphone message information. PhoneMessage isa subtype of Message.
Query	Providesquery information and actions. This objectis associated with a folder of type Query.
Recipient	The addressingobject used in a distribution list. Thisis a subtype of Address.
Recipients	A Recipientcollection object.
Task	Providestask information and actions. Task is a subtypeof Message.
TimeBlock	Providestime block information in BusySearchElement.
TimeBlocks	A TimeBlockcollection object.

Figure 1: Relationships of various GWOAPI objects.

Custom 3rd Party Objects

Custom 3rd Party Objects (C3POs) are used to extend the GroupWise XTD client. The extensions take various forms, ranging from implementing custom data types in the GroupWise data store to modifying the GroupWise browser Toolbar functionality. C3POs can be developed by using C++ or Delphi.

C3POs combine and replace the older and less functional notion of custom messages and custom commands. The 16 bit custom message and custom command drivers of GroupWise 4.x do not run under the 32 bit C3PO implementation. However, a 32 bit C3PO can be written to support 16 bit custom messages and custom commands.

C3POs may make the following modifications to the user interface:

Add new commands to the menus and new buttons to the Toolbar.
Place user defined bitmaps on the Toolbar.
Add separator lines to enhance the appearance of menu items.
Provide a Help file with customized information about the C3PO.

The ability to modify the user interface allows a C3PO to appear as an integrated feature of GroupWise.

One way to run a C3PO is to select the menu item or Toolbar button that was added by the C3PO. However, C3POs may be registered to run when an existing menu item or Toolbar button is selected. This allows a C3PO to enhance or replace the normal functionality. C3POs can be also be triggered to run when GroupWise starts, when GroupWise ends, and when a new item arrives in the In Box.

All objects in the GroupWise data store are theoretically C3POs, even mail messages, appointments, tasks, and so forth. By installing a C3PO against the default Message Class names, customized C3PO behavior can be invoked. For example, arrival of all items in the XTD 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.

C3POs and GWOAPI

C3POs access and manipulate the GroupWise data store through the GroupWise XTD Object API (GWOAPI). The combination of C3POs and GWOAPI 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.

Empty Objects

It is permissible to create a C3PO which will never generate any data records in the GroupWise XTD 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. This allows a single set of extensions (the C3PO specification) to be used for client extensions. Although it is legal to register C3PO implementations that do not generate instance records under other headings, they should generally be registered under GW.APPLICATION.

C3PO Interfaces

C3POs are COM servers that implement the appropriate interfaces to achieve desired behavior. The C3PO specification defines the prototypes of functions or methods. The C3PO writer must write the code to implement these methods. This is distinct from other APIs which supply a library of functions which may be called by the user. A list of the C3PO interfaces appears later in this document.

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 XTD client determines which interfaces a C3PO supports by calling the Query interface.

Minimizing the set of supported interfaces can improve performance. The C3PO developer should take care not to disturb system processing beyond reasonable

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.