Outlook Items

Every individual contact, appointment, and task stored within Pocket Outlook is considered its own object. Each has its own unique identifier, as well as a set of properties and methods that are appropriate for the object type.

All of the item interfaces (IContact, ITask, and IAppointment) expose the methods described in Table 10.10, which are used for adding, deleting, and modifying the object.

Using the base methods of an object is fairly straightforward. For example, let's look at what is involved in using the IContact::Display() method to show a contact:

// Get an item
IContact *pNewContact = NULL;
hr = pIContactItems->Add((IDispatch **)&pNewContact);
if(FAILED(hr))
   return FALSE;

// Configure the contact
pNewContact->put_FirstName(TEXT("Randy"));
pNewContact->put_LastName(TEXT("Rants"));
pNewContact->put_WebPage(TEXT("http://www.randyrants.com"));

// Save it, then display it
hr = pNewContact->Save();
hr = pNewContact->Display();

Figure 10.3 illustrates the contact that is shown when calling the IContact::Display() method.

The IContact Interface

The IContact interface is used to represent an individual contact entry in the Contacts folder. The interface implements the common Outlook item methods?Save(), Delete(), Copy(), and Display()?and supports the properties described in Table 10.11.

To add a new contact to Pocket Outlook's database, you can create a new IContact item by using the IPOutlookItemCollection interface to get a pointer and add it to the Contacts folder. Once you have modified the properties for the contact, use the IContact::Save() method to save it to the object store.

In addition to storing the basic properties for a contact, Pocket Outlook also supports the capability to store an InkNote with each item (see Figure 10.4). An InkNote is a Binary Large Object (BLOB) that contains data. They are drawn on the screen (attached to the item), and are used with the Rich Ink control.

To work with an InkNote that is attached to an Outlook contact (or any other Outlook item), you can use the Body and BodyInk parameters. The Body parameter is used to extract a text string from the hand-drawn note.

The IAppointment Interface

The IAppointment interface is used to represent an object in the Calendar folder, and can specify an appointment, meeting, or recurring event (such as a weekly meeting). In addition to the common Outlook item methods?Save(), Delete(), Copy(), and Display()?the IAppointment interface also supports the methods described in Table 10.12.

The IAppointment interface supports the properties described in Table 10.13.

You can create, modify, and delete Pocket Outlook appointments just as you would any other Pocket Outlook object. After getting a pointer to the IPOutlookItemCollection interface for the Calendar database, you can perform any action you want on it.

For example, if you wanted to add a new appointment, you could do the following:

// Calendar folder
IFolder *pIFolder = NULL;
hr = pOlApp->GetDefaultFolder(olFolderCalendar, &pIFolder);
if(FAILED(hr)) {
   OutputDebugString(TEXT("Could not get the calendar
       folder"));
   return FALSE;
}

// Get the collection
IPOutlookItemCollection *pIAppItems = NULL;
hr = pIFolder->get_Items(&pIAppItems);
if(FAILED(hr)) {
   pIFolder->Release();
   return FALSE;
}

// Add a new appointment
IAppointment *pIAppoint = NULL;
hr = pIAppItems->Add((IDispatch **)&pIAppoint);
if(FAILED(hr)) {
   pIAppItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Set up my appointment details
SYSTEMTIME sysTime;
DATE dtAppoint;

memset(&sysTime, 0, sizeof(SYSTEMTIME));
sysTime.wMonth = 8;
sysTime.wDay = 30;
sysTime.wYear = 2003;

SystemTimeToVariantTime(&sysTime, &dtAppoint);

pIAppoint->put_Subject(TEXT("Mike's Birthday"));
pIAppoint->put_Start(dtAppoint);
pIAppoint->put_AllDayEvent(VARIANT_TRUE);

// Save it
pIAppoint->Save();

// Clean up
if(pIAppoint)
   pIAppoint->Release();
if(pIAppItems)
   pIAppItems->Release();
if(pIFolder)
   pIFolder->Release();

Two additional interfaces can be used in conjunction with the IAppointment interface to provide more robust appointments:

The methods IAppointment::ClearRecurrencePattern() and IAppointment::GetRecurrencePattern() are used with the IRecurrencePattern interface, and are covered later in this chapter (both the ITask and IAppointment interfaces can support recurrence patterns).

When you create a new appointment, you generally need to include other individuals besides yourself. This is where the IRecipients interface is used; it changes an appointment into what is called a meeting request. The methods IAppointment::Cancel() and IAppointment::Send() are used for canceling and sending these types of requests to other people.

To get the pointer to the IRecipients interface that will be used for an appointment, you can use the IAppointment::get_Recipients() property, which is defined as follows:

HRESULT IAppointment::get_Recipients(IRecipients **pRecipients);

This property returns a pointer to an IRecipient interface that you can use to add, modify, or delete people from the recipients list.

Appointment Recipients

The IRecipients interface is a collection of recipients for an appointment. The interface supports the methods described in Table 10.14.

The IRecipients interface also supports the properties described in Table 10.15.

Each individual recipient in the collection is represented by an IRecipient interface, which supports the properties described in Table 10.16.

To either add or delete individuals from a meeting request, you first must get the appointment's specific IRecipients interface by calling the IAppointment::get_Recipients() property. For example, if you wanted to add a few individuals to a meeting request, you could do the following:

// Get the collection
IPOutlookItemCollection *pIAppItems = NULL;
hr = pIFolder->get_Items(&pIAppItems);
if(FAILED(hr)) {
   pIFolder->Release();
   return FALSE;
}

// Get an appointment
IAppointment *pIAppoint = NULL;
hr = pIAppItems->Item(1, (IDispatch **)&pIAppoint);
if(FAILED(hr)) {
   pIAppItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Get the recipient list
IRecipients *pIRecip = NULL;
hr = pIAppoint->get_Recipients(&pIRecip);
if(FAILED(hr)) {
   pIAppoint->Release();
   pIAppItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Add recipients
IRecipient *pINewRecipient = NULL, *pINewRecipient2 = NULL;
pIRecip->Add(TEXT("Barry"), &pINewRecipient);
pIRecip->Add(TEXT("Jennifer"), &pINewRecipient2);

// Remember to save appointment
pIAppoint->Save();

Verifying a Recipient

After you have used the IRecipients::Add() method to add new people to a recipient list for an appointment (or you have modified the list), it is a good practice to verify that the names you have added are actually valid. This task is simplified by using the IPOlRecipient interface. The interface has a single method, described in Table 10.17.

To get a valid pointer for the IPOlRecipient interface, you need to call the QueryInterface() function on the IRecipient object that you want to validate:

// Resolve
IPOlRecipient *pResolvRecip = NULL;
hr = pINewRecipient->QueryInterface(IID_IPOlRecipient,
   (LPVOID *)&pResolvRecip);

After you have the pointer to the interface, you can call the IPOlRecipient::Resolve() method. This will validate the name of the IRecipient object by searching the Contacts database for a matching first and last name. The method has the following prototype:

HRESULT IPOlRecipient::Resolve(VARIANT_BOOL fShowDialog,
   VARIANT_BOOL *pfResolved);

The first parameter, fShowDialog, should be set to TRUE if you want the method to display a dialog box that lists all of the matching e-mail addresses. If it is set to FALSE, then the function will fail if more than one contact matches. The pfResolved parameter will return TRUE or FALSE, depending on whether the function has successfully resolved an address or not.

The ITask Interface

The ITask interface is used to represent an individual task that is located in the Tasks folder. In addition to the common Outlook item methods?Save(), Delete(), Copy(), and Display()?the ITask interface also supports the methods described in Table 10.18.

The ITask interface supports the properties described in Table 10.19.

Using Recurrence Patterns in Appointments and Tasks

Both the IAppointment and ITask interfaces enable you to set up a recurrence pattern for a particular Outlook item by using the IRecurrencePattern interface. The interface supports the method described in Table 10.20.

The IRecurrencePattern interface supports the properties described in Table 10.21.

To create a new recurring appointment or task, you first need to get the IRecurrencePattern interface for the IAppointment or ITask object by calling the ::GetRecurrencePattern() method on the object.

You should initially configure how often the recurrence will occur by using the IRecurrencePattern::RecurrenceType() property. A recurrence pattern's frequency can be set with one of the following values:

• Use the olRecursDaily constant to have the task or appointment repeat every day.

• Use the olRecursWeekly constant to have the task or appointment repeat every week.

• Use the olRecursMonthly constant to have the task or appointment repeat every month.

• Use the olRecursMonthNth constant to have the task or appointment repeat every Nth month.

• Use the olRecursYearly constant to have the task or appointment repeat every year.

• Use the olRecursYearNth constant to have the task or appointment repeat every Nth year.

Once you have set the IRecurrencePattern::RecurrenceType() property, you can proceed to configure the start time and date for the pattern.

The following example creates a new task that has a recurrence pattern:

// Create a new task
IFolder *pIFolder = NULL;
hr = pOlApp->GetDefaultFolder(olFolderTasks, &pIFolder);
if(FAILED(hr)) {
   OutputDebugString(TEXT("Could not get the tasks
      folder"));
   return FALSE;
}

// Get the collection
IPOutlookItemCollection *pITaskItems = NULL;
hr = pIFolder->get_Items(&pITaskItems);
if(FAILED(hr)) {
   pIFolder->Release();
   return FALSE;
}

// Create a new task
ITask *pITask = NULL;
hr = pITaskItems->Add((IDispatch **)&pITask);
if(FAILED(hr)) {
   pITaskItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Add some info
pITask->put_Subject(TEXT("Check morning news"));

// Get the recurrence pattern
IRecurrencePattern *pIRecur = NULL;
hr = pITask->GetRecurrencePattern(&pIRecur);
if(FAILED(hr)) {
   pITask->Release();
   pITaskItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Set it to fire daily starting tommorow
SYSTEMTIME sysTime;
DATE dtAppoint;

GetSystemTime(&sysTime);
sysTime.wDay++;
SystemTimeToVariantTime(&sysTime, &dtAppoint);

pIRecur->put_RecurrenceType(olRecursDaily);
pIRecur->put_NoEndDate(VARIANT_TRUE);
pIRecur->put_StartTime(dtAppoint);

// Save it
pITask->Save();

// Clean up
pIRecur->Release();
pITask->Release();
pITaskItems->Release();
pIFolder->Release();

Recurrence Exceptions

Whenever an appointment that already has a recurrence pattern assigned to it is modified, Pocket Outlook will automatically create an exception for it. To get a list of exceptions for a recurring appointment, you can use the IRecurrencePattern::get_Exceptions() property, as shown in the following example:

IExceptions *pIExcepts = NULL;
hr = pIRecur->get_Exceptions(&pIExcepts);
if(FAILED(hr)) {
   pIRecur->Release();
   pITask->Release();
   pITaskItems->Release();
   pIFolder->Release();
   return FALSE;
}

// Do something with the exceptions...

The IExceptions interface that is returned is a read-only collection of exceptions for the appointment. The interface supports the single method shown in Table 10.22.

The IExceptions interface supports the properties described in Table 10.23.

To retrieve a specific exception, you should use the IExceptions::Item() method, which is defined as follows:

HRESULT IExceptions::Item(int iIndex,
  IException **ppExcept);

The first parameter is the index for the exception you are interested in, and is followed by a pointer to a value that will be filled in with the pointer to the specific IException interface.

The IException interface supports the properties described in Table 10.24.