WindowsSyncSource Class Reference
[Client DLL]

This class is the extension of SyncSource class for specific Client objects. More...

#include <WindowsSyncSource.h>

Inheritance diagram for WindowsSyncSource:
[legend]
Collaboration diagram for WindowsSyncSource:
[legend]

List of all members.

Public Member Functions

 WindowsSyncSource (const WCHAR *name, WindowsSyncSourceConfig *wsc)
 Constructor: creates a WindowsSyncSource with the specified name and config.
const WindowsSyncSourceConfiggetConfig () const
 Used to access configuration of SS.
WindowsSyncSourceConfiggetConfig ()
 read-write access to win configuration
int beginSync ()
 This is the first method called.
int endSync ()
 This is the last method called.
void setItemStatus (const WCHAR *key, int status)
 called by the sync engine with the status returned by the server for a certain item that the client sent to the server
void assign (WindowsSyncSource &s)
int removeAllItems ()
 Deletes all items in Outlook for this source.
SyncItem * getFirstItem ()
 It's called in case of full-sync or refresh-from-client sync.
SyncItem * getNextItem ()
 It's called in case of full-sync or refresh-from-client sync.
SyncItem * getFirstNewItem ()
 It's called in case of two-way sync.
SyncItem * getNextNewItem ()
 It's called in case of two-way sync.
SyncItem * getFirstUpdatedItem ()
 It's called in case of two-way sync.
SyncItem * getNextUpdatedItem ()
 It's called in case of two-way sync.
SyncItem * getFirstDeletedItem ()
 It's called in case of two-way sync.
SyncItem * getNextDeletedItem ()
 It's called in case of two-way sync.
int addItem (SyncItem &item)
 Adds the item from the server to the client.
int updateItem (SyncItem &item)
 Update the item from the server to the client.
int deleteItem (SyncItem &item)
 Delete the SyncItem (empty, only key) from server to client.
DateFiltergetDateFilter ()
 Returns a reference to DateFilter (proxy method).

Protected Member Functions

ClientFoldergetStartFolder ()
 Get the starting Outlook folder for this source.
void pushAllSubfolderItemsToList (ClientFolder *folder, itemKeyList &listItems, itemKeyList &listItemsPaths)
 Get all items inside 'folder' and also all items from every subfolder (call to this method recursively).
void pushAllItemsToList (ClientFolder *folder, itemKeyList &listItems, itemKeyList &listItemsPaths)
 Get all items inside 'folder' and push them (only keys) into 'listItems' list.
int manageModificationsFromLastSync ()
 Creates the NEW/MOD/DEL items lists from last successfull sync.
int addForcedItemsToModList (itemKeyList &forcedItems)
 Scan the passed list of 'forced modified items' and add each element to the 'modItems' list.
std::wstring createOldItems ()
 Format the list of all current items into a string, as an XML.
void parseOldItems (std::wstring &data, itemKeyList &listItems, itemKeyList &listFolders)
 Parse the list of all current items into a string, from an XML.
int resetDataFile (const std::wstring &itemType)
 Reset the specified data file: destroy any content and add a "<itemType>" tag at the beginning of file.
int closeDataFile (const std::wstring &itemType)
 Close the specified data file: append a "</itemType>" tag at the end of the file.
bool folderPathAllowed (const std::wstring &p)
 Returns true if path passed is allowed to sync items inside it.
void checkBirthdayAnniversary (ClientItem *cItem)
 Verifies if birthday/anniversary were created by Outlook (only for contacts save).
int deleteAppointment (ClientItem *cItem, const std::wstring &propertyName)
 Deletes an appointement event (birthday or anniversary) automatically created by Outlook while saving item 'cItem'.
void manageSourceError (const int errorCode, const char *errorMsg)
 Common actions to do when an error occurs inside SyncSource.
void manageSourceErrorF (const int errorCode, const char *msgFormat,...)
 Calls manageSourceError, with msg formatted in a string.
void extractFolder (const std::wstring dataString, const std::wstring dataType, std::wstring &path)
 Extract 'Folder' path searching inside string 'dataString' (SIF or vCard/vCal).
bool filterClientItem (ClientItem *item, DateFilter::FilterDirection direction, const char *command=NULL)
 Applies all active filters for this source, on the passed clientItem.
void updateFilters ()
 Refresh all active filters.

Protected Attributes

WindowsSyncSourceConfigwinConfig
 Configuration object for the source.
itemKeyList allItems
 Lists of item keys.
itemKeyList newItems
itemKeyList modItems
itemKeyList delItems
itemKeyList allItemsPaths
 This is the list of all items path in Outlook.
itemKeyList filteredItems
 List of all items filtered out, during first scan.
itemKeyIterator iAll
 Iterators of lists.
itemKeyIterator iNew
itemKeyIterator iMod
itemKeyIterator iDel
itemKeyIterator iAllPaths
itemKeyIterator iFiltered
unsigned int numErrors
 Counter of number of errors occurred.
std::wstring defaultFolderPath
 Default folder path in Outlook.

Private Attributes

ClientApplicationoutlook
 Pointer to the sole instance of ClientApplication (singleton).
int filterDirection


Detailed Description

This class is the extension of SyncSource class for specific Client objects.

Implements all methods to get/add syncItems on Client, plus there are some internal methods to handle operations on the SyncSource.

All syncItems are managed inside this class, the only difference is the member 'name'.


Constructor & Destructor Documentation

WindowsSyncSource::WindowsSyncSource ( const WCHAR *  name,
WindowsSyncSourceConfig wsc 
)

Constructor: creates a WindowsSyncSource with the specified name and config.

Parameters:
name the name of the SyncSource
wsc to init by reference the 'winConfig' member (for client-specific props) 'config' member is initialized from wsc->getCommonConfig() to get the original common properties used by API.

References allItems, allItemsPaths, defaultFolderPath, filteredItems, numErrors, and outlook.


Member Function Documentation

int WindowsSyncSource::addForcedItemsToModList ( itemKeyList forcedItems  )  [protected]

Scan the passed list of 'forced modified items' and add each element to the 'modItems' list.

Elements are added ONLY if not yet found in one of the lists (NEW/MOD/DEL) - to avoid duplicates.

Parameters:
forcedItems list of forced items to scan
Returns:
the number of items added to modItems list

Referenced by manageModificationsFromLastSync().

int WindowsSyncSource::addItem ( SyncItem &  item  )  [virtual]

int WindowsSyncSource::beginSync (  )  [virtual]

This is the first method called.

It executes all operations to be done before synchronizing this source:

  • opens Outlook session (if not yet done)
  • gets the selected folder for synchronization defined in configuration
  • creates a list of ALL items (keys) to be synchronized

Returns:
0 if no errors occurred

Reimplemented from SyncSource.

References allItems, allItemsPaths, checkAbortedSync(), defaultFolderPath, filteredItems, getConfig(), getDateFilter(), ClientApplication::getDefaultFolder(), DateFilter::getDirection(), ClientApplication::getInstance(), SyncSource::getName(), ClientFolder::getPath(), getStartFolder(), SyncSource::getSyncMode(), manageClientException(), manageSourceErrorF(), outlook, pushAllItemsToList(), pushAllSubfolderItemsToList(), DateFilter::setDirection(), WindowsSyncSourceConfig::setIsSynced(), SyncSourceReport::setState(), SOURCE_ERROR, updateFilters(), and winConfig.

void WindowsSyncSource::checkBirthdayAnniversary ( ClientItem cItem  )  [protected]

Verifies if birthday/anniversary were created by Outlook (only for contacts save).

If created, they are immediately deleted.

References ClientContact::createdAnniversaryEvent(), ClientContact::createdBirthdayEvent(), deleteAppointment(), SyncSource::getName(), getSafeItemName(), and manageClientException().

Referenced by addItem(), and updateItem().

int WindowsSyncSource::closeDataFile ( const std::wstring &  itemType  )  [protected]

Close the specified data file: append a "</itemType>" tag at the end of the file.

The file path is "<APP_DATA>\Funambol\Outlook Client\<itemType>.db"

Parameters:
itemType the itemType
Returns:
0 if no errors

References readDataPath(), and writeToFile().

Referenced by endSync().

wstring WindowsSyncSource::createOldItems (  )  [protected]

Format the list of all current items into a string, as an XML.

<contact> <LastSyncTime>1168862109</LastSyncTime> <ID>00013505600G4BGG494D009680</ID> <Folder>\Personal Folder</Folder> <ID>00033505600G4BGG494D006620</ID> <Folder>\Personal Folder</Folder> ... </contact>

'ID' is the item's ID in Outlook. 'Folder' is the item's folder path in Outlook.

Returns:
the formatted XML string

References allItems, allItemsPaths, checkAbortedSync(), CLIENT, ClientApplication::getItemFromID(), SyncSourceReport::getItemReport(), SyncSourceReport::getItemReportCount(), SyncSource::getName(), ClientItem::getParentPath(), iAll, isErrorStatus(), and outlook.

Referenced by endSync().

int WindowsSyncSource::deleteAppointment ( ClientItem cItem,
const std::wstring &  propertyName 
) [protected]

Deletes an appointement event (birthday or anniversary) automatically created by Outlook while saving item 'cItem'.

The item to delete is searched inside default Outlook folder, where:

  • 'Start' corresponds exactly to the date of birthday/anniversary
  • 'Subject' contains the 'Subject' of contact cItem (usually is e.g. "Mike Portnoy's birthday"). [Note: the subject does not contain exactly the FullName nor the FileAs nor FirstName...]

Parameters:
cItem : the ClientContact that was saved
propertyName : "Anniversary" or "Birthday"
Returns:
0 if found and correctly deleted - 1 otherwise

References ClientItem::deleteItem(), ClientApplication::getDefaultFolder(), ClientApplication::getInstance(), ClientFolder::getItemsCount(), ClientFolder::getItemsIndex(), ClientFolder::getLastItem(), ClientFolder::getPreviousItem(), ClientItem::getProperty(), manageClientException(), and outlook.

Referenced by checkBirthdayAnniversary().

int WindowsSyncSource::deleteItem ( SyncItem &  item  )  [virtual]

Delete the SyncItem (empty, only key) from server to client.

Returns:
code 200 if operation succesful, 211 if item not found, 500 if errors occurred.

Implements SyncSource.

References checkAbortedSync(), SyncSourceReport::checkState(), ClientItem::deleteItem(), filterClientItem(), folderPathAllowed(), ClientApplication::getItemFromID(), SyncSource::getName(), ClientItem::getParentPath(), getSafeItemName(), manageClientException(), manageSourceErrorF(), and outlook.

int WindowsSyncSource::endSync (  )  [virtual]

This is the last method called.

It executes all operations to be done after this source has been synchronized:

  • creates a list of ALL items (keys) currently on Outlook
  • formats the list as an XML with item keys/path
  • stores the XML string into FileSystem (create a cache file)

Returns:
0 if no errors occurred

Reimplemented from SyncSource.

References checkAbortedSync(), closeDataFile(), createOldItems(), getConfig(), getDateFilter(), SyncSource::getName(), SyncSource::getSyncMode(), makeDataDirs(), manageSourceError(), readDataPath(), DateFilter::setDirection(), SyncSourceReport::setLastErrorMsg(), SyncSourceReport::setState(), SOURCE_ERROR, winConfig, and writeToFile().

void WindowsSyncSource::extractFolder ( const std::wstring  dataString,
const std::wstring  dataType,
std::wstring &  path 
) [protected]

Extract 'Folder' path searching inside string 'dataString' (SIF or vCard/vCal).

Path retrieved is written into 'path' variable (empty string if 'Folder' not found).

Parameters:
dataString the input string to search 'Folder' info
dataType the mime data type (SIF/vCard)
path [OUTPUT] the folder path exctracted

References createWinItem(), defaultFolderPath, SyncSource::getName(), WinItem::getProperty(), isSIF(), and winConfig.

Referenced by addItem(), and updateItem().

bool WindowsSyncSource::filterClientItem ( ClientItem item,
DateFilter::FilterDirection  direction,
const char *  command = NULL 
) [protected]

Applies all active filters for this source, on the passed clientItem.

Parameters:
item the ClientItem to check
direction DIR_IN if it's an incoming item, DIR_OUT if it's an outgoing item (the method will also check filters settings) TODO: 'direction' should be defined in a more generic 'ClientFilter' class.
command It is the command the server send to the client. It could be ADD, DELETE, REPLACE There are some test to be perfomed in the method. It is null by default because for exiting items we don't need to know it.
Returns:
true, if the item passed all filters (so it should be synced) false, if the item didn't pass at least 1 filter (so it should be filtered out, ignored)

References DateFilter::execute(), ClientAppointment::getCOMPtr(), getDateFilter(), DateFilter::getDirection(), ClientAppointment::getRecPattern(), ClientItem::getType(), ClientRecurrence::refresh(), and ClientRecurrence::save().

Referenced by addItem(), deleteItem(), pushAllItemsToList(), and updateItem().

const WindowsSyncSourceConfig & WindowsSyncSource::getConfig (  )  const

Used to access configuration of SS.

read-only access to win configuration

Reimplemented from SyncSource.

References winConfig.

Referenced by beginSync(), endSync(), folderPathAllowed(), getStartFolder(), printReport(), and startSync().

SyncItem * WindowsSyncSource::getFirstDeletedItem (  )  [virtual]

It's called in case of two-way sync.

Returns:
the first SyncItem of delItems list.
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), and SyncSourceReport::checkState().

SyncItem * WindowsSyncSource::getFirstItem (  )  [virtual]

SyncItem * WindowsSyncSource::getFirstNewItem (  )  [virtual]

It's called in case of two-way sync.

Creates the lists of newItems, modItems and delItems, comparing differences between allItems list and the list of all items from the last sync (stored in cache files).

Returns:
the first SyncItem of newItems list.
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), SyncSourceReport::checkState(), convertToSyncItem(), defaultFolderPath, ClientApplication::getItemFromID(), WindowsSyncSourceConfig::getName(), SyncSource::getName(), getSafeItemName(), SyncSource::getSyncMode(), WindowsSyncSourceConfig::getType(), WindowsSyncSourceConfig::getURI(), manageClientException(), manageModificationsFromLastSync(), manageSourceErrorF(), outlook, resetDataFile(), and winConfig.

SyncItem * WindowsSyncSource::getFirstUpdatedItem (  )  [virtual]

It's called in case of two-way sync.

Returns:
the first SyncItem of modItems list
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), SyncSourceReport::checkState(), convertToSyncItem(), defaultFolderPath, ClientApplication::getItemFromID(), SyncSource::getName(), getSafeItemName(), WindowsSyncSourceConfig::getType(), manageClientException(), manageSourceErrorF(), outlook, and winConfig.

SyncItem * WindowsSyncSource::getNextDeletedItem (  )  [virtual]

It's called in case of two-way sync.

Returns:
the next SyncItem of delItems list.
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), and SyncSourceReport::checkState().

SyncItem * WindowsSyncSource::getNextItem (  )  [virtual]

It's called in case of full-sync or refresh-from-client sync.

Returns:
the next SyncItem of allItems list.
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References allItems, checkAbortedSync(), SyncSourceReport::checkState(), convertToSyncItem(), defaultFolderPath, ClientApplication::getItemFromID(), SyncSource::getName(), getSafeItemName(), WindowsSyncSourceConfig::getType(), iAll, manageClientException(), manageSourceErrorF(), outlook, and winConfig.

SyncItem * WindowsSyncSource::getNextNewItem (  )  [virtual]

It's called in case of two-way sync.

Returns:
the next SyncItem of newItems list
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), SyncSourceReport::checkState(), convertToSyncItem(), defaultFolderPath, ClientApplication::getItemFromID(), SyncSource::getName(), getSafeItemName(), WindowsSyncSourceConfig::getType(), manageClientException(), manageSourceErrorF(), outlook, and winConfig.

SyncItem * WindowsSyncSource::getNextUpdatedItem (  )  [virtual]

It's called in case of two-way sync.

Returns:
the next SyncItem of modItems list.
Note:
returns a new allocated SyncItem, deleted internally by API.

Implements SyncSource.

References checkAbortedSync(), SyncSourceReport::checkState(), convertToSyncItem(), defaultFolderPath, ClientApplication::getItemFromID(), SyncSource::getName(), getSafeItemName(), WindowsSyncSourceConfig::getType(), manageClientException(), manageSourceErrorF(), outlook, and winConfig.

ClientFolder * WindowsSyncSource::getStartFolder (  )  [protected]

Get the starting Outlook folder for this source.

Starting folder is retrieved from path (stored in config), if path not set the default folder for this source will be returned.

Returns:
the starting folder with items to sync

References getConfig(), ClientApplication::getFolderFromPath(), SyncSource::getName(), ClientFolder::getPath(), manageClientException(), and outlook.

Referenced by beginSync().

int WindowsSyncSource::manageModificationsFromLastSync (  )  [protected]

Creates the NEW/MOD/DEL items lists from last successfull sync.

  • read old items list from filesystem -> fill oldItems list
  • fill NEW/MOD/DEL lists comparing allItems and oldItems
  • add forced MOD items from previous sync (for appointment exceptions)

Returns:
0 if no errors. In case of error, all items will be set as modified items.

References addForcedItemsToModList(), allItems, checkAbortedSync(), filteredItems, ClientApplication::getItemFromID(), SyncSource::getName(), ClientItem::getParentPath(), ClientItem::getProperty(), iAll, manageSourceError(), outlook, parseOldItems(), readDataPath(), readFromFile(), and variantTimeToTimeStamp().

Referenced by getFirstNewItem().

void WindowsSyncSource::manageSourceError ( const int  errorCode,
const char *  errorMsg 
) [protected]

Common actions to do when an error occurs inside SyncSource.

Updates the internal report. Doesn't set the Source state, as generally we want to continue the sync. (source state is set only after too many errors on this source)

References SyncSource::getName(), numErrors, SyncSourceReport::setLastErrorCode(), SyncSourceReport::setLastErrorMsg(), SyncSourceReport::setState(), and SOURCE_ERROR.

Referenced by endSync(), folderPathAllowed(), manageModificationsFromLastSync(), and manageSourceErrorF().

void WindowsSyncSource::parseOldItems ( std::wstring &  data,
itemKeyList listItems,
itemKeyList listFolders 
) [protected]

Parse the list of all current items into a string, from an XML.

<contact> <LastSyncTime>1168862109</LastSyncTime> <ID>00013505600G4BGG494D009680</ID> <Folder>\Personal Folder</Folder> <ID>00033505600G4BGG494D006620</ID> <Folder>\Personal Folder</Folder> ... </contact>

and push all items' keys into 'listItems' list. Also push all items' folder paths into 'listFolder' list. Each key of listItems corresponds to the folder element of the same index. It supports old format of db files (before v.6.0.9), like this:

<contact> <LastSyncTime>1168862109</LastSyncTime> 00013505600G4BGG494D009680 00033505600G4BGG494D006620 ... </contact>

Parameters:
data the input string to parse
listItems [IN-OUT] list of item keys, filled here
listFolders [IN-OUT] list of folder paths, filled here

Referenced by manageModificationsFromLastSync().

void WindowsSyncSource::pushAllItemsToList ( ClientFolder folder,
itemKeyList listItems,
itemKeyList listItemsPaths 
) [protected]

Get all items inside 'folder' and push them (only keys) into 'listItems' list.

Sends messages to update statusbar on each item read. Also normalize appointment exceptions: mod exceptions need to be converted to new appointments (see doc on Recurrence Exceptions) and added to the 'listItems'.

Parameters:
folder the ClientFolder pointer to search items
listItems the list<wstring> where pushing items ID
listItemsPaths the list<wstring> where pushing items paths (optimization, used at the end of sync)

References allItems, allItemsPaths, checkAbortedSync(), filterClientItem(), filteredItems, ClientFolder::getFirstItem(), ClientItem::getID(), ClientFolder::getItemsCount(), SyncSource::getName(), ClientFolder::getNextItem(), ClientItem::getParentPath(), ClientFolder::getPath(), and getSafeItemName().

Referenced by beginSync(), and pushAllSubfolderItemsToList().

void WindowsSyncSource::pushAllSubfolderItemsToList ( ClientFolder folder,
itemKeyList listItems,
itemKeyList listItemsPaths 
) [protected]

Get all items inside 'folder' and also all items from every subfolder (call to this method recursively).

All items are pushed into 'listItems' list.

Parameters:
folder the ClientFolder pointer to search items
listItems the list<wstring> where pushing items
listItemsPaths the list<wstring> where pushing items paths (optimization, used at the end of sync)

References ClientFolder::getFirstSubfolder(), ClientFolder::getNextSubfolder(), ClientFolder::getSubfoldersCount(), and pushAllItemsToList().

Referenced by beginSync().

int WindowsSyncSource::removeAllItems (  )  [virtual]

Deletes all items in Outlook for this source.

It's called in case of refresh-from-server sync.

Returns:
0 if no errors

Implements SyncSource.

References SyncSourceReport::addItem(), allItems, checkAbortedSync(), SyncSourceReport::checkState(), CLIENT, ClientItem::deleteItem(), filteredItems, ClientApplication::getItemFromID(), SyncSource::getName(), ClientItem::getParentPath(), getSafeItemName(), manageClientException(), manageSourceErrorF(), outlook, and resetDataFile().

int WindowsSyncSource::resetDataFile ( const std::wstring &  itemType  )  [protected]

Reset the specified data file: destroy any content and add a "<itemType>" tag at the beginning of file.

The file path is "<APP_DATA>\Funambol\Outlook Client\<itemType>.db"

Parameters:
itemType the itemType
Returns:
0 if no errors

References readDataPath(), and writeToFile().

Referenced by getFirstItem(), getFirstNewItem(), and removeAllItems().

void WindowsSyncSource::setItemStatus ( const WCHAR *  ,
int   
) [virtual]

called by the sync engine with the status returned by the server for a certain item that the client sent to the server

Parameters:
key the local key of the item
status the SyncML status returned by the server
Deprecated:
Since:
SyncML API v7

Reimplemented from SyncSource.

void WindowsSyncSource::updateFilters (  )  [protected]

Refresh all active filters.

DateFilter on events is related to the current time.

References getDateFilter(), SyncSource::getName(), DateFilter::isEnabled(), and DateFilter::updateNow().

Referenced by beginSync().

int WindowsSyncSource::updateItem ( SyncItem &  item  )  [virtual]

Update the item from the server to the client.

Checks if destination folder is the same of the item's folder.

Note:
If folder path is changed we need to move the item to new position (return code 201). Cannot move the item without changing the ID, so we have to create a new item and delete the old one. We MUST NOT update the allItems list (nor the allItemsPath), so during next sync we will have 1 deleted item and 1 new item to send to server.
Returns:
code 200 if operation succesful, code 201 if item updated to a new position, code 500 if errors.

Implements SyncSource.

References addItem(), checkAbortedSync(), checkBirthdayAnniversary(), SyncSourceReport::checkState(), extractFolder(), fillClientItem(), filterClientItem(), folderPathAllowed(), ClientApplication::getItemFromID(), SyncSource::getName(), getSafeItemName(), isAcceptedDataType(), isSIF(), manageClientException(), manageSourceErrorF(), and outlook.


Member Data Documentation

Configuration object for the source.

It's a reference to WindowsSyncSourceConfig object owned by OutlookConfig. It's automatically initialized in the constructor.

Referenced by beginSync(), endSync(), extractFolder(), folderPathAllowed(), getConfig(), getFirstItem(), getFirstNewItem(), getFirstUpdatedItem(), getNextItem(), getNextNewItem(), and getNextUpdatedItem().


The documentation for this class was generated from the following files:

Generated on Tue Apr 6 13:00:43 2010 for Funambol Outlook Plug-in Library by  doxygen 1.5.7.1