|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 |
|
17 |
|
18 #ifndef C32COMM_H |
|
19 #define C32COMM_H |
|
20 |
|
21 /** @file |
|
22 |
|
23 C32 header file to be included by the clients. |
|
24 Defines the main interface to C32, RCommServ and RComm |
|
25 */ |
|
26 |
|
27 #include <e32base.h> |
|
28 #include <d32comm.h> |
|
29 |
|
30 /** |
|
31 @publishedAll |
|
32 @released |
|
33 */ |
|
34 IMPORT_C TInt StartC32(); |
|
35 IMPORT_C TInt StartC32WithCMISuppressions(const TDesC& aCMISuppressionList); |
|
36 |
|
37 |
|
38 /** Specifies the mode in which a port is opened. |
|
39 |
|
40 We specify the mode when it is opened, and the mode cannot thereafter be |
|
41 changed. If we open the port in Shared mode, other clients of the comms |
|
42 server can use the same port while we have it open. If we open the port |
|
43 in Exclusive mode, then it is locked for our own use and any attempt to |
|
44 access it from another process will fail. Furthermore, our own attempt |
|
45 to open a port in exclusive mode will fail if another process has already |
|
46 opened the port in shared mode. |
|
47 |
|
48 Infra-red ports using IRCOMM.CSY can be opened in either shared or exclusive |
|
49 mode. However they SHOULD only be opened in Exclusive mode, since opening |
|
50 them any other way warm-boots the computer. |
|
51 |
|
52 @publishedAll |
|
53 @released |
|
54 */ |
|
55 enum TCommAccess |
|
56 { |
|
57 /** Once open, the port cannot be used by any other RComm clients. An attempt to |
|
58 open a port in exclusive mode will fail if another process has already opened |
|
59 the port in shared mode. */ |
|
60 ECommExclusive, |
|
61 /** The port can be shared by other RComm clients who open in the same mode. */ |
|
62 ECommShared, |
|
63 /** Allows another client to pre-empt the session with an open request in one of |
|
64 the other two modes. The port will be lost if other clients are trying to open it.*/ |
|
65 ECommPreemptable |
|
66 }; |
|
67 /** |
|
68 Use full buffering. Used by RComm::SetMode(). |
|
69 |
|
70 @publishedAll |
|
71 @released |
|
72 */ |
|
73 const TUint KCommBufferFull = 0x0000; |
|
74 /** |
|
75 Use partial buffering. Used by RComm::SetMode(). |
|
76 |
|
77 @publishedAll |
|
78 @released |
|
79 */ |
|
80 const TUint KCommBufferPartial = 0x0001; |
|
81 |
|
82 |
|
83 /** |
|
84 trace flags for debugging purposes |
|
85 @publishedAll |
|
86 */ |
|
87 enum TC32Trace |
|
88 { |
|
89 ETraceC32Startup = 0x00000001, |
|
90 ETraceC32Panic = 0x00000002, |
|
91 ETraceC32Request = 0x00000004, |
|
92 ETraceC32IPC = 0x00000008, |
|
93 ETraceC32All = 0xFFFFFFFF, |
|
94 }; |
|
95 |
|
96 /** |
|
97 Used by the package TCommServerConfig to configure the comm port. |
|
98 |
|
99 Holds the buffer configuration settings for the comms server. |
|
100 |
|
101 The comms server copies data between the descriptors provided by the client |
|
102 and the buffers used by the serial port drivers, for each read and write request. |
|
103 There are two methods by which this can be accomplished. Full buffering means |
|
104 that the comms server will always attempt to allocate enough memory to satisfy |
|
105 any reads or writes in a single copy, while partial buffering means that the |
|
106 comms server will allocate a static buffer and use partial copies to transfer |
|
107 data to the serial driver. When a port is opened, the default is full buffering. |
|
108 |
|
109 @publishedAll |
|
110 @released |
|
111 */ |
|
112 struct TCommServerConfigV01 |
|
113 { |
|
114 /** Buffering option: either KCommBufferFull or KCommBufferPartial */ |
|
115 TUint iBufFlags; //< contains buffer flags e.g for partial read/write |
|
116 /** Size of server buffer if partial buffering is being used */ |
|
117 TUint iBufSize; //< size of the Tx/Rx buffer |
|
118 }; |
|
119 |
|
120 /** Package buffer for a server configuration object. TCommServerConfig is used |
|
121 as an argument to RComm::Mode() and RComm::SetMode(). |
|
122 |
|
123 @publishedAll |
|
124 @released |
|
125 */ |
|
126 typedef TPckgBuf<TCommServerConfigV01> TCommServerConfig; |
|
127 |
|
128 /** Maximum length of port full name, TPortDescription (48 characters). |
|
129 |
|
130 @publishedAll |
|
131 @released |
|
132 */ |
|
133 const TInt KMaxPortDescription = 0x30; |
|
134 /** Maximum length of the Port Prefix format name, as used by TPortName (16 characters). |
|
135 |
|
136 @publishedAll |
|
137 @released |
|
138 */ |
|
139 const TInt KMaxPortName = 0x10; |
|
140 |
|
141 /** Reset the receive buffer |
|
142 |
|
143 @publishedAll |
|
144 @released |
|
145 */ |
|
146 const TUint KCommResetRx = 0x00000001; //< to by used as flag by RComm::ResetBuffers |
|
147 /** Reset the transmit buffer |
|
148 |
|
149 @publishedAll |
|
150 @released |
|
151 */ |
|
152 const TUint KCommResetTx = 0x00000002; //< to by used as flag by RComm::ResetBuffers |
|
153 /** Port name. Used by TSerialInfo::iName. |
|
154 |
|
155 @publishedAll |
|
156 @released |
|
157 */ |
|
158 typedef TBuf<KMaxPortName> TPortName; |
|
159 /** Full port name/description. Used by TSerialInfo::iDescription. |
|
160 |
|
161 @publishedAll |
|
162 @released |
|
163 */ |
|
164 typedef TBuf<KMaxPortDescription> TPortDescription; |
|
165 |
|
166 |
|
167 class TSerialInfo |
|
168 /** Describes a serial protocol's general capabilities. |
|
169 |
|
170 Used by RCommServ::GetPortInfo to retrieve information |
|
171 about the comm ports and the CSY. |
|
172 |
|
173 Notes: |
|
174 |
|
175 1. The lowest port need not necessarily be numbered zero. |
|
176 |
|
177 2. At least one port is always guaranteed. |
|
178 |
|
179 3. The full name of the serial port (used when opening it) consists of the name |
|
180 returned by TSerialInfo (the Port Prefix), followed by a double colon separator, followed by |
|
181 the unit number (port number) as an ASCII number (for instance COMM::0). |
|
182 |
|
183 @publishedAll |
|
184 @released |
|
185 */ |
|
186 { |
|
187 public: |
|
188 /** Description of the CSY meant only for human reading. It |
|
189 can be up to KMaxPortDescription (48) characters long. */ |
|
190 TPortDescription iDescription; //< description of the port (CSY) |
|
191 /** The short name of the port (Port Prefix). This is used in calls to RComm::Open(). It can be up to |
|
192 KMaxPortName (i.e. 16) characters long. */ |
|
193 TPortName iName; //< name of the port |
|
194 TUint iLowUnit; //< The lowest port number supported by the serial module |
|
195 TUint iHighUnit; //< the highest port number supported by the serial module |
|
196 }; |
|
197 |
|
198 /** |
|
199 Specifies the DTE/DCE role in which a port is opened. |
|
200 |
|
201 @see RComm::Open() |
|
202 @publishedAll |
|
203 @released |
|
204 */ |
|
205 enum TCommRole |
|
206 { |
|
207 /** Port takes on role of DTE. (DTE=computer). |
|
208 This is the default. |
|
209 */ |
|
210 ECommRoleDTE, |
|
211 /** Port takes on role of DCE. (DCE=modem). |
|
212 */ |
|
213 ECommRoleDCE |
|
214 }; |
|
215 |
|
216 class RComm; |
|
217 |
|
218 |
|
219 class RCommServ : public RSessionBase |
|
220 /** Represents a session with the serial comms server. |
|
221 Functions are provided for connection |
|
222 to the server and for loading and unloading different comms modules, and services |
|
223 for finding out the name and numbers of the available ports. |
|
224 |
|
225 Sessions with the serial comms server are not shareable. |
|
226 |
|
227 Comms modules are also known as "CSY"s due to their ".CSY" extension, |
|
228 derived from the term "Comms SYstem". |
|
229 |
|
230 This class is not intended for user derivation. |
|
231 |
|
232 @publishedAll |
|
233 @released */ |
|
234 { |
|
235 public: |
|
236 IMPORT_C RCommServ(); |
|
237 IMPORT_C TInt Connect(); |
|
238 IMPORT_C TVersion Version() const; |
|
239 |
|
240 IMPORT_C TInt LoadCommModule(const TDesC& aFileName); |
|
241 IMPORT_C TInt UnloadCommModule(const TDesC& aName); |
|
242 IMPORT_C TInt NumPorts(TInt& aNum); |
|
243 IMPORT_C TInt GetPortInfo(const TDesC& aName, TSerialInfo& aInfo); |
|
244 IMPORT_C TInt GetPortInfo(TInt aIndex, TDes& aModuleName, TSerialInfo& aInfo); |
|
245 |
|
246 IMPORT_C TInt __DbgMarkHeap(); |
|
247 IMPORT_C TInt __DbgCheckHeap(TInt aCount); |
|
248 IMPORT_C TInt __DbgMarkEnd(TInt aCount); |
|
249 IMPORT_C TInt __DbgFailNext(TInt aCount); |
|
250 IMPORT_C TInt __DbgSetTraceMask(TC32Trace aMask); |
|
251 |
|
252 IMPORT_C static TInt CreateThreadInCommProc(const TDesC& aLibraryName, const TDesC& aThreadName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize); |
|
253 private: |
|
254 static TBool IsServerThreadL(); |
|
255 }; |
|
256 // |
|
257 |
|
258 struct TCommDebugInfo; // defined in d32comm.h |
|
259 |
|
260 |
|
261 class RComm : public RSubSessionBase |
|
262 /** A sub-session to the C32 Serial Server used for addressing a serial port. |
|
263 |
|
264 All the necessary functions are provided by this class for communicating via |
|
265 a port, including functions for opening, closing, reading, writing, |
|
266 port configuration and capability checking. An RComm session represents |
|
267 a single serial port and once opened cannot be altered to represent another port. |
|
268 |
|
269 Ports are referenced by a character string whose format is referred to as Port Prefix format. |
|
270 This format is also known as the CSY internal name, and the ports "short" name in older releases. |
|
271 |
|
272 @publishedAll |
|
273 @released |
|
274 */ |
|
275 { |
|
276 public: |
|
277 IMPORT_C RComm(); |
|
278 IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode); |
|
279 IMPORT_C TInt Open(RCommServ& aServer, const TDesC& aName, TCommAccess aMode, TCommRole aRole); |
|
280 IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName); |
|
281 IMPORT_C void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ& aServer, const TDesC& aName, TCommRole aRole); |
|
282 IMPORT_C void OpenWhenAvailableCancel(); |
|
283 IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes); |
|
284 IMPORT_C void Read(TRequestStatus& aStatus, TDes8& aDes, TInt aLength); |
|
285 IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes); |
|
286 IMPORT_C void Read(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8& aDes, TInt aLength); |
|
287 IMPORT_C void ReadOneOrMore(TRequestStatus& aStatus, TDes8& aDes); |
|
288 IMPORT_C TInt ReadCancel(); |
|
289 IMPORT_C TInt QueryReceiveBuffer() const; |
|
290 IMPORT_C TInt ResetBuffers(TUint aFlags=(KCommResetRx|KCommResetTx)); |
|
291 IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes); |
|
292 IMPORT_C void Write(TRequestStatus& aStatus, const TDesC8& aDes, TInt aLength); |
|
293 IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes); |
|
294 IMPORT_C void Write(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8& aDes, TInt aLength); |
|
295 IMPORT_C TInt WriteCancel(); |
|
296 IMPORT_C void Break(TRequestStatus& aStatus, TTimeIntervalMicroSeconds32 aTime); |
|
297 IMPORT_C TInt BreakCancel(); |
|
298 IMPORT_C TInt Cancel(); |
|
299 IMPORT_C TInt Config(TDes8& aConfig) const; |
|
300 IMPORT_C TInt SetConfig(const TDesC8& aConfig); |
|
301 IMPORT_C TInt Caps(TDes8& aCaps) const; |
|
302 IMPORT_C TInt SetMode(const TCommServerConfig& aConfig); |
|
303 IMPORT_C TInt Mode(TCommServerConfig& aConfig) const; |
|
304 IMPORT_C TUint Signals(TUint aSignalMask = 0x3F) const; |
|
305 IMPORT_C TInt SetSignalsToMark(TUint aSignalMask); |
|
306 IMPORT_C TInt SetSignalsToSpace(TUint aSignalMask); |
|
307 IMPORT_C TInt ReceiveBufferLength() const; |
|
308 IMPORT_C TInt SetReceiveBufferLength(TInt aLength); |
|
309 IMPORT_C void Close(); |
|
310 inline void SetSignals(TUint aSetMask, TUint aClearMask); |
|
311 IMPORT_C void NotifySignalChange(TRequestStatus& aStatus, TUint& aSignals, TUint aSignalMask=0x3F); |
|
312 IMPORT_C TInt NotifySignalChangeCancel() const; |
|
313 IMPORT_C void NotifyConfigChange(TRequestStatus& aStatus, TDes8& aNewConfig) const; |
|
314 IMPORT_C TInt NotifyConfigChangeCancel() const; |
|
315 IMPORT_C void NotifyFlowControlChange(TRequestStatus& aStatus, TFlowControl& aFlowControl); |
|
316 IMPORT_C TInt NotifyFlowControlChangeCancel() const; |
|
317 IMPORT_C void NotifyBreak(TRequestStatus& aStatus) const; |
|
318 IMPORT_C TInt NotifyBreakCancel() const; |
|
319 IMPORT_C void NotifyDataAvailable(TRequestStatus& aStatus) const; |
|
320 IMPORT_C TInt NotifyDataAvailableCancel() const; |
|
321 IMPORT_C void NotifyOutputEmpty(TRequestStatus& aStatus) const; |
|
322 IMPORT_C TInt NotifyOutputEmptyCancel() const; |
|
323 IMPORT_C TInt GetFlowControlStatus(TFlowControl& aFlowControl) const; |
|
324 IMPORT_C TInt GetRole(TCommRole& aRole) const; |
|
325 |
|
326 IMPORT_C TInt SetAccessMode(TCommAccess aNewMode); |
|
327 IMPORT_C TInt DebugState(TCommDebugInfo&); |
|
328 |
|
329 #ifdef _DEBUG_DEVCOMM |
|
330 IMPORT_C TInt RComm::DebugInfo(TDes8& aDes); |
|
331 #endif |
|
332 private: |
|
333 TPtr8 iSignalsNotification; //< pointer to the signals to be changed during notification |
|
334 TPtr8 iFlowNotification; //< pointer to the flow control to be changed during notification |
|
335 }; |
|
336 |
|
337 |
|
338 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
339 #include <c32comm_internal.h> |
|
340 #endif |
|
341 |
|
342 #include <c32comm.inl> |
|
343 |
|
344 #endif // C32COMM_H |