# Problem (or not ?) with FirstDateTime on RecurrencePatterns (Tasks mostly)

• ### Question

• Dear All - I wonder if you could help with this rather abstract problem...

I have the MS-OXOCAL specification for RecurrencePattern structure. In this, the reasons for calculating the FirstDateTime Offset for certain daily and weekly recurrence patterns are well documented and comprehensible.

However, for monthly (and therefore also yearly) recurrence patterns, I'm a bit confused.

Given that for monthly/yearly recurrence patterns, the FirstDateTime is NOT dependent on the FirstDOW parameter but on the CalendarType parameter, if I don't plan to use any other calendar than the Gregorian calendar, starting 1/1/1601, then is the FirstDateTime 4-byte part of the RecurrencePattern bit structure irrelevant for me ?

Example (using the Default Outlook (i.e. for me, Gregorian) calendar):

today is 30 August 2012;I set a RecurrencePattern recurring on the 30th day of the month, recurring every 2 months, ending after 10 occurrences, starting 30 August 2012; Outlook naturally correctly calculates that the first Occurrence is 30 Aug 2012, and that the end date is 28 Feb 2014;

Does this calculation anyway involve FirstDateTime ?

According to MS-OXOCAL, it should: (Quote) "Given an input date, the next valid month is found by adding the difference between the input month and a 1600-year offset (the value of the FirstDateTime field) modulo (the value of the Period field)."

In my example, the input month is 8, the FirstDateTime value is 44640 (i.e. 31 days after 1/1/1601, or a 1 month offset), and therefore, according to this, the first valid month for the RecurrencePattern should be 8 + ( (8-1) MOD 2)=9, i.e. September.

September is neither a month in which an Occurrence occurs, nor a month from which, using Occurrences*Period, the End Date can or should be determined.

Outlook calculates exactly the same FirstDateTime value for a similar RecurrencePattern but which begins on, e.g. 25 August, or any date in August before the startDate (30-Aug) specified.

I have a feeling I'm seeing far too many trees and far too little of the forest here...

As always, any help greatly appreciated.

Jim

Thursday, August 30, 2012 9:31 PM

### Answers

• I don't know if this will help at all for your problem or understanding, but the following information was from originally reverse engineering the recurrence pattern information, based on work by Dan Mitchell and Cain Random (among others). At the time I asked a friend who owned CDO 1.21 on the Exchange team and who was one of the original authors of MAPI 1.0 if the information was good and he said it was better than anything he had, he had to reverse engineer it himself <g>.

MAPI Recurrence Pattern and Exception Data Structure Reference

Last Updated July 20, 2004

Intro

As newer versions of Outlook have been released, this document has gotten
further out of date. Although older versions of the data appear to be
forward-compatible, anyone comparing this document against the data in their
current version of Outlook would doubtlessly be confused, so I've brought it
up to date. As of July, 2004, this document describes data produced by and
intended to be compatible with Outlook 2003.

Outlook stores the recurrence pattern in a binary field with id 0x8216, i.e.
PROP_TAG( PT_BINARY, 0x8216) in the Outlook appointment property set.
Without exceptions, these data will be either 72 or 80 bytes long. Outlook
apparently uses these data alone to determine the pattern: the rest of the
recurrence-related fields in the set (e.g. recurrence start date, end date,
and type) don't have any affect on the actual recurrence.

I've figured out what most of the bytes are (with some help-- see credits).
At a minimum, I've identified everything well enough to be able to export
recurrence patterns from my program to MAPI and have Outlook recognize them
appropriately, and that's all we really need. Those that I haven't seem not
to vary, so their meaning isn't very important, but if anyone knows what
they might mean, please let me know. OutlookSpy
(http://www.dimastr.com/outspy/) is an excellent tool for examining the
contents of this field (and for everything else under Heaven).

Recurrence Data Structure Offset Type Value

0 ULONG (?) Constant : { 0x04, 0x30, 0x04, 0x30}

4 UCHAR 0x0A + recurrence type: 0x0A for daily, 0x0B for weekly, 0x0C for
monthly, 0x0D for yearly

5 UCHAR Constant: { 0x20}

6 ULONG Seems to be a variant of the recurrence type: 1 for daily every n
days, 2 for daily every weekday and weekly, 3 for monthly or yearly. The
special exception is regenerating tasks that regenerate on a weekly basis: 0
is used in that case (I have no idea why).

Here's the recurrence-type-specific data. Because the daily every N days
data are 4 bytes shorter than the data for the other types, the offsets for
the rest of the data will be 4 bytes off depending on the recurrence type.
Daily every N days: 10 ULONG ( N - 1) * ( 24 * 60). I'm not sure what this
is used for, but it's consistent.

14 ULONG N * 24 * 60: minutes between recurrences

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

Daily every weekday (this is essentially a subtype of weekly recurrence): 10
ULONG 6 * 24 * 60: minutes between recurrences ( a week... sort of)

14 ULONG 1: recur every week (corresponds to the second parameter for weekly
recurrence)

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG 0x3E: bitmask for recurring every weekday (corresponds to fourth
parameter for weekly recurrence)

Weekly every N weeks for all events and non-regenerating tasks: 10 ULONG 6 *
24 * 60: minutes between recurrences (a week... sort of)

14 ULONG N: recurrence interval

18 ULONG Constant: 0

22 ULONG Bitmask for determining which days of the week the event recurs on
( 1 << dayOfWeek, where Sunday is 0).

Weekly every N weeks for regenerating tasks: 10 ULONG Constant: 0

14 ULONG N * 7 * 24 * 60: recurrence interval in minutes between occurrences

18 ULONG Constant: 1

Monthly every N months on day D: 10 ULONG This is the most complicated value
in the entire mess. It's basically a very complicated way of stating the
recurrence interval. I tweaked fbs' basic algorithm. DateTime::MonthInDays
simply returns the number of days in a given month, e.g. 31 for July for 28
for February (the algorithm doesn't take into account leap years, but it
doesn't seem to matter). My DateTime object, like Microsoft's COleDateTime,
uses 1-based months (i.e. January is 1, not 0). With that in mind, this
works:

long monthIndex = ( ( ( ( 12 % schedule->GetInterval()) *

( ( schedule->GetStartDate().GetYear() - 1601) %

schedule->GetInterval())) % schedule->GetInterval()) +

( schedule->GetStartDate().GetMonth() - 1)) % schedule->GetInterval();

for( int i = 0; i < monthIndex; i++)

{

value += DateTime::GetDaysInMonth( ( i % 12) + 1) * 24 * 60;

}

This should work for any recurrence interval, including those greater than
12.

14 ULONG N: recurrence interval

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG D: day of month the event recurs on (if this value is greater than
the number of days in a given month [e.g. 31 for and recurs in June], then
the event will recur on the last day of the month)

Monthly every N months on the Xth Y (e.g. "2nd Tuesday"): 10 ULONG See
above: same as for monthly every N months on day D

14 ULONG N: recurrence interval

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG Y: bitmask for determining which day of the week the event recurs
on (see weekly every N weeks). Some useful values are 0x7F for any day, 0x3E
for a weekday, or 0x41 for a weekend day.

26 ULONG X: 1 for first occurrence, 2 for second, etc. 5 for last
occurrence. E.g. for "2nd Tuesday", you should have values of 0x04 for the
prior value and 2 for this one.

Yearly on day D of month M: 10 ULONG M (sort of): This is another messy
value. It's the number of minute since the beginning of the year to the
given month. For an explanation of GetDaysInMonth, see monthly every N
months. This will work:

ULONG monthOfYearInMinutes = 0;

for( int i = DateTime::cJanuary; i < schedule->GetMonth(); i++)

{

monthOfYearInMinutes += DateTime::GetDaysInMonth( i) * 24 * 60;

}

14 ULONG 12: recurrence interval in months. Naturally, 12.

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG D: day of month the event recurs on. See monthly every N months on
day D.

Yearly on the Xth Y of month M: 10 ULONG M (sort of): See yearly on day D of
month M.

14 ULONG 12: recurrence interval in months. Naturally, 12.

18 ULONG Constant: 0

22 ULONG Y: see monthly every N months on the Xth Y.

26 ULONG X: see monthly every N months on the Xth Y.

After these recurrence-type-specific values, the offsets will change
depending on the type. For every type except daily every N days, the offsets
will grow by at least 4. For those types using the Xth Y, the offsets will
grow by an additional 4, for a total of 8. The offsets for the rest of these
values will be given for the most basic case, daily every N days, i.e.
without any growth. Adjust as necessary. Also, the presence of exceptions
will change the offsets following the exception data by a variable number of
bytes, so the offsets given in the table are accurate only for those
recurrence patterns without any exceptions. 22 UCHAR Type of pattern
termination: 0x21 for terminating on a given date, 0x22 for terminating
after a given number of recurrences, or 0x23 for never terminating
(recurring infinitely)

23 UCHARx3 Constant: { 0x20, 0x00, 0x00}

26 ULONG Number of occurrences in pattern: 0 for infinite recurrence,
otherwise supply the value, even if it terminates on a given date, not after
a given number

30 ULONG Constant: 0

34 ULONG Number of exceptions to pattern (i.e. deleted or changed
occurrences)

.... ULONGxN Base date of each exception, given in hundreds of nanoseconds
since 1601, so see below to turn them into a comprehensible format. The base
date of an exception is the date (and only the date-- not the time) the
exception would have occurred on in the pattern. They must occur in
ascending order.

38 ULONG Number of changed exceptions (i.e. total number of exceptions -
number of deleted exceptions): if there are changed exceptions, again, more
data will be needed, but that will wait

.... ULONGxN Start date (and only the date-- not the time) of each changed
exception, i.e. the exceptions which aren't deleted. These must also occur
in ascending order. If all of the exceptions are deleted, this data will be
absent. If present, they will be in the format above. Any dates that are in
the first list but not in the second are exceptions that have been deleted
(i.e. the difference between the two sets). Note that this is the start date
(including time), not the base date. Given that the values are unordered and
that they can't be matched up against the previous list in this iteration of
the recurrence data (they could in previous ones), it is very difficult to
tell which exceptions are deleted and which are changed. Fortunately, for
this new format, the base dates are given on the attachment representing the
changed exception (described below), so you can simply ignore this list of
changed exceptions. Just create a list of exceptions from the previous list
and assume they're all deleted unless you encounter an attachment with a
matching base date later on.

42 ULONG Start date of pattern given in hundreds of nanoseconds since 1601;
see below for an explanation.

46 ULONG End date of pattern: see start date of pattern

50 ULONG Constant: { 0x06, 0x30, 0x00, 0x00}

NOTE: I find the following 8-byte sequence of bytes to be very useful for
orienting myself when looking at the raw data. If you can find { 0x06, 0x30,
0x00, 0x00, 0x08, 0x30, 0x00, 0x00}, you can use these tables to work either
forwards or backwards to find the data you need. The sequence sort of
delineates certain critical exception-related data and delineates the
exceptions themselves from the rest of the data and is relatively easy to
find. If you're going to be meddling in here a lot, I suggest making a
friend of ol' 0x00003006.

54 UCHAR This number is some kind of version indicator. Use 0x08 for Outlook
2003. I believe 0x06 is Outlook 2000 and possibly 98, while 0x07 is Outlook
XP. This number must be consistent with the features of the data structure
generated by the version of Outlook indicated thereby-- there are subtle
differences between the structures, and, if the version doesn't match the
data, Outlook will sometimes failto read the structure.

55 UCHARx3 Constant: { 0x30, 0x00, 0x00}

58 ULONG Start time of occurrence in minutes: e.g. 0 for midnight or 720 for
12 PM

62 ULONG End time of occurrence in minutes: i.e. start time + duration, e.g.
900 for an event that starts at 12 PM and ends at 3PM

Exception Data 66 USHORT Number of changed exceptions: essentially a check
on the prior occurrence of this value; should be equivalent.

NOTE: The following structure will occur N many times (where N = number of
changed exceptions), and each structure can be of variable length.

.... ULONG Start date of changed exception given in hundreds of nanoseconds
since 1601

.... ULONG End date of changed exception given in hundreds of nanoseconds
since 1601

.... ULONG This is a value I don't clearly understand. It seems to be some
kind of archival value that matches the start time most of the time, but
will lag behind when the start time is changed and then match up again under
certain conditions later. In any case, setting to the same value as the
start time seems to work just fine (more information on this value would be
appreciated).

.... USHORT Bitmask of changes to the exception (see below). This will be 0
if the only changes to the exception were to its start or end time.

.... ULONGxN Numeric values (e.g. label or minutes to remind before the
event) changed in the exception. These will occur in the order of their
corresponding bits (see below). If no numeric values were changed, then
these values will be absent.

NOTE: The following three values constitute a single sub-structure that will
occur N many times, where N is the number of strings that are changed in the
exception. Since there are at most 2 string values that can be excepted
(i.e. subject [or description], and location), there can at most be two of
these, but there may be none.

.... USHORT Length of changed string value with NULL character

.... USHORT Length of changed string value without NULL character (i.e.
previous value - 1)

.... CHARxN Changed string value (without NULL terminator)

Unicode Data NOTE: If a string value was changed on an exception, those
changed string values will reappear here in Unicode format after 8 bytes of
NULL padding (possibly a Unicode terminator?). For each exception with a
changed string value, there will be an identifier, followed by the changed
strings in Unicode. The strings will occur in the order of their
corresponding bits (see below). E.g., if both subject and location were
changed in the exception, there would be the 3-ULONG identifier, then the
length of the subject, then the subject, then the length of the location,
then the location.

70 ULONGx2 Constant: { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}. This
padding serves as a barrier between the older data structure and the
appended Unicode data. This is the same sequence as the Unicode terminator,
but I'm not sure whether that's its identity or not.

.... ULONGx3 These are the three times used to identify the exception above:
start date, end date, and repeated start date. These should be the same as
they were above.

.... USHORT Length of changed string value without NULL character. This is
given as count of WCHARs, so it should be identical to the value above.

.... WCHARxN Changed string value in Unicode (without NULL terminator)

Terminator ... ULONGxN Constant: { 0x00, 0x00, 0x00, 0x00}. 4 bytes of NULL
padding per changed exception. If there were no changed exceptions, all
you'll need is the final terminator below.

.... ULONGx2 Constant: { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}.

Manipulating Values Given in Nanoseconds since 1601

These values are an abridged form of the FILETIME representation). Values in
the present end with byte 0x0C when you're looking at them in OutlookSpy.
Note that my DateTime object handles conversions between itself and
FILETIME, but the COleDateTime will as well. Also note that these times are
in LOCAL time, not in UTC as with all the rest of the Outlook dates.
Therefore, it is unnecessary to call FileTimeToLocalFileTime or the inverse
when converting either direction. However, you may need to put those values
back in local time if the object you're using automatically adjusts them to
UTC. These can be calculated using the following functions:

#define cFileTimeUnitsPerSecond 10000000i64

DateTime CMAPIEvent::ConvertRecurrenceMinutesToDate( ULONG minutes)

{

ULONGLONG fileTimeUnitsBeforeStart = (ULONGLONG) minutes * 60i64 *
cFileTimeUnitsPerSecond;

FILETIME ft = { (DWORD) ( fileTimeUnitsBeforeStart & 0xFFFFFFFF), (DWORD)
( fileTimeUnitsBeforeStart >> 32)};

DateTime date;

date.SetDateTime( ft);

return date;

}

ULONG CMAPIEvent::ConvertRecurrenceDateToMinutes( DateTime date)

{

FILETIME ft = date;

ULONGLONG minutes = ( ( (ULONGLONG) ft.dwHighDateTime) << 32) +
ft.dwLowDateTime;

minutes = minutes / 60i64;

minutes = minutes / cFileTimeUnitsPerSecond;

return (ULONG) minutes;

}

Exceptions

Here are the bits for the change bitmask: Bit Value Change Stored As

1 1 Description String following

2 2 Notes Creates attachment

3 4 Remind before ULONG following

4 8 Reminder set ULONG ( 0 or 1) following

5 16 Location String following

6 32 Show time as ULONG following

7 64 RESERVED

8 128 Is all day ULONG (0 or 1) following

9 256 Label/color ULONG following

10 512 Has attachment Creates attachment

In order of the bit, the changed values will occur after this bitmask. For
numeric values, they'll occur simply as ULONGs. For string values, there
will be two USHORTs and then the characters. The first USHORT will be the
length of the string including the NULL character, whereas the second will
be the length without, so that the second number is just the first number -
1. The NULL character isn't in the stream, though.

Further Notes

In order to make Outlook prompt the user to delete either the entire series
or the individual occurrence, you have to set property PROP_TAG( PT_LONG,
0x8510) in the COMMON property set to 369.

Here are the essential property tag definitions I've gathered together:

#define PS_OUTLOOK_EVENT Guid( "0x0220060000000000C000000000000046")
//CdoPropSetID1

#define PR_OUTLOOK_EVENT_START_DATE PROP_TAG( PT_SYSTIME, 0x820D)

#define PR_OUTLOOK_EVENT_END_DATE PROP_TAG( PT_SYSTIME, 0x820E)

#define PR_OUTLOOK_EVENT_LOCATION PROP_TAG( PT_STRING8, 0x8208)

#define PR_OUTLOOK_EVENT_SHOW_TIME_AS PROP_TAG( PT_LONG, 0x8205)

#define PR_OUTLOOK_EVENT_ALL_DAY PROP_TAG( PT_BOOLEAN, 0x8215)

#define PR_OUTLOOK_EVENT_RECURRENCE_TYPE PROP_TAG( PT_LONG, 0x8231)

#define PR_OUTLOOK_EVENT_RECURRENCE_SET PROP_TAG( PT_BOOLEAN, 0x8223)

#define PR_OUTLOOK_EVENT_RECURRENCE_DATA PROP_TAG( PT_BINARY, 0x8216)

#define PR_OUTLOOK_EVENT_RECURRENCE_START PROP_TAG( PT_SYSTIME, 0x8235)

#define PR_OUTLOOK_EVENT_RECURRENCE_END PROP_TAG( PT_SYSTIME, 0x8236)

#define PR_OUTLOOK_EVENT_DURATION PROP_TAG( PT_LONG, 0x8213)

#define PR_OUTLOOK_EVENT_RECURRENCE_BASE PROP_TAG( PT_SYSTIME, 0x8228)

#define PS_OUTLOOK_COMMON Guid( "0x0820060000000000C000000000000046")
//CdoPropSetID4

#define PR_OUTLOOK_COMMON_REMINDER_MINUTES_BEFORE PROP_TAG( PT_LONG, 0x8501)

#define PR_OUTLOOK_COMMON_REMINDER_DATE PROP_TAG( PT_SYSTIME, 0x8502)

#define PR_OUTLOOK_COMMON_REMINDER_SET PROP_TAG( PT_BOOLEAN, 0x8503)

#define PR_OUTLOOK_COMMON_ALLOW_EXCEPTION_DELETE PROP_TAG( PT_LONG, 0x8510)

Credits

Daniel Mitchell: A lot of the data offsets and explanations.

fbs: The monthly recurrence interval algorithm.

Robert Swofford: The property value to set to allow occurrences to be
deleted independently.

Dmitry Streblechenko: Author of OutlookSpy, without which this would have
been nearly impossible.

Hisham Shafi: Corrected a few of the bits in the exception structure.

Cameron Ring: Figured out time zone information, task recurrence, and some
other pieces of the puzzle.

Cain T. S. Random

--
Ken Slovak
[MVP-Outlook]
http://www.slovaktech.com
Author: Professional Programming Outlook 2007
"JimDenmark" <=?utf-8?B?SmltRGVubWFyaw==?=> wrote in message news:364dee34-2f18-47f3-b78a-6728dd193cf2...

Dear All - I wonder if you could help with this rather abstract problem...

I have the MS-OXOCAL specification for RecurrencePattern structure. In this, the reasons for calculating the FirstDateTime Offset for certain daily and weekly recurrence patterns are well documented and comprehensible.

However, for monthly (and therefore also yearly) recurrence patterns, I'm a bit confused.

Given that for monthly/yearly recurrence patterns, the FirstDateTime is NOT dependent on the FirstDOW parameter but on the CalendarType parameter, if I don't plan to use any other calendar than the Gregorian calendar, starting 1/1/1601, then is the FirstDateTime 4-byte part of the RecurrencePattern bit structure irrelevant for me ?

Example (using the Default Outlook (i.e. for me, Gregorian) calendar):

today is 30 August 2012;I set a RecurrencePattern recurring on the 30th day of the month, recurring every 2 months, ending after 10 occurrences, starting 30 August 2012; Outlook naturally correctly calculates that the first Occurrence is 30 Aug 2012, and that the end date is 28 Feb 2014;

Does this calculation anyway involve FirstDateTime ?

According to MS-OXOCAL, it should: (Quote) "Given an input date, the next valid month is found by adding the difference between the input month and a 1600-year offset (the value of the FirstDateTime field) modulo (the value of the Period field)."

In my example, the input month is 8, the FirstDateTime value is 44640 (i.e. 31 days after 1/1/1601, or a 1 month offset), and therefore, according to this, the first valid month for the RecurrencePattern should be 8 + ( (8-1) MOD 2)=9, i.e. September.

September is neither a month in which an Occurrence occurs, nor a month from which, using Occurrences*Period, the End Date can or should be determined.

Outlook calculates exactly the same FirstDateTime value for a similar RecurrencePattern but which begins on, e.g. 25 August, or any date in August before the startDate (30-Aug) specified.

I have a feeling I'm seeing far too many trees and far too little of the forest here...

As always, any help greatly appreciated.

Jim

Ken Slovak MVP - Outlook
• Marked as answer by Sunday, September 2, 2012 9:00 AM
Friday, August 31, 2012 7:35 PM

### All replies

• I don't know if this will help at all for your problem or understanding, but the following information was from originally reverse engineering the recurrence pattern information, based on work by Dan Mitchell and Cain Random (among others). At the time I asked a friend who owned CDO 1.21 on the Exchange team and who was one of the original authors of MAPI 1.0 if the information was good and he said it was better than anything he had, he had to reverse engineer it himself <g>.

MAPI Recurrence Pattern and Exception Data Structure Reference

Last Updated July 20, 2004

Intro

As newer versions of Outlook have been released, this document has gotten
further out of date. Although older versions of the data appear to be
forward-compatible, anyone comparing this document against the data in their
current version of Outlook would doubtlessly be confused, so I've brought it
up to date. As of July, 2004, this document describes data produced by and
intended to be compatible with Outlook 2003.

Outlook stores the recurrence pattern in a binary field with id 0x8216, i.e.
PROP_TAG( PT_BINARY, 0x8216) in the Outlook appointment property set.
Without exceptions, these data will be either 72 or 80 bytes long. Outlook
apparently uses these data alone to determine the pattern: the rest of the
recurrence-related fields in the set (e.g. recurrence start date, end date,
and type) don't have any affect on the actual recurrence.

I've figured out what most of the bytes are (with some help-- see credits).
At a minimum, I've identified everything well enough to be able to export
recurrence patterns from my program to MAPI and have Outlook recognize them
appropriately, and that's all we really need. Those that I haven't seem not
to vary, so their meaning isn't very important, but if anyone knows what
they might mean, please let me know. OutlookSpy
(http://www.dimastr.com/outspy/) is an excellent tool for examining the
contents of this field (and for everything else under Heaven).

Recurrence Data Structure Offset Type Value

0 ULONG (?) Constant : { 0x04, 0x30, 0x04, 0x30}

4 UCHAR 0x0A + recurrence type: 0x0A for daily, 0x0B for weekly, 0x0C for
monthly, 0x0D for yearly

5 UCHAR Constant: { 0x20}

6 ULONG Seems to be a variant of the recurrence type: 1 for daily every n
days, 2 for daily every weekday and weekly, 3 for monthly or yearly. The
special exception is regenerating tasks that regenerate on a weekly basis: 0
is used in that case (I have no idea why).

Here's the recurrence-type-specific data. Because the daily every N days
data are 4 bytes shorter than the data for the other types, the offsets for
the rest of the data will be 4 bytes off depending on the recurrence type.
Daily every N days: 10 ULONG ( N - 1) * ( 24 * 60). I'm not sure what this
is used for, but it's consistent.

14 ULONG N * 24 * 60: minutes between recurrences

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

Daily every weekday (this is essentially a subtype of weekly recurrence): 10
ULONG 6 * 24 * 60: minutes between recurrences ( a week... sort of)

14 ULONG 1: recur every week (corresponds to the second parameter for weekly
recurrence)

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG 0x3E: bitmask for recurring every weekday (corresponds to fourth
parameter for weekly recurrence)

Weekly every N weeks for all events and non-regenerating tasks: 10 ULONG 6 *
24 * 60: minutes between recurrences (a week... sort of)

14 ULONG N: recurrence interval

18 ULONG Constant: 0

22 ULONG Bitmask for determining which days of the week the event recurs on
( 1 << dayOfWeek, where Sunday is 0).

Weekly every N weeks for regenerating tasks: 10 ULONG Constant: 0

14 ULONG N * 7 * 24 * 60: recurrence interval in minutes between occurrences

18 ULONG Constant: 1

Monthly every N months on day D: 10 ULONG This is the most complicated value
in the entire mess. It's basically a very complicated way of stating the
recurrence interval. I tweaked fbs' basic algorithm. DateTime::MonthInDays
simply returns the number of days in a given month, e.g. 31 for July for 28
for February (the algorithm doesn't take into account leap years, but it
doesn't seem to matter). My DateTime object, like Microsoft's COleDateTime,
uses 1-based months (i.e. January is 1, not 0). With that in mind, this
works:

long monthIndex = ( ( ( ( 12 % schedule->GetInterval()) *

( ( schedule->GetStartDate().GetYear() - 1601) %

schedule->GetInterval())) % schedule->GetInterval()) +

( schedule->GetStartDate().GetMonth() - 1)) % schedule->GetInterval();

for( int i = 0; i < monthIndex; i++)

{

value += DateTime::GetDaysInMonth( ( i % 12) + 1) * 24 * 60;

}

This should work for any recurrence interval, including those greater than
12.

14 ULONG N: recurrence interval

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG D: day of month the event recurs on (if this value is greater than
the number of days in a given month [e.g. 31 for and recurs in June], then
the event will recur on the last day of the month)

Monthly every N months on the Xth Y (e.g. "2nd Tuesday"): 10 ULONG See
above: same as for monthly every N months on day D

14 ULONG N: recurrence interval

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG Y: bitmask for determining which day of the week the event recurs
on (see weekly every N weeks). Some useful values are 0x7F for any day, 0x3E
for a weekday, or 0x41 for a weekend day.

26 ULONG X: 1 for first occurrence, 2 for second, etc. 5 for last
occurrence. E.g. for "2nd Tuesday", you should have values of 0x04 for the
prior value and 2 for this one.

Yearly on day D of month M: 10 ULONG M (sort of): This is another messy
value. It's the number of minute since the beginning of the year to the
given month. For an explanation of GetDaysInMonth, see monthly every N
months. This will work:

ULONG monthOfYearInMinutes = 0;

for( int i = DateTime::cJanuary; i < schedule->GetMonth(); i++)

{

monthOfYearInMinutes += DateTime::GetDaysInMonth( i) * 24 * 60;

}

14 ULONG 12: recurrence interval in months. Naturally, 12.

18 ULONG 0 for all events and non-regenerating recurring tasks. 1 for
regenerating tasks.

22 ULONG D: day of month the event recurs on. See monthly every N months on
day D.

Yearly on the Xth Y of month M: 10 ULONG M (sort of): See yearly on day D of
month M.

14 ULONG 12: recurrence interval in months. Naturally, 12.

18 ULONG Constant: 0

22 ULONG Y: see monthly every N months on the Xth Y.

26 ULONG X: see monthly every N months on the Xth Y.

After these recurrence-type-specific values, the offsets will change
depending on the type. For every type except daily every N days, the offsets
will grow by at least 4. For those types using the Xth Y, the offsets will
grow by an additional 4, for a total of 8. The offsets for the rest of these
values will be given for the most basic case, daily every N days, i.e.
without any growth. Adjust as necessary. Also, the presence of exceptions
will change the offsets following the exception data by a variable number of
bytes, so the offsets given in the table are accurate only for those
recurrence patterns without any exceptions. 22 UCHAR Type of pattern
termination: 0x21 for terminating on a given date, 0x22 for terminating
after a given number of recurrences, or 0x23 for never terminating
(recurring infinitely)

23 UCHARx3 Constant: { 0x20, 0x00, 0x00}

26 ULONG Number of occurrences in pattern: 0 for infinite recurrence,
otherwise supply the value, even if it terminates on a given date, not after
a given number

30 ULONG Constant: 0

34 ULONG Number of exceptions to pattern (i.e. deleted or changed
occurrences)

.... ULONGxN Base date of each exception, given in hundreds of nanoseconds
since 1601, so see below to turn them into a comprehensible format. The base
date of an exception is the date (and only the date-- not the time) the
exception would have occurred on in the pattern. They must occur in
ascending order.

38 ULONG Number of changed exceptions (i.e. total number of exceptions -
number of deleted exceptions): if there are changed exceptions, again, more
data will be needed, but that will wait

.... ULONGxN Start date (and only the date-- not the time) of each changed
exception, i.e. the exceptions which aren't deleted. These must also occur
in ascending order. If all of the exceptions are deleted, this data will be
absent. If present, they will be in the format above. Any dates that are in
the first list but not in the second are exceptions that have been deleted
(i.e. the difference between the two sets). Note that this is the start date
(including time), not the base date. Given that the values are unordered and
that they can't be matched up against the previous list in this iteration of
the recurrence data (they could in previous ones), it is very difficult to
tell which exceptions are deleted and which are changed. Fortunately, for
this new format, the base dates are given on the attachment representing the
changed exception (described below), so you can simply ignore this list of
changed exceptions. Just create a list of exceptions from the previous list
and assume they're all deleted unless you encounter an attachment with a
matching base date later on.

42 ULONG Start date of pattern given in hundreds of nanoseconds since 1601;
see below for an explanation.

46 ULONG End date of pattern: see start date of pattern

50 ULONG Constant: { 0x06, 0x30, 0x00, 0x00}

NOTE: I find the following 8-byte sequence of bytes to be very useful for
orienting myself when looking at the raw data. If you can find { 0x06, 0x30,
0x00, 0x00, 0x08, 0x30, 0x00, 0x00}, you can use these tables to work either
forwards or backwards to find the data you need. The sequence sort of
delineates certain critical exception-related data and delineates the
exceptions themselves from the rest of the data and is relatively easy to
find. If you're going to be meddling in here a lot, I suggest making a
friend of ol' 0x00003006.

54 UCHAR This number is some kind of version indicator. Use 0x08 for Outlook
2003. I believe 0x06 is Outlook 2000 and possibly 98, while 0x07 is Outlook
XP. This number must be consistent with the features of the data structure
generated by the version of Outlook indicated thereby-- there are subtle
differences between the structures, and, if the version doesn't match the
data, Outlook will sometimes failto read the structure.

55 UCHARx3 Constant: { 0x30, 0x00, 0x00}

58 ULONG Start time of occurrence in minutes: e.g. 0 for midnight or 720 for
12 PM

62 ULONG End time of occurrence in minutes: i.e. start time + duration, e.g.
900 for an event that starts at 12 PM and ends at 3PM

Exception Data 66 USHORT Number of changed exceptions: essentially a check
on the prior occurrence of this value; should be equivalent.

NOTE: The following structure will occur N many times (where N = number of
changed exceptions), and each structure can be of variable length.

.... ULONG Start date of changed exception given in hundreds of nanoseconds
since 1601

.... ULONG End date of changed exception given in hundreds of nanoseconds
since 1601

.... ULONG This is a value I don't clearly understand. It seems to be some
kind of archival value that matches the start time most of the time, but
will lag behind when the start time is changed and then match up again under
certain conditions later. In any case, setting to the same value as the
start time seems to work just fine (more information on this value would be
appreciated).

.... USHORT Bitmask of changes to the exception (see below). This will be 0
if the only changes to the exception were to its start or end time.

.... ULONGxN Numeric values (e.g. label or minutes to remind before the
event) changed in the exception. These will occur in the order of their
corresponding bits (see below). If no numeric values were changed, then
these values will be absent.

NOTE: The following three values constitute a single sub-structure that will
occur N many times, where N is the number of strings that are changed in the
exception. Since there are at most 2 string values that can be excepted
(i.e. subject [or description], and location), there can at most be two of
these, but there may be none.

.... USHORT Length of changed string value with NULL character

.... USHORT Length of changed string value without NULL character (i.e.
previous value - 1)

.... CHARxN Changed string value (without NULL terminator)

Unicode Data NOTE: If a string value was changed on an exception, those
changed string values will reappear here in Unicode format after 8 bytes of
NULL padding (possibly a Unicode terminator?). For each exception with a
changed string value, there will be an identifier, followed by the changed
strings in Unicode. The strings will occur in the order of their
corresponding bits (see below). E.g., if both subject and location were
changed in the exception, there would be the 3-ULONG identifier, then the
length of the subject, then the subject, then the length of the location,
then the location.

70 ULONGx2 Constant: { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}. This
padding serves as a barrier between the older data structure and the
appended Unicode data. This is the same sequence as the Unicode terminator,
but I'm not sure whether that's its identity or not.

.... ULONGx3 These are the three times used to identify the exception above:
start date, end date, and repeated start date. These should be the same as
they were above.

.... USHORT Length of changed string value without NULL character. This is
given as count of WCHARs, so it should be identical to the value above.

.... WCHARxN Changed string value in Unicode (without NULL terminator)

Terminator ... ULONGxN Constant: { 0x00, 0x00, 0x00, 0x00}. 4 bytes of NULL
padding per changed exception. If there were no changed exceptions, all
you'll need is the final terminator below.

.... ULONGx2 Constant: { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}.

Manipulating Values Given in Nanoseconds since 1601

These values are an abridged form of the FILETIME representation). Values in
the present end with byte 0x0C when you're looking at them in OutlookSpy.
Note that my DateTime object handles conversions between itself and
FILETIME, but the COleDateTime will as well. Also note that these times are
in LOCAL time, not in UTC as with all the rest of the Outlook dates.
Therefore, it is unnecessary to call FileTimeToLocalFileTime or the inverse
when converting either direction. However, you may need to put those values
back in local time if the object you're using automatically adjusts them to
UTC. These can be calculated using the following functions:

#define cFileTimeUnitsPerSecond 10000000i64

DateTime CMAPIEvent::ConvertRecurrenceMinutesToDate( ULONG minutes)

{

ULONGLONG fileTimeUnitsBeforeStart = (ULONGLONG) minutes * 60i64 *
cFileTimeUnitsPerSecond;

FILETIME ft = { (DWORD) ( fileTimeUnitsBeforeStart & 0xFFFFFFFF), (DWORD)
( fileTimeUnitsBeforeStart >> 32)};

DateTime date;

date.SetDateTime( ft);

return date;

}

ULONG CMAPIEvent::ConvertRecurrenceDateToMinutes( DateTime date)

{

FILETIME ft = date;

ULONGLONG minutes = ( ( (ULONGLONG) ft.dwHighDateTime) << 32) +
ft.dwLowDateTime;

minutes = minutes / 60i64;

minutes = minutes / cFileTimeUnitsPerSecond;

return (ULONG) minutes;

}

Exceptions

Here are the bits for the change bitmask: Bit Value Change Stored As

1 1 Description String following

2 2 Notes Creates attachment

3 4 Remind before ULONG following

4 8 Reminder set ULONG ( 0 or 1) following

5 16 Location String following

6 32 Show time as ULONG following

7 64 RESERVED

8 128 Is all day ULONG (0 or 1) following

9 256 Label/color ULONG following

10 512 Has attachment Creates attachment

In order of the bit, the changed values will occur after this bitmask. For
numeric values, they'll occur simply as ULONGs. For string values, there
will be two USHORTs and then the characters. The first USHORT will be the
length of the string including the NULL character, whereas the second will
be the length without, so that the second number is just the first number -
1. The NULL character isn't in the stream, though.

Further Notes

In order to make Outlook prompt the user to delete either the entire series
or the individual occurrence, you have to set property PROP_TAG( PT_LONG,
0x8510) in the COMMON property set to 369.

Here are the essential property tag definitions I've gathered together:

#define PS_OUTLOOK_EVENT Guid( "0x0220060000000000C000000000000046")
//CdoPropSetID1

#define PR_OUTLOOK_EVENT_START_DATE PROP_TAG( PT_SYSTIME, 0x820D)

#define PR_OUTLOOK_EVENT_END_DATE PROP_TAG( PT_SYSTIME, 0x820E)

#define PR_OUTLOOK_EVENT_LOCATION PROP_TAG( PT_STRING8, 0x8208)

#define PR_OUTLOOK_EVENT_SHOW_TIME_AS PROP_TAG( PT_LONG, 0x8205)

#define PR_OUTLOOK_EVENT_ALL_DAY PROP_TAG( PT_BOOLEAN, 0x8215)

#define PR_OUTLOOK_EVENT_RECURRENCE_TYPE PROP_TAG( PT_LONG, 0x8231)

#define PR_OUTLOOK_EVENT_RECURRENCE_SET PROP_TAG( PT_BOOLEAN, 0x8223)

#define PR_OUTLOOK_EVENT_RECURRENCE_DATA PROP_TAG( PT_BINARY, 0x8216)

#define PR_OUTLOOK_EVENT_RECURRENCE_START PROP_TAG( PT_SYSTIME, 0x8235)

#define PR_OUTLOOK_EVENT_RECURRENCE_END PROP_TAG( PT_SYSTIME, 0x8236)

#define PR_OUTLOOK_EVENT_DURATION PROP_TAG( PT_LONG, 0x8213)

#define PR_OUTLOOK_EVENT_RECURRENCE_BASE PROP_TAG( PT_SYSTIME, 0x8228)

#define PS_OUTLOOK_COMMON Guid( "0x0820060000000000C000000000000046")
//CdoPropSetID4

#define PR_OUTLOOK_COMMON_REMINDER_MINUTES_BEFORE PROP_TAG( PT_LONG, 0x8501)

#define PR_OUTLOOK_COMMON_REMINDER_DATE PROP_TAG( PT_SYSTIME, 0x8502)

#define PR_OUTLOOK_COMMON_REMINDER_SET PROP_TAG( PT_BOOLEAN, 0x8503)

#define PR_OUTLOOK_COMMON_ALLOW_EXCEPTION_DELETE PROP_TAG( PT_LONG, 0x8510)

Credits

Daniel Mitchell: A lot of the data offsets and explanations.

fbs: The monthly recurrence interval algorithm.

Robert Swofford: The property value to set to allow occurrences to be
deleted independently.

Dmitry Streblechenko: Author of OutlookSpy, without which this would have
been nearly impossible.

Hisham Shafi: Corrected a few of the bits in the exception structure.

Cameron Ring: Figured out time zone information, task recurrence, and some
other pieces of the puzzle.

Cain T. S. Random

--
Ken Slovak
[MVP-Outlook]
http://www.slovaktech.com
Author: Professional Programming Outlook 2007
"JimDenmark" <=?utf-8?B?SmltRGVubWFyaw==?=> wrote in message news:364dee34-2f18-47f3-b78a-6728dd193cf2...

Dear All - I wonder if you could help with this rather abstract problem...

I have the MS-OXOCAL specification for RecurrencePattern structure. In this, the reasons for calculating the FirstDateTime Offset for certain daily and weekly recurrence patterns are well documented and comprehensible.

However, for monthly (and therefore also yearly) recurrence patterns, I'm a bit confused.

Given that for monthly/yearly recurrence patterns, the FirstDateTime is NOT dependent on the FirstDOW parameter but on the CalendarType parameter, if I don't plan to use any other calendar than the Gregorian calendar, starting 1/1/1601, then is the FirstDateTime 4-byte part of the RecurrencePattern bit structure irrelevant for me ?

Example (using the Default Outlook (i.e. for me, Gregorian) calendar):

today is 30 August 2012;I set a RecurrencePattern recurring on the 30th day of the month, recurring every 2 months, ending after 10 occurrences, starting 30 August 2012; Outlook naturally correctly calculates that the first Occurrence is 30 Aug 2012, and that the end date is 28 Feb 2014;

Does this calculation anyway involve FirstDateTime ?

According to MS-OXOCAL, it should: (Quote) "Given an input date, the next valid month is found by adding the difference between the input month and a 1600-year offset (the value of the FirstDateTime field) modulo (the value of the Period field)."

In my example, the input month is 8, the FirstDateTime value is 44640 (i.e. 31 days after 1/1/1601, or a 1 month offset), and therefore, according to this, the first valid month for the RecurrencePattern should be 8 + ( (8-1) MOD 2)=9, i.e. September.

September is neither a month in which an Occurrence occurs, nor a month from which, using Occurrences*Period, the End Date can or should be determined.

Outlook calculates exactly the same FirstDateTime value for a similar RecurrencePattern but which begins on, e.g. 25 August, or any date in August before the startDate (30-Aug) specified.

I have a feeling I'm seeing far too many trees and far too little of the forest here...

As always, any help greatly appreciated.

Jim

Ken Slovak MVP - Outlook
• Marked as answer by Sunday, September 2, 2012 9:00 AM
Friday, August 31, 2012 7:35 PM
• Ken - many thanks for this valuable analysis; in the above, the "10 ULONG" portion of the recurrence pattern (which equates to the FirstDateTime property in the MS-OXOCAL specification) is described as

"the most complicated value
in the entire mess"

At least I'm not alone in having difficulty ! For now, I have managed to get something working, so I'll review in detail when I get chance.

Again, many thanks,

Jim

Sunday, September 2, 2012 9:00 AM