Create a complex recurrent appointment item
Applies to: Outlook 2013 | Outlook 2016
MAPI can be used to create recurring appointment items.
For information about how to download, view, and run the code from the MFCMAPI application and CreateOutlookItemsAddin project referenced in this topic, see Install the Samples Used in This Section.
To create an appointment item
Open a message store. For information on how to open a message store, see Opening a Message Store.
Open a Calendar folder in the message store. See PR_IPM_APPOINTMENT_ENTRYID (PidTagIpmAppointmentEntryId).
Call the IMAPIFolder::CreateMessage method on the Calendar folder to create the new appointment item.
Set the dispidApptRecur (PidLidAppointmentRecur) property and other properties required to create a recurrent appointment.
Save the new appointment item.
The AddAppointment function in the Appointments.cpp source file of the CreateOutlookItemsAddin project demonstrates these steps. The AddAppointment function takes parameters from the Add Appointment dialog box that is displayed when you click Add Appointment on the Addins menu in the MFCMAPI sample application. The DisplayAddAppointmentDialog function in Appointments.cpp displays the dialog box and passes values from the dialog box to the AddAppointment function. The DisplayAddAppointmentDialog function does not relate directly to creating an appointment item using MAPI, so it is not listed here.
Important
The code in the MFCMAPI application does not ensure that the Calendar folder has been selected when you click the Add Appointment command on the Addins menu. Creating an appointment item in a folder other than the Calendar folder can cause undefined behavior. Make sure that you have selected the Calendar folder before using the Add Appointment command in the MFCMAPI application.
The AddAppointment method is listed below. Note that the lpFolder parameter passed to the AddAppointment method is a pointer to an IMAPIFolder interface that represents the folder where the recurrent appointment is created. Given the lpFolder parameter that represents an IMAPIFolder interface, the code calls the IMAPIFolder::CreateMessage method. The CreateMessage method returns a success code and a pointer to a pointer to an IMessage interface. Most of the AddAppointment function code handles the work of specifying properties in preparation for calling the IMAPIProp::SetProps method. If the call to the SetProps method succeeds, the IMAPIProp::SaveChanges method is called to commit the changes to the store and create a new calendar item.
The AddAppointment function sets a number of named properties. For information about named properties and how they are created, see Using MAPI to Create Outlook 2007 Items. Because the named properties used for appointment items occupy multiple property sets, care must be taken when building parameters to pass to the IMAPIProp::GetIDsFromNames method.
The AddAppointment function uses several helper functions to build a structure for various appointment-related properties. The BuildTimeZoneStruct and BuildTimeZoneDefinition helper functions are used to build a structure that specifies the time-zone-related properties. The time-zone-related properties are dispidTimeZoneStruct (PidLidTimeZoneStruct), dispidTimeZoneDesc (PidLidTimeZoneDescription), dispidApptTZDefRecur (PidLidAppointmentTimeZoneDefinitionRecur), dispidApptTZDefStartDisplay (PidLidAppointmentTimeZoneDefinitionStartDisplay), and dispidApptTZDefEndDisplay (PidLidAppointmentTimeZoneDefinitionEndDisplay), and they are discussed in the corresponding sections of [MS-OXOCAL].
The BuildGlobalObjectID function is used to build a structure that specifies the LID_GLOBAL_OBJID (PidLidGlobalObjectId) and dispidCleanGlobalObjId (PidLidCleanGlobalObjectId) properties, which are discussed in the corresponding sections of [MS-OXOCAL]. The structure that specifies the dispidApptRecur property is built using the BuildWeeklyAppointmentRecurrencePattern function.
For information about the structure built by the BuildWeeklyAppointmentRecurrencePattern function, see PidLidAppointmentRecur Canonical Property. Note that while a large variety of appointment recurrence patterns are possible, the BuildWeeklyAppointmentRecurrencePattern function only builds a weekly appointment recurrence pattern. It also uses several hard-coded values, such as the calendar type (Gregorian), the first day of the week (Sunday), and number of modified or deleted instances (none). A more general purpose appointment recurrence pattern creation function would need to accept these sorts of variables as parameters.
The following is the complete listing of the AddAppointment function.
HRESULT AddAppointment(LPMAPIFOLDER lpFolder,
SYSTEMTIME* lpstStartDateLocal, // PidLidAppointmentRecur
SYSTEMTIME* lpstEndDateLocal, // PidLidAppointmentRecur
SYSTEMTIME* lpstStartFirstUST, // PidLidAppointmentStartWhole, PidLidCommonStart, PR_START_DATE
SYSTEMTIME* lpstEndFirstUST, // PidLidAppointmentEndWhole, PidLidCommonEnd, PR_END_DATE
SYSTEMTIME* lpszClipStartUST, // PidLidClipStart
SYSTEMTIME* lpstClipEndUST, // PidLidClipEnd
SYSTEMTIME* lpstFirstDOW, // PidLidAppointmentRecur
DWORD dwStartOffsetLocal, // PidLidAppointmentRecur
DWORD dwEndOffsetLocal, // PidLidAppointmentRecur
DWORD dwPeriod, // PidLidAppointmentRecur
DWORD dwOccurrenceCount, // PidLidAppointmentRecur
DWORD dwPatternTypeSpecific, // PidLidAppointmentRecur
ULONG ulDuration, // PidLidAppointmentDuration
LPWSTR szSubject, // PR_SUBJECT_W
LPWSTR szLocation, // PidLidLocation
LPWSTR szPattern) // PidLidRecurrencePattern
{
if (!lpFolder) return MAPI_E_INVALID_PARAMETER;
HRESULT hRes = S_OK;
LPMESSAGE lpMessage = 0;
// create a message and set its properties
hRes = lpFolder->CreateMessage(0,
0,
&lpMessage);
if (SUCCEEDED(hRes))
{
MAPINAMEID rgnmid[ulAppointmentProps];
LPMAPINAMEID rgpnmid[ulAppointmentProps];
LPSPropTagArray lpNamedPropTags = NULL;
ULONG i = 0;
for (i = 0 ; i < ulAppointmentProps ; i++)
{
if (i < ulFirstMeetingProp)
rgnmid[i].lpguid = (LPGUID)&PSETID_Appointment;
else if (i < ulFirstCommonProp)
rgnmid[i].lpguid = (LPGUID)&PSETID_Meeting;
else
rgnmid[i].lpguid = (LPGUID)&PSETID_Common;
rgnmid[i].ulKind = MNID_ID;
rgnmid[i].Kind.lID = aulAppointmentProps[i];
rgpnmid[i] = &rgnmid[i];
}
hRes = lpFolder->GetIDsFromNames(
ulAppointmentProps,
(LPMAPINAMEID*) &rgpnmid,
NULL,
&lpNamedPropTags);
if (SUCCEEDED(hRes) && lpNamedPropTags)
{
// Because the properties to be set are known in advance,
// most of the structures involved can be statically declared
// to minimize expensive MAPIAllocateBuffer calls.
SPropValue spvProps[NUM_PROPS] = {0};
spvProps[p_PidLidAppointmentSequence].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentSequence],PT_LONG);
spvProps[p_PidLidBusyStatus].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidBusyStatus],PT_LONG);
spvProps[p_PidLidLocation].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidLocation],PT_UNICODE);
spvProps[p_PidLidAppointmentStartWhole].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentStartWhole],PT_SYSTIME);
spvProps[p_PidLidAppointmentEndWhole].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentEndWhole],PT_SYSTIME);
spvProps[p_PidLidAppointmentDuration].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentDuration],PT_LONG);
spvProps[p_PidLidAppointmentColor].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentColor],PT_LONG);
spvProps[p_PidLidResponseStatus].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidResponseStatus],PT_LONG);
spvProps[p_PidLidRecurring].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurring],PT_BOOLEAN);
spvProps[p_PidLidClipStart].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidClipStart],PT_SYSTIME);
spvProps[p_PidLidClipEnd].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidClipEnd],PT_SYSTIME);
spvProps[p_PidLidTimeZoneStruct].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTimeZoneStruct],PT_BINARY);
spvProps[p_PidLidTimeZoneDescription].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidTimeZoneDescription],PT_UNICODE);
spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionRecur],
PT_BINARY);
spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionStartDisplay],
PT_BINARY);
spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentTimeZoneDefinitionEndDisplay],
PT_BINARY);
spvProps[p_PidLidAppointmentRecur].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidAppointmentRecur],PT_BINARY);
spvProps[p_PidLidRecurrenceType].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurrenceType],PT_LONG);
spvProps[p_PidLidRecurrencePattern].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidRecurrencePattern],PT_UNICODE);
spvProps[p_PidLidIsRecurring].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidIsRecurring],PT_BOOLEAN);
spvProps[p_PidLidGlobalObjectId].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidGlobalObjectId],PT_BINARY);
spvProps[p_PidLidCleanGlobalObjectId].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCleanGlobalObjectId],PT_BINARY);
spvProps[p_PidLidCommonStart].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCommonStart],PT_SYSTIME);
spvProps[p_PidLidCommonEnd].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidCommonEnd],PT_SYSTIME);
spvProps[p_PidLidSideEffects].ulPropTag
= CHANGE_PROP_TYPE(lpNamedPropTags->aulPropTag[p_PidLidSideEffects],PT_LONG);
spvProps[p_PR_SUBJECT_W].ulPropTag = PR_SUBJECT_W;
spvProps[p_PR_START_DATE].ulPropTag = PR_START_DATE;
spvProps[p_PR_END_DATE].ulPropTag = PR_END_DATE;
spvProps[p_PR_MESSAGE_CLASS_W].ulPropTag = PR_MESSAGE_CLASS_W;
spvProps[p_PR_ICON_INDEX].ulPropTag = PR_ICON_INDEX;
spvProps[p_PR_CONVERSATION_INDEX].ulPropTag = PR_CONVERSATION_INDEX;
spvProps[p_PR_MESSAGE_FLAGS].ulPropTag = PR_MESSAGE_FLAGS;
spvProps[p_PidLidAppointmentSequence].Value.l = 0;
spvProps[p_PidLidBusyStatus].Value.l = olBusy;
spvProps[p_PidLidLocation].Value.lpszW = szLocation;
SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PidLidAppointmentStartWhole].Value.ft);
SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PidLidAppointmentEndWhole].Value.ft);
spvProps[p_PidLidAppointmentDuration].Value.l = ulDuration;
spvProps[p_PidLidAppointmentColor].Value.l = 0; // No color
spvProps[p_PidLidResponseStatus].Value.l = respNone;
spvProps[p_PidLidRecurring].Value.b = true;
SystemTimeToFileTime(lpszClipStartUST,&spvProps[p_PidLidClipStart].Value.ft);
SystemTimeToFileTime(lpstClipEndUST,&spvProps[p_PidLidClipEnd].Value.ft);
SYSTEMTIME stStandard = {0};
stStandard.wMonth = 0xB;
stStandard.wDay = 0x1;
stStandard.wHour = 0x2;
SYSTEMTIME stDaylight = {0};
stDaylight.wMonth = 0x3;
stDaylight.wDay = 0x2;
stDaylight.wHour = 0x2;
hRes = BuildTimeZoneStruct(
300,
0,
(DWORD)-60,
&stStandard,
&stDaylight,
&spvProps[p_PidLidTimeZoneStruct].Value.bin.cb,
&spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb);
spvProps[p_PidLidTimeZoneDescription].Value.lpszW = L"(GMT-05:00) Eastern Time (US & Canada)";
SYSTEMTIME stRule1Standard = {0};
stRule1Standard.wMonth = 0xA;
stRule1Standard.wDay = 0x5;
stRule1Standard.wHour = 0x2;
SYSTEMTIME stRule1Daylight = {0};
stRule1Daylight.wMonth = 0x4;
stRule1Daylight.wDay = 0x1;
stRule1Daylight.wHour = 0x2;
if (SUCCEEDED(hRes)) hRes = BuildTimeZoneDefinition(
L"Eastern Standard Time",
0, // TZRule Flags
2006, // wYear
300, // lbias
0, // lStandardBias,
(DWORD)-60, // lDaylightBias,
&stRule1Standard, // stStandardDate
&stRule1Daylight, // stDaylightDate
TZRULE_FLAG_EFFECTIVE_TZREG, // TZRule Flags
2007, // wYear
300, // lbias
0, // lStandardBias,
(DWORD)-60, // lDaylightBias,
&stStandard, // stStandardDate
&stDaylight, // stDaylightDate
&spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb,
&spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb);
spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].Value.bin.cb
= spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb;
spvProps[p_PidLidAppointmentTimeZoneDefinitionStartDisplay].Value.bin.lpb
= spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].Value.bin.cb
= spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.cb;
spvProps[p_PidLidAppointmentTimeZoneDefinitionEndDisplay].Value.bin.lpb
= spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
if (SUCCEEDED(hRes)) hRes = BuildWeeklyAppointmentRecurrencePattern(
lpstStartDateLocal,
lpstEndDateLocal,
lpstFirstDOW,
dwStartOffsetLocal,
dwEndOffsetLocal,
dwPeriod,
dwOccurrenceCount,
dwPatternTypeSpecific,
&spvProps[p_PidLidAppointmentRecur].Value.bin.cb,
&spvProps[p_PidLidAppointmentRecur].Value.bin.lpb);
spvProps[p_PidLidRecurrenceType].Value.l = rectypeWeekly;
spvProps[p_PidLidRecurrencePattern].Value.lpszW = szPattern;
spvProps[p_PidLidIsRecurring].Value.b = true;
if (SUCCEEDED(hRes)) hRes = BuildGlobalObjectId(
&spvProps[p_PidLidGlobalObjectId].Value.bin.cb,
&spvProps[p_PidLidGlobalObjectId].Value.bin.lpb);
spvProps[p_PidLidCleanGlobalObjectId].Value.bin.cb = spvProps[p_PidLidGlobalObjectId].Value.bin.cb;
spvProps[p_PidLidCleanGlobalObjectId].Value.bin.lpb = spvProps[p_PidLidGlobalObjectId].Value.bin.lpb;
SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PidLidCommonStart].Value.ft);
SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PidLidCommonEnd].Value.ft);
spvProps[p_PidLidSideEffects].Value.l
= seOpenToDelete | seOpenToCopy | seOpenToMove | seCoerceToInbox | seOpenForCtxMenu;
spvProps[p_PR_SUBJECT_W].Value.lpszW = szSubject;
SystemTimeToFileTime(lpstStartFirstUST,&spvProps[p_PR_START_DATE].Value.ft);
SystemTimeToFileTime(lpstEndFirstUST,&spvProps[p_PR_END_DATE].Value.ft);
spvProps[p_PR_MESSAGE_CLASS_W].Value.lpszW = L"IPM.Appointment";
spvProps[p_PR_ICON_INDEX].Value.l = 0x00000401; // Recurring Appointment
if (SUCCEEDED(hRes)) hRes = BuildConversationIndex(
&spvProps[p_PR_CONVERSATION_INDEX].Value.bin.cb,
&spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb);
spvProps[p_PR_MESSAGE_FLAGS].Value.l = MSGFLAG_READ;
if (SUCCEEDED(hRes)) hRes = lpMessage->SetProps(NUM_PROPS, spvProps, NULL);
if (SUCCEEDED(hRes))
{
hRes = lpMessage->SaveChanges(FORCE_SAVE);
}
if (spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb)
delete[] spvProps[p_PidLidTimeZoneStruct].Value.bin.lpb;
if (spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb)
delete[] spvProps[p_PidLidAppointmentTimeZoneDefinitionRecur].Value.bin.lpb;
// Do not delete p_PidLidAppointmentTimeZoneDefinitionStartDisplay,
// it was borrowed from p_PidLidAppointmentTimeZoneDefinitionStartDisplay
// Do not delete p_PidLidAppointmentTimeZoneDefinitionEndDisplay,
// it was borrowed from p_PidLidAppointmentTimeZoneDefinitionStartDisplay
if (spvProps[p_PidLidAppointmentRecur].Value.bin.lpb)
delete[] spvProps[p_PidLidAppointmentRecur].Value.bin.lpb;
if (spvProps[p_PidLidGlobalObjectId].Value.bin.lpb)
delete[] spvProps[p_PidLidGlobalObjectId].Value.bin.lpb;
// Do not delete p_PidLidCleanGlobalObjectId, it was borrowed from p_PidLidGlobalObjectId
if (spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb)
delete[] spvProps[p_PR_CONVERSATION_INDEX].Value.bin.lpb;
}
MAPIFreeBuffer(lpNamedPropTags);
}
if (lpMessage) lpMessage->Release();
return hRes;
}