|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D043376C-29D2-5196-96F4-15E99CFB5639" xml:lang="en"><title> RSubConnection |
|
13 API Tutorial</title><shortdesc>How to use an <apiname>RSubConnection</apiname>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-254081A7-16C0-45C5-B964-4B47D6EB4590"><title>Procedure</title> <ol id="GUID-C81387B5-9ED3-59ED-A5DC-C6FE807B2E1C"> |
|
15 <li id="GUID-46077726-D57D-5A89-A022-D1EDD45FFE3C"><p>Use the <codeph>Open()</codeph> method |
|
16 to open an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> object on an ESOCK session. </p> <p>The <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> must |
|
17 already be active. A sub-connection type is passed as a parameter to this |
|
18 method. It is then attached to the default sub-connection that is the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>, |
|
19 or creates a sub-connection. When an application calls the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API, |
|
20 a system wide error code is returned. When it is successful, it returns <codeph>KErrNone</codeph>. </p> </li> |
|
21 <li id="GUID-32926A01-B170-5413-8FAC-0022F80EE1D1"><p>Use the <codeph>Add()</codeph> method |
|
22 to move the socket from the default sub-connection to the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref>. </p> </li> |
|
23 <li id="GUID-BD4E28EF-3DAA-5DC5-8F68-2889C4B826B9"><p>The <codeph>Remove()</codeph> method |
|
24 returns the socket to the default sub-connection. </p> </li> |
|
25 <li id="GUID-49044666-971D-59E6-8FBB-3AD1410726B7"><p>Use the <codeph>GetParameters()</codeph> and <codeph>SetParameters()</codeph> methods |
|
26 are to retrieve and set bundles of properties on the sub-connection. </p> </li> |
|
27 <li id="GUID-FC5ABE8D-AA9C-502B-8E9F-BC8F2ECB2D1F"><p>The <codeph>GetParameters()</codeph> returns <codeph>KErrNotReady</codeph> if |
|
28 properties are not negotiated. </p> </li> |
|
29 <li id="GUID-1B1C7EE8-2B94-5BC9-9797-9D560C5F8E39"><p>The <codeph>SetParameters()</codeph> method, |
|
30 like the <codeph>Add()</codeph> and <codeph>Remove()</codeph> methods returns |
|
31 an error code indicating the success or failure of the request to perform |
|
32 the action. </p> </li> |
|
33 <li id="GUID-CB745754-DF5D-5392-BA7C-79CB5DA2F708"><p>When the properties |
|
34 are negotiated either the <codeph>CSubConGenEventParamsGranted</codeph> or <codeph>CSubConGenEventParamsRejected</codeph> event |
|
35 is notified for each family within the parameter bundle. </p> </li> |
|
36 <li id="GUID-4D290B37-0C6D-5794-A8C7-3CCDF872FCA8"><p>Use the <codeph>EventNotification()</codeph> methods |
|
37 to asynchronously register for event notifications. </p> <p>The methods support |
|
38 filtering of events in two different ways, through a Boolean flag to receive |
|
39 notification of generic or all events, and through an array of <codeph>TEventFilter</codeph>. </p> </li> |
|
40 <li id="GUID-9728A1AA-E0AC-589D-A251-B46CB369F90E"><p>Use <xref href="GUID-B25D68E9-BAD2-358F-9FB0-956E3A2AEDCE.dita"><apiname>CancelEventNotification()</apiname></xref> method |
|
41 cancel the registration for event notifications. </p> </li> |
|
42 </ol> </section> |
|
43 <example><title>Connecting to the default SubConnection example</title> <p>In |
|
44 the following example, the application connects to the default sub-connection |
|
45 to set the properties. When it has set properties on the default sub-connection, |
|
46 the application tries to connect a socket over the default sub-connection. </p> <codeblock id="GUID-A30FEC87-9D24-5BEF-A47C-85721B73DB70" xml:space="preserve">RSocketServ ss; |
|
47 RConnection conn; |
|
48 RSubConnection subconn; |
|
49 RSocket sock; |
|
50 TRequestStatus status; |
|
51 |
|
52 // Connect to ESOCK |
|
53 ss.Connect(); |
|
54 |
|
55 // Open a Connection |
|
56 conn.Open(ss, KAfInet); |
|
57 |
|
58 // Start the connection |
|
59 conn.Start(status); |
|
60 User::WaitForRequest(status); |
|
61 |
|
62 // Attach to the default sub-connection |
|
63 subconn.Open(ss, RSubConnection::EAttachToDefault, conn); |
|
64 |
|
65 // Set Properties of the default sub-connection |
|
66 subconn.SetParameters(…); |
|
67 |
|
68 // Open a TCP socket on the connection (this is the same as using the default sub-connection) |
|
69 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, conn); |
|
70 |
|
71 _LIT(KRasAddr,"10.159.24.13"); |
|
72 const TInt KEchoPort = 7; |
|
73 |
|
74 TInetAddr destAddr; |
|
75 destAddr.Input(KRasAddr); |
|
76 destAddr.SetPort(KEchoPort); |
|
77 |
|
78 // Request the Socket to connect to the destination over the default sub-connection |
|
79 sock.Connect(destAddr, status); |
|
80 </codeblock> </example> |
|
81 <section id="GUID-D707232A-A1B5-4F8F-98D4-D6EBC253DF94"><title>Creating a sub-connection - Socket connected over the |
|
82 SubConnection example</title> <p>The following example shows how an |
|
83 application can use a sub-connection through an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> instance. |
|
84 It attaches an <codeph>RSocket</codeph> to the sub-connection. </p> <codeblock id="GUID-F7E8A10E-4A1C-5547-A2F5-783D0A914EA3" xml:space="preserve">RSocketServ ss; |
|
85 RConnection conn; |
|
86 RSubConnection subconn; |
|
87 RSocket sock; |
|
88 TRequestStatus status; |
|
89 |
|
90 // Connect to ESOCK |
|
91 ss.Connect(); |
|
92 |
|
93 // Open an Connection |
|
94 conn.Open(ss, KAfInet); |
|
95 |
|
96 // Start the connection |
|
97 conn.Start(status); |
|
98 User::WaitForRequest(status); |
|
99 |
|
100 // Create a new sub-connection |
|
101 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
102 |
|
103 // Set Properties of the sub-connection |
|
104 subconn.SetParameters(…); |
|
105 |
|
106 // Open a TCP socket on the sub-connection |
|
107 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn); |
|
108 |
|
109 _LIT(KRasAddr,"10.159.24.13"); |
|
110 const TInt KEchoPort = 7; |
|
111 |
|
112 TInetAddr destAddr; |
|
113 destAddr.Input(KRasAddr); |
|
114 destAddr.SetPort(KEchoPort); |
|
115 |
|
116 // Request the Socket to connect to the destination over the sub-connection |
|
117 sock.Connect(destAddr, status); |
|
118 </codeblock> </section> |
|
119 <section id="GUID-0766B25A-8073-47E7-A86E-4D172D050064"><title>Creating a new sub-connection - Adding an already connected |
|
120 socket example</title> <p>The following example shows how an application |
|
121 can use a sub-connection through an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> instance. |
|
122 It attaches a connected <codeph>RSocket</codeph> to the sub-connection. </p> <codeblock id="GUID-27ACF33C-004D-5538-AF34-175F66D73C6B" xml:space="preserve">RSocketServ ss; |
|
123 RConnection conn; |
|
124 RSubConnection subconn; |
|
125 RSocket sock; |
|
126 TRequestStatus status; |
|
127 |
|
128 // Connect to ESOCK |
|
129 ss.Connect(); |
|
130 |
|
131 // Open a Connection |
|
132 conn.Open(ss, KAfInet); |
|
133 |
|
134 // Start the connection |
|
135 conn.Start(status); |
|
136 User::WaitForRequest(status); |
|
137 |
|
138 // Open a TCP socket on the connection |
|
139 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, conn); |
|
140 |
|
141 _LIT(KRasAddr,"10.159.24.13"); |
|
142 const TInt KEchoPort = 7; |
|
143 |
|
144 TInetAddr destAddr; |
|
145 destAddr.Input(KRasAddr); |
|
146 destAddr.SetPort(KEchoPort); |
|
147 |
|
148 // Connect the Socket to the destination over the connection (default sub-connection) |
|
149 sock.Connect(destAddr, status); |
|
150 |
|
151 // Create a new sub-connection |
|
152 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
153 |
|
154 // Set Properties of the sub-connection |
|
155 subconn.SetParameters(…); |
|
156 |
|
157 // Move the connected socket onto the new sub-connection |
|
158 TRequestStatus status; |
|
159 subconn.Add(sock, status); |
|
160 |
|
161 // Wait for socket to added |
|
162 User::WaitForRequest(status); |
|
163 </codeblock> </section> |
|
164 <section id="GUID-BC00A713-123E-401D-9E99-BE52C920D71B"><title>Creating and setting properties for a SubConnection |
|
165 example</title> <p>The following example shows how an application creates |
|
166 and sets the QoS properties. It assigns the properties to a sub-connection. </p> <codeblock id="GUID-6A478B1D-3A6E-5FB1-BD5E-2485A86539C1" xml:space="preserve">// Create the container for all sub connection parameters |
|
167 RSubConParameterBundle subconParams; |
|
168 CleanupClosePushL(subconParams); |
|
169 |
|
170 // Create a container for QoS sub connection parameters (Param bundle takes ownership) |
|
171 CSubConParameterFamily* qosFamily = CSubConParameterFamily::NewL(subconParams, |
|
172 KSubConQoSFamily); |
|
173 |
|
174 // Create the requested generic parameter set for QoS (Qos family takes ownership) |
|
175 CSubConQosGenericParamSet* reqGenericParams = CSubConQosGenericParamSet::NewL(*qosFamily, |
|
176 CSubConParameterFamily::ERequested); |
|
177 |
|
178 // Set the requested Generic Parameters |
|
179 reqGenericParams->SetDownlinkBandwidth(128); |
|
180 reqGenericParams->SetUplinkBandwidth(64); |
|
181 |
|
182 // Create the acceptable generic parameter set for QoS (Qos family takes ownership) |
|
183 CSubConQosGenericParamSet* accGenericParams = CSubConQosGenericParamSet::NewL(*qosFamily, |
|
184 CSubConParameterFamily::EAcceptable); |
|
185 |
|
186 // Set the acceptable Generic Parameters |
|
187 accGenericParams->SetDownlinkBandwidth(48); |
|
188 accGenericParams->SetUplinkBandwidth(32); |
|
189 |
|
190 // Create a requested technology specific parameter set for QoS (Qos family takes ownership) |
|
191 CSubConQosR99ParamSet* reqRel99Params = CSubConQosR99ParamSet::NewL(*qosFamily, |
|
192 CSubConParameterFamily::ERequested); |
|
193 |
|
194 // Set the requested Technology Specific Params |
|
195 reqRel99Params->SetMaxSDUSize(1024); |
|
196 |
|
197 // Create a acceptable technology specific parameter set for QoS (Qos family takes ownership) |
|
198 CSubConQosR99ParamSet* accRel99Params = CSubConQosR99ParamSet::NewL(*qosFamily, |
|
199 CSubConParameterFamily::EAcceptable); |
|
200 |
|
201 // Set the acceptable Technology Specific Params |
|
202 accRel99Params->SetMaxSDUSize(512); |
|
203 |
|
204 // Now open the sub-connection as normal… |
|
205 ……… |
|
206 ……… |
|
207 // Create a new sub-connection |
|
208 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
209 |
|
210 // Set Properties of the sub-connection |
|
211 subconn.SetParameters(subconParams); |
|
212 |
|
213 // Destroy parameters |
|
214 CleanupStack::PopAndDestroy(); // subconParams |
|
215 |
|
216 // Open a TCP socket on the sub-connection |
|
217 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn); |
|
218 |
|
219 _LIT(KRasAddr,"10.159.24.13"); |
|
220 const TInt KEchoPort = 7; |
|
221 |
|
222 TInetAddr destAddr; |
|
223 destAddr.Input(KRasAddr); |
|
224 destAddr.SetPort(KEchoPort); |
|
225 |
|
226 // Connect the Socket to the destination over the sub-connection |
|
227 sock.Connect(destAddr, status); |
|
228 User::WaitForRequest(status); |
|
229 |
|
230 // Fetch the granted qos |
|
231 RSubConParameterBundle grantedParams; |
|
232 subconn.GetParameters(grantedParams); |
|
233 </codeblock> </section> |
|
234 <section id="GUID-781F3343-94E7-4BF5-8840-0CDFFB0B99B2"><title>Registering for events example</title> <p>The following example |
|
235 shows how an application can register events that occur on a sub-connection. |
|
236 In this example the application registers for notification of all events. </p> <codeblock id="GUID-B6B202DB-323A-528F-B6F6-60160A140EA5" xml:space="preserve">// Create the container for all sub connection parameters |
|
237 RSubConParameterBundle subconParams; |
|
238 CleanupClosePushL(subconParams); |
|
239 |
|
240 ……… |
|
241 ……… |
|
242 // Create and initialise parameters sets as above |
|
243 ……… |
|
244 ……… |
|
245 |
|
246 // Create a new sub-connection |
|
247 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
248 |
|
249 TNotificationEventBuf eventBuffer; |
|
250 TRequestStatus eventStatus; |
|
251 subconn.EventNotification(eventBuffer, EFalse, eventStatus); |
|
252 |
|
253 // Set Properties of the sub-connection |
|
254 subconn.SetParameters(subconParams); |
|
255 |
|
256 // Destroy parameters |
|
257 CleanupStack::PopAndDestroy(); // subconParams |
|
258 |
|
259 // Open and connect a TCP socket on the sub-connection |
|
260 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn); |
|
261 sock.Connect(destAddr, status); |
|
262 User::WaitForRequest(status); |
|
263 |
|
264 // Negotiation may not occur until a socket is assigned to the sub-connection |
|
265 // First event should be cSubConGenEventDataClientJoining |
|
266 User::WaitForRequest(eventStatus); |
|
267 |
|
268 // Next we’d expect a CSubconGenEventParamsGranted/ CSubconGenEventParamsRejected |
|
269 subconn.EventNotification(eventBuffer, EFalse, eventStatus); |
|
270 User::WaitForRequest(eventStatus); |
|
271 </codeblock> <p><b>Registering for events – Using filters</b> </p> <p>The |
|
272 following example code shows how to register for specific events using filters. |
|
273 In this example the application registers for notification when sub-connection |
|
274 parameters are granted or rejected. Each <xref href="GUID-FDE12D94-17D3-3646-B645-26A08926F86C.dita"><apiname>TEventFilter</apiname></xref> contains |
|
275 events of the factory UID and mask of event IDs. </p> <codeblock id="GUID-9368C7DA-B870-55C6-A84B-756EE1DF4E33" xml:space="preserve">// Create the container for all sub connection parameters |
|
276 RSubConParameterBundle subconParams; |
|
277 CleanupClosePushL(subconParams); |
|
278 |
|
279 ……… |
|
280 ……… |
|
281 // Create and initialise parameters sets as above |
|
282 ……… |
|
283 ……… |
|
284 |
|
285 // Create a new sub-connection |
|
286 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
287 |
|
288 // Create event filter |
|
289 TEventFilter filter; |
|
290 filter.iEventGroupUid = KSubConnGenericEventsImplUid; |
|
291 filter.iEventMask = KSubConGenericEventParamsRejected | KSubConGenericEventParamsGranted; |
|
292 |
|
293 // Register for event |
|
294 TNotificationEventBuf eventBuffer; |
|
295 TRequestStatus eventStatus; |
|
296 subconn.EventNotification(eventBuffer, &filter, 1, eventStatus); |
|
297 |
|
298 // Set Properties of the sub-connection |
|
299 subconn.SetParameters(subconParams); |
|
300 |
|
301 // Destroy parameters |
|
302 CleanupStack::PopAndDestroy(); // subconParams |
|
303 |
|
304 // Open and connect a TCP socket on the sub-connection |
|
305 sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn); |
|
306 sock.Connect(destAddr, status); |
|
307 User::WaitForRequest(status); |
|
308 |
|
309 // Event should be CSubconGenEventParamsGranted/CSubconGenEventParamsRejected |
|
310 User::WaitForRequest(eventStatus); |
|
311 </codeblock> </section> |
|
312 <section id="GUID-6FDFB388-B265-4A7B-9752-AC75DF6C3995"><title>Extracting information from received events example</title> <p>The |
|
313 following example code shows how to extract the information contained within |
|
314 an event notification when it is received. </p> <codeblock id="GUID-BCCE128C-0042-5E36-B22C-35A22A6DFE85" xml:space="preserve">// Create the container for all sub connection parameters |
|
315 RSubConParameterBundle subconParams; |
|
316 CleanupClosePushL(subconParams); |
|
317 |
|
318 ……… |
|
319 ……… |
|
320 // Create and initialise parameters sets as above |
|
321 ……… |
|
322 ……… |
|
323 |
|
324 // Create a new sub-connection |
|
325 subconn.Open(ss, RSubConnection::ECreateNew, conn); |
|
326 |
|
327 // Create filter, register for events, and set parameters as above |
|
328 …… |
|
329 subconn.EventNotification(eventBuffer, &filter, 1, eventStatus); |
|
330 …… |
|
331 |
|
332 // Open and connect a TCP socket on the sub-connection |
|
333 …… |
|
334 |
|
335 // Receive the event notification |
|
336 User::WaitForRequest(eventStatus); |
|
337 |
|
338 CSubConNotificationEvent* event; |
|
339 event = CSubConNotificationEvent::NewL(eventBuffer); |
|
340 CleanupStack::PushL (event); |
|
341 |
|
342 if (event->GroupId() == KSubConnGenericEventsImplUid |
|
343 && event->Id() == CSubConGenEventParamsRejected) |
|
344 { |
|
345 CSubConGenEventParamsRejected* rejectedEvent = |
|
346 static_cast< CSubConGenEventParamsRejected*>(event); |
|
347 |
|
348 TInt error = rejectedEvent->Error(); |
|
349 …… |
|
350 // Do something with the error |
|
351 …… |
|
352 } |
|
353 |
|
354 CleanupStack::PopAndDestroy (event); |
|
355 </codeblock> </section> |
|
356 </conbody></concept> |