|
1 |
|
2 /** |
|
3 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 * All rights reserved. |
|
5 * This component and the accompanying materials are made available |
|
6 * under the terms of "Eclipse Public License v1.0" |
|
7 * which accompanies this distribution, and is available |
|
8 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
9 * |
|
10 * Initial Contributors: |
|
11 * Nokia Corporation - initial contribution. |
|
12 * |
|
13 * Contributors: |
|
14 * |
|
15 * Description: |
|
16 * Baseband Channel Adaptor(BCA) APIs. |
|
17 * This file contains all the APIs required to implement a BCA interface for Symbian OS. |
|
18 * |
|
19 * |
|
20 */ |
|
21 |
|
22 |
|
23 |
|
24 /** |
|
25 @file |
|
26 @publishedPartner |
|
27 @prototype |
|
28 @released |
|
29 */ |
|
30 #ifndef BCA2_H |
|
31 #define BCA2_H |
|
32 |
|
33 /** This namespace includes the BCA component names.*/ |
|
34 namespace BasebandChannelAdaptation2 |
|
35 { |
|
36 /** |
|
37 * The class implemented by an upper component to accept control signals from the lower component |
|
38 |
|
39 * @publishedPartner |
|
40 * @prototype |
|
41 */ |
|
42 class MUpperControl |
|
43 { |
|
44 public: |
|
45 /** |
|
46 * Indicates to the layer above (link layer) that the Bca is ready to start |
|
47 * receiving packets from the upper layer (either after MBca start |
|
48 * completes or following congestion) |
|
49 |
|
50 * @param none |
|
51 * @return none. |
|
52 */ |
|
53 virtual void StartSending()=0; |
|
54 |
|
55 /** |
|
56 * Any fatal error which occurs during the send/receive session is reported |
|
57 * to the client by a call to this function. Fatal errors are errors which can’t |
|
58 * be recovered from (e.g.: connection down) in which case MBca has become |
|
59 * defunct and can no longer be used to send and receive data |
|
60 |
|
61 * @param aErr TThe fatal error code from the session failures propagated |
|
62 * to the upper layer of the communications stack . Non fatal errors keep |
|
63 * the MBca2 functional which in the context of MBca2 implementation may |
|
64 * include KErrNoMemory, KErrCommsParity, KErrCommsOverrun, KErrCommsFrame. |
|
65 * @return none. |
|
66 */ |
|
67 virtual void Error(TInt aErr)=0; |
|
68 |
|
69 }; |
|
70 |
|
71 /** |
|
72 * The Class implemented by an upper component to accept inbound data travelling |
|
73 * upwards from the lower component |
|
74 |
|
75 * @publishedPartner |
|
76 * @prototype |
|
77 */ |
|
78 class MUpperDataReceiver |
|
79 { |
|
80 public: |
|
81 /** |
|
82 * This function is called whenever data has been received by MBca which |
|
83 * should be processed by its client. The implementer takes ownership of the |
|
84 * buffer and is responsible for its deletion. |
|
85 |
|
86 * @param aCommsBufChain - The list of comms buffers containing data to be processed. |
|
87 * Destination keeps the custody of the buffer. |
|
88 * @return none. |
|
89 */ |
|
90 virtual void Process(RCommsBufChain& aCommsBufChain)=0; |
|
91 }; |
|
92 |
|
93 /** |
|
94 * The interface implemented by the lower component to accept data from the upper component |
|
95 |
|
96 * @publishedPartner |
|
97 * @prototype |
|
98 */ |
|
99 |
|
100 class MLowerDataSender |
|
101 { |
|
102 public: |
|
103 enum TSendResult |
|
104 { |
|
105 // data accepted, send no more until MUpperControl::StartSending() is called |
|
106 ESendBlocked, |
|
107 // data accepted, can send more. |
|
108 ESendAccepted |
|
109 }; |
|
110 /** |
|
111 * Sends the specified buffer data down to the base-band. The implementer takes |
|
112 * ownership of the buffer and is responsible for its deletion. |
|
113 |
|
114 * @param aCommsBufChain the comms buffer list to be sent.The buffer ownership is passed |
|
115 * to the BCA |
|
116 * @return TTSendResult either ESendBlocked or SendAccepted. When the Bca |
|
117 * is congested and cannot send any data beyond the current packet (which is |
|
118 * always accepted), the implementation returns ESendBlocked. If BCA is not |
|
119 * congested then ESendAccepted is returned to continue sending. When congestion |
|
120 * passes, the Bca calls StartSending on the upper layer to resume sending. The |
|
121 * implementation is recommended to panic any attempts to call Send during congestion |
|
122 */ |
|
123 virtual TSendResult Send(RCommsBufChain& aCommsBufChain)=0; |
|
124 }; |
|
125 |
|
126 /** |
|
127 * The interface implemented by the lower component to accept control signals from the upper component |
|
128 |
|
129 * @publishedPartner |
|
130 * @prototype |
|
131 */ |
|
132 class MBca2 |
|
133 { |
|
134 public: |
|
135 struct TBcaParams |
|
136 { |
|
137 RCommsBufPond iCommsBufPond; // Pond to be used by BCA implementation for creating, using pools and buffers |
|
138 const TDesC& iChannelId; // port number or channel which BCA uses to communicate with its lower layers |
|
139 TBcaParams(RCommsBufPond aCommsBufPond,const TDesC& aChannelId) |
|
140 : iCommsBufPond(aCommsBufPond), |
|
141 iChannelId(aChannelId){} |
|
142 }; |
|
143 |
|
144 |
|
145 /** |
|
146 * Opens the BCA instance and commences a BCA session (::Close() terminates the session). |
|
147 |
|
148 * @param aControl reference to a MUpperControl implementation, which will |
|
149 * serve as the call-back interface for incoming control calls |
|
150 * @param aData - reference to a MUpperDataReceiver implementation, which |
|
151 * will serve as the call-back interface for incoming data |
|
152 * @param aBcaParams A reference to the BCA start up params |
|
153 * @return KErrNone if successful, system-wide error code otherwise. All |
|
154 * other error codes reported are fatal denoting that MBca interface has |
|
155 * failed to open and MBca is not good for transferring data |
|
156 */ |
|
157 virtual TInt Open(MUpperControl& aControl, |
|
158 MUpperDataReceiver& aData, |
|
159 const TBcaParams& aBcaParams)=0; |
|
160 |
|
161 /** |
|
162 * The API starts the baseband connection asynchronously. The Start () request |
|
163 * API’s successful completion is acknowledged with MUpperControl::StartSending(). |
|
164 * The request failure is acknowledged with MUpperControl::Error(). Client should |
|
165 * take care of scenarios when MUpperControl::StartSending() gets very delayed |
|
166 * or not called at all |
|
167 |
|
168 * @param none |
|
169 * @return none |
|
170 */ |
|
171 virtual void Start()=0; |
|
172 |
|
173 /** |
|
174 * Returns a reference to the MLowerDataSender, This reference is used by |
|
175 * upper components to send packets to the lower components. This API must be |
|
176 * called only after Start() completes, otherwise the implementation should panic. |
|
177 |
|
178 * @param none |
|
179 * @return reference to the MLowerDataSender. |
|
180 */ |
|
181 virtual MLowerDataSender& GetSender()=0; |
|
182 |
|
183 /** |
|
184 * Synchronously closes the BCA immediately. Informs the BCA is no longer |
|
185 * required by the client and can release its resources. Close cancels all |
|
186 * pending asynchronous operations which can only be ::Start() or ::Control() . |
|
187 * To use the BCA instance it needs to be re-opened. Close operation must not fail. |
|
188 |
|
189 * @param none |
|
190 * @return none. |
|
191 */ |
|
192 virtual void Close()=0; |
|
193 |
|
194 /** |
|
195 * Release/deletes the BCA instance. Derived classes will typically implement |
|
196 * this as ‘delete this’. |
|
197 |
|
198 * @param none |
|
199 * @return none. |
|
200 */ |
|
201 virtual void Release()=0; |
|
202 |
|
203 enum TBlockOption |
|
204 { |
|
205 //stop sending [block] data on interface |
|
206 EBlockFlow, |
|
207 // start sending [unblock] data on interface |
|
208 EUnblockFlow |
|
209 }; |
|
210 /** |
|
211 * Either blocks or unblocks the pushing of received data to the upper layers, |
|
212 * depending on TBlockOption. If the upper layers can’t process any more |
|
213 * data to stop receiving packets this API is called with EBlockFlow. |
|
214 * Later after the congestion eases, to start receiving packets again call |
|
215 * this API with EUnblockFlow |
|
216 |
|
217 * @param aOption either block or unblock receive flow |
|
218 * @return none. |
|
219 */ |
|
220 virtual void SetFlowControl(TBlockOption aOption)=0; |
|
221 |
|
222 /** |
|
223 * The BCA control function to get or set the options of the BCA in an |
|
224 * asynchronous manner. |
|
225 |
|
226 * @param aStatus asynchronous completion status, KErrNone if successful, |
|
227 * system-wide error code otherwise |
|
228 * @param aOptLevel option level to be used KBcaOptLevelGeneric |
|
229 * or KBcaOptLevelExtSerial |
|
230 * @param aOptName option name to be used. |
|
231 * @param aOpt an optional parameter,holds the option value on return or the |
|
232 * option value to be set. |
|
233 * @return none. |
|
234 */ |
|
235 virtual void Control(TRequestStatus& aStatus, |
|
236 TUint aOptLevel, |
|
237 TUint aOptName, |
|
238 TDes8& aOpt)=0; |
|
239 |
|
240 /** |
|
241 * Cancels the Control request in a synchronous way. |
|
242 |
|
243 * @param none |
|
244 * @return none. |
|
245 */ |
|
246 virtual void CancelControl()=0; |
|
247 }; |
|
248 |
|
249 /** |
|
250 * Control option level. |
|
251 */ |
|
252 const TUint KBcaOptLevelGeneric = 0x0194; |
|
253 const TUint KBcaOptLevelExtSerial = 0x0195; |
|
254 |
|
255 /** |
|
256 * C32 BCA capability |
|
257 */ |
|
258 const TUint KBcaCapSerial = 0x01; //Serial port capability supported |
|
259 |
|
260 /** |
|
261 * Generic Control option name |
|
262 */ |
|
263 const TUint KBCAMru = 0x12; |
|
264 const TUint KBCAMtu = 0x13; |
|
265 const TUint KBCASpeedMetric = 0x14; |
|
266 const TUint KBCACaps = 0x15; |
|
267 const TUint KBCASetIapId = 0x16; |
|
268 const TUint KBCASetBcaStack = 0x1e; |
|
269 const TUint KVersionNumber = 0x1c; |
|
270 /** |
|
271 Purges the buffers */ |
|
272 const TUint KBCAResetBuffers = 0x1f; |
|
273 |
|
274 /** |
|
275 * Serial Control option name |
|
276 */ |
|
277 const TUint KSerialCaps = 0x17; |
|
278 const TUint KSerialConfig = 0x18; |
|
279 const TUint KSerialSetConfig = 0x1a; |
|
280 const TUint KSerialPortName = 0x19; |
|
281 const TUint KSerialSetCsyName = 0x1b; |
|
282 const TUint KSerialSetCommRole = 0x1d; |
|
283 |
|
284 /** |
|
285 Set the size of receive & transmit buffers. |
|
286 Provided for compatibility with C32 RComm */ |
|
287 const TUint KSerialSetTxRxBufferSize = 0x2a; |
|
288 |
|
289 /** Retrieves the size of the receive & transmit buffers */ |
|
290 const TUint KSerialTxRxBufferSize = 0x2b; |
|
291 |
|
292 /** Set and/or clear signal lines */ |
|
293 const TUint KSerialSetControlLines = 0x2c; |
|
294 |
|
295 struct TSerialSetControlLines { |
|
296 /** |
|
297 Structure associated with KSerialSetSignals control. |
|
298 Indicates which control lines to set/clear. |
|
299 */ |
|
300 TUint iSetMask; |
|
301 TUint iClearMask; |
|
302 }; |
|
303 |
|
304 // |
|
305 // Bitmasks specifying which buffer to reset. Used with KBCaResetBuffers |
|
306 // |
|
307 |
|
308 /** Reset Rx buffer only */ |
|
309 const TUint KResetRxBuf = 0x01; |
|
310 |
|
311 /** Reset Tx buffer only */ |
|
312 const TUint KResetTxBuf = 0x02; |
|
313 |
|
314 |
|
315 /** Monitor EIA-232 control lines and take action specified. */ |
|
316 const TUint KSerialMonitorControlLines = 0x30; |
|
317 |
|
318 /** Turn control line monitoring off - do not fail on line change */ |
|
319 const TUint KMonitorOff = 0x0; |
|
320 |
|
321 /** Fail when BCA-specific lines go from high to low. |
|
322 This is the "Default" option, where the BCA itself selects what lines to monitor |
|
323 This mask must not be specified in conjunction with other masks, as the BCA will monitor |
|
324 & fail on its specific lines ONLY. The other lines will be ignored.*/ |
|
325 const TUint KFailBcaSpecificOnly = 0xFFFFFFFF; |
|
326 } |
|
327 |
|
328 #endif // BCA2_H |