epoc32/include/app/calchangecallback.h
branchSymbian3
changeset 4 837f303aceeb
parent 3 e1b950c65cb4
     1.1 --- a/epoc32/include/app/calchangecallback.h	Wed Mar 31 12:27:01 2010 +0100
     1.2 +++ b/epoc32/include/app/calchangecallback.h	Wed Mar 31 12:33:34 2010 +0100
     1.3 @@ -1,9 +1,9 @@
     1.4  // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5  // All rights reserved.
     1.6  // This component and the accompanying materials are made available
     1.7 -// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     1.8 +// under the terms of "Eclipse Public License v1.0"
     1.9  // which accompanies this distribution, and is available
    1.10 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.11 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.12  //
    1.13  // Initial Contributors:
    1.14  // Nokia Corporation - initial contribution.
    1.15 @@ -84,61 +84,104 @@
    1.16  class MCalChangeCallBack2
    1.17  	{
    1.18  public:
    1.19 -	/** Instance view change type
    1.20 -	@publishedAll
    1.21 -	@released
    1.22 +	/**
    1.23 +	Type of change to the entry.
    1.24  	*/
    1.25  	enum TChangeType
    1.26  		{
    1.27 -		/**	Entries are added */
    1.28 +		/**	Calendar entry added. */
    1.29  		EChangeAdd,
    1.30 -		/** Entries are deleted */
    1.31 +		/** Calendar entry deleted. */
    1.32  		EChangeDelete,
    1.33 -		/** Entries are modified */
    1.34 +		/** Calendar entry modified. */
    1.35  		EChangeModify,
    1.36 -		/** Undefined entries */
    1.37 -		EChangeUndefined
    1.38 +		/** Undefined Calendar entry change. */
    1.39 +		EChangeUndefined,
    1.40 +		/** The time zone rules for one or more Calendar entries have changed. */
    1.41 +		EChangeTzRules,
    1.42 +        /** Backup Starts
    1.43 +        * When the backup event is in process, the Calendar file is locked. 
    1.44 +        * Most of operations are not permitted when it happens. However, few
    1.45 +        * operations, such as notification request, enabling broadcast
    1.46 +        * and closing Calendar is still permitted.
    1.47 +        * */
    1.48 +        EBackupStart,
    1.49 +        /** Restore Starts 
    1.50 +        * When the restore event is in process, the Calendar file is locked. 
    1.51 +        * Most of operations are not permitted when it happens. However, few
    1.52 +        * operations, such as notification request, enabling broadcast
    1.53 +        * and closing Calendar is still permitted.
    1.54 +        */
    1.55 +        ERestoreStart,       
    1.56 +        /** Backup Ends 
    1.57 +        * When the backup event is completed, the Calendar file is unlocked. 
    1.58 +        * The application can continue to operate on the current Calendar file.
    1.59 +        */
    1.60 +        EBackupEnd,
    1.61 +        /** Restore Ends
    1.62 +        * When the restore event is completed, the Calendar file is unlocked. 
    1.63 +        * The application can operate on the restored Calendar file after the application
    1.64 +        * is notified with the message. However, if the application has cached any
    1.65 +        * Calendar objects, such as Calendar file ID, Calendar entries, Calendar instances,
    1.66 +        * they are not necessarily synched with the data in the newly restored Calendar file. 
    1.67 +        */
    1.68 +        ERestoreEnd,
    1.69 +        /** The restored Calendar file can not be opened 
    1.70 +        * When the restore event is completed, the newly restored Calendar file can not
    1.71 +        * be opened. It is because either the file version is not supported or the data is corrupted.
    1.72 +        * Apart from closing the session and delete the file, no any other operation is permitted
    1.73 +        * when it happens.
    1.74 +        */
    1.75 +        ERestoredFileCanNotBeOpened
    1.76  		};
    1.77  
    1.78 -	/** Instance view entry type
    1.79 -	@publishedAll
    1.80 -	@released
    1.81 +	/**
    1.82 +	Type of entry.
    1.83  	*/
    1.84  	enum TChangeEntryType
    1.85  		{
    1.86 -		/** Entry type is todo */
    1.87 +		/** Entry type is todo. */
    1.88  		EChangeEntryTodo,
    1.89 -		/** Entry type is event */
    1.90 +		/** Entry type is event. */
    1.91  		EChangeEntryEvent,
    1.92 -		/** All entry types */
    1.93 +		/** All entry types. */
    1.94  		EChangeEntryAll
    1.95  		};
    1.96 -	/** A call back function for change notification
    1.97 -	@param aChangeItems  List of changes since the last notification.
    1.98  
    1.99 +	/**
   1.100 +	A call back function for change notification.
   1.101 +	
   1.102 +	@param aChangeItems List of changes since the last notification.
   1.103  	*/
   1.104  	virtual void CalChangeNotification(RArray<TCalChangeEntry>& aChangeItems) = 0;
   1.105  	};
   1.106  
   1.107 -/** Struct for storing change notification data.
   1.108 -This contains the calendar local ID, the type of change and the entry type.
   1.109 +/**
   1.110 +A structure for storing Calendar change notification data.  This contains the
   1.111 +Calendar entry local UID, the type of change and the entry type.
   1.112  
   1.113 -The iChangeType will only be set to EChangeEntryTodo or EChangeEntryEvent
   1.114 -values. EChangeEntryAll is provided for callback registration only.
   1.115 +The iChangeEntryType member may be set to MCalChangeCallBack2::EChangeEntryTodo
   1.116 +or MCalChangeCallBack2::EChangeEntryEvent.  MCalChangeCallBack2::EChangeEntryAll
   1.117 +is provided for call back registration only.
   1.118  
   1.119 -If iChangeType is EChangeUndefined or EChangeOverflowError, iEntryId and
   1.120 -iEntryType are undefined and should not be used by clients.
   1.121 +If the iChangeType member is MCalChangeCallBack2::EChangeUndefined or
   1.122 +MCalChangeCallBack2::EChangeTzRules, iEntryId and iEntryType are undefined and
   1.123 +should not be used by clients.
   1.124 +
   1.125 +When the iChangeType member is MCalChangeCallBack2::EChangeTzRules a change in
   1.126 +time zone rules has been detected and processed by the Calendar server.  The
   1.127 +client should refresh any instance data they own as a result of this change.
   1.128  
   1.129  @publishedAll
   1.130  @released
   1.131  */
   1.132  struct TCalChangeEntry
   1.133  	{
   1.134 -	/** Local UID of the entry */
   1.135 +	/** Local UID of the entry. */
   1.136  	TCalLocalUid iEntryId;
   1.137 -	/** Type of change to the entry */
   1.138 +	/** Type of change to the entry. */
   1.139  	MCalChangeCallBack2::TChangeType iChangeType;
   1.140 -	/** Type of entry */
   1.141 +	/** Type of entry. */
   1.142  	MCalChangeCallBack2::TChangeEntryType iEntryType;
   1.143  	};
   1.144