1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __EIKNOTAPI_H__
17 #define __EIKNOTAPI_H__
23 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
24 #include <uikon/eikscchange.h>
27 /** Defines the second Uid value for plug in notifier DLLs.
31 const TUid KUidNotifierPlugIn = {0x10005522};
32 const TUid KUidNotifierPlugInV2 = {0x101fdfae};
40 EEikNotExtRequestCompleted = 0,
41 EEikNotExtRequestQueued = 1
44 /** A set of flags that define the capabilities of the notifier.
46 Capabilities are returned by calling MEikSrvNotifierBase2::NotifierCapabilites().
50 enum TNotifierCapabilities
52 /** The notifier has no special capabilities. */
53 ENoSpecialCapabilities = 0x00000000,
54 /** The notifier can handle a change to the screen device. */
55 EScreenDeviceChangeSupported = 0x00000001,
59 Interface to allow notifiers to manage their own startup/shutdown. This class is likely to be of most
60 interest to notifiers that observe engines using publically available APIs rather than those that are run
66 class MEikSrvNotifierManager
69 virtual void StartNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
70 virtual void CancelNotifier(TUid aNotifierUid) = 0;
71 virtual void UpdateNotifierL(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse) = 0;
73 IMPORT_C MEikSrvNotifierManager();
75 IMPORT_C virtual void MEikSrvNotifierManager_Reserved1();
76 IMPORT_C virtual void MEikSrvNotifierManager_Reserved2();
78 TInt iMEikSrvNotifierManager_Spare1;
82 /** Interface to a plug-in server side notifier.
84 Any number of MEikSrvNotifierBase2 objects can be included in a single DLL.
85 All notifiers are loaded during device startup and are not destroyed until
86 the Uikon server closes down.
88 All notifiers run in the uikon server thread so are able to directly access
89 server side status panes but cannot call any functions on REikAppUiSession.
93 class MEikSrvNotifierBase2
96 /** Defines a set of notifier priorities. The use and application of these values
97 is implementation-dependent. */
98 enum TNotifierPriority
100 /** The highest priority value. */
101 ENotifierPriorityAbsolute = 500,
102 /** The second highest priority value. */
103 ENotifierPriorityVHigh = 400,
104 /** The third highest priority value. */
105 ENotifierPriorityHigh = 300,
106 /** The fourth highest priority value. */
107 ENotifierPriorityLow = 200,
108 /** The fifth highest priority value. */
109 ENotifierPriorityVLow = 100,
110 /** The lowest priority value. */
111 ENotifierPriorityLowest = 0
114 /** Contains the notifier parameters.
116 @see TNotifierPriority */
120 /** The Uid that identifies the notifier. */
122 /** The Uid that identifies the channel to be used by the notifier (e.g. the screen,
125 /** The notifier priority, typically chosen from the standard set.
127 @see TNotifierPriority */
132 IMPORT_C MEikSrvNotifierBase2();
133 IMPORT_C virtual ~MEikSrvNotifierBase2();
135 /** Frees all resources owned by this notifier.
137 This function is called by the notifier framework when all resources allocated
138 by notifiers should be freed. As a minimum, this function should delete this
139 object (i.e. delete this;).
141 Note that it is important to implement this function correctly to avoid memory
143 virtual void Release() = 0;
144 /** Performs any initialisation that this notifier may require.
146 The function is called when the notifier is loaded (when the plug-in DLL is
147 loaded). It is called only once.
149 As a minimum, the function should return a TNotifierInfo instance describing
150 the notifier parameters. A good implementation would be to set this into a
151 data member, and then to return it. This is because the same information is
154 The function is safe to leave from, so it is possible, although rarely necessary,
155 to allocate objects as you would normally do in a ConstructL() function as
156 part of two-phase construction.
158 @return Describes the parameters of the notifier. */
159 virtual TNotifierInfo RegisterL() = 0;
160 /** Gets the notifier parameters.
162 This is usually the same information as returned by RegisterL() but can be
165 @return Describes the parameters of the notifier. */
166 virtual TNotifierInfo Info() const = 0;
167 /** Starts the notifier.
169 This is called as a result of a client-side call to RNotifier::StartNotifier(),
170 which the client uses to start a notifier from which it does not expect a
173 The function is synchronous, but it should be implemented so that it completes
174 as soon as possible, allowing the notifier framework to enforce its priority
177 It is not possible to to wait for a notifier to complete before returning
178 from this function unless the notifier is likely to finish implementing its
179 functionality immediately.
181 @param aBuffer Data that can be passed from the client-side. The format and
182 meaning of any data is implementation dependent.
183 @return A pointer descriptor representing data that may be returned. The format
184 and meaning of any data is implementation dependent. */
185 virtual TPtrC8 StartL(const TDesC8& aBuffer) = 0;
186 /** Starts the notifier.
188 This is called as a result of a client-side call to the asynchronous function
189 RNotifier::StartNotifierAndGetResponse(). This means that the client is waiting,
190 asynchronously, for the notifier to tell the client that it has finished its
193 It is important to return from this function as soon as possible, and derived
194 classes may find it useful to take a copy of the reply-slot number and
197 The implementation of a derived class must make sure that Complete() is called
198 on the RMessage object when the notifier is deactivated.
200 This function may be called multiple times if more than one client starts
203 @param aBuffer Data that can be passed from the client-side. The format and
204 meaning of any data is implementation dependent.
205 @param aReplySlot Identifies which message argument to use for the reply.
206 This message argument will refer to a modifiable descriptor, a TDes8 type,
207 into which data can be returned. The format and meaning of any returned data
208 is implementation dependent.
209 @param aMessage Encapsulates a client request. */
210 virtual void StartL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage) = 0;
212 /** Cancels an active notifier.
214 This is called as a result of a client-side call to RNotifier::CancelNotifier().
216 An implementation should free any relevant resources and complete any outstanding
217 messages, if relevant. */
218 virtual void Cancel() = 0;
219 /** Updates a currently active notifier with new data.
221 This is called as a result of a client-side call to RNotifier::UpdateNotifier().
223 @param aBuffer Data that can be passed from the client-side. The format and
224 meaning of any data is implementation dependent.
225 @return A pointer descriptor representing data that may be returned. The format
226 and meaning of any data is implementation dependent. */
227 virtual TPtrC8 UpdateL(const TDesC8& aBuffer) = 0;
228 /** Updates a currently active notifier with new data.
230 This is called as a result of a client-side call to the asynchronous function
231 RNotifier::UpdateNotifierAndGetResponse(). This means that the client is waiting,
232 asynchronously, for the notifier to tell the client that it has finished its
235 It is important to return from this function as soon as possible, and derived
236 classes may find it useful to take a copy of the reply-slot number and
239 The implementation of a derived class must make sure that Complete() is called
240 on the RMessage object when the notifier is deactivated.
242 This function may be called multiple times if more than one client updates
245 @param aBuffer Data that can be passed from the client-side. The format and
246 meaning of any data is implementation dependent.
247 @param aReplySlot Identifies which message argument to use for the reply.
248 This message argument will refer to a modifiable descriptor, a TDes8 type,
249 into which data can be returned. The format and meaning of any returned data
250 is implementation dependent.
251 @param aMessage Encapsulates a client request. */
252 IMPORT_C virtual void UpdateL(const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage);
254 void SetManager(MEikSrvNotifierManager* aManager);
256 MEikSrvNotifierManager* iManager;
258 IMPORT_C virtual void MEikSrvNotifierBase2_Reserved_2();
260 IMPORT_C virtual void HandleSystemEventL(TUid aEvent);
261 IMPORT_C virtual TInt NotifierCapabilites();
264 TInt iMEikSrvNotifierBase2_Spare;
268 #endif // __EIKNOTAPI_H__