The IPOutlookApp Interface

The IPOutlookApp interface is the main object that is used to gain access to all of the POOM data on a device. It is the only object that can be created by calling the CoCreateInstance() function, and is used to gain access to both folder and time zone information. The interface supports the methods described in Table 10.1.

Table 10.1. IPOutlookApp Methods

Method	Description
GetDefaultFolder()	Gets an IFolder interface for Calendar, Tasks, Contacts, or Infrared
GetItemFromOid()	Gets the interface for an item based on its OID
GetTimeZoneFromIndex()	Gets an ITimeZone from the index
GetTimeZoneInformationFromIndex()	Gets time zone information
Logoff()	Logs off from Pocket Outlook
Logon()	Logs on to Pocket Outlook
ReceiveFromInfrared()	Receives an Outlook item over infrared

Table 10.2 describes the properties supported by the IPOutlookApp interface.

Table 10.2. IPOutlookApp Properties

Property	Get/Put	Description
Application	Get	Returns a pointer to the IPOutlookApp interface
OutlookCompatible	Get	Returns TRUE if synchronized with Outlook; FALSE, if with Schedule+
Version	Get	Returns the current version information for Pocket Outlook

The first thing you need to do to get access to Pocket Outlook's data is create a new instance of the IPOutlookApp interface, which is done by calling the CoCreateInstance() function:

 HRESULT hr = S_OK; IPOutlookApp *pOlApp = NULL; if(FAILED(CoInitializeEx(NULL, 0)))    return FALSE; // Get a pointer to the IPOutlookApp interface hr = CoCreateInstance(CLSID_Application, NULL,   CLSCTX_INPROC_SERVER, IID_IPOutlookApp, (LPVOID *)&pOlApp); if (FAILED(hr))    return FALSE; 

Once you have successfully created a new instance of the IPOutlookApp interface, you need to "log in" to the Pocket Outlook session before you can call any of the other POOM functions. This can be done by using the IPOutlookApp::Logon() function, which has the following prototype:

 HRESULT IPOutlookApp::Logon(long hWnd); 

The only parameter the function uses is an optional handle to a window, which can be set to NULL. This handle is used by POOM as the parent window whenever any of the Outlook items (such as Tasks, Contacts, etc.) receive a call into their own ::Display() method. In addition, the Infrared Transfer dialog box uses this handle as its parent.

Once you have logged into Pocket Outlook, you can continue to make additional calls into the object. When you have completed whatever operations you needed to use POOM with, be sure to log off of Pocket Outlook using the following function:

 HRESULT IPOutlookApp::Logoff(); 

The following code sample shows how easily you can log in and out of the POOM interfaces:

 #define INITGUID #include <windows.h> #include <pimstore.h> int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE   hPrevInstance, LPWSTR lpCmdLine, int nShowCmd) {    HRESULT hr = S_OK;    IPOutlookApp *pOlApp = NULL;    if(FAILED(CoInitializeEx(NULL, 0)))       return FALSE;    // Get a pointer to the IPOutlookApp interface    hr = CoCreateInstance(CLSID_Application, NULL,       CLSCTX_INPROC_SERVER, IID_IPOutlookApp, (LPVOID *)&pOlApp);    if(FAILED(hr))       return FALSE;    // Log into Pocket Outlook    hr = pOlApp->Logon(NULL);    if(FAILED(hr))       return FALSE;    // Do whatever we want with POOM    // ...    // Log off and clean up    pOlApp->Logoff();    pOlApp->Release();    return 0; } 

You may also need to get information about the version of Pocket Outlook that is running on the device:

 HRESULT IPOutlookApp::get_Version(BSTR *pbstrVersion); 

The only parameter that this property takes is a pointer to a BSTR value that will be filled in with the version information. Remember that whenever POOM allocates a string, you must call the SysFreeString() function to properly free the memory that it uses, as shown in the following example:

 // Get the current POOM version BSTR bstrVersion; hr = pOlApp->get_Version(&bstrVersion); if(FAILED(hr))    OutputDebugString(TEXT("Could not get POOM version")); // Do something with it ... // When finished, free it SysFreeString(bstrVersion); 

Accessing Pocket Outlook Folders

Each of the data objects (an individual task, contact, or appointment is considered an individual object) used within Pocket Outlook is contained within its own folder object, and is handled through its own IFolder interface. Essentially, each folder is a wrapper to the internal database that Outlook will use for each item type.

To get the pointer for a particular folder, you use the IPOutlookApp::GetDefaultFolder() function, which is prototyped as follows:

 HRESULT IPOutlookApp::GetDefaultFolder(int olFolder,   IFolder **ppIFolder); 

The first parameter, olFolder, specifies which folder to get, and can be one of the following options:

• Use the olFolderCalendar flag to get the Calendar folder. Items in this folder are represented by the IAppointment interface.

• Use the olFolderTasks flag to get the Tasks folder. Items in this folder are represented by the ITasks interface.

• Use the olFolderContacts flag to get the Contacts folder. Items in this folder are represented by the IContact interface.

• Use the olFolderInfrared flag to get the Infrared folder. This folder is used to send and receive Outlook data over the infrared port.

The last parameter, ppIFolder, should be a pointer to a pointer of an IFolder interface, which is filled in with the proper folder object when the function returns. Remember that folders cannot be created, changed, or deleted in Pocket Outlook.

As you can see by the following code sample, getting the pointer to the folder containing calendar items is fairly straightforward:

 // At this point, we should already be logged into IPOutlookApp IFolder *pIFolder = NULL; hr = pOlApp->GetDefaultFolder(olFolderCalendar, &pIFolder); if(FAILED(hr))    OutputDebugString(TEXT("Could not get the calendar       folder")); else {    // Do something here... } // Clean up if(pIFolder)    pIFolder->Release();