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 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:

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 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 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:

// 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 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.