ClientRecurrence Class Reference
[Recurrence pattern]

Wraps the Outlook recurrence object (for tasks and events). More...

#include <ClientRecurrence.h>

List of all members.

Public Member Functions

 ClientRecurrence ()
 Constructor.
 ~ClientRecurrence ()
 Destructor.
void setCOMPtr (RecurrencePatternPtr &ptr)
 Set a COM pointer to this object.
int read ()
 Retrieve all properties from Outlook -> set isUpdated = true.
int refresh ()
 Refresh the values of the internal reference with the data sent from the server.
int save ()
 Save all the properties to Outlook.
bool isRecurring ()
 Return true if the rec pattern is active.
void setRecurrence ()
 Set 'recurring' to true.
void clearRecurrence ()
 Reset all members, set 'recurring' to false.
const int getRecurrenceType ()
const int getInterval ()
const int getMonthOfYear ()
const int getDayOfMonth ()
const int getDayOfWeekMask ()
const int getInstance ()
const std::wstring & getPatternStartDate ()
const BOOL getNoEndDate ()
const std::wstring & getPatternEndDate ()
const int getOccurrences ()
const std::wstring & getStartTime ()
const std::wstring & getEndTime ()
bool getHasTimezone ()
void setHasTimezone (bool v)
const std::wstring getProperty (const std::wstring &propertyName)
 Return the property value (wstring) from its name.
void setRecurrenceType (const int val)
void setInterval (const int val)
void setMonthOfYear (const int val)
void setDayOfMonth (const int val)
void setDayOfWeekMask (const int val)
void setInstance (const int val)
void setPatternStartDate (const std::wstring &val)
void setNoEndDate (const BOOL val)
void setPatternEndDate (const std::wstring &val)
void setOccurrences (const int val)
void setStartTime (const std::wstring &val)
void setEndTime (const std::wstring &val)
void setStart (const std::wstring &val)
 for the change-day option
void setIsAllDay (const BOOL val)
void setEnd (const std::wstring &val)
int setProperty (const std::wstring &propertyName, const std::wstring &propertyValue)
 Set property value from its name: set internal object values.
ClientAppExceptiongetException (const int index)
 Returns the desired ClientAppException stored in 'appExceptions' internal list.
const int getExceptionsCount ()
 Returns the number of exceptions stored in this recurrence.
int addException (ClientAppException *cException)
 Adds a ClientAppException into 'appExceptions' internal list.
void resetExceptions ()
 Reset the exception list 'appExceptions'.
int saveAllExceptions ()
 Save all exceptions from internal exception list to Outlook (server to client).
int removeDuplicatedExceptions ()
 This utility method is used to remove all duplicated exceptions that are extracted from Outlook.
_AppointmentItemPtr getOccurrence (const DATE originalDate)
 Returns the specific occurrence of date "originalDate" from the recurrence pattern.
void setRecurringTimezone (const TIME_ZONE_INFORMATION *tz)
const TIME_ZONE_INFORMATION & getRecurringTimezone () const

Private Member Functions

void checkIfRecIsCorrect ()
bool changeDay (const std::wstring dest)
 Change-day of rec props, according on UTC <-> Local time.
ClientAppExceptiongetExceptionOnClient (const int index)
 used during 'read()' method (get data from client)
const int getExceptionsCountOnClient ()
 Returns the number of appointment exceptions.
int saveException (ClientAppException *cException)
 Save the exception 'cException' into Outlook.

Private Attributes

int recurrenceType
int interval
int monthOfYear
int dayOfMonth
int dayOfWeekMask
int instance
std::wstring patternStartDate
BOOL noEndDate
std::wstring patternEndDate
int occurrences
std::wstring startTime
std::wstring endTime
bool hasTimezone
std::wstring start
 for the change-day option
BOOL isAllDay
 for the change-day option
std::wstring end
RecurrencePatternPtr pRec
 Pointer to microsoft outlook objects.
clientExceptionList appExceptions
 Internal list of appointment exceptions.
bool recurring
 Is this rec pattern active? this is linked to the property 'recurring' of Outlook event (it's set at constructor and each time setting property IsRecurring).
bool isUpdated
 Internal use: true if values are updated with Outlook.
int numRecursions
 Internal use: to avoid deadlocking into safeSaveException() recursive call.
TIME_ZONE_INFORMATION timeZoneInfo
 The timezone information of the recurring appointment It is used ONLY when the app is recurring.


Detailed Description

Wraps the Outlook recurrence object (for tasks and events).

This object is the same contained by ClientAppointment and ClientTask objects. Contains all recurrence properties, MUST read and save them all together (read() and save()), so they're internally stored.

A recurrence object has a list of appointment exceptions inside it.


Member Function Documentation

int ClientRecurrence::addException ( ClientAppException cException  ) 

Adds a ClientAppException into 'appExceptions' internal list.

The object passed is copied, so can be safely deleted by the caller.

Parameters:
cException : the ClientAppException* to add
Returns:
: the number of exceptions stored after the add operation

References appExceptions.

Referenced by deleteOccurrencesInInterval(), and setRecurrenceExceptions().

void ClientRecurrence::checkIfRecIsCorrect (  )  [private]

Todo:
Verify if some props are not correct for the rec type.

Referenced by save().

void ClientRecurrence::clearRecurrence (  ) 

Reset all members, set 'recurring' to false.

This is called by 'ClientAppointment.setProperty("IsRecurring", "0")'.

References isUpdated, and recurring.

Referenced by ClientTask::clearRecPattern(), ClientAppointment::clearRecPattern(), and ClientRecurrence().

ClientAppException * ClientRecurrence::getException ( const int  index  ) 

Returns the desired ClientAppException stored in 'appExceptions' internal list.

Parameters:
index : the index of exception desired
Returns:
: the ClientAppException pointer (to internal item, MUST NOT free it)

References appExceptions.

Referenced by convertToSyncItem().

ClientAppException * ClientRecurrence::getExceptionOnClient ( const int  index  )  [private]

used during 'read()' method (get data from client)

Returns the ClientAppException object of the desired index [0, numExceptions-1].

Value is always retrieved from Outlook (not saved in this object). This method is used from client to server, initially to populate the exceptions list. Note: the pointer returned is a new allocated object.

Parameters:
index : the index of Exception required
Returns:
: the correspondent pointer (new allocated) of ClientAppException (NULL if not found).

References isRecurring(), pRec, and ClientAppException::setCOMPtr().

Referenced by read().

const int ClientRecurrence::getExceptionsCountOnClient (  )  [private]

Returns the number of appointment exceptions.

Value is always retrieved from Outlook (not saved in this object). This method is used from client to server, initially to populate the exceptions list.

References isRecurring(), and pRec.

Referenced by read().

_AppointmentItemPtr ClientRecurrence::getOccurrence ( const DATE  originalDate  ) 

Returns the specific occurrence of date "originalDate" from the recurrence pattern.

Returned object is an appointement COM pointer '_AppointmentItemPtr' (each occurrence is an appointment itself). If the occurrence is not found, returns NULL.

Parameters:
originalDate : the original date of the occurrence to be found (double format)
Returns:
: the new COM pointer "_AppointmentItemPtr" which is the desired occurrence (NULL if not found)

References isRecurring(), and pRec.

Referenced by deleteOccurrencesInInterval(), and saveException().

const wstring ClientRecurrence::getProperty ( const std::wstring &  propertyName  ) 

Return the property value (wstring) from its name.

Properties are retrieved from internal members (switch to correct property). Rec pattern values must be first retrieved all together, this is done internally when the first property is retrieved.

Parameters:
propertyName : the name of the property
Returns:
: the value retrieved as wstring

References throwClientException().

Referenced by convertToSyncItem().

int ClientRecurrence::read (  ) 

Retrieve all properties from Outlook -> set isUpdated = true.

If UTC is used, all props are converted to correct values.

Returns:
0 if no errors
If UTC is used, all props are converted to correct values. For the Task remember the StartTime and EndTime are not valid properties so the timezone is not considered and the PatternStartDate and PatterEndDate are in the format yyyy-mm-dd according with the startdate and due date

Returns:
: 0 if no errors

References appExceptions, changeDay(), doubleToSystemTime(), getExceptionOnClient(), getExceptionsCountOnClient(), ClientApplication::getInstance(), ClientApplication::getOutgoingTimezone(), isAllDay, isRecurring(), isUpdated, LIMIT_MAX_DATE, numRecursions, pRec, start, systemTimeToDouble(), throwClientException(), USE_CHANGE_DAY, USE_UTC, and vBoolToBOOL().

Referenced by getExceptionsCount().

int ClientRecurrence::refresh (  ) 

Refresh the values of the internal reference with the data sent from the server.

Retrieve all properties from Outlook -> set isUpdated = true.

Returns:
0 if no errors
If UTC is used, all props are converted to correct values. For the Task remember the StartTime and EndTime are not valid properties so the timezone is not considered and the PatternStartDate and PatterEndDate are in the format yyyy-mm-dd according with the startdate and due date

Returns:
: 0 if no errors

References changeDay(), doubleToSystemTime(), ClientApplication::getInstance(), ClientApplication::getOutgoingTimezone(), isAllDay, isRecurring(), isUpdated, LIMIT_MAX_DATE, pRec, start, systemTimeToDouble(), throwClientException(), USE_CHANGE_DAY, USE_UTC, and vBoolToBOOL().

Referenced by WindowsSyncSource::filterClientItem().

int ClientRecurrence::removeDuplicatedExceptions (  ) 

This utility method is used to remove all duplicated exceptions that are extracted from Outlook.

We don't want more than one exception with the same "OriginalDate" (it's nonsense...). Outlook may send more than one, for example:

<OriginalDate>2007-01-15</OriginalDate> <ExAppointment> <ExSubject>Subject modified</ExSubject> <ExBody> <ExLocation> <ExStart>2007-01-16</ExStart> <ExEnd>2007-01-16</ExEnd> <ExAllDayEvent>1</ExAllDayEvent> <ExBusyStatus>1</ExBusyStatus> </ExAppointment>

<OriginalDate>2007-01-15</OriginalDate>

In this case, the second exception is nonsense, and will be removed from list.

Returns:
: the number of exceptions removed from list.

References appExceptions.

int ClientRecurrence::save (  ) 

Save all the properties to Outlook.

Properties are verified to be consistent all together, as Outlook doesn't accept wrong values. If UTC is used, all props are converted to correct values.

Returns:
0 if no errors

References BOOLToVBool(), changeDay(), checkIfRecIsCorrect(), doubleToSystemTime(), isAllDay, isRecurring(), isUpdated, LIMIT_MAX_DATE, pRec, recurrenceProps, start, systemTimeToDouble(), throwClientException(), USE_CHANGE_DAY, and USE_UTC.

Referenced by WindowsSyncSource::filterClientItem().

int ClientRecurrence::saveAllExceptions (  ) 

Save all exceptions from internal exception list to Outlook (server to client).

All exceptions are 'deleted occurrence' exceptions, 'modified exceptions' are not expected at this level (should be normalized in upper layer).

Returns:
: 0 if all exceptions saved correctly

References appExceptions, and saveException().

int ClientRecurrence::saveException ( ClientAppException cException  )  [private]

Save the exception 'cException' into Outlook.

First check if this exception depends on another exception of the list. In this case, we first execute that exception (recursive call). Than saves this exception to Outlook.

Returns:
0 if no errors Save the exception 'cException' into Outlook. No check on exceptions dependences is done here. Before saving the exception, we MUST check that the destination date is free (the "StartDate") -> call 'freeDestinationDays()'. Note: before calling this method, the Appointment Item MUST be already saved to Outlook.

0 if no errors

References ClientAppException::deleteOccurrence(), ClientAppException::formatOriginalDate(), ClientAppException::getDeleted(), getOccurrence(), ClientAppException::getOriginalDate(), ClientAppException::setCOMPtr(), start, and systemTimeToDouble().

Referenced by saveAllExceptions().

void ClientRecurrence::setCOMPtr ( RecurrencePatternPtr &  ptr  ) 

Set a COM pointer to this object.

This method is used to link the object to the correspondent outlook COM pointer. The method MUST be called before using this object, as the constructor doesn't link the class COM pointer.

Note:
RecPatternPtr could be passed NULL (if new item), so check it before using it (read() and save()).

References appExceptions, isUpdated, numRecursions, and pRec.

int ClientRecurrence::setProperty ( const std::wstring &  propertyName,
const std::wstring &  propertyValue 
)

Set property value from its name: set internal object values.

All rec pattern must be saved together at the end calling 'save()' method. This is because:

  • rec props MUST be verified consistent each others
  • if UTC is used, rec props are first converted inside recPattern.

Parameters:
propertyName : the name of the property
propertyValue : the value to store
Returns:
: 0 if no errors, 1 if errors

References throwClientException().

Referenced by fillClientItem().

void ClientRecurrence::setRecurrence (  ) 

Set 'recurring' to true.

This is called by 'ClientAppointment.setProperty("IsRecurring", "1")'.

References recurring.


Member Data Documentation

Internal use: true if values are updated with Outlook.

Used because all values need to be retrieved together, so this flag notifies when it's necessary to update properties.

Referenced by clearRecurrence(), getExceptionsCount(), read(), refresh(), save(), and setCOMPtr().


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

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