Rebase That: Update to the Calendar Rebasing Library

We just released an update to our calendar rebasing library, Tzmovelib.dll. This update includes a refresh to the documentation. One thing that didn't make it into this refresh was an updated sample and documentation for a new exported function, primarily because I didn't have it ready in time. So I'm documenting the new function here, and it will make it into the MSDN the next time we refresh the docs.

We've added a new export to tzmovelib.dll in this refresh. It's name is HrCreateApptRebaserEx. It functions exactly the same as HrCreateApptRebaser unless a new flag, REBASE_FLAG_PHYSICAL_MOVE is passed. In that case, we use the new pTZFrom parameter to effect a rebase from an old time zone to a new time zone. Additionally, we renamed the pftInstallDateUTC parameter to ptfRebaseExpireUTC, and the REBASE_FLAG_ONLY_CREATED_PRE_PATCH flag to REBASE_FLAG_ONLY_REBASE_BEFORE_EXPIRE to reflect that this parameter and flag apply to physical moves as well. The behavior of this parameter and flag did not change.

Resources

Documentation

HrCreateApptRebaserEx

The HrCreateApptRebaserEx function initializes a IOlkApptRebaser object for use in rebasing appointments.

Quick Info

Syntax

 HRESULT HrCreateApptRebaserEx( 
    ULONG ulFlags,
    IMAPISession *pSession,
    IMsgStore *pCalendarMsgStore,
    IMAPIFolder *pCalendarFolder,
    LPCWSTR pwszUpdatePrefix,
    const FILETIME *pftRebaseExpireUTC,
    LONG lExpansionDepth,
    const TZDEFINITION *pTZFrom,
    const TZDEFINITION *pTZTo,
    const TZDEFINITION *pTZMissing,
    MAPIERROR **ppError,
    IOlkApptRebaser **ppApptRebase);

Parameters

ulFlags [in] Bitmask of flags used to control how rebasing is performed. The following flags can be set:

REBASE_FLAG_UPDATE_ORGANIZED_MEETINGS

Items in which the user is the meeting organizer will be rebased. Note that by default this will cause meeting updates to be sent out to all attendees of any meeting being rebased. Combine this flag with either REBASE_FLAG_FORCE_NO_EX_UPDATES or REBASE_FLAG_FORCE_NO_UPDATES to change the behavior of how meeting updates are handled.

REBASE_FLAG_UPDATE_UNMARKED

Update items that aren't marked with a time zone. If this flag is specified, the pTZMissing value passed to HrCreateApptRebaser will be used as created-in time zone for all items that do not have time zone data.

REBASE_FLAG_UPDATE_ONLYRECURRING

Update only recurring items.

REBASE_FLAG_NO_UI

Do not show any UI (prevents the display of any logon dialog boxes when opening the message store).

REBASE_FLAG_UPDATE_MINIMIZEAPPTS

Do not rebase items that will only have changes which occur in the past.

REBASE_FLAG_FORCE_REBASE

Do not check the organizer for rebasing decisions (enables items in which the user is the attendee to be rebased).

REBASE_FLAG_FORCE_NO_EX_UPDATES

Only send updates if the user is the organizer and recipient is non-EX.

REBASE_FLAG_FORCE_NO_UPDATES

Never send updates.

REBASE_FLAG_ONLY_REBASE_BEFORE_EXPIRE

Only rebase single instance items created before a specified date, which is either a patch install date or a physical move date.

REBASE_FLAG_REPORTING_MODE

Do not actually rebase, just report items that would be rebased.

REBASE_FLAG_SEND_RESOURCE_UPDATES

Send meeting updates to resources (attendees explicitly specified on the "Resource" line of a meeting).

REBASE_FLAG_PHYSICAL_MOVE

Don't skip rebasing of unaffected future recurring appointments for physical move. Only valid for HrCreateApptRebaseEx. If this flag is set, pTZFrom must be a valid time zone definition representing the "from" time zone and pTZTo then represents the "to" time zone. If this new flag is not set, then pTZFrom must be NULL, and HrCreateApptRebaseEx functions exactly the same as HrCreateApptRebase. REBASE_FLAG_PHYSICAL_MOVE is not valid with REBASE_FLAG_UPDATE_ONLYRECURRING. REBASE_FLAG_PHYSICAL_MOVE implies REBASE_FLAG_UPDATE_UNMARKED and REBASE_FLAG_UPDATE_MINIMIZEAPPTS.

pSession [in] Required. Pointer to a MAPI session interface.

pCalendarMsgStore [in] Required. Pointer to a message store containing items to be rebased.

pCalendarFolder [in] Require. Pointer to a Calendar folder containing items to be rebased.

pwszUpdatePrefix [in] Optional. Pointer to a string containing the prefix to be prepended on meeting requests. May be NULL.

pftRebaseExpireUTC [in] Optional. Only rebase items before this date. Only used if the REBASE_FLAG_ONLY_REBASE_BEFORE_EXPIRE flag is set.

lExpansionDepth [in] Expansion depth when expanding distribution lists to exclude EX recipients. Only used if the REBASE_FLAG_FORCE_NO_EX_UPDATES flag is set.

pTZFrom [in] Required. Pointer to a TZDEFINITION structure describing the time zone to be rebased from.

pTZTo [in] Required. Pointer to a TZDEFINITION structure describing the time zone to be rebased to.

pTZMissing [in] Required. Pointer to a TZDEFINITION structure describing the time zone to be assumed if time zone information is not stamped on an item. Must not be NULL, but only used if the REBASE_FLAG_UPDATE_UNMARKED flag is set.

ppError [out] Optional. Pointer to a pointer to a MAPIERROR structure containing version, component, and context information for the error. Can be NULL if no extended error information is desired. Free with MAPIFreeBuffer.

ppApptRebase [out] Pointer to a pointer to the returned IOlkApptRebaser interface.

Remarks

Obtain this function from tzmovelib.dll by calling GetProcAddress with the function name HrCreateApptRebaserEx@48. When REBASE_FLAG_PHYSICAL_MOVE and pTZFrom are not passed, this function is identical in behavior to HrCreateApptRebaser.

Not all of the flags are valid in combination with each other. View the "Glossary of command-line options for the Outlook Time Zone Data Update tool" section of https://support.microsoft.com/kb/931667 for more information on the various options.