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. Figure 10.3. The IContact::Display() method in action The IContact InterfaceThe 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. Figure 10.4. An InkNote attached to a contact 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 InterfaceThe 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 RecipientsThe 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 RecipientAfter 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 InterfaceThe 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 TasksBoth 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:
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 ExceptionsWhenever 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.
|
EAN: 2147483647
Pages: 90