1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/eiknotapi.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,270 @@
1.4 +// Copyright (c) 1997-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 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __EIKNOTAPI_H__
1.20 +#define __EIKNOTAPI_H__
1.21 +
1.22 +#include <e32std.h>
1.23 +#include <e32base.h>
1.24 +#include <f32file.h>
1.25 +
1.26 +/** Defines the second Uid value for plug in notifier DLLs.
1.27 +
1.28 +@publishedAll
1.29 +@released */
1.30 +const TUid KUidNotifierPlugIn = {0x10005522};
1.31 +const TUid KUidNotifierPlugInV2 = {0x101fdfae};
1.32 +
1.33 +/**
1.34 +@publishedAll
1.35 +@released
1.36 +*/
1.37 +enum TEikNotExtStatus
1.38 + {
1.39 + EEikNotExtRequestCompleted = 0,
1.40 + EEikNotExtRequestQueued = 1
1.41 + };
1.42 +
1.43 +/** The Uid that identifies a screen change event.
1.44 +
1.45 +@see MEikSrvNotifierBase2::HandleSystemEventL()
1.46 +@internalTechnology */
1.47 +const TUid KUidEventScreenModeChanged = {0x101F3648};
1.48 +
1.49 +/** A set of flags that define the capabilities of the notifier.
1.50 +
1.51 +Capabilities are returned by calling MEikSrvNotifierBase2::NotifierCapabilites().
1.52 +
1.53 +@publishedAll
1.54 +@released */
1.55 +enum TNotifierCapabilities
1.56 + {
1.57 + /** The notifier has no special capabilities. */
1.58 + ENoSpecialCapabilities = 0x00000000,
1.59 + /** The notifier can handle a change to the screen device. */
1.60 + EScreenDeviceChangeSupported = 0x00000001,
1.61 + };
1.62 +
1.63 +/**
1.64 +Interface to allow notifiers to manage their own startup/shutdown. This class is likely to be of most
1.65 +interest to notifiers that observe engines using publically available APIs rather than those that are run
1.66 +via RNotifier.
1.67 +
1.68 +@publishedAll
1.69 +@released
1.70 +*/
1.71 +class MEikSrvNotifierManager
1.72 + {
1.73 +public:
1.74 + virtual void StartNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
1.75 + virtual void CancelNotifier(TUid aNotifierUid) = 0;
1.76 + virtual void UpdateNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
1.77 +protected:
1.78 + IMPORT_C MEikSrvNotifierManager();
1.79 +private:
1.80 + IMPORT_C virtual void MEikSrvNotifierManager_Reserved1();
1.81 + IMPORT_C virtual void MEikSrvNotifierManager_Reserved2();
1.82 +private:
1.83 + TInt iMEikSrvNotifierManager_Spare1;
1.84 + };
1.85 +
1.86 +
1.87 +/** Interface to a plug-in server side notifier.
1.88 +
1.89 +Any number of MEikSrvNotifierBase2 objects can be included in a single DLL.
1.90 +All notifiers are loaded during device startup and are not destroyed until
1.91 +the Uikon server closes down.
1.92 +
1.93 +All notifiers run in the uikon server thread so are able to directly access
1.94 +server side status panes but cannot call any functions on REikAppUiSession.
1.95 +
1.96 +@publishedAll
1.97 +@released */
1.98 +class MEikSrvNotifierBase2
1.99 + {
1.100 +public:
1.101 + /** Defines a set of notifier priorities. The use and application of these values
1.102 + is implementation-dependent. */
1.103 + enum TNotifierPriority
1.104 + {
1.105 + /** The highest priority value. */
1.106 + ENotifierPriorityAbsolute = 500,
1.107 + /** The second highest priority value. */
1.108 + ENotifierPriorityVHigh = 400,
1.109 + /** The third highest priority value. */
1.110 + ENotifierPriorityHigh = 300,
1.111 + /** The fourth highest priority value. */
1.112 + ENotifierPriorityLow = 200,
1.113 + /** The fifth highest priority value. */
1.114 + ENotifierPriorityVLow = 100,
1.115 + /** The lowest priority value. */
1.116 + ENotifierPriorityLowest = 0
1.117 + };
1.118 +public:
1.119 + /** Contains the notifier parameters.
1.120 +
1.121 + @see TNotifierPriority */
1.122 + class TNotifierInfo
1.123 + {
1.124 + public:
1.125 + /** The Uid that identifies the notifier. */
1.126 + TUid iUid;
1.127 + /** The Uid that identifies the channel to be used by the notifier (e.g. the screen,
1.128 + an LED etc) */
1.129 + TUid iChannel;
1.130 + /** The notifier priority, typically chosen from the standard set.
1.131 +
1.132 + @see TNotifierPriority */
1.133 + TInt iPriority;
1.134 + };
1.135 +
1.136 +public:
1.137 + IMPORT_C MEikSrvNotifierBase2();
1.138 + IMPORT_C virtual ~MEikSrvNotifierBase2();
1.139 +public:
1.140 + /** Frees all resources owned by this notifier.
1.141 +
1.142 + This function is called by the notifier framework when all resources allocated
1.143 + by notifiers should be freed. As a minimum, this function should delete this
1.144 + object (i.e. delete this;).
1.145 +
1.146 + Note that it is important to implement this function correctly to avoid memory
1.147 + leaks. */
1.148 + virtual void Release() = 0;
1.149 + /** Performs any initialisation that this notifier may require.
1.150 +
1.151 + The function is called when the notifier is loaded (when the plug-in DLL is
1.152 + loaded). It is called only once.
1.153 +
1.154 + As a minimum, the function should return a TNotifierInfo instance describing
1.155 + the notifier parameters. A good implementation would be to set this into a
1.156 + data member, and then to return it. This is because the same information is
1.157 + returned by Info().
1.158 +
1.159 + The function is safe to leave from, so it is possible, although rarely necessary,
1.160 + to allocate objects as you would normally do in a ConstructL() function as
1.161 + part of two-phase construction.
1.162 +
1.163 + @return Describes the parameters of the notifier. */
1.164 + virtual TNotifierInfo RegisterL() = 0;
1.165 + /** Gets the notifier parameters.
1.166 +
1.167 + This is usually the same information as returned by RegisterL() but can be
1.168 + varied at run time.
1.169 +
1.170 + @return Describes the parameters of the notifier. */
1.171 + virtual TNotifierInfo Info() const = 0;
1.172 + /** Starts the notifier.
1.173 +
1.174 + This is called as a result of a client-side call to RNotifier::StartNotifier(),
1.175 + which the client uses to start a notifier from which it does not expect a
1.176 + response.
1.177 +
1.178 + The function is synchronous, but it should be implemented so that it completes
1.179 + as soon as possible, allowing the notifier framework to enforce its priority
1.180 + mechanism.
1.181 +
1.182 + It is not possible to to wait for a notifier to complete before returning
1.183 + from this function unless the notifier is likely to finish implementing its
1.184 + functionality immediately.
1.185 +
1.186 + @param aBuffer Data that can be passed from the client-side. The format and
1.187 + meaning of any data is implementation dependent.
1.188 + @return A pointer descriptor representing data that may be returned. The format
1.189 + and meaning of any data is implementation dependent. */
1.190 + virtual TPtrC8 StartL(const TDesC8& aBuffer) = 0;
1.191 + /** Starts the notifier.
1.192 +
1.193 + This is called as a result of a client-side call to the asynchronous function
1.194 + RNotifier::StartNotifierAndGetResponse(). This means that the client is waiting,
1.195 + asynchronously, for the notifier to tell the client that it has finished its
1.196 + work.
1.197 +
1.198 + It is important to return from this function as soon as possible, and derived
1.199 + classes may find it useful to take a copy of the reply-slot number and
1.200 + the RMessage object.
1.201 +
1.202 + The implementation of a derived class must make sure that Complete() is called
1.203 + on the RMessage object when the notifier is deactivated.
1.204 +
1.205 + This function may be called multiple times if more than one client starts
1.206 + the notifier.
1.207 +
1.208 + @param aBuffer Data that can be passed from the client-side. The format and
1.209 + meaning of any data is implementation dependent.
1.210 + @param aReplySlot Identifies which message argument to use for the reply.
1.211 + This message argument will refer to a modifiable descriptor, a TDes8 type,
1.212 + into which data can be returned. The format and meaning of any returned data
1.213 + is implementation dependent.
1.214 + @param aMessage Encapsulates a client request. */
1.215 + virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage) = 0;
1.216 +
1.217 + /** Cancels an active notifier.
1.218 +
1.219 + This is called as a result of a client-side call to RNotifier::CancelNotifier().
1.220 +
1.221 + An implementation should free any relevant resources and complete any outstanding
1.222 + messages, if relevant. */
1.223 + virtual void Cancel() = 0;
1.224 + /** Updates a currently active notifier with new data.
1.225 +
1.226 + This is called as a result of a client-side call to RNotifier::UpdateNotifier().
1.227 +
1.228 + @param aBuffer Data that can be passed from the client-side. The format and
1.229 + meaning of any data is implementation dependent.
1.230 + @return A pointer descriptor representing data that may be returned. The format
1.231 + and meaning of any data is implementation dependent. */
1.232 + virtual TPtrC8 UpdateL(const TDesC8& aBuffer) = 0;
1.233 + /** Updates a currently active notifier with new data.
1.234 +
1.235 + This is called as a result of a client-side call to the asynchronous function
1.236 + RNotifier::UpdateNotifierAndGetResponse(). This means that the client is waiting,
1.237 + asynchronously, for the notifier to tell the client that it has finished its
1.238 + work.
1.239 +
1.240 + It is important to return from this function as soon as possible, and derived
1.241 + classes may find it useful to take a copy of the reply-slot number and
1.242 + the RMessage object.
1.243 +
1.244 + The implementation of a derived class must make sure that Complete() is called
1.245 + on the RMessage object when the notifier is deactivated.
1.246 +
1.247 + This function may be called multiple times if more than one client updates
1.248 + the notifier.
1.249 +
1.250 + @param aBuffer Data that can be passed from the client-side. The format and
1.251 + meaning of any data is implementation dependent.
1.252 + @param aReplySlot Identifies which message argument to use for the reply.
1.253 + This message argument will refer to a modifiable descriptor, a TDes8 type,
1.254 + into which data can be returned. The format and meaning of any returned data
1.255 + is implementation dependent.
1.256 + @param aMessage Encapsulates a client request. */
1.257 + IMPORT_C virtual void UpdateL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
1.258 +public:
1.259 + void SetManager(MEikSrvNotifierManager* aManager);
1.260 +protected:
1.261 + MEikSrvNotifierManager* iManager;
1.262 +private:
1.263 + IMPORT_C virtual void MEikSrvNotifierBase2_Reserved_2();
1.264 +public: // internal
1.265 + IMPORT_C virtual void HandleSystemEventL(TUid aEvent);
1.266 + IMPORT_C virtual TInt NotifierCapabilites();
1.267 +private:
1.268 + TInt iNotBSpare;
1.269 + TInt iMEikSrvNotifierBase2_Spare;
1.270 + };
1.271 +
1.272 +
1.273 +#endif // __EIKNOTAPI_H__