GroupWise Object API

Readme

November 2012

1.0 Overview

The GroupWise Object API lets you see, use, and manipulate the GroupWise information store from outside GroupWise 8 and later. The Object API lets you use the GroupWise address book and document management capabilities to manipulate mail messages, appointments, tasks, notes, and phone messages.

You can use the Object API through OLE languages such as Visual Basic and Delphi and object-oriented languages such as C++. The Object API supports OLE Automation, which is an industry standard for interfacing applications.

2.0 What's New

To see what has changed for each version of GroupWise, see Revision History in GroupWise SDK: Object API.

3.0 GroupWise Installation

You can download an evaluation copy of GroupWise from the Novell Downloads site.

For complete installation instructions, see the GroupWise 2012 Installation Guide.

4.0 Known Issues

4.1 Header Files

The gwoapi.h file is the original header file and contains all interfaces defined for the GroupWise Object API system in the original interface.

The gwoapi2.h file was created after the GroupWise 6.0 Service Pack 1 release. The file contains all the original interfaces and many new interfaces, properties, and methods that have been defined since the original interface.

If you are writing new code, you can use the gwoapi.h file to access the GroupWise Object API. However, you cannot use any of the new interfaces, methods, or properties.

If you use the gwoapi2.h file, it gives you access to all interfaces, methods, and properties supported in the GroupWise Object API release version 6.0 SP1 and later.

For the Messages collection and Account2 new GUID, the new code must handle a possible E_NOINTERFACE error that is returned when running against earlier versions of GroupWise. If E_NOINTERFACE is returned, ask for the interface from the older version (Account2Old or MessagesOld). If the second call is successful, all older methods and properties of the interface can be called.

For example, if the code logs in to a system, it receives a DIGWAccount pointer on successful return. You can then request the Account2 interface using the new GUID in the gwoapi2.h file. If it returns an error, request an older Account2 interface (without the new methods) by using the Account2Old GUID defined in the gwoapi2.h file. If this call succeeds, the code can call all the original Account2 methods and properties. (If this second interface is used to call a new method, an error occurs.)

Some examples for handling the new Account2 GUID and a possible E_NOINTERFACE error follow (assuming that pGWApp has been previously retrieved from the OLE system and that the vrName, vrCmdLine, vrPwrd, vrPrompt, and vrReserved variants were previously built). The following example is for the Account2 interface. However, similar code could be written for other objects such as the new Messages collection.

DIGWAccount   pdAcct;
IGWAccount2   pAcct;
BOOLbNewGUID = TRUE;

hr=pGWApp->Login(vrName, vrCmdLine, vrPwrd, vrPrompt,
  vrReserved, &pdAcct);

if(SUCCEEDED(hr))
{
   hr=pdAcct->QueryInterface(IID_IGWAccount2, &pAcct);
   if(FAILED(hr))
   {
      bNewGUID = FALSE;
      hr = pdAcct->QueryInterface(IID_IGWAccount2Old,
&pAcct); 
      if(FAILED(hr))
      {
         //execute error condition
         //could not retrieve either account pointer
      }
   }
}

Or, if the code needs to use the new methods but you want to include the gwoapi2.h file, you can take the DIGWAccount pointer from login and call for an Account object using the Account2Old GUID at all times. This code can then be run against any GroupWise version. The following sample code is the same as the preceding example but has been modified to use only the old Account2 GUID:

DIGWAccount   pdAcct;
|IGWAccount2  pAcct;

hr=pGWApp->Login(vrName, vrCmdLine, vrPwrd, vrPrompt,
  vrReserved, &pdAcct);

if(SUCCEEDED(hr))
{
   hr=pdAcct->QueryInterface(IID_IGWAccount2Old, &pAcct);
   if(FAILED(hr))
   {
      //execute error condition
      //could not retrieve either account pointer
   }
}

4.2 Hits Per Source Limit

The GroupWise engine currently contains a limit of 2500 hits per source on any query driven by the Object API. For example, if you are querying ten libraries, the engine returns no more than 2500 hits for each library.

4.3 AddExistingMethod

The AddExistingMethod (Messages object) method has the following problems:

  • The current version allows only the Private, Read, and opened flags to be set in the MessageStatus bitmask.

  • AddExistingMessage does not preserve any flags in the MessageStatus bitmask other than Private for a draft message. GroupWise assumes that a draft message is read, opened, and delivered, so these values are overwritten. (The other flags are lost for the above reason.)

  • If a FROM_TEXT property is set on a draft message and the display name has more characters than FROM_TEXT, the new SenderDisplayName is used, but truncated.

5.0 Documentation

You can view the GroupWise Object API documentation on the Novell Developer Web site.

6.0 Support and Feedback

Please direct technical questions and comments to the Novell Developer Forum.

You can also find helpful information in GroupWise Cool Solutions.

7.0 Legal Notices

Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.

Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export, or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. Please refer to the Novell International Trade Services Web page for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals.

All files provided in this release are subject to the Novell Developer License Agreement, which can be found in the license.txt file provided in this download.

Copyright © 1999-2007, 2012 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

For Novell trademarks, see the Novell Trademark and Service Mark list.

All third-party products are the property of their respective owners.