none
Problem (or not ?) with FirstDateTime on RecurrencePatterns (Tasks mostly) RRS feed

  • 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 JimDenmark Sunday, September 2, 2012 9:00 AM
    Friday, August 31, 2012 7:35 PM
    Moderator

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 JimDenmark Sunday, September 2, 2012 9:00 AM
    Friday, August 31, 2012 7:35 PM
    Moderator
  • 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