|
1 /* |
|
2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of the License "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef __MP2PIF_H__ |
|
21 #define __MP2PIF_H__ |
|
22 |
|
23 #include <p2pdefs.h> // For TP2PProtocol |
|
24 |
|
25 // Forward declarations |
|
26 class MP2PIf; |
|
27 |
|
28 /* |
|
29 * Factory class for creating the Point-to-point interface. |
|
30 */ |
|
31 class TP2PFactory |
|
32 { |
|
33 |
|
34 public: |
|
35 |
|
36 /* |
|
37 * Creates a new P2P inteface. |
|
38 * Interface must be released with MP2PIf::Release |
|
39 * Execution: Synchronous |
|
40 * Re-entrant: Yes |
|
41 * Blocking: No |
|
42 * Panic mode: Kern::Fault |
|
43 * SMP safe: Yes |
|
44 * @return pointer to new interface |
|
45 * @pre Called always in kernel thread context |
|
46 * @pre No fastmutex held |
|
47 * @post Calling thread not blocked |
|
48 */ |
|
49 IMPORT_C static MP2PIf* NewP2PIfF(); |
|
50 |
|
51 }; |
|
52 |
|
53 /** |
|
54 * An interface for transceiving point-to-point (P2P) data between |
|
55 * two end points according to used P2P protocol. |
|
56 * Interface is used from kernel side. |
|
57 * NOTE! Do remember binary compatibility issues when chaning the interface. |
|
58 */ |
|
59 class MP2PIf |
|
60 { |
|
61 |
|
62 public: |
|
63 |
|
64 /** |
|
65 * Returns a free block for data sending. |
|
66 * Blocks descriptor length is set to zero, but maximum length can be bigger |
|
67 * than size given as parameter (it depends on memory block configurations). |
|
68 * Responsibility to deallocate the block is transferred to caller. |
|
69 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
70 * NOTE! Kern::Fault raised if no free blocks left. |
|
71 * Execution: Synchronous |
|
72 * Re-entrant: No |
|
73 * Blocking: Yes |
|
74 * Panic mode: Kern::Fault |
|
75 * SMP safe: Yes |
|
76 * @param aSize, minimum size of the buffer. |
|
77 * @return TDes8&, reference to allocated block. |
|
78 * @pre Called always in kernel thread context. |
|
79 * @pre No fastmutex held. |
|
80 * @pre Called with interrupts enabled and kernel unlocked. |
|
81 * @post Calling thread not blocked |
|
82 */ |
|
83 virtual TDes8& AllocateBlock( const TUint16 aSize ) = 0; |
|
84 |
|
85 /** |
|
86 * Closes the interface and cancels any outstanding DFC requests. |
|
87 * If interface is not opened with MP2PIf::Open function does nothing. |
|
88 * Automatically called in Release. |
|
89 * Execution: Synchronous |
|
90 * Re-entrant: No |
|
91 * Blocking: Yes |
|
92 * Panic mode: Kern::Fault |
|
93 * SMP safe: Yes |
|
94 * @pre Called always in kernel thread context |
|
95 * @pre No fastmutex held |
|
96 * @pre Called with interrupts enabled and kernel unlocked. |
|
97 * @post Calling thread not blocked |
|
98 */ |
|
99 virtual void Close() = 0; |
|
100 |
|
101 /* |
|
102 * Notifies when connection to other point is lost. |
|
103 * DFC function given as param shall be queued to run when connection is lost. |
|
104 * Automatically cancelled in MP2PIf::Close. |
|
105 * All data received after connection is lost shall be discarded. |
|
106 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
107 * NOTE! After connection lost MP2PIf::Close shall be called. |
|
108 * Execution: Asynchronous |
|
109 * Re-entrant: No |
|
110 * Blocking: Yes |
|
111 * Panic mode: Kern::Fault |
|
112 * SMP safe: Yes |
|
113 * @param aStatus, updated when connection is lost |
|
114 * KErrNotReady when connection is lost |
|
115 * KErrCancel when request is cancelled |
|
116 * @param aConnectionResetedCompletedDfc, clients DFC function to notify connection lost |
|
117 * @pre Called always in kernel thread context |
|
118 * @pre No fastmutex held |
|
119 * @pre Called with interrupts enabled and kernel unlocked. |
|
120 * @post Calling thread not blocked |
|
121 */ |
|
122 virtual void ConnectionLost( TInt& aStatus, const TDfc& aConnectionResetedCompletedDfc ) = 0; |
|
123 |
|
124 /* |
|
125 * Cancels the pending connection lost request with KErrCancel. |
|
126 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
127 * Automatically called in MP2PIf::Close |
|
128 * Execution: Synchronous |
|
129 * Re-entrant: No |
|
130 * Blocking: Yes |
|
131 * Panic mode: Kern::Fault |
|
132 * SMP safe: Yes |
|
133 * @pre Called always in kernel thread context |
|
134 * @pre No fastmutex held |
|
135 * @pre Called with interrupts enabled and kernel unlocked. |
|
136 * @post Calling thread not blocked |
|
137 */ |
|
138 virtual void ConnectionLostCancel() = 0; |
|
139 |
|
140 |
|
141 /** |
|
142 * Deallocates the data block retrieved with MP2PIf::Receive. |
|
143 * NOTE! After deallocation set pointer to NULL. |
|
144 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
145 * NOTE! Data shall be received before with MP2PIf::Receive. |
|
146 * Execution: Synchronous |
|
147 * Re-entrant: No |
|
148 * Blocking: Yes |
|
149 * Panic mode: Kern::Fault |
|
150 * SMP safe: Yes |
|
151 * @param aDataBlock, reference to block to deallocate. |
|
152 * @pre Called always in kernel thread context |
|
153 * @pre No fastmutex held |
|
154 * @pre Called with interrupts enabled and kernel unlocked. |
|
155 * @post Calling thread not blocked |
|
156 */ |
|
157 virtual void DeallocateBlock( TDes8& aDataBlock ) = 0; |
|
158 |
|
159 /** |
|
160 * Asynchronously opens the interface. |
|
161 * When open request is set to pending blocked caller thread is released. |
|
162 * Automatically cancelled in MP2PIf::Close. |
|
163 * NOTE! Inteface either not opened or closed with MP2PIf::Close. |
|
164 * NOTE! Kern::Fault will be raised if same request is set when it is already pending. |
|
165 * Execution: Asynchronous |
|
166 * Re-entrant: No |
|
167 * Blocking: Yes |
|
168 * Panic mode: Kern::Fault |
|
169 * SMP safe: Yes |
|
170 * @param aP2PProtocolId, dedicated P2P protocol id. |
|
171 * @param aDfcStatus, updated when DFC queued. |
|
172 * KErrNone, succesfully opened |
|
173 * KErrCancel, outstanding request is cancelled |
|
174 * KErrInUse if someone uses the same protocol id |
|
175 * KErrAlreadyExists same interface object is opened with other protocol id |
|
176 * @param aOpenCompleteDfc, reference to DFC to be queued when open completes. |
|
177 * @pre Called always in kernel thread context |
|
178 * @pre No fastmutex held |
|
179 * @pre Called with interrupts enabled and kernel unlocked. |
|
180 * @post Calling thread not blocked |
|
181 */ |
|
182 virtual void Open( const TP2PProtocol aP2PProtocolId, TInt& aDfcStatus, TDfc& aOpenCompleteDfc ) = 0; |
|
183 |
|
184 /** |
|
185 * Cancels the pending open DFC request with KErrCancel. |
|
186 * If the request is not pending anymore does nothing. |
|
187 * Automatically called in MP2PIf::Close |
|
188 * Execution: Synchronous |
|
189 * Re-entrant: No |
|
190 * Blocking: Yes |
|
191 * Panic mode: Kern::Fault |
|
192 * SMP safe: Yes |
|
193 * @pre Called always in kernel thread context |
|
194 * @pre No fastmutex held |
|
195 * @pre Called with interrupts enabled and kernel unlocked. |
|
196 * @post Calling thread not blocked |
|
197 */ |
|
198 virtual void OpenCancel() = 0; |
|
199 |
|
200 /** |
|
201 * Receives data from other point. |
|
202 * Either receives data immediately or set the receive request pending. |
|
203 * Responsibility to deallocate the data is transferred to caller. |
|
204 * DFC function given as param shall be queued to run when data is received. |
|
205 * Automatically cancelled in MP2PIf::Close. |
|
206 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
207 * NOTE! After Receive DFC completion, client shall deallocate the block with |
|
208 * MP2PIf::DeallocateBlock and set aRxDataBlock pointer to NULL. |
|
209 * NOTE! pointer to the aRxDataBlock shall not be modified from other DFC functions |
|
210 * only from aReceiveCompletedDfc function. |
|
211 * NOTE! If interface is not opened when other point is sending data to it data shall |
|
212 * be deallocated. |
|
213 * NOTE! Kern::Fault will be raised if aRxDataBlock ptr is not NULL. |
|
214 * NOTE! Kern::Fault will be raised if API can't allocate receive buffer. |
|
215 * NOTE! Kern::Fault will be raised if same request is set when it is already pending. |
|
216 * Execution: Asynchronous |
|
217 * Re-entrant: No |
|
218 * Blocking: Yes |
|
219 * Panic mode: Kern::Fault |
|
220 * SMP safe: Yes |
|
221 * @param aRxDataBlock, block where received data shall be stored. |
|
222 * @param aStatus, updated when DFC is queued. |
|
223 * KErrNone, succefull |
|
224 * KErrCancel, receive was cancelled client no need to deallocate block get from receive. |
|
225 * @param aReceiveCompletedDfc, clients DFC function for receiving data. |
|
226 * @pre Called always in kernel thread context |
|
227 * @pre No fastmutex held |
|
228 * @pre Called with interrupts enabled and kernel unlocked. |
|
229 * @post Calling thread not blocked |
|
230 */ |
|
231 virtual void Receive( TDes8*& aRxDataBlock, TInt& aStatus, const TDfc& aReceiveCompletedDfc ) = 0; |
|
232 |
|
233 /** |
|
234 * Cancels the pending receive request with KErrCancel. |
|
235 * If the request is not pending anymore does nothing. |
|
236 * Automatically called in MP2PIf::Close |
|
237 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
238 * Execution: Synchronous |
|
239 * Re-entrant: No |
|
240 * Blocking: Yes |
|
241 * Panic mode: Kern::Fault |
|
242 * SMP safe: Yes |
|
243 * @pre Called always in kernel thread context |
|
244 * @pre No fastmutex held |
|
245 * @pre Called with interrupts enabled and kernel unlocked. |
|
246 * @post Calling thread not blocked |
|
247 */ |
|
248 virtual void ReceiveCancel() = 0; |
|
249 |
|
250 /* |
|
251 * Deletes the concret object of the interface and releases reserved resources. |
|
252 * Caller is responsible to set the interface pointer to NULL. |
|
253 * NOTE! Called when interface shall not be used anymore (usually after MP2PIf::Close). |
|
254 * Execution: Synchronous |
|
255 * Re-entrant: No |
|
256 * Blocking: Yes |
|
257 * Panic mode: Kern::Fault |
|
258 * SMP safe: Yes |
|
259 * @pre Called always in kernel thread context |
|
260 * @pre No fastmutex held |
|
261 * @pre Called with interrupts enabled and kernel unlocked. |
|
262 * @post Calling thread not blocked |
|
263 */ |
|
264 virtual void Release() = 0; |
|
265 |
|
266 /** |
|
267 * Sends the data and deallocates the block given as parameter. |
|
268 * Responsibility to deallocate the block is transferred. |
|
269 * NOTE! Interface shall be opened before with MP2PIf::Open or Kern::Fault raised. |
|
270 * NOTE! Descriptor shall be allocated before with MP2PIf::AllocateMsgBlock. |
|
271 * Execution: Synchronous |
|
272 * Re-entrant: No |
|
273 * Blocking: Yes |
|
274 * Panic mode: Kern::Fault |
|
275 * SMP safe: Yes |
|
276 * Called in kernel thread context. |
|
277 * Called with no fastmutex held. |
|
278 * Called with interrupts enabled. |
|
279 * Called without kernel lock held. |
|
280 * @param TDes8& aData, reference to the data to be send. |
|
281 * @return TInt, an error code |
|
282 * KErrNone, data send |
|
283 * KErrNotReady, connection to other point lost and data discarded, MP2PIf::Close shall be called after this |
|
284 * @pre Called always in kernel thread context |
|
285 * @pre No fastmutex held |
|
286 * @pre Called with interrupts enabled and kernel unlocked. |
|
287 * @post Calling thread not blocked |
|
288 */ |
|
289 virtual TInt Send( TDes8& aData ) = 0; |
|
290 |
|
291 }; |
|
292 |
|
293 #endif // __MP2PIF_H__ |
|
294 |
|
295 // End of File. |
|
296 |