|
1 // Copyright (c) 2005-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 the License "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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // in its implementation. |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file The interface to an example data converter device driver which uses Shared Chunks |
|
20 @publishedPartner |
|
21 @prototype 9.1 |
|
22 */ |
|
23 |
|
24 #ifndef __CONVERT1_H__ |
|
25 #define __CONVERT1_H__ |
|
26 |
|
27 #include <e32cmn.h> |
|
28 #include <e32ver.h> |
|
29 #ifndef __KERNEL_MODE__ |
|
30 #include <e32std.h> |
|
31 #endif |
|
32 |
|
33 /** |
|
34 User interface for 'Convert1' |
|
35 */ |
|
36 class RConvert1 : public RBusLogicalChannel |
|
37 { |
|
38 public: |
|
39 /** |
|
40 Structure for holding driver capabilities information |
|
41 */ |
|
42 class TCaps |
|
43 { |
|
44 public: |
|
45 TVersion iVersion; |
|
46 TInt iMaxChannels; /**< Maximum number of simultaneous channels supported by driver */ |
|
47 }; |
|
48 |
|
49 /** |
|
50 Structure for holding driver configuration data |
|
51 */ |
|
52 class TConfig |
|
53 { |
|
54 public: |
|
55 TInt iBufferSize; /**< Size of convert buffer */ |
|
56 TBool iCreateInputChunk; /**< True if driver is to create an input chunk */ |
|
57 TInt iSpeed; /**< Speed of converter in bytes/second (for this example test) */ |
|
58 }; |
|
59 typedef TPckgBuf<TConfig> TConfigBuf; |
|
60 |
|
61 #ifndef __KERNEL_MODE__ |
|
62 public: |
|
63 RConvert1(); |
|
64 TInt Open(); |
|
65 void Close(); |
|
66 TInt GetConfig(TConfigBuf& aConfig); |
|
67 TInt SetConfig(const TConfigBuf& aConfig); |
|
68 void Convert(const TDesC8& aInput,TRequestStatus& aStatus); |
|
69 void Convert(RChunk aInputChunk,TInt aInputOffset,TInt aInputSize,TRequestStatus& aStatus); |
|
70 void Convert(TInt aSize,TRequestStatus& aStatus); |
|
71 inline RChunk OutChunk() const; |
|
72 inline RChunk InChunk(); |
|
73 inline TPtr8 InBuffer(); |
|
74 private: |
|
75 /** |
|
76 Hide the Duplicate() method by making it private. |
|
77 The purpose of hiding the method is to prevent it's use because this object also contains |
|
78 chunk handles which would need special consideration. |
|
79 We don't want to bother supporting Duplicate() for this particular driver because |
|
80 it only supports a single client thread so normal use wouldn't require Duplicate(). |
|
81 */ |
|
82 TInt Duplicate(const RThread& aSrc,TOwnerType aType=EOwnerProcess); |
|
83 #endif |
|
84 |
|
85 public: |
|
86 inline static const TDesC& Name(); |
|
87 inline static TVersion VersionRequired(); |
|
88 private: |
|
89 /** |
|
90 Enumeration of Control messages. |
|
91 */ |
|
92 enum TControl |
|
93 { |
|
94 EGetConfig, |
|
95 ESetConfig, |
|
96 EConvertDes, |
|
97 EConvertChunk, |
|
98 EConvertInChunk, |
|
99 }; |
|
100 |
|
101 /** |
|
102 Enumeration of Request messages. |
|
103 (None used in this example) |
|
104 */ |
|
105 enum TRequest |
|
106 { |
|
107 ENumRequests, |
|
108 EAllRequests = (1<<ENumRequests)-1 |
|
109 }; |
|
110 |
|
111 /** |
|
112 Structure used to package arguments for a EConvertChunk control message |
|
113 */ |
|
114 struct TConvertArgs |
|
115 { |
|
116 TInt iChunkHandle; |
|
117 TInt iOffset; |
|
118 TInt iSize; |
|
119 }; |
|
120 |
|
121 /** |
|
122 Structure representing input and output buffers |
|
123 */ |
|
124 struct TBufferInfo |
|
125 { |
|
126 TInt iOutChunkHandle; /**< Handle to Shared Chunk used to hold output data */ |
|
127 TInt iInChunkHandle; /**< Handle to Shared Chunk used to hold input data */ |
|
128 TInt iInBufferOffset; /**< Offset within input chunk where the input buffer actually starts */ |
|
129 TUint8* iInBufferPtr; /**< Calculated address for start of input buffer within client process */ |
|
130 TInt iInBufferSize; /**< Size of input buffer in bytes */ |
|
131 }; |
|
132 |
|
133 TBufferInfo iBufferInfo; |
|
134 |
|
135 // Kernel side LDD channel is a friend |
|
136 friend class DConvert1Channel; |
|
137 }; |
|
138 |
|
139 /** |
|
140 The driver's name |
|
141 |
|
142 @return The name of the driver |
|
143 |
|
144 @internalComponent |
|
145 */ |
|
146 inline const TDesC& RConvert1::Name() |
|
147 { |
|
148 _LIT(KConvert1Name,"CONVERT1"); |
|
149 return KConvert1Name; |
|
150 } |
|
151 |
|
152 /** |
|
153 The driver's version |
|
154 |
|
155 @return The version number of the driver |
|
156 |
|
157 @internalComponent |
|
158 */ |
|
159 inline TVersion RConvert1::VersionRequired() |
|
160 { |
|
161 const TInt KMajorVersionNumber=1; |
|
162 const TInt KMinorVersionNumber=0; |
|
163 const TInt KBuildVersionNumber=KE32BuildVersionNumber; |
|
164 return TVersion(KMajorVersionNumber,KMinorVersionNumber,KBuildVersionNumber); |
|
165 } |
|
166 |
|
167 /* |
|
168 NOTE: The following methods would normally be exported from a seperate client DLL |
|
169 but are included inline in this header file for convenience. |
|
170 */ |
|
171 |
|
172 #ifndef __KERNEL_MODE__ |
|
173 |
|
174 /** |
|
175 Constructor to clear member data |
|
176 */ |
|
177 RConvert1::RConvert1() |
|
178 { |
|
179 memclr(&iBufferInfo,sizeof(iBufferInfo)); |
|
180 } |
|
181 |
|
182 /** |
|
183 Open a logical channel to the driver. |
|
184 The opened channel may only be used by the calling trhead. |
|
185 |
|
186 @return One of the system wide error codes. |
|
187 */ |
|
188 TInt RConvert1::Open() |
|
189 { |
|
190 return DoCreate(Name(),VersionRequired(),KNullUnit,NULL,NULL,EOwnerThread); |
|
191 } |
|
192 |
|
193 /** |
|
194 Close a logical channel to the driver |
|
195 */ |
|
196 void RConvert1::Close() |
|
197 { |
|
198 OutChunk().Close(); |
|
199 InChunk().Close(); |
|
200 RBusLogicalChannel::Close(); |
|
201 } |
|
202 |
|
203 /** |
|
204 Get the current configuration settings. |
|
205 |
|
206 @param aConfig A structure which will be filled with the configuration settings. |
|
207 |
|
208 @return KErrNone |
|
209 */ |
|
210 TInt RConvert1::GetConfig(TConfigBuf& aConfig) |
|
211 { |
|
212 return DoControl(EGetConfig,(TAny*)&aConfig); |
|
213 } |
|
214 |
|
215 /** |
|
216 Set the current configuration settings. |
|
217 |
|
218 @param aConfig The new configuration settings to be used. |
|
219 |
|
220 @return KErrInUse if data convertion is already in progress |
|
221 KErrArgument if any configuration values are invalid. |
|
222 KErrNone otherwise |
|
223 |
|
224 @post On success, new memory buffers will have been created and mapped into client process. |
|
225 */ |
|
226 TInt RConvert1::SetConfig(const TConfigBuf& aConfig) |
|
227 { |
|
228 OutChunk().Close(); |
|
229 InChunk().Close(); |
|
230 TInt r = DoControl(ESetConfig,(TAny*)&aConfig,&iBufferInfo); |
|
231 if(r!=KErrNone) |
|
232 return r; |
|
233 // Sett address of input |
|
234 if(InChunk().Handle()) |
|
235 iBufferInfo.iInBufferPtr = InChunk().Base()+iBufferInfo.iInBufferOffset; |
|
236 return r; |
|
237 } |
|
238 |
|
239 /** |
|
240 Convert data in the specified descriptor. |
|
241 |
|
242 @param aInput A descriptor containing the data to be converted |
|
243 @param aStatus The request status signaled when convertion is complete (or on error). |
|
244 The result value is the offset within OutChunk() where the coverted output |
|
245 data resides; or set to one of the system wide error codes when an error |
|
246 occurs: |
|
247 |
|
248 @pre The driver must have been previousely initialised by a call to SetConfig() |
|
249 */ |
|
250 void RConvert1::Convert(const TDesC8& aInput,TRequestStatus& aStatus) |
|
251 { |
|
252 DoControl(EConvertDes,(TAny*)&aInput,&aStatus); |
|
253 } |
|
254 |
|
255 /** |
|
256 Convert data in the specified chunk. |
|
257 |
|
258 @param aInputChunk The chunk containing the data to be converted |
|
259 @param aInputOffset Offset from start of chunk for the start of data to be converted. |
|
260 @param aInputSize Number of bytes of data to be converted. |
|
261 @param aStatus The request status signaled when convertion is complete (or on error). |
|
262 The result value is the offset within OutChunk() where the coverted output |
|
263 data resides; or set to one of the system wide error codes when an error |
|
264 occurs: |
|
265 |
|
266 @pre The driver must have been previousely initialised by a call to SetConfig() |
|
267 */ |
|
268 void RConvert1::Convert(RChunk aInputChunk,TInt aInputOffset,TInt aInputSize,TRequestStatus& aStatus) |
|
269 { |
|
270 TConvertArgs args; |
|
271 args.iChunkHandle = aInputChunk.Handle(); |
|
272 args.iOffset = aInputOffset; |
|
273 args.iSize = aInputSize; |
|
274 DoControl(EConvertChunk,(TAny*)&args,(TAny*)&aStatus); |
|
275 } |
|
276 |
|
277 /** |
|
278 Convert data in the input chunk. I.e. placed in InBuffer(). |
|
279 |
|
280 @param aSize Number of bytes of data to be converted. |
|
281 @param aStatus The request status signaled when convertion is complete (or on error). |
|
282 The result value is the offset within OutChunk() where the coverted output |
|
283 data resides; or set to one of the system wide error codes when an error |
|
284 occurs: |
|
285 |
|
286 @pre The driver must have been previousely initialised by a call to SetConfig() |
|
287 */ |
|
288 void RConvert1::Convert(TInt aSize,TRequestStatus& aStatus) |
|
289 { |
|
290 DoControl(EConvertInChunk,(TAny*)aSize,(TAny*)&aStatus); |
|
291 } |
|
292 |
|
293 /** |
|
294 Obtain the chunk into which converted data will be placed. |
|
295 This chunk may change after calls to SetConfig(). |
|
296 |
|
297 @return The chunk |
|
298 |
|
299 @pre The driver must have been configured using SetConfig() |
|
300 with TConfig::iCreateInputChunk set true. |
|
301 */ |
|
302 inline RChunk RConvert1::InChunk() |
|
303 { |
|
304 return RChunk((RChunk&)iBufferInfo.iInChunkHandle); |
|
305 } |
|
306 |
|
307 /** |
|
308 Obtain the chunk into which converted data will be placed. |
|
309 This chunk may change after calls to SetConfig(). |
|
310 |
|
311 @return The chunk |
|
312 |
|
313 @pre The driver must have been configured using SetConfig() |
|
314 */ |
|
315 inline RChunk RConvert1::OutChunk() const |
|
316 { |
|
317 return RChunk((RChunk&)iBufferInfo.iOutChunkHandle); |
|
318 } |
|
319 |
|
320 /** |
|
321 Get a pointer descriptor for the input buffer. |
|
322 |
|
323 @return A pointer descriptor to the input buffer memory. |
|
324 |
|
325 @pre The driver must have been configured using SetConfig() |
|
326 with TConfig::iCreateInputChunk set true. |
|
327 */ |
|
328 inline TPtr8 RConvert1::InBuffer() |
|
329 { |
|
330 return TPtr8(iBufferInfo.iInBufferPtr,iBufferInfo.iInBufferSize); |
|
331 } |
|
332 |
|
333 #endif // !__KERNEL_MODE__ |
|
334 |
|
335 #endif |
|
336 |