Outlook appointment 常用方法模型

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(), andDisplay()?the IAppointment interface also supports the methods described in Table 10.12.

Table 10.12. IAppointment Methods

Method

Description

Cancel()

Sends a cancellation request for the appointment

ClearRecurrencePattern()

Clears the recurrence pattern for the appointment

GetRecurrencePattern()

Gets the IRecurrencePattern interface for the appointment

Send()

Sends the appointment (meeting request) to all recipients

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.

Table 10.13. IAppointment Properties

Property

Get/Put

Description

AllDayEvent

Get/put

Indicates whether the appointment is an all-day appointment

Application

Get

Returns a pointer to the IPOutlookApp interface

Body

Get/put

Gets or sets the note attached to the appointment (up to 20KB)

BodyInk

Get/put

Gets or sets an InkNote BLOB for the appointment. Both the IAppointment::Body andIAppointment::BodyInk properties access the same note; however,IAppointment::Body returns only the text, whereas IAppointment::BodyInk returns the entire ink object.

BusyStatus

Get/put

Gets or sets the status when a meeting is occurring; options include Busy, Free, Out of Office, or Tentative

Categories

Get/put

Gets or sets the categories assigned

Duration

Get/put

Gets or sets the length of the appointment, in minutes

End

Get/put

Gets or sets the end date and time of the appointment. This must be later than or equal to the start time.

isRecurring

Get

Indicates whether the appointment is recurring

Location

Get/put

Gets or sets the location

MeetingStatus

Get

Indicates whether the appointment is a meeting request or not. An appointment is considered a meeting if it has recipients.

Oid

Get

Gets the object identifier

Recipients

Get

Gets the IRecipients interface for the appointment

ReminderMinutesBeforeStart

Get/put

Gets or sets the number of minutes before the start of the appointment that the reminder should be launched

ReminderOptions

Get/put

Gets or sets the reminder options for the appointment

ReminderSet

Get/put

Indicates whether the user should be reminded of the appointment

ReminderSoundFile

Get/put

Gets or sets the path and filename of the sound file to be used for the reminder. TheIAppointment::ReminderSet property should be set to TRUE, and theIAppointment::Reminder Options should have the olSound option turned on.

Sensitivity

Get/put

Indicates the sensitivity of the appointment: normal or private

Start

Get/put

Gets or sets the start date and time of the appointment. This must be earlier or equal to the end time.

Subject

Get/put

Gets or sets the subject of the appointment (up to 4,096 characters)

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

// Calendar folderIFolder *pIFolder = NULL;hr = pOlApp->GetDefaultFolder(olFolderCalendar, &pIFolder);if(FAILED(hr)) {   OutputDebugString(TEXT("Could not get the calendar       folder"));   return FALSE;}// Get the collectionIPOutlookItemCollection *pIAppItems = NULL;hr = pIFolder->get_Items(&pIAppItems);if(FAILED(hr)) {   pIFolder->Release();   return FALSE;}// Add a new appointmentIAppointment *pIAppoint = NULL;hr = pIAppItems->Add((IDispatch **)&pIAppoint);if(FAILED(hr)) {   pIAppItems->Release();   pIFolder->Release();   return FALSE;}// Set up my appointment detailsSYSTEMTIME 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 itpIAppoint->Save();// Clean upif(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:

1. The IRecurrencePattern interface is used to set up appointments and meetings that occur on more than one occasion.

2. The IRecipients interface is used to change an appointment into a meeting request.

The methods IAppointment::ClearRecurrencePattern() and IAppointment::GetRecurrencePattern() are used with theIRecurrencePattern 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 IRecipientsinterface is used; it changes an appointment into what is called a meeting request. The methods IAppointment::Cancel() andIAppointment::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 theIAppointment::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.

Table 10.14. IRecipients Methods

Method

Description

Add()

Adds a recipient to the meeting request

Item()

Gets the IRecipient interface for the specified item

Remove()

Removes a recipient

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

Table 10.15. IRecipients Properties

Property

Get/Put

Description

Application

Get

Returns a pointer to the IPOutlookApp interface

Count

Get

Gets the number of recipients in the list

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

Table 10.16. IRecipient Properties

Property

Get/Put

Description

Address

Get/put

Gets or sets the e-mail address of the recipient. This property cannot be set to NULL.

Application

Get

Returns a pointer to the IPOutlookApp interface

Name

Get

Gets the display name of the recipient

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 collectionIPOutlookItemCollection *pIAppItems = NULL;hr = pIFolder->get_Items(&pIAppItems);if(FAILED(hr)) {   pIFolder->Release();   return FALSE;}// Get an appointmentIAppointment *pIAppoint = NULL;hr = pIAppItems->Item(1, (IDispatch **)&pIAppoint);if(FAILED(hr)) {   pIAppItems->Release();   pIFolder->Release();   return FALSE;}// Get the recipient listIRecipients *pIRecip = NULL;hr = pIAppoint->get_Recipients(&pIRecip);if(FAILED(hr)) {   pIAppoint->Release();   pIAppItems->Release();   pIFolder->Release();   return FALSE;}// Add recipientsIRecipient *pINewRecipient = NULL, *pINewRecipient2 = NULL;pIRecip->Add(TEXT("Barry"), &pINewRecipient);pIRecip->Add(TEXT("Jennifer"), &pINewRecipient2);// Remember to save appointmentpIAppoint->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 theIPOlRecipient interface. The interface has a single method, described in Table 10.17.

Table 10.17. IPOlRecipient Method

Method

Description

Resolve()

Resolves the name of a recipient with the Contacts database

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:

// ResolveIPOlRecipient *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 theIRecipient 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.