1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   handles policies for transitions, wich are supported, what kml to use etc.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_POLICYHANDLER_H

    20 #define C_POLICYHANDLER_H

    21 

    22 #include <e32base.h>

    23 #include <s32file.h>

    24 

    25 

    26 #include "alfpolicy.h"

    27 #include "alfpolicyrequesthandler.h"

    28 //#include "transitionserver.h"

    29 

    30 //======= Forward declarations =======

    31 class TFullScreenBlock;

    32 class CClientControlPolicy;

    33 class CFullscreenPolicy;

    34 class CControlPolicy;

    35 class CListBoxPolicy;

    36 

    37 /**

    38  *  policy handler

    39  *

    40  *  handles policies for transitions, if it is supported or not, and if so, what 

    41  *  kml file to use for the effect. This class handles both Fullscreen and 

    42  *	control policies.

    43  *

    44  *  @since S60 3.2

    45  */

    46 NONSHARABLE_CLASS(CPolicyHandler) : public CBase

    47     {  	

    48 public: 

    49 	friend class CPolicyClientRequestHandler;

    50 	/**

    51      * Public part of two phase construction.

    52      * @since S60 3.2

    53      *

    54      * @return 

    55     */  

    56     static CPolicyHandler* NewL();

    57 

    58     /**

    59      * Destructor. 

    60      * @since S60 3.2

    61      *

    62     */  

    63     ~CPolicyHandler();

    64 

    65 /**

    66 	 * Register the KML files and resource directory to be used by a listbox.

    67 	 * The KML files and resource directory will be used for listboxes of the specified type

    68      * in the process with the Uid aUid.

    69      *

    70      * KNullUid will be treated as the "default" Uid - listboxes in processes

    71 	 * with no KML registered for their uid will use KML registered with KNullUid.

    72 	 * EListTypeAny works the same way for listbox types.  More specific settings have 

    73      * priority over less specific ones, and the uid has higher priority than the list type,

    74      * which means that when assigning KML to a specific listbox, the search for KML is

    75      * done in the following order:

    76      *

    77      * 1. KML that has been registered with the uid of the listbox' app and with the

    78      *    listbox type that matches the specific listbox.

    79      * 2. KML that has been registered with the uid of the listbox' app, with type EListTypeAny.

    80      * 3. KML that has been registered with KNullUid and with the matching listbox type.

    81      * 4. KML that has been registered with KNullUid and EListTypeAny.

    82      *

    83 	 * If a Uid is registered with aBackgroundFileName of length zero this Uid will be treated as

    84 	 * having no effect, even if there is a "default" Uid. 

    85 	 *

    86 	 * @since S60 v3.1

    87 	 * @param aUid the TUid to associate the kml files with, KNullUid as default

    88 	 * @param aThreadId. The thread Id to associate the kml files with

    89      * @param aListBoxType the type of listbox to associate the KML files with,

    90      *        EListTypeAny to associate it with any type of list.

    91 	 * @param aResourceDir the resource directory

    92 	 * @param aBackgroundFileName the kml file to use for the background and highlight of the listbox, 

    93 	 		  must be relative the resource directory.

    94 	 * @param aListItemFilename the kml file to use for the listitems of the listbox, 

    95 	 		  must be relative the resource directory.

    96 	 * @return KErrNone if successful, otherwise another of the system-wide error codes.	

    97 	 */

    98 	void RegisterListBoxKmlL( const TUid& aUid, 

    99 							  const TThreadId& aThreadId,

   100 	                          const CAlfTransitionServerClient::TListBoxType aListBoxType,

   101 	                          const TDesC& aResourceDir, 

   102 							  const TDesC& aBackgroundFileName,

   103 							  const TDesC& aListItemFilename,

   104 							  TInt aCachePriority = -1,

   105 							  TInt aWantedTime = -1, TInt aMinTime = -1 );

   106 	/**

   107 	 * Unregisters KML files previously registered for a listbox.

   108 	 *

   109 	 * @param aUid the Uid to unregisted KML files for.

   110 	 * @param aListBoxType The type of listbox to unregister KML for.

   111 	 * @return KErrNone if successful, otherwise another of the system-wide error codes.

   112 	 */    

   113 	TInt UnregisterListBoxKml( const TUid& aUid,

   114                                const CAlfTransitionServerClient::TListBoxType aListBoxType );

   115                                

   116     /**

   117 	 * Unregisters KML files previously registered for a listbox from one Thread.

   118 	 *

   119 	 * @param aThreadId the thead id to unregisted KML files for.

   120 	 * @return KErrNone if successful, otherwise another of the system-wide error codes.

   121 	 */    

   122 	TInt UnregisterListBoxKml( const TThreadId& aThreadId );

   123 

   124 

   125     /**

   126      * Get the KML files for listboxes in the app with the specified Uid.

   127      *

   128      * @param aAppId The AppUid of the application that the listbox belongs

   129      *        to.

   130      * @param aResourceDir

   131      * @param aBackgroundFilename Name of the KML file that defines the

   132      *        background behaviour.

   133      * @param aItemFilename Name of the KML file that defines the item

   134      *        behaviour.

   135      * @aCachePriority

   136      * @aWantedTime

   137      * @aMinTime

   138      */

   139     TInt GetListBoxKml(	const TUid& aAppId, 

   140                         const CAlfTransitionServerClient::TListBoxType aListBoxType,

   141                         TPtrC& aResourceDir,

   142                         TPtrC& aBackgroundFilename,

   143                         TPtrC& aItemFilename,

   144                         TInt& aCachePriority, TInt& aWantedTime, 

   145                         TInt& aMinTime );

   146 

   147   	/**

   148      * Registers a KML file for use with FullScreen transitions. 

   149      * If the filename stored here is NULL, the action is blocked

   150      * from any UID.

   151      * @since S60 3.2

   152      *

   153      * @param aAction. Action for which this KML file will be used.

   154      * @param aUid. UID for which this KML file will be used.

   155      * @param aThreadId. Thread ID for which this KML file will be used.

   156      * @param aResourceDir. Descriptor containing the full path

   157      *		  to the location of the KML file.

   158      * @param aFilename. Descriptor contrianing the name of the

   159      *		  KML file.

   160      * @param Proirity when it's stored in the cache.

   161      * @param wanted time between frames.

   162      * @param Minimum allowed time between frames.

   163      * @return KErrNone or any of the system error codes.

   164      */    

   165 	void RegisterFullscreenKmlL( TUint aAction, const TUid& aUid, 

   166 								 const TThreadId& aThreadId,

   167 								 const TDesC& aResourceDir, const TDesC& aFilename,

   168 								 TInt aCachePriority = -1, TInt aWantedTime = -1 , TInt aMinTime = -1);

   169   	/**

   170      * Unregisters a KML file for <action,uid> pair. Both action

   171      * and UID must match in order for the file to be unregistered.

   172      * @since S60 3.2

   173      *

   174      * @param aAction. Action to unregister.

   175      * @param aUid. UID to unregister.

   176      * @return KErrNone or any of the system error codes.

   177      */    

   178   	TInt UnregisterFullscreenKml(TUint aAction, const TUid& aUid);

   179   	

   180   	/**

   181      * Unregisters all of Fullscreen KML files from one thread Id

   182      * @since S60 3.2

   183      *

   184      * @param aThreadId. the thread Id to unregisted KML files for.

   185      * @return KErrNone or any of the system error codes.

   186      */   

   187      TInt UnregisterFullscreenKml(const TThreadId& aThreadId);

   188      

   189   	/**

   190      * Unregisters all of registered KML files for a thread ID.

   191      * @since S60 3.2

   192      *

   193      * @param aThreadId the thread id to unregisted KML files for.

   194      * @return KErrNone or any of the system wide error codes.

   195     */  

   196 	TInt UnregisterAllKml(const TThreadId& aThreadId);

   197 	

   198   	/**

   199      * Retrieves the path and name of a KML file that corresponds to the

   200      * supplied aAction and aToUid. This method will return 

   201      * KErrNotSupported if the <aAction, aToUid> pairs are not found,

   202      * the aToTuid or aFromUid are blocked. If the aToUid is the default

   203      * UID (KNullUid) and the default action has been blocked 

   204      * KerrNotSupported will also be returned.

   205      * @since S60 3.2

   206      *

   207      * @param aAction. The action for which to retireve file data.

   208      * @param aToUid. The ToUid for which to retrieve file data.

   209      * @param aFromUid. The FromUid for which to retrieve file data.

   210      * @param aResourceDir. Pointer reference where the resource

   211      *  	  directory will be stored.

   212      * @param aFileName. Pointere reference where the file name will

   213      * 		  be stored.

   214      * @return KerrNone or KErrNotSupported.

   215      */    

   216   	TInt GetFullscreenKml(	TUint aAction, const TUid& aToUid, 

   217   							const TUid& aFromUid, TPtrC& aResourceDir, TPtrC& aFilename,

   218   							TInt& aCachePriority, TInt& aWantedTime, TInt& aMinTime);

   219 

   220 private:

   221   	/**

   222      * Retrieves all stored policies for CCoeControls. The policies

   223      * will be copied (by pointer) and stored in the supplied arrray.

   224      * This method is only used by CPolicyClientRequestHandler.

   225      *

   226      * @param aControlPolicies. Array where the policies will be stored.

   227      * @return KerrNone or any of the system error codes.

   228      */    

   229   	TInt GetAllControlPolicies(RPointerArray<CClientControlPolicy>& aControlPolicies);

   230 

   231 public:

   232   	/**

   233      * Passes the call on to the AlfPolicyRequestHandler

   234      * @since S60 3.2

   235      *

   236      * @param aMessage. Reference to the message sent by the client.

   237      * @return KErrNone or any of the system error messages.

   238      */    

   239   	TInt RequestPolicy(const RMessage2& aMessage);

   240 

   241   	/**

   242      * Passes the call on to the AlfPolicyRequestHandler

   243      *

   244      * @param aClientId id of the client that wants the policies

   245      * @param aPolicyCount number of policies the caller can handle

   246      * @param aOutBuf the buffer that will be filled with the policies

   247      * @return KErrNone or any of the system error messages.

   248      */    

   249   	TInt GetPolicyL( TThreadId aClientId, TInt aPolicyCount, TPtr8& aOutBuf );

   250 

   251   	/**

   252      * Passes the call on to the AlfPolicyRequestHandler

   253      * @since S60 3.2

   254      *

   255      * @param aClientId id of the client whose request are cancelled

   256      */    

   257   	void RemoveClient( TThreadId aClientId );

   258 

   259 	/**

   260      * Removes all requests that belong to terminated clients.

   261      * Passes the call on to the PolicyRequtHandler

   262      *

   263      * @since S60 3.2

   264      */

   265 //	void RemoveDeadClients();

   266 	

   267 	/**

   268 	 * Dumps a list of threadids of all connected clients waiting for 

   269 	 * policy updates

   270 	 *

   271 	 * Used for testing

   272      * @since S60 3.2

   273 	 *

   274 	 * @param aFile an open write stream to dump clients to.

   275 	 */

   276 //	void DumpClientsL(RFileWriteStream& aFile);

   277   	

   278   	/**

   279      * Blocks/Unblocks a UID for fullscreen effects. If both aBlockTo

   280      * and aBlockFrom are false, the UID is unblocked. This unblocking 

   281      * feature will unblock all blocks containing the supplied UID. 

   282      * @since S60 3.2

   283      *

   284      * @param aUid. The UID to block.

   285      * @param aBlockTo. True if the ToUid is to be blocked.

   286      * @param aBlockFrom. True if the FromUid is to be blocked.

   287      * @return KErrNone or any of hte system error codes.

   288      */    

   289   	TInt BlockFullScreenUid(const TUid& aUid, TBool aBlockFrom, 

   290   							TBool aBlockTo);

   291 

   292   	/**

   293      * Registers a KML file for use with a CCoeControl. Although a file

   294      * has been registered, the policy for this UID is still unsupported

   295      * since no actions have been registered.

   296      * @since S60 3.2

   297      *

   298      * @param aUid. The UID for which the KML file contains actions.

   299      * @param aThreadId, the Thread ID to associate the kml files with.

   300      * @param aResourceDir. Descriptor containing the full path to

   301      * 		  the location of the KML file.

   302      * @param aFilename. Descriptor containing the filename of the 

   303      * 		  KML file.

   304      */    

   305   	void RegisterControlKmlL(const TUid &aUid, 

   306   							 const TThreadId& aThreadId,

   307   							 const TDesC& aResourceDir, 

   308   							 const TDesC& aFilename,

   309   							 TInt aWantedTime = -1,

   310   							 TInt aMinTime = -1);

   311   	

   312   	/**

   313      * Unregisters a KML file for the supplied UID. This method will 

   314      * also unregister all actions for this UID.

   315      * @since S60 3.2

   316      *

   317      * @param aUid. The UID to unregister.

   318      * @return KerrNone if successfully unregistered, otherwise

   319      *		   KErrNotFound.

   320      */    

   321   	TInt RemoveControlKml(const TUid &aUid);

   322   	

   323   	/**

   324      * Unregisters KML files for the supplied Thread ID. This method will 

   325      * also unregister all actions from them.

   326      * @since S60 3.2

   327      *

   328      * @param aThreadId. The thead ID to unregister for.

   329      * @return KerrNone if successfully unregistered, otherwise

   330      *		   KErrNotFound.

   331      */    

   332   	TInt UnregisterControlKml(const TThreadId& aThreadId);

   333   	

   334   	

   335   	/**

   336      * Retrieves the resource directory, filename and action for a 

   337      * CCoeControl animation based on the UID and Action supplied.

   338      * If the action was not found the supplied pointer will be set

   339      * to NULL.

   340      * @since S60 3.2

   341      *

   342      * @param aUid. UID of the CCoeControl.

   343      * @param aAction. Action to be performed.

   344      * @param aResourceDir. Pointer reference that will contain the

   345      *		  full path to where the KML file is located. Not owning.

   346      * @param aFileName. Pointer reference that will contain the

   347      *		  filename. Not owning.

   348      * @param aActionString. Pointer reference that will contain the

   349      *		  string-name of the action to be performed.

   350      * @return KerrNone if data was found otherwise KErrNotFound.

   351      */    

   352   	TInt GetControlKml(	TUid aUid, TUint aAction, TPtrC& aResourceDir, 

   353   						TPtrC& aFileName, TPtrC& aActionString, TInt& aCachePriority,

   354   						TInt& aWantedTime, TInt& aMinTime);

   355   	

   356    	/**

   357      * Registers an actionstring  for a CCoeControl with a <UID, Action>

   358      * pair. This method will fail if no KML file has been registered for  

   359      * the UID.

   360      * @since S60 3.2

   361      *

   362      * @param aUid. UID for which to register the action string.

   363      * @param aAction. Action for which to register the actionstring.

   364      * @param aActionString. Descriptor containing the action string

   365      *		  to register.

   366      * @return KErrNone if successfull, otherwise any of the system

   367      *		   error codes.

   368      */    

   369   	TInt RegisterControlAction( const TUid aUid, TUint aAction, 

   370   								const TDesC& aActionString);

   371   	

   372   	/**

   373      * Unregisters an CCoeControl transition action for a UID.

   374      * @since S60 3.2

   375      *

   376      * @param aUid. UID for which to unregister the action.

   377      * @param aAction. Action to unregister.

   378      * @return KErrNone if action is unregistered, otherwise KerrNotFound.

   379      */    

   380   	TInt UnregisterControlAction( const TUid aUid, TUint aAction );

   381 

   382 private:

   383     CPolicyHandler();

   384 

   385   	/**

   386      * Looks through the stored policy list for a specific policy.

   387      * @since S60 3.2

   388      *

   389      * @param aAction. Action too look for.

   390      * @param aUidT. Uid to look for

   391      * @param aPolicy. Reference to a CActionPolicy where the policy

   392      *		  will be stored for future reference.

   393      * @param aIndex. Reference where the index of the policy item 

   394      *		  will be stored for future reference.

   395      * @return KErrNone if found. Otherwise KErrNotFound.

   396      */    

   397     TInt FindControlPolicy(	TUint aAction, TUid aUidT, 

   398     						CActionPolicy*& aPolicy, TInt& aIndex);

   399     

   400 private:	// data

   401     RPointerArray<CFullscreenPolicy> 	iFullscreenPolicies;

   402     

   403     RPointerArray<CControlPolicy> 		iControlPolicies;

   404     

   405     CPolicyClientRequestHandler* 		iClientRequestHandler;

   406     

   407     RPointerArray<TFullScreenBlock> 	iFullScreenBlocks;

   408 

   409     RPointerArray<CListBoxPolicy> 		iListBoxPolicies;

   410 

   411     };

   412 

   413 

   414 #endif