ClientApplication Class Reference
[Outlook Wrapper]

The main class of Outlook wrapper, used to wrap Outlook Application instance, MAPI namespace and Redemption utility methods. More...

#include <ClientApplication.h>

Collaboration diagram for ClientApplication:
[legend]

List of all members.

Public Member Functions

 ~ClientApplication ()
 Destructor.
const std::wstring & getVersion ()
const std::wstring & getName ()
ClientFoldergetDefaultFolder (const std::wstring &itemType)
 Returns the default ClientFolder for the specific item type.
ClientFoldergetFolderFromID (const std::wstring &folderID)
 Returns the ClientFolder from its entryID.
ClientFolderpickFolder ()
 Returns the ClientFolder manually selected by the user.
ClientFolderpickFolder (const std::wstring &itemType)
 Returns the ClientFolder manually selected by the user.
ClientFoldergetFolderFromPath (const std::wstring &itemType, const std::wstring &path)
 Returns the ClientFolder from the full folder path (eg "\\Personal Folders\Contacts").
ClientFoldergetDefaultRootFolder ()
 Returns the default root folder (index = 0).
ClientFoldergetRootFolder (const int index)
 Returns the root folder from its index.
ClientFoldergetRootFolderFromName (const std::wstring &folderName)
 Returns the root folder from its name.
ClientItemgetItemFromID (const std::wstring &itemID, const std::wstring &itemType)
 Returns the ClientItem from its entryID.
HRESULT cleanUp ()
 To release shared session of Outlook.
std::wstring getSMTPfromEX (const std::wstring &EXAddress)
 Utility to convert an Exchange mail address into a SMTP address.
std::wstring getBodyFromID (const std::wstring &itemID)
 Utility to get body of a specified item (used for notes body which is protected).
std::wstring getCurrentProfileName ()
 Utility to retrieve the userName of current Outlook profile used.
const bool isLoggedOn ()
 Returns true if Outlook MAPI object is logged on.
StringBuffer getHexTimezone (const char *buf, int len)
 It gets a StringBuffer containing the timezone converted in hex.
void setTimezone (ClientAppointment *cApp)
 It set the timezone in the recurring appointment.
TIME_ZONE_INFORMATION * getTimezone (ClientAppointment *cApp)
 It returns the timezone information of the current recurrent appointment.
void setOutgoingTimezone (bool v)
bool getOutgoingTimezone ()
bool setStartAndEnd (ClientAppointment *cApp, DATE start, DATE end)
 It sets at low level the start and end date of the original appointment.
bool isTheSameTimezoneRule (REG_TZI_FORMAT &tz, std::wstring *standardName)
 It checks if the timezone from the appointment sent by the server is the same as is set on the OS.
bool isTheSameTimezoneRule (const TIME_ZONE_INFORMATION &tzInfo)
 It checks if the timezone (in TIME_ZONE_INFORMATION structure) is the same as the OS.

Static Public Member Functions

static ClientApplicationgetInstance ()
 Method to create the sole instance of ClientApplication.
static bool isInstantiated ()
 Returns true if static instance is not NULL.

Protected Member Functions

 ClientApplication ()
 Constructor.

Private Member Functions

void createSafeInstances ()
 Creates instances for Redemption COM pointers:
  • MAPIUtils (used for notes body)
  • RDOSession (used for EX->SMTP addresses).

TIME_ZONE_INFORMATION * convertRegTziOutlookFormat2TimezoneInformation (REG_TZI_FORMAT_FOR_OUTLOOK &rtf)
 For outgoing timezone.
REG_TZI_FORMAT convertTimezoneInformation2RegTziFormat (const TIME_ZONE_INFORMATION &rtf)
 it converts the TIME_ZONE_INFORMATION in a similar one REG_TZI_FORMAT to be used inside the application
REG_TZI_FORMAT_FOR_OUTLOOK convertTimezoneInformation2RegTziOutlookFormat (const TIME_ZONE_INFORMATION &rtf)
 it converts the TIME_ZONE_INFORMATION in a similar one but customized to be used inside the application with Redemption object.
bool getDisplayTimezone (REG_TZI_FORMAT &tz, StringBuffer *display)
 It retrieves the name that is in the Timezone registry.

Private Attributes

std::wstring version
 Version of Client used.
std::wstring programName
 Name of Client used.
_ApplicationPtr pApp
_NameSpacePtr pMAPI
MAPIFolderPtr pFolder
Redemption::IMAPIUtilsPtr pRedUtils
Redemption::IRDOSessionPtr rdoSession
ClientFolderfolder
ClientMailmail
ClientContactcontact
ClientAppointmentappointment
ClientTasktask
ClientNotenote
HRESULT hr
 Result of COM pointers operations.
bool useOutgoingTimezone

Static Private Attributes

static ClientApplicationpinstance = NULL
 pointer to ClientApplication instance


Detailed Description

The main class of Outlook wrapper, used to wrap Outlook Application instance, MAPI namespace and Redemption utility methods.

Start from the unique instance of this class (it's a singleton) to get the desired ClientFolder, and the desired ClientItem. Class methods automatically catch and manage COM pointers exceptions. Class methods throw ClientException pointer in case of error.


Constructor & Destructor Documentation

ClientApplication::ClientApplication (  )  [protected]

Constructor.

Creates a new instance of Outlook application then logs in. Initializes version & programName.

References createSafeInstances(), hr, OL_APPLICATION, OL_NEW_SESSION, OL_PASSWORD, OL_PROFILE, OL_SHOW_DIALOG, programName, throwClientFatalException(), and version.

ClientApplication::~ClientApplication (  ) 

Destructor.

Log off and clean up shared objects, delete internal objects.

References cleanUp(), hr, pinstance, throwClientException(), and version.


Member Function Documentation

HRESULT ClientApplication::cleanUp (  ) 

To release shared session of Outlook.

This function avoids Outlook being instable after usage of Redemption. Release:

  • RDOSession (used for EX->SMTP addresses)
  • MAPIUtils (used for notes body)

References throwClientException().

Referenced by ~ClientApplication().

TIME_ZONE_INFORMATION * ClientApplication::convertRegTziOutlookFormat2TimezoneInformation ( REG_TZI_FORMAT_FOR_OUTLOOK &  rtf  )  [private]

For outgoing timezone.

It transforms the retrieved timezone of the event (see the REG_TZI_FORMAT_OUTLOOK struct) into a standard timezone information

Parameters:
rtf the reference to a REG_TZI_FORMAT_FOR_OUTLOOK struct
Returns:
a new REG_TZI_FORMAT_FOR_OUTLOOK. It must be freed bu the caller

Referenced by getTimezone().

REG_TZI_FORMAT ClientApplication::convertTimezoneInformation2RegTziFormat ( const TIME_ZONE_INFORMATION &  rtf  )  [private]

it converts the TIME_ZONE_INFORMATION in a similar one REG_TZI_FORMAT to be used inside the application

Parameters:
the TIME_ZONE_INFORMATION from which calculate the REG_TZI_FORMAT
Returns:
the REG_TZI_FORMAT (MS structure that store a subset of TIME_ZONE_INFORMATION. It is used inside the windows registry editor

References _REG_TZI_FORMAT::Bias, _REG_TZI_FORMAT::DaylightBias, _REG_TZI_FORMAT::DaylightDate, _REG_TZI_FORMAT::StandardBias, and _REG_TZI_FORMAT::StandardDate.

Referenced by isTheSameTimezoneRule(), and setTimezone().

REG_TZI_FORMAT_FOR_OUTLOOK ClientApplication::convertTimezoneInformation2RegTziOutlookFormat ( const TIME_ZONE_INFORMATION &  rtf  )  [private]

it converts the TIME_ZONE_INFORMATION in a similar one but customized to be used inside the application with Redemption object.

The structure has been created studying the property bit a bit...

Parameters:
the TIME_ZONE_INFORMATION from which calculate the one for outlook
Returns:
the REG_TZI_FORMAT_FOR_OUTLOOK

Referenced by setTimezone().

wstring ClientApplication::getBodyFromID ( const std::wstring &  itemID  ) 

Utility to get body of a specified item (used for notes body which is protected).

Note:
: this method uses the redemption library (MAPIUtils object). It is placed here because the MAPIUtils object needs to be linked to Outlook MAPI.
Parameters:
itemID : the ID of item to search
Returns:
: the value of 'body' property

References createSafeInstances(), and throwClientException().

wstring ClientApplication::getCurrentProfileName (  ) 

Utility to retrieve the userName of current Outlook profile used.

In case of errors, or not yet logged on Outlook, throws a ClientException.

Note:
this method uses the redemption library (RDOSession object).

References createSafeInstances(), and throwClientException().

ClientFolder * ClientApplication::getDefaultFolder ( const std::wstring &  itemType  ) 

Returns the default ClientFolder for the specific item type.

Note:
the pointer returned is a reference to the internal ClientFolder. (the internal object is fred in the destructor)

References ClientFolder::setCOMPtr(), and throwClientFatalException().

Referenced by WindowsSyncSource::beginSync(), WindowsSyncSource::deleteAppointment(), getDefaultFolderPath(), and getFolderFromPath().

ClientFolder * ClientApplication::getDefaultRootFolder (  ) 

Returns the default root folder (index = 0).

Root folders are the Outlook data files folders (this should be "Personal Folder").

References getRootFolder().

Referenced by WindowsSyncSource::folderPathAllowed(), and getFolderFromPath().

bool ClientApplication::getDisplayTimezone ( REG_TZI_FORMAT tz,
StringBuffer *  display 
) [private]

It retrieves the name that is in the Timezone registry.

It is language dependent.

Parameters:
tz (IN) the REG_TZI_FORMAT that it is used to be compared with the ones got from the registry. If the blob is the same, then the name property is used
display (OUT) is a string buffer provided bu the caller that has the name that is visualized in the appointment (i.e. (GMT - 7.00 h) Arizona.)
Returns:
true if a match between the REG_TZI_FORMAT is retrieved, false otherwise

References isTheSameTimezoneRule().

Referenced by setTimezone().

ClientFolder * ClientApplication::getFolderFromID ( const std::wstring &  folderID  ) 

Returns the ClientFolder from its entryID.

Note: the pointer returned is a reference to the internal ClientFolder. (the internal object is fred in the destructor)

References ClientFolder::setCOMPtr(), and throwClientFatalException().

ClientFolder * ClientApplication::getFolderFromPath ( const std::wstring &  itemType,
const std::wstring &  path 
)

Returns the ClientFolder from the full folder path (eg "\\Personal Folders\Contacts").

If empty (or "\\" or "/") path passed, the default folder will be returned. If correspondent folder does not exist, it will be created.

Note:
the pointer returned is a reference to a internal object (internal objects are fred in the destructor)

References ClientFolder::addSubFolder(), getDefaultFolder(), getDefaultRootFolder(), ClientFolder::getPath(), getRootFolderFromName(), ClientFolder::getSubfolderFromName(), ClientFolder::getType(), and throwClientException().

Referenced by WindowsSyncSource::addItem(), and WindowsSyncSource::getStartFolder().

StringBuffer ClientApplication::getHexTimezone ( const char *  buf,
int  len 
)

It gets a StringBuffer containing the timezone converted in hex.

It is used to be set into the recurring appointment

Parameters:
buf the char array whose character has to be converted
len the length of the buf array
Returns:
StringBuffer the hex converted

Referenced by setTimezone().

ClientItem * ClientApplication::getItemFromID ( const std::wstring &  itemID,
const std::wstring &  itemType 
)

ClientFolder * ClientApplication::getRootFolder ( const int  index  ) 

Returns the root folder from its index.

Root folders are the Outlook data files folders (e.g. "Personal Folder"). If folder not found returns NULL. Note: the pointer returned is a reference to the internal ClientFolder. (the internal object is freed in the destructor) 'index + 1' is used, as first outlook folder has index = 1.

References ClientFolder::setCOMPtr().

Referenced by getDefaultRootFolder(), and getRootFolderFromName().

ClientFolder * ClientApplication::getRootFolderFromName ( const std::wstring &  folderName  ) 

Returns the root folder from its name.

Root folders are the Outlook data files folders (e.g. "Personal Folder"). If folder not found returns NULL. Note: the pointer returned is a reference to the internal ClientFolder. (the internal object is fred in the destructor)

References ClientFolder::getName(), and getRootFolder().

Referenced by WindowsSyncSource::folderPathAllowed(), and getFolderFromPath().

wstring ClientApplication::getSMTPfromEX ( const std::wstring &  EXAddress  ) 

Utility to convert an Exchange mail address into a SMTP address.

Note:
this method uses the redemption library (RDOSession object). It is placed here because the RDOSession object needs to be linked to Outlook MAPI.
Parameters:
EXAddress : the EX address to be converted
Returns:
: the SMTP address if found (else empty string)

References createSafeInstances(), and throwClientException().

TIME_ZONE_INFORMATION * ClientApplication::getTimezone ( ClientAppointment cApp  ) 

It returns the timezone information of the current recurrent appointment.

It returns the TIME_ZONE_INFORMATION of the current recurring appointment.

Parameters:
cApp a valid ClientAppointment with the COM ptr set
Returns:
the TIME_ZONE_INFORMATION struct of the current recurrent appointment
It is used only with the recurring ones. It returns a new instance of the timezone
Todo:
to be implemented to get the real timezone of the appointment

References convertRegTziOutlookFormat2TimezoneInformation(), createSafeInstances(), ClientAppointment::getCOMPtr(), and hr.

Referenced by convertToSyncItem().

bool ClientApplication::isTheSameTimezoneRule ( const TIME_ZONE_INFORMATION &  tzInfo  ) 

It checks if the timezone (in TIME_ZONE_INFORMATION structure) is the same as the OS.

Parameters:
tzi the TIME_ZONE_INFORMATION structure to be compared with the OS one

References convertTimezoneInformation2RegTziFormat(), and isTheSameTimezoneRule().

bool ClientApplication::isTheSameTimezoneRule ( REG_TZI_FORMAT tz,
std::wstring *  standardName 
)

It checks if the timezone from the appointment sent by the server is the same as is set on the OS.

If it is the same, there is no needed to set all the timezone info too.

Parameters:
tz the REG_TZI_FORMAT to be compared with the current timezone
standardName if not null, il will contain the standard name found in the OS registry

References convertTimezoneInformation2RegTziFormat().

Referenced by getDisplayTimezone(), and isTheSameTimezoneRule().

ClientFolder * ClientApplication::pickFolder ( const std::wstring &  itemType  ) 

Returns the ClientFolder manually selected by the user.

If 'itemType' is not empty string, verifies if folder selected is correct for the item type passed. Note: the pointer returned is a reference to the internal ClientFolder. (the internal object is fred in the destructor)

References safeMessageBox(), and ClientFolder::setCOMPtr().

ClientFolder * ClientApplication::pickFolder (  ) 

Returns the ClientFolder manually selected by the user.

No item type verification is performed. Note: the pointer returned is a reference to the internal ClientFolder. (the internal object is fred in the destructor)

Referenced by pickOutlookFolder().

bool ClientApplication::setStartAndEnd ( ClientAppointment cApp,
DATE  start,
DATE  end 
)

It sets at low level the start and end date of the original appointment.

This is needed because when setting an appointment params and then the recurrence, the start/end are changed according with the local patternstart and patternend date/time. Then changing the timezone, the Start and End are no more consistent with them. So changing the appointment timezone needs to change the start/end date/time with the original one sent by the server

Parameters:
cApp the clientAppointment instance
start the start date (it is a DATE value. It is the local time)
end the end date (it is a DATE value. It is the local time)

References createSafeInstances(), and ClientAppointment::getCOMPtr().

void ClientApplication::setTimezone ( ClientAppointment cApp  ) 


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