--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/classicui_plat/extended_notifiers_api/inc/AknNotifierWrapper.h Tue Feb 02 01:00:49 2010 +0200
@@ -0,0 +1,490 @@
+/*
+* Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Notifier server app wrapper definition.
+*
+*/
+
+#ifndef __AKNNOTIFIERSERVERAPPWRAPPER_H__
+#define __AKNNOTIFIERSERVERAPPWRAPPER_H__
+
+#include <eiknotapi.h>
+#include <eikserverapp.h>
+#include <AknNotifierWrapperDefs.h>
+
+// FORWARD DECLARATIONS
+class CAknNotifierMessageObserver;
+
+/**
+ * Avkon notifier wrapper interface.
+ *
+ * Abstract class for accessing an object implementing actual client-session to Notifier
+ * App Server.
+ *
+ * @lib aknnotifierwrapper.lib
+ * @since S60 v3.0
+ */
+class MAknNotifierWrapper
+ {
+public:
+ /**
+ * Command session owning object to update a notifier with given uid
+ * Method is synchronous. On error leaves with standard Symbian OS error code.
+ * @since 3.0
+ * @param aNotifierUid Notifier to be updated
+ * @param aBuffer Buffer from RNotifier client
+ * @return Return package from app server. Implementation specific.
+ */
+ virtual TPtrC8 UpdateNotifierL( TUid aNotifierUid, const TDesC8& aBuffer) = 0;
+
+ /**
+ * Command session owning object to cancel a notifier with given uid
+ * Method is synchronous
+ * @since 3.0
+ * @param aNotifierUid Notifier to be cancelled
+ */
+ virtual void CancelNotifier( TUid aNotifierUid ) = 0;
+
+ /**
+ * Command session owning object to start a notifier with given uid
+ * Method is asynchronous. On error leaves with standard Symbian OS error code.
+ * @since 3.0
+ * @param aNotifierUid Notifier to be started
+ * @param aBuffer Buffer from RNotifier client
+ * @param aReplySlot to which slot plugin will write its reply
+ * @param aMessage Message into which reply is written when async request is completed
+ */
+ virtual void StartNotifierL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage) = 0;
+
+ /**
+ * Command session owning object to start a notifier with given uid
+ * Method is synchronous. On error leaves with standard Symbian OS error code.
+ * @since 3.0
+ * @param aNotifierUid Notifier to be started
+ * @param aBuffer Buffer from RNotifier client
+ * @return Return package from app server. Implementation specific.
+ */
+ virtual TPtrC8 StartNotifierL( TUid aNotifierUid, const TDesC8& aBuffer) = 0;
+
+ /**
+ * Return unique identifier of server application implmenting the service
+ * @since 3.0
+ * @return refrence to Uid
+ */
+ virtual const TUid& AppServerUid() const = 0;
+
+ /**
+ * Return reference to buffer used in syncronous commands to store reply before sending
+ * it to client.
+ * @since 3.0
+ * @return refrence to synch reply buffer
+ */
+ virtual TPtr8 SynchronousReplyBuf() = 0;
+
+ /**
+ * Callback method, called when async request from app server completes.
+ * @since 3.0
+ * @param aEntry queue object which was completed by app server. Called before FW
+ * completes request from client using RNotifier.
+ * Instance implementing this API, may complete the message during this method if default
+ * implementation is not suitable (just writes the reply from client to replyslot given)
+ */
+ virtual void AsyncMessageCompleted( CAknNotifierMessageObserver* aEntry ) = 0;
+
+ /**
+ * Command session owning object to update a notifier with given uid
+ * Method is asynchronous. On error leaves with standard Symbian OS error code.
+ *
+ * This method was added to 3.2 and in order to preserve SC it has a default
+ * implementation which leaves with @c KErrNotSupported.
+ *
+ * @since 3.2
+ * @param aNotifierUid Notifier to be updated
+ * @param aBuffer Buffer from RNotifier client
+ * @param aReplySlot To which slot plugin will write its reply
+ * @param aMessage Message into which reply is written when async request is completed
+ */
+ IMPORT_C virtual void UpdateNotifierL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage);
+ };
+
+class CAknCommonNotifierWrapper;
+
+// Class implementing queue entry for asynchronous requests.
+// Deletion of an entry is possible only by completing the request status of entry.
+class CAknNotifierMessageObserver : public CActive
+ {
+public:
+ /**
+ * Creates new queue entry which combines message from client using RNotifier
+ * to an asynchronous app server requests. When app server completes TRequestStatus of this
+ * entry callback AsyncMessageCompleted() will be called.
+ * On error leaves with standard Symbian OS error code.
+ * @since 3.0
+ * @param aNotifierUid Notifier to be started
+ * @param aOwner Object which will be notified when request is complete
+ * @param aClientMessage Message into which reply is written when async request is completed
+ * @param aReplySlot Index to which reply will be copied.
+ * @return New queue entry ready for use.
+ */
+ IMPORT_C static CAknNotifierMessageObserver* NewServerRequestL(
+ TUid aNotifierUid,
+ MAknNotifierWrapper* aOwner,
+ const RMessagePtr2& aClientMessage,
+ TInt aReplySlot);
+
+ void Start(){ CActive::SetActive(); };
+
+private:
+ ~CAknNotifierMessageObserver();
+
+ CAknNotifierMessageObserver(
+ TUid aNotifierUid,
+ MAknNotifierWrapper* aOwner,
+ const RMessagePtr2& aClientMessage,
+ TInt aReplySlot);
+
+private: // from CActive
+ void RunL();
+ void Cancel();
+ void DoCancel();
+
+ // Offer access for owning class, it may complete the message if default implementation
+ // is not suitable for its purposes.
+public:
+ TUid iNotifierUid;
+ HBufC8* iReplyBuf;
+ TPtr8* iReplyDesc; // cannot be constructed otherwise
+ HBufC8* iInputBuf;
+ RMessagePtr2 iMessage;
+ TInt iReplySlot;
+
+private: // data
+ MAknNotifierWrapper* iOwner; // not owned
+ };
+
+// Simple client to App Server. Internal to Avkon.
+class RAknNotifierAppServClient : public REikAppServiceBase
+ {
+public:
+ RAknNotifierAppServClient();
+ void SetServerAppUid(TUid aAppServerUid);
+ TUid ServiceUid() const;
+
+ TInt SendSync(
+ TNotifierMessage aFunction,
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TPtr8 aReply,
+ const TDesC& aLibraryName);
+
+ void SendAsync(TNotifierMessage aFunction,
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ CAknNotifierMessageObserver* aQueueEntry,
+ const TDesC& aLibraryName);
+
+ TInt StartServer(); // or rather connect
+ TInt SendAsync(TInt aNotifierControllerFunction);
+ void SetOwnerUsingMonitor(CAknCommonNotifierWrapper* aOwner)
+ {
+ iOwnerUsingMonitor = aOwner;
+ }
+
+private:
+ void StartServerL();
+ TUid iAppServerUid;
+ CAknCommonNotifierWrapper* iOwnerUsingMonitor;
+ };
+
+
+// Ligthweight implementation of MEikSrvNotifierBase2.
+// Instances cannot access app server directly but only via session owning instace which
+// implemets MAknNotifierWrapper API.
+class CAknNotifierWrapperLight : public CBase, public MEikSrvNotifierBase2
+ {
+public:
+ IMPORT_C ~CAknNotifierWrapperLight();
+ /**
+ * Constructor. Requires reference to a session owning instance (MAknNotifierWapper
+ * derived).
+ *
+ * @since 3.0
+ * @param aSessionOwningNotifier Object which provides the actual client server session
+ * to app server.
+ * @param aNotifierUid Uid of this notifier, returned in Info()
+ * @param aChannel Channel uid of this notifier, returned in Info()
+ * @param aPriority Priority of this notifier, see declaration of MEikSrvNotifierBase2,
+ * returned in Info()
+ */
+ IMPORT_C CAknNotifierWrapperLight(
+ MAknNotifierWrapper& aSessionOwningNotifier,
+ TUid aNotifierUid,
+ TUid aChannel,
+ TInt aPriority );
+
+public:
+ // from MEikSrvNotifierBase2
+ IMPORT_C TPtrC8 UpdateL(const TDesC8& aBuffer);
+ IMPORT_C void Cancel();
+ IMPORT_C void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
+ IMPORT_C TPtrC8 StartL(const TDesC8& aBuffer);
+ IMPORT_C TNotifierInfo Info() const;
+ IMPORT_C TNotifierInfo RegisterL();
+ IMPORT_C TInt NotifierCapabilites(); // just base calls currently
+
+ /**
+ * Cancels asynchronous requests and deletes instance.
+ */
+ IMPORT_C void Release();
+
+ /**
+ * Updates a currently active notifier with new data.
+ *
+ * @since S60 3.2
+ *
+ * @param aBuffer Data from the client side.
+ * @param aReplySlot Identifies which message argument to use for the reply.
+ * @param aMessage Encapsulates the client request.
+ */
+ IMPORT_C void UpdateL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
+
+private:
+ MAknNotifierWrapper& iOwner;
+ TNotifierInfo iInfo;
+ TAny* iSpare;
+ };
+
+// Class implementing both session to AppServer and MEikSrvNotifierBase (CAknNotifierWrapperLight).
+class CAknNotifierWrapper : public CAknNotifierWrapperLight, public MAknNotifierWrapper
+ {
+public: // for convenience, no need to derive if default implementation is enough
+ /**
+ * Static constructor. This does not connect (nor create) app server, but the server is created
+ * when RegisterL is being called by Symbian FW. Real connection to app server is formed during
+ * first actual notifier request
+ *
+ * @since 3.0
+ * @param aNotifierUid Uid of this notifier, returned in Info()
+ * @param aChannel Channel uid of this notifier, returned in Info()
+ * @param aPriority Priority of this notifier, see declaration of MEikSrvNotifierBase2, returned
+ * in Info()
+ * @param aAppServerUid Uid of App Server to connect (implementation specific)
+ * @param aReplyBufSize Size of a reply buffer used in synchrouns notifier requests
+ */
+ IMPORT_C static CAknNotifierWrapper* NewL(
+ TUid aNotifierUid,
+ TUid aChannel,
+ TInt aPriority,
+ TUid aAppServerUid,
+ TUint aReplyBufSize);
+
+ const TUid& AppServerUid() const {return iAppServerUid;}
+ TPtr8 SynchronousReplyBuf(){return iReplyBuffer->Des();}
+
+protected: // c'tor
+ /**
+ * Constructor. Intended only for derivation. Uses AppServerUid() to initialize iAppServerUid.
+ *
+ * @since 3.0
+ * @param aNotifierUid Uid of this notifier, returned in Info()
+ * @param aChannel Channel uid of this notifier, returned in Info()
+ * @param aPriority Priority of this notifier, see declaration of MEikSrvNotifierBase2,
+ * returned in Info().
+ */
+ IMPORT_C CAknNotifierWrapper(TUid aNotifierUid, TUid aChannel, TInt aPriority);
+
+public: // d'tor
+ IMPORT_C ~CAknNotifierWrapper();
+
+public: // from CAknNotifierWrapperLight
+ // This effectively starts server immediately after eiksrv construction has been completed.
+ IMPORT_C TNotifierInfo RegisterL();
+
+public: // from MAknNotifierWrapper
+ IMPORT_C TPtrC8 UpdateNotifierL(TUid aNotifierUid, const TDesC8& aBuffer);
+ IMPORT_C void CancelNotifier(TUid aNotifierUid);
+
+ IMPORT_C void StartNotifierL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage);
+
+ IMPORT_C TPtrC8 StartNotifierL(TUid aNotifierUid, const TDesC8& aBuffer);
+ IMPORT_C void AsyncMessageCompleted(CAknNotifierMessageObserver* aEntry);
+
+ IMPORT_C void UpdateNotifierL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage);
+
+public: // for generic notifier window controller
+ IMPORT_C void DoNotifierControllerCommand(TInt aCommand);
+
+protected:
+ void SetSynchReplybuf(HBufC8* aReplyBuffer)
+ {
+ delete iReplyBuffer;
+ iReplyBuffer = aReplyBuffer;
+ }
+
+ RAknNotifierAppServClient& Client()
+ {
+ return iClient;
+ }
+
+ CAknNotifierMessageObserver* CreateNewQueueEntryL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage);
+
+private: // internal utilities
+ // Completes all requests with matching uid with given reason.
+ void CompleteOutstandingRequests( TUid aNotifierUid, TInt aReason );
+ void ConstructL(TUint aReplyBufSize);
+
+private: // for convenience methods needs
+ CAknNotifierWrapper(
+ TUid aNotifierUid,
+ TUid aChannel,
+ TInt aPriority,
+ TUid aAppServerUid);
+
+private: // data
+ RAknNotifierAppServClient iClient;
+ //CApaServerAppExitMonitor* iServerExitMonitor;
+ RPointerArray<CAknNotifierMessageObserver> iMessageQueue;
+ HBufC8* iReplyBuffer;
+ TUid iAppServerUid;
+ };
+
+
+class MAknNotifierCustomSecurityCheck
+ {
+public:
+ // releases resources allocated (usually: delete this)
+ virtual void Release()=0;
+ // Called from asynch StartL() other places we don't have access to actual message.
+ virtual void CustomSecurityCheckL(const RMessagePtr2& aMessage) = 0;
+ };
+
+
+class CAknCommonNotifierWrapper : public CAknNotifierWrapper, public MApaServerAppExitObserver
+ {
+public:
+ /**
+ * Static constructor. This does not connect (nor create) app server, but the server is created
+ * when RegisterL is being called by Symbian FW. Real connection to app server is formed during
+ * first actual notifier request.
+ *
+ * @since 3.1
+ * @param aNotifierUid Uid of this notifier, returned in Info().
+ * @param aChannel Channel uid of this notifier, returned in Info().
+ * @param aPriority Priority of this notifier, see declaration of MEikSrvNotifierBase2,
+ * returned in Info().
+ * @param aReplyBufSize Size of a reply buffer used in synchrouns notifier requests.
+ */
+ IMPORT_C static CAknCommonNotifierWrapper* NewL(
+ TUid aNotifierUid,
+ TUid aChannel,
+ TInt aPriority,
+ const TDesC& aLibraryName,
+ TUint aReplyBufSize,
+ TBool aPreload = EFalse );
+
+ /**
+ * Sets custom security checking object, ownership taken. When ever notifier wrapper receives a
+ * command with actual message message is first passed to given object.
+ *
+ * If callback (CustomSecurityCheckL()) does not leave, it is assumed that security checking
+ * was successfully passed.
+ *
+ * @since 3.1
+ * @param aNotifierUid Uid of this notifier, returned in Info().
+ */
+ IMPORT_C void SetCustomSecurityHandler(MAknNotifierCustomSecurityCheck* aHandler);
+
+
+ /**
+ * Loads the notifier plugin once app server is available. Keeps this plugin (aLibraryName
+ * in constructor).
+ * always loaded
+ *
+ * @since 3.1
+ * @param aNotifierUid Uid of this notifier, returned in Info().
+ */
+ IMPORT_C void PreLoadLibraryL();
+
+ // callback
+ TBool PreLoadLibrary();
+
+ ~CAknCommonNotifierWrapper();
+
+public: // from base class
+ const TUid& AppServerUid() const {return KCommonNotifierAppSrvUid;}
+
+ void StartNotifierL(
+ TUid aNotifierUid,
+ const TDesC8& aBuffer,
+ TInt aReplySlot,
+ const RMessagePtr2& aMessage );
+
+ TPtrC8 StartNotifierL( TUid aNotifierUid, const TDesC8& aBuffer );
+ void CancelNotifier( TUid aNotifierUid );
+ TNotifierInfo RegisterL();
+
+public: // callback from client once server is connected
+ void AppServerConnectedL();
+
+ // Introduce to this namespace to avoid possible conflicts
+ struct TPendingMsg
+ {
+ TPendingMsg(TUid uid, const RMessagePtr2& msg): iUid(uid.iUid),iMessage(msg){}
+ TInt iUid;
+ RMessagePtr2 iMessage;
+ };
+
+private:
+ // from MApaServerAppExitObserver
+ void HandleServerAppExit(TInt aReason);
+
+ void ConstructL(const TDesC& aLibraryName, TUint aReplyBufSize);
+
+ CAknCommonNotifierWrapper(
+ TUid aNotifierUid,
+ TUid aChannel,
+ TInt aPriority,
+ TBool aPreLoad);
+
+ HBufC* iLibraryName;
+ MAknNotifierCustomSecurityCheck* iCustomSecurityCheck;
+ CIdle* iIdle;
+ TBool iPreLoad;
+ CApaServerAppExitMonitor* iMonitor;
+ RArray<TPendingMsg> iPendingArray;
+ };
+
+#endif // __AKNNOTIFIERSERVERAPPWRAPPER_H__
+
+// End of file
+
\ No newline at end of file