Jaa

Incremental Change Synchronization API Definitions

  • Artikkeli

The following interfaces and properties are defined in the Exchange header file edkmdb.h. They are provided here in case your application has to use them, and you are unsure of their function.

Applications implement interfaces according to the IExchangeImportContentsChanges definition. The interface that is used by the Incremental Change Synchronization (ICS) system can notify the application when changes to the mailbox content have occurred. The interface is registered for callback when you configure the synchronizer object that is returned by the MAPI folder object.

The interface definition is commented-out in the header file edkmdb.h because Exchange does not actually implement the interface. The application implements the interface.

// IExchangeImportContentsChanges
    STDMETHOD(GetLastError)(HRESULT hResult, ULONG ulFlags, __in LPMAPIERROR *lppMAPIError);
    STDMETHOD(Config)(__in LPSTREAM lpStream, ULONG ulFlags);
    STDMETHOD(UpdateState)(__in LPSTREAM lpStream);
    STDMETHOD(ImportMessageChange)
        (ULONG cpvalChanges, __in LPSPropValue ppvalChanges, ULONG ulFlags, __in LPMESSAGE *lppMessage);
    STDMETHOD(ImportMessageDeletion)(ULONG ulFlags, __in LPENTRYLIST lpSrcEntryList);
    STDMETHOD(ImportPerUserReadStateChange)(ULONG cElements, __in LPREADSTATE lpReadState);
    STDMETHOD(ImportMessageMove)
        (ULONG cbSourceKeySrcFolder, __in BYTE *pbSourceKeySrcFolder,
         ULONG cbSourceKeySrcMessage, __in BYTE *pbSourceKeySrcMessage,
         ULONG cbPCLMessage, __in BYTE *pbPCLMessage,
         ULONG cbSourceKeyDestMessage, __in BYTE *pbSourceKeyDestMessage,
         ULONG cbChangeNumDestMessage, __in BYTE *pbChangeNumDestMessage)

The following interface definition, found in the edkmdb.h header file, is returned by the MAPI folder object. Configure the object properties using the object methods, and then call the Synchronize method to register the custom ExchangeImportContentsChanges callback routine of your application.

#define EXCHANGE_IEXCHANGEEXPORTCHANGES_METHODS(IPURE) \
    MAPIMETHOD(GetLastError) \
       (THIS_ HRESULT hResult, \
        ULONG ulFlags, \
        LPMAPIERROR FAR * lppMAPIError) IPURE; \
    MAPIMETHOD(Config) \
       (THIS_ LPSTREAM lpStream, \
        ULONG ulFlags, \
        LPUNKNOWN lpUnk, \
        LPSRestriction lpRestriction, \
        LPSPropTagArray lpIncludeProps, \
        LPSPropTagArray lpExcludeProps, \
        ULONG ulBufferSize) IPURE; \
    MAPIMETHOD(Synchronize) \
       (THIS_ ULONG FAR * lpulSteps, \
        ULONG FAR * lpulProgress) IPURE; \
    MAPIMETHOD(UpdateState) \
       (THIS_ LPSTREAM lpStream) IPURE;
#undef INTERFACE

The PR_CONTENTS_SYNCHRONIZER property is used to request a pointer to the IExchangeExportChanges object. Note that the PT_Object and PROP_TAG are also defined in the edkmdb.h header file.

#define pidStoreMin 0x6618
#define PR_CONTENTS_SYNCHRONIZER PROP_TAG( PT_OBJECT, pidStoreMin+0x15)

The following flags instruct ICS as to what types of changes the application is interested in receiving.

/*------------------------------------------------------------------------
 *
 * Flags used by Exchange Incremental Change Synchronization Interface
 *
 *-----------------------------------------------------------------------*/
#define SYNC_UNICODE 0x01
#define SYNC_NO_DELETIONS 0x02
#define SYNC_NO_SOFT_DELETIONS 0x04
#define SYNC_READ_STATE 0x08
#define SYNC_ASSOCIATED 0x10
#define SYNC_NORMAL 0x20
#define SYNC_NO_CONFLICTS 0x40
#define SYNC_ONLY_SPECIFIED_PROPS 0x80
#define SYNC_NO_FOREIGN_KEYS 0x100
#define SYNC_LIMITED_IMESSAGE 0x200
#define SYNC_CATCHUP 0x400
#define SYNC_NEW_MESSAGE 0x800 // only applicable to ImportMessageChange()
#define SYNC_MSG_SELECTIVE 0x1000 // Used internally. Will reject if used by clients.
#define SYNC_BEST_BODY 0x2000
#define SYNC_IGNORE_SPECIFIED_ON_ASSOCIATED 0x4000
#define SYNC_PROGRESS_MODE 0x8000 // AirMapi progress mode
#define SYNC_FXRECOVERMODE 0x10000
#define SYNC_DEFER_CONFIG 0x20000
#define SYNC_FORCE_UNICODE 0x40000 // Forces server to return Unicode properties

When combined with the others defined in the ebkmdb.h, the following bit-field definitions are used to indicate the scope of changes that Exchange ICS will report to the application:

#define CONVENIENT_DEPTH ((ULONG) 0x00000001
#define SHOW_SOFT_DELETES ((ULONG) 0x00000002)
#define SHOW_SUBFOLDERS ((ULONG 0x00000004)

The PR_LOCAL_COMMIT_TIME_MAX property, which is returned for a folder, indicates when any items in the folder were last changed. When this property value is different from the PR_LOCAL_COMMIT_TIME property value, items in the folder have changed since the last time changes to the folder were committed to the database.

#define pidAdminMin 0x6690
#define PR_LOCAL_COMMIT_TIME_MAX PROP_TAG(PT_SYSTIME, pidAdminMin+0x7a)

The PR_DELETED_COUNT_TOTAL property indicates how many items have been deleted from the folder since the folder was created.

#define pidAdminMin 0x6690
#define PR_DELETED_COUNT_TOTAL PROP_TAG(PT_LONG, pidAdminMin+0x7b)

Comments

  • Anonymous
    March 28, 2008
    Managing Folders in Outlook 2007 Cross Forest Exchange Impersonation in Exchange 2007 Service Pack 1

  • Anonymous
    August 13, 2008
    Any ides for this error: Error in IExchangeExportChanges::Synchronize: MAPI_E_CALL_FAILED Only happens on the calendar of one user. Exporting the data to a PST and importing it into another user's calendar seems to fix the issue. Two different ICS apps get this error now for this user's calendar. How can we tell what is wrong with the calendar (which appointment or porperty)?

  • Anonymous
    October 15, 2008
    Really simple guide, has given me an idea for a blog of my friends.

  • Anonymous
    October 20, 2008
    A really well explained article and has given me a nice idea for a project!

  • Anonymous
    July 07, 2010
    Is there detailed explaination about these flags?