POOMWrapper Evaluation Release 0.1 Developer Manual

 

Methods supported in POOMWrapper Evaluation Version

 

 

q       Introduction

 

§         What is POOM?

 

While developing a Pocket PC application, many a times interaction with the Pocket Outlook application is needed. Developers are provided with a library called POOM (Pocket Outlook Object Model) by Microsoft®. It consists of a set of COM interfaces each representing single entity in Pocket Outlook. Developers need to work with interfaces and respective collection object given by POOM to be able to interact with Pocket Outlook.

 

§         Problems in Programming with POOM.

 

A developer needs to code a series of interface instantiation, logging in to POOM application, requesting folders, working with collection objects of POOM, logging off from POOM application object and at the end of all releasing all what you have instantiated. This at times can lead to a series of bugs as less experienced COM programmers find it more difficult to manage instantiation and release of the POOM interfaces. To add to all this comprehensive error handling has to be in place to trap exceptions.

 

This leads to, code becoming very bulky and finally code starts containing lot more of instantiation and releasing of COM objects and their error trapping rather than having the business logic.

 

§         How POOMWrapper overcomes these Problems

 

POOMWrapper is essentially a COM based DLL. It sits on top of the POOM interfaces and encapsulates all the POOM interfaces related functionality so developers can build seamless application in quick time without worrying much about the internal functionalities of POOM.

 

It consists of a single interface named WrapperInterface. This interface exposes different methods to achieve different operations. e.g. to insert an appointment into Pocket Outlook it has a method called SaveAppointment. To retrieve appointment details it has a method called GetAppointment. All these methods take parameters that describe particular item. e.g. SaveAppointment method has all the parameters required to save an appointment. 

 

Using POOMWrapper for developing Pocket Outlook based application would save a lot of development time and effort as developers can concentrate on business logic rather than bending their backs against internals of POOM.

 

q       Advantages of using POOMWrapper

 

POOMWrapper takes care of following POOM related operations along with error handling:

 

  • Creating POOM application object instance.
  • Logging into the POOM application object
  • Requesting desired POOM folders.
  • Populating items collections.
  • Logging off from POOM application object.
  • Releasing all POOM objects used.

 

The POOMWrapper is built and packaged as an automation DLL so it can be used in any language that supports automation interfaces viz. eMbedded VC++® or eMbedded Visual Basic®.

 

 

q       Scope of POOMWrapper

 

POOMWrapper covers almost all the functionalities provided by POOM interfaces viz. IAppointment, ITask, and IContact. It is encapsulated and made available in the form of methods.

 

It includes following features:

 

  • Create new appointment.
  • Retrieve appointment.
  • Find and filter appointments by criteria such as subject, date, and venue.
  • Modify appointment.
  • Delete appointment.

 

  • Create new task.
  • Retrieve task.
  • Find and filter tasks by criteria such as subject, date.
  • Find task by date.
  • Modify task.
  • Delete task.

 

  • Create new contact.
  • Retrieve contact.
  • Find and filter contact by criteria such as subject, date.
  • Modify contact.
  • Delete contact.
  • Error message customization.
  • Complete event logging.

 

All of the above features are self-descriptive. The Error Message Customization is the way to specify own error messages specific to application. The POOMWrapper would use these messages whenever error is trapped.

 

 

q       Features Supported in Evaluation Version

 

The evaluation version does not support all of the features listed above. Essentially it supports following features:

 

  • Create new appointment.
  • Retrieve appointment.

 

  • Create new task.
  • Retrieve task.

 

  • Create new contact.
  • Retrieve contact.

 

 

q       How to use POOMWrapper

 

The evaluation version is shipped in 2 variants:

 

POOMWrapper Installer

 

It comes as a setup program. It installs and registers the POOMWrapper.dll automatically on the Pocket PC.

Developers having a Pocket PC device can download and run the setup to install POOMWrapper.dll on their Pocket PC.

 

Download POOMWrapper Installer

 

POOMWrapper ZIP file

         

The zip file is given for those developers who don’t have Pocket PC and carry out development and testing using desktop emulator.

 

After downloading the ZIP, extract it.

Copy POOMWrapper.dll to the \windows folder of the emulator.

Run regsvrce.exe from the emulator and register POOMWrapper.dll.

 

Download POOMWrapper

 

Following code snippet describes how to use POOMWrapper to add new appointment in VC++.

 

#define POOMWRAPPER_PROGID    _T(“POOMWrapper.WrapperInterface”)

 

/*********************************************/

/* importing POOMWrapper.dll in application. */

/*********************************************/

#import "POOMWrapper.dll" no_namespace raw_interfaces_only

 

/************************************************************/

/* Name           : AddAppointment                          */

/* Purpose        : Add new appointment in Pocket Outlook   */

/* Input          : void.                                   */

/* Output         : A HRESULT indicating SUCCESS or FAILURE.*/

/* Dependencies   : POOMWrapper.dll                         */

/************************************************************/         

 

HRESULT AddAppointment(void)  {

 

HRESULT     returnVal;

 

VARIANT     statusFlag;

VARIANT     appStartDate;

VARIANT     appEndDate;

VARIANT     varBlank;

 

VariantInit(&statusFlag);

statusFlag.vt           = VT_BOOL;

statusFlag.boolVal      = VARIANT_FALSE;

 

VariantInit(&appStartDate);

appStartDate.vt   = VT_BSTR;

appStartDate.bstrVal    = SysAllocstring(“09/10/02”);

 

VariantInit(&appEndDate);

appEndDate.vt           = VT_BSTR;

appEndDate.bstrVal      = SysAllocstring(“09/10/02”);

     

 

      /********************************/

      /* Declaring interface pointer  */

      /********************************/

      IWrapperInterfacePtr    wrapperPtr;

 

      returnVal   = S_FASLE;

      wrapperPtr  = NULL;

 

      while(TRUE) {

       

         /****************************/

         /* Initializing COM runtime */

         /****************************/

         returnVal = CoInitializeEx(NULL,COINIT_MULTITHREADED);

 

         if(FAILED(returnVal))      {

 

              break;

         }

 

         /******************************/

         /* Instantiating POOMWrapper  */

         /******************************/

         returnVal = wrapperPtr.CreateInstance(POOMWRAPPER_PROGID);

 

         if(FAILED(returnVal))      {

 

            break;

         }

 

         /*******************************/

         /* changing Variant type date  */

         /*******************************/           

VariantChangeType(&appStartDate, &appStartDate,VARIANT_NOUSEROVERRIDE,VT_DATE);

VariantChangeType(&appStartDate, &appStartDate,VARIANT_NOUSEROVERRIDE,VT_DATE); 

 

         /*****************************/

         /* Inserting new Appointment */

         /*****************************/

         returnVal = wrapperPtr->SaveAppointment(0,L“Business Meeting”,L“Holiday Inn”, L“”,L“Business”,L””,

                                         appStartDate, appEndDate,VARIANT_FALSE, varBlank,

                                         olBusy,0,olSound, olPrivate, &statusFlag);

 

         /**************************/

         /* Checking method status */

         /**************************/

         if(FAILED(returnVal))       {

 

               break;

         }

        

         /************************/

         /* Releasing WrapperPtr */

         /************************/

         wrapperPtr->Release();

         break;

     }

 

     CounInitialize( );

 

     return returnVal;

}

      

Inserting a new appointment in Pocket Outllook using POOMWrapper is as simple as the above code shows. Make sure you release WrapperInterface pointer, rest of the clean up is automatically done.

 

q       Platforms Supported

 

POOMWrapper is tested on Following Windows CE versions:

 

·         Windows CE 3.0

·         Pocket PC 2002.

 

Testing of POOMWrapper was done on Compaq Pocket PC with ARM processor. But it is guarantied to run on any Pocket PC that runs on Windows CE 2.0 onwards. The POOMWrapper installer comes with 3 DLL versions. One each for following processors:

 

·         ARM

·         MIPS

·         SH3  

 

The Installer would automatically install appropriate DLL.

 

q       Dependencies

 

POOMWrapper wraps all the functionality of  POOM. Microsoft also has implemented the POOM interfaces as a DLL. It is named as pimstore.dll. This DLL has to be registered on the Pocket PC. POOMWrapper internally used this DLL.

 

An error message will be shown in case pimstore.dll is missing or corrupted.

 

q       POOMWrapper Error Messages

 

POOMWrapper evaluation version has comprehensive error trapping. Appropriate error messages are displayed whenever error occurs. Following is the list of error messages displayed in the event of an error. You require it to understand what error causes which message.

 

Event

Error Message

Retrieving POOM library PROGID.

The Pocket Outlook Object Library not available on this device.

Instantiating POOM Library.

The Pocket Outlook Object Library not available on this device/is corrupt.

Logging into Pocket Outlook.

Cannot login to the Pocket Outlook.

Saving Appointment.

Unable to Save Appointment. Please try later. If problem persists, contact the Program Vendor.

Saving Contact.

Unable to Save Contact. Please try later. If problem persists, contact the Program Vendor.

Saving Task.

Unable to Save Task. Please try later. If problem persists, contact the Program Vendor.

Getting item count for a particular Outlook folder.

Invalid Folder ID passed. Please check passed Folder ID.

Getting Appointment details.

Cannot retrieve Calendar items. Please try later. If problem persists, contact Program Vendor.

                         --- OR ---

Cannot retrieve requested Calendar item. Please check itemNo parameter to be non-zero.

 

Getting Task details.

Cannot retrieve Task items. Please try later. If problem persists, contact Program Vendor.

                         --- OR ---

Cannot retrieve requested Task item. Please check itemNo parameters to be non-zero.

 

Getting Contact details

Cannot retrieve Contact items. Please try later. If problem persists, contact Program Vendor.

                         --- OR ---

Cannot retrieve requested Contact item. Please check itemNo parameters to be non-zero.

 

 

 

q       Error Reporting and Feedback

 

Your experience and suggestions would be extremely helpful for us in enhancing POOMWrapper and writing similar wrappers for other complicated functionalities.

 

In case of any errors witnessed while using and testing this wrapper, please report errors at devproducts@consultant.com specifying following information:

 

·         Functionality tried to achieve.

·         Error message flashed.

·         Short description of the test environment that caused the error.

 

We would get back to you as early as possible on errors reported.

 

 

 

Home
Copyright 2000 C3IT Software Solutions