|
1 // Copyright (c) 2008-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 #if !defined(__SS_FLOWBINDERS_INTERNAL_H__) |
|
17 #define __SS_FLOWBINDERS_INTERNAL_H__ |
|
18 |
|
19 class RMBufChain; |
|
20 class MProvdSecurityChecker; |
|
21 |
|
22 namespace ESock |
|
23 { |
|
24 |
|
25 class MUpperDataReceiver; |
|
26 class MUpperControl; |
|
27 class MLowerDataSender; |
|
28 class MLowerControl; |
|
29 |
|
30 class MSessionDataNotify; |
|
31 class MSessionControlNotify; |
|
32 class MSessionData; |
|
33 class MSessionControl; |
|
34 |
|
35 class CSubConnectionFlowBase; |
|
36 class MFlowBinderControl |
|
37 /** |
|
38 Interface that a flow implements to allow creation of binders on it. |
|
39 |
|
40 @internalTechnology |
|
41 */ |
|
42 { |
|
43 public: |
|
44 //protocol binder |
|
45 IMPORT_C virtual MLowerControl* GetControlL(const TDesC8& aProtocol); |
|
46 IMPORT_C virtual MLowerDataSender* BindL(const TDesC8& aProtocol, MUpperDataReceiver* aReceiver, MUpperControl* aControl); |
|
47 IMPORT_C virtual void Unbind( MUpperDataReceiver* aReceiver, MUpperControl* aControl); |
|
48 |
|
49 //session binder |
|
50 IMPORT_C virtual MSessionControl* GetControlL(TInt aSessionType, MSessionControlNotify& aSessionControlNotify); |
|
51 IMPORT_C virtual MSessionData* BindL(MSessionDataNotify& aNotify); |
|
52 IMPORT_C virtual void Unbind(); |
|
53 |
|
54 IMPORT_C virtual CSubConnectionFlowBase& CloneFlowL(); //creates an unitialised duplicate of |
|
55 //its flow |
|
56 virtual CSubConnectionFlowBase* Flow() = 0; //returns its own flow |
|
57 }; |
|
58 |
|
59 /**************************************************************************************** |
|
60 Interface Module related classes |
|
61 |
|
62 The following four classes are used by stacked interface modules to pass data and control |
|
63 information up and down. These interfaces do not cross a thread boundary. In the comments |
|
64 that follow, the terms "upper" and "lower" are used to describe, in relative terms, which |
|
65 classes are implemented by which of a pair of stacked interface modules. |
|
66 |
|
67 ----------------------------------------- |
|
68 | Upper Module | |
|
69 ----------------------------------------- |
|
70 ^ ^ | | CSubConnectionFlowBase |
|
71 MUpperControl | | MUpperDataReceiver | | | |
|
72 | | | | | |
|
73 | | MLowerDataSender | | MLowerControl | |
|
74 | | v v | |
|
75 ----------------------------------------- | |
|
76 | Lower Module |<---------------+ |
|
77 ----------------------------------------- |
|
78 */ |
|
79 |
|
80 class MUpperDataReceiver |
|
81 /** |
|
82 Class implemented by an "upper" interface module to accept inbound data travelling |
|
83 upwards from the interface module below. |
|
84 |
|
85 @since Argus |
|
86 @internalTechnology |
|
87 */ |
|
88 { |
|
89 public: |
|
90 virtual void Process(RMBufChain& aData) = 0; |
|
91 }; |
|
92 |
|
93 class MLowerDataSender |
|
94 /** |
|
95 Class implemented by a "lower" interface module to accept outbound data travelling downwards |
|
96 from the interface module above. |
|
97 |
|
98 @since Argus |
|
99 @internalTechnology |
|
100 */ |
|
101 { |
|
102 public: |
|
103 enum TSendResult |
|
104 { |
|
105 // Send Flow Control |
|
106 // The 0 and 1 values below explicitly match the legacy return values from a NIF Send() call. |
|
107 ESendBlocked = 0, // data accepted, send no more until MUpperControl::Unblock() |
|
108 ESendAccepted = 1 // data accepted, can send more |
|
109 }; |
|
110 |
|
111 virtual TSendResult Send(RMBufChain& aData) = 0; |
|
112 }; |
|
113 |
|
114 class MUpperControl |
|
115 /** |
|
116 Class implemented by an "upper" interface module to accept control signals from the |
|
117 interface module below. |
|
118 |
|
119 @since Argus |
|
120 @internalTechnology |
|
121 */ |
|
122 { |
|
123 public: |
|
124 virtual void StartSending() = 0; |
|
125 virtual void Error(TInt anError) = 0; |
|
126 }; |
|
127 |
|
128 class MLowerControl |
|
129 /** |
|
130 Class implemented by a "lower" interface module to accept control signals from the |
|
131 interface module above. |
|
132 |
|
133 @since Argus |
|
134 @internalTechnology |
|
135 */ |
|
136 { |
|
137 public: |
|
138 enum TBlockOption |
|
139 { |
|
140 EDisableAllOtherBindersOnFlow, |
|
141 EDisableAllOtherBindersOnInterface, |
|
142 EEnableAllBinders |
|
143 }; |
|
144 |
|
145 IMPORT_C virtual TInt GetName(TDes& aName); |
|
146 IMPORT_C virtual TInt BlockFlow(TBlockOption aOption); |
|
147 IMPORT_C virtual TInt GetConfig(TBinderConfig& aConfig); |
|
148 IMPORT_C virtual TInt Control(TUint aLevel, TUint aName, TDes8& aOption); |
|
149 }; |
|
150 |
|
151 class MSessionControl |
|
152 /** |
|
153 @internalTechnology |
|
154 */ |
|
155 { |
|
156 public: |
|
157 /** Describes the behaviour the SAP should take on shutdown.*/ |
|
158 //the values of the enum directly map to CServProviderBase::TCloseType enum values |
|
159 enum TCloseType |
|
160 { |
|
161 ENormal, //< The protocol should shutdown gracefully & no further input or output will be requested. |
|
162 EStopInput, //< The protocol should shut down gracefully & all further and pending input should be discarded. |
|
163 EStopOutput, //< The protocol should shutdown gracefully & all pending output should be discarded. |
|
164 EImmediate //< The protocol should close the connection immediately and free all resources without performing a graceful disconnect. |
|
165 }; |
|
166 /** |
|
167 Start a service provider. |
|
168 */ |
|
169 virtual void Start()=0; |
|
170 /** Gets the local name (address) of the socket service provider entity. The format |
|
171 of the data in the TSockAddr object is defined by individual protocols. |
|
172 |
|
173 The local address is the address of the local machine plus a local port number. |
|
174 Generally only the port number is important, unless you have two IP interfaces, |
|
175 for example. |
|
176 |
|
177 @param anAddr The address to be filled in */ |
|
178 virtual void LocalName(TSockAddr& anAddr) const =0; |
|
179 |
|
180 /**When the set local name operation has completed, the protocol should call SetLocalNameComplete() |
|
181 on its TNotify */ |
|
182 virtual void SetLocalName(TSockAddr& anAddr)=0; |
|
183 |
|
184 /** Gets the remote name (address) of the socket service provider entity. The format |
|
185 of the data in the TSockAddr object is defined by individual protocols. |
|
186 |
|
187 A remote address is either the address you're sending data to (non connection-oriented |
|
188 sockets)* or the remote end of the connection. It is the address of the remote |
|
189 machine (your peer in the network) plus a port number. |
|
190 |
|
191 @note RemName is only meaningful if the socket server client has called Connect() |
|
192 to set up a default address for SendTo(). This function will only be called |
|
193 on the protocol if this is the case. |
|
194 |
|
195 @param anAddr The address to be filled in */ |
|
196 virtual void RemName(TSockAddr& anAddr) const =0; |
|
197 /** Sets the remote name (address) of the socket service provider entity. The format |
|
198 of the data in the TSockAddr object is defined by individual protocols. |
|
199 |
|
200 @param anAddr The address |
|
201 @return Returns KErrNone if the remote name is correctly set or, if this is |
|
202 not the case, an informative error number. */ |
|
203 virtual TInt SetRemName(TSockAddr& anAddr)=0; |
|
204 /** Gets some protocol specific option when called by the socket server on behalf of a |
|
205 client. A protocol may pass the request down a protocol stack (to protocols it is bound |
|
206 to) using the GetOption() function of CProtocolBase. |
|
207 |
|
208 @param aLevel Option level. |
|
209 @param aName Option name. |
|
210 @param anOption Option data. |
|
211 @return System wide error code. |
|
212 */ |
|
213 virtual TInt GetOption(TUint level,TUint name,TDes8& anOption)const =0; |
|
214 /** Performs some protocol specific IO control. |
|
215 |
|
216 @note If this function is called erroneously, the protocol should call Error() on the |
|
217 socket. If an Ioctl call is already outstanding, the client will be panicked with the |
|
218 value ETwoIoctls. |
|
219 |
|
220 @param aLevel Option level. |
|
221 @param aName Option name. |
|
222 @param anOption Option data. |
|
223 @return System wide error code. |
|
224 */ |
|
225 virtual void Ioctl(TUint level,TUint name,TDes8* anOption)=0; |
|
226 /** Cancels an outstanding Ioctl call. You are guaranteed only to have one outstanding |
|
227 at once. |
|
228 |
|
229 @param aLevel IOCTL level. |
|
230 @param aName IOCTL name. |
|
231 */ |
|
232 virtual void CancelIoctl(TUint aLevel,TUint aName)=0; |
|
233 /** Sets some protocol specific option when called by the socket server on behalf of a |
|
234 client. A protocol may pass the request down a protocol stack (to protocols it is bound |
|
235 to) using the SetOption() function of CProtocolBase. |
|
236 |
|
237 @param aLevel Option level. |
|
238 @param aName Option name. |
|
239 @param anOption Option data. |
|
240 @return System wide error code. |
|
241 */ |
|
242 virtual TInt SetOption(TUint level,TUint name,const TDesC8& anOption)=0; |
|
243 virtual void ActiveOpen()=0; |
|
244 /** Initiates a connection operation - this means that it tells the protocol to |
|
245 attempt to connect to a peer. It is called by the socket server in response |
|
246 to a connect request from a client. |
|
247 |
|
248 This version of the function has user data in the connection frame. |
|
249 |
|
250 Only ever called on connection-oriented sockets. Such a socket |
|
251 should always have both the local address and the remote address specified |
|
252 before this function is called. If this is not the case then the protocol |
|
253 should panic. |
|
254 |
|
255 When a connection has completed, the protocol should call ConnectComplete() |
|
256 on its TNotify. If an error occurs during connection the protocol should not |
|
257 call ConnectComplete() at all; instead it should call Error(). |
|
258 |
|
259 @param aConnectionData If the protocol supports user specified connection |
|
260 data, then it will be held in this buffer. */ |
|
261 virtual void ActiveOpen(const TDesC8& aConnectionData)=0; |
|
262 /** Tells the protocol to start waiting for an incoming connection request on this |
|
263 socket (i.e. port). It is called by the socket server in response to a listen |
|
264 request from a client. |
|
265 |
|
266 Only ever called on connection-oriented sockets. Such a socket |
|
267 should always have both the local address and the remote address specified |
|
268 before this function is called. If this is not the case, then the protocol |
|
269 should panic. |
|
270 |
|
271 The aQue parameter is the number of sockets which can be waiting for an outstanding |
|
272 Start after calling ConnectComplete(). The protocol should keep a count of |
|
273 sockets in this state - incrementing a variable in ConnectComplete(), and |
|
274 decrementing it in Start(). |
|
275 |
|
276 When a connection has completed, the protocol should call ConnectComplete() |
|
277 on its TNotify. If an error occurs during connection the protocol should not |
|
278 call ConnectComplete() at all; instead it should call Error(). |
|
279 |
|
280 @param aQueSize Size of connect queue. |
|
281 */ |
|
282 virtual TInt PassiveOpen(TUint aQueSize)=0; |
|
283 /** Tells the protocol to start waiting for an incoming connection request on this |
|
284 socket (i.e. port). It is called by the socket server in response to a listen |
|
285 request from a client. |
|
286 |
|
287 This version of the function has user data in the connection frame. |
|
288 |
|
289 Only ever called on connection-oriented sockets. Such a socket |
|
290 should always have both the local address and the remote address specified |
|
291 before this function is called. If this is not the case then the protocol |
|
292 should panic. |
|
293 |
|
294 The aQue parameter is the number of sockets which can be waiting for an outstanding |
|
295 Start after calling ConnectComplete(). The protocol should keep a count of |
|
296 sockets in this state - incrementing a variable in ConnectComplete(), and |
|
297 decrementing it in Start(). |
|
298 |
|
299 When a connection has completed the protocol should call ConnectComplete() |
|
300 on its TNotify. If an error occurs during connection the protocol should not |
|
301 call ConnectComplete() at all; instead it should call Error(). |
|
302 |
|
303 @param aQueSize size of connect queue |
|
304 @param aConnectionData if the protocol supports user specified connection data |
|
305 then it will be held in this buffer. */ |
|
306 virtual TInt PassiveOpen(TUint aQueSize,const TDesC8& aConnectionData)=0; |
|
307 /** Terminates a connection (or closes a non connection-oriented socket down). |
|
308 |
|
309 The value of the option argument specifies the type of processing which will |
|
310 be required of the protocol after this function is called. |
|
311 |
|
312 Normally, when the socket server has called Shutdown() for a socket, it will |
|
313 wait for the socket to call CanClose() before destroying the CSubConnectionFlowBase |
|
314 object. However, if the option argument is EImmediate, the CSubConnectionFlowBase |
|
315 will be destroyed as soon as Shutdown() returns. |
|
316 |
|
317 @param option The shutdown type. */ |
|
318 virtual void Shutdown(MSessionControl::TCloseType option)=0; |
|
319 /** Terminates a connection (or closes a non connection-oriented socket down). |
|
320 |
|
321 The value of the option argument specifies the type of processing which will |
|
322 be required of the protocol after this function is called. |
|
323 |
|
324 Normally, when the socket server has called Shutdown() for a socket, it will |
|
325 wait for the socket to call CanClose() before destroying the CSubConnectionFlowBase |
|
326 object. However, if the option argument is EImmediate, the CSubConnectionFlowBase |
|
327 will be destroyed as soon as Shutdown() returns. |
|
328 |
|
329 @param option The shutdown type. |
|
330 @param aDisconnectionData If the protocol supports disconnect data, any such |
|
331 data required will be held in this buffer. */ |
|
332 virtual void Shutdown(MSessionControl::TCloseType option, const TDesC8& aDisconnectionData)=0; |
|
333 /** Specifies that the protocol should choose a local address for the service access |
|
334 point itself. */ |
|
335 virtual void AutoBind()=0; |
|
336 |
|
337 |
|
338 /** Use the class instance argument to perform security policy checks on the originating client process. |
|
339 |
|
340 This method is called when a SAP is created and when a socket is transferred between sessions. The SAP is |
|
341 required to check whether the originating client process has enough privileges to request services from the SAP. |
|
342 The MProvdSecurityChecker class instance is used to perform security policy checks. The SAP may choose |
|
343 to perform a security policy check in its SecurityCheck(...) method, or it may choose to store the |
|
344 MProvdSecurityChecker class instance argument and perform checking later (i.e. when subsequent |
|
345 SAP methods are called). |
|
346 |
|
347 @param aSecurityChecker Pointer to class used by SAP to perform security checks on the client process. This |
|
348 pointer becomes invalid when the SAP is destroyed or detached. |
|
349 @returns KErrPermissionDenied if SAP wishes to disallow access to the client, else KErrNone. This would |
|
350 normally be as a result of calling MProvdSecurityChecker::CheckPolicy(...) with a suitable security policy argument. |
|
351 */ |
|
352 virtual TInt SecurityCheck(MProvdSecurityChecker *aSecurityChecker) = 0; |
|
353 }; |
|
354 |
|
355 class MSessionData |
|
356 { |
|
357 /** |
|
358 @internalTechnology |
|
359 */ |
|
360 public: |
|
361 // protocol read/write data; ESock v1.5 calls down to the v1.5 itf (RMBufChain). |
|
362 // v1.5-ready protocols implement this, laggard protocols inherit these base class |
|
363 // implementations which call the v1.0 descriptor itf instead. |
|
364 |
|
365 /** Sends data onto the network via the protocol. |
|
366 |
|
367 Connection-oriented sockets must be in a connected state (that is ConnectComplete() has |
|
368 been called on their MSocketNotify before Write() is called). |
|
369 |
|
370 The socket server keeps track of how much data is waiting and then tries to send it all |
|
371 until the protocol tells it to hold off by returning 0 (datagram sockets) or 'less than |
|
372 all data consumed' (stream sockets) to Write(). The protocol should call CanSend() when it |
|
373 is ready to send more data. |
|
374 |
|
375 anAddr is the address to write the data to. Connection oriented sockets always use the |
|
376 default value. |
|
377 |
|
378 @param aDesc The data to be sent. |
|
379 @param aOptions Protocol specific options. |
|
380 @param anAddr Address to write the data to. |
|
381 |
|
382 @returns For stream-oriented protocols the return value is the number of bytes actually written. |
|
383 If this is less than the length of the descriptor then the protocol should call CanSend() |
|
384 when it is ready to send more data. For datagram-oriented protocols, the write should return |
|
385 either 0 if the write cannot be completed, or the length of the descriptor if the write succeeds - |
|
386 no other values are valid. If the Write() must return 0, then it should call CanSend() when it is |
|
387 ready to send more data. If the Write() fails due to some error, then it should call Error() with |
|
388 an informative error number. |
|
389 */ |
|
390 virtual TUint Write(const TDesC8& aDesc,TUint options, TSockAddr* anAddr=NULL) = 0; |
|
391 /** Sends data onto the network via the protocol. |
|
392 |
|
393 Connection-oriented sockets must be in a connected state (that is ConnectComplete() has |
|
394 been called on their MSocketNotify before Write() is called). |
|
395 |
|
396 The socket server keeps track of how much data is waiting and then tries to send it all |
|
397 until the protocol tells it to hold off by returning 0 (datagram sockets) or 'less than |
|
398 all data consumed' (stream sockets) to Write(). The protocol should call CanSend() when it |
|
399 is ready to send more data. |
|
400 |
|
401 anAddr is the address to write the data to. Connection oriented sockets always use the |
|
402 default value. |
|
403 |
|
404 @param aData The data to be sent. |
|
405 @param aOptions Protocol specific options. |
|
406 @param anAddr Address to write the data to. |
|
407 |
|
408 @returns For stream-oriented protocols the return value is the number of bytes actually written. |
|
409 If this is less than the length of the descriptor then the protocol should call CanSend() |
|
410 when it is ready to send more data. For datagram-oriented protocols, the write should return |
|
411 either 0 if the write cannot be completed, or the length of the descriptor if the write succeeds - |
|
412 no other values are valid. If the Write() must return 0, then it should call CanSend() when it is |
|
413 ready to send more data. If the Write() fails due to some error, then it should call Error() with |
|
414 an informative error number. |
|
415 */ |
|
416 virtual TInt Write(RMBufChain& aData, TUint aOptions, TSockAddr* anAddr=NULL) = 0; |
|
417 |
|
418 /** Gets data which the protocol has indicated is waiting in its buffers using the NewData |
|
419 up-call on the MSocketNotify. |
|
420 |
|
421 GetData() will only ever be called for as much data as the protocol has specified it can process |
|
422 using the NewData up-call. |
|
423 |
|
424 For stream oriented protocols GetData() should fill the descriptor with data from the stream. On |
|
425 a datagram protocol GetData() should copy one datagram into the descriptor and set the length of |
|
426 the descriptor. If a full datagram will not fit into the supplied descriptor, the overflow should |
|
427 be discarded. |
|
428 |
|
429 anAddr should be filled in by the protocol with the address of where the data came from. |
|
430 |
|
431 @param aDesc The buffer for data. |
|
432 @param aOptions Protocol specific options. |
|
433 @param anAddr Address where the data came from. |
|
434 */ |
|
435 virtual void GetData(TDes8& aDesc,TUint options,TSockAddr* anAddr=NULL) = 0; |
|
436 /** Gets data which the protocol has indicated is waiting in its buffers using the NewData |
|
437 up-call on the MSocketNotify. |
|
438 |
|
439 GetData() will only ever be called for as much data as the protocol has specified it can process |
|
440 using the NewData up-call. |
|
441 |
|
442 For stream oriented protocols GetData() should fill the descriptor with data from the stream. On |
|
443 a datagram protocol GetData() should copy one datagram into the descriptor and set the length of |
|
444 the descriptor. If a full datagram will not fit into the supplied descriptor, the overflow should |
|
445 be discarded. |
|
446 |
|
447 anAddr should be filled in by the protocol with the address of where the data came from. |
|
448 |
|
449 @param aDesc The buffer for data. |
|
450 @param aOptions Protocol specific options. |
|
451 @param anAddr Address where the data came from. |
|
452 */ |
|
453 virtual TInt GetData(RMBufChain& aData, TUint aLength, TUint aOptions, TSockAddr* anAddr=NULL) = 0; |
|
454 }; |
|
455 } |
|
456 |
|
457 #endif |
|
458 |