|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280" xml:lang="en"><title>Socket |
|
13 Server Reference</title><shortdesc>This topic provides a summary of related documentation for the |
|
14 ESock APIs. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
15 |
|
16 <section id="GUID-0D8CE9A1-7056-4A0B-A3D7-8469F9029341"><p>Socket Server APIs: </p> </section> |
|
17 <table id="GUID-C269B63A-A1D7-5A4B-8608-65462143CBA6"> |
|
18 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
19 <thead> |
|
20 <row> |
|
21 <entry>Server session APIs</entry> |
|
22 <entry/> |
|
23 <entry>Header</entry> |
|
24 <entry>Description</entry> |
|
25 </row> |
|
26 </thead> |
|
27 <tbody> |
|
28 <row> |
|
29 |
|
30 <entry><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref> </p> <p> </p> <p> </p> <p> </p> <p> </p> <p> </p> <p> </p> <p> </p> </entry> |
|
31 <entry><p> </p> </entry> |
|
32 <entry><p>ES_SOCK.H </p> </entry> |
|
33 <entry><p>RSocketServ establishes and reserves resources for the base communication |
|
34 session to the socket server. All other client interfaces require a valid |
|
35 session to be opened </p> </entry> |
|
36 </row> |
|
37 <row> |
|
38 |
|
39 <entry><p> <b>RSocketServ Subsession APIs</b> </p> </entry> |
|
40 </row> |
|
41 <row> |
|
42 <entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> </p> </entry> |
|
43 <entry><p>ES_SOCK.H </p> </entry> |
|
44 <entry><p>End point for all socket-based communications. </p> </entry> |
|
45 </row> |
|
46 <row> |
|
47 <entry><p> <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> </p> </entry> |
|
48 <entry><p>ES_SOCK.H </p> </entry> |
|
49 <entry><p>Makes host name resolution queries. </p> </entry> |
|
50 </row> |
|
51 <row> |
|
52 <entry><p> <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> </p> </entry> |
|
53 <entry><p>ES_SOCK.H </p> </entry> |
|
54 <entry><p>Used to startup and manage active connections. It is possible to |
|
55 start a connection either implicitly, via the RSocket or RHostResolver APIs, |
|
56 or explicitly via the RConnection API. The RConnection creates a default subconnection. </p> <p> <xref href="GUID-5CFC075C-8F53-5E1B-A111-C6F4567DFD1E.dita">RConnection API Reference</xref> </p> </entry> |
|
57 </row> |
|
58 <row> |
|
59 <entry><p> <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> </p> </entry> |
|
60 <entry><p>ES_SOCK.H </p> </entry> |
|
61 <entry><p>Used to organise channels within a connection and manage Quality |
|
62 of Service. Multihoming-aware applications must use this API. Only valid in |
|
63 the context of an RConnection. </p> </entry> |
|
64 </row> |
|
65 <row> |
|
66 <entry><p> <xref href="GUID-7489739B-3608-3F9F-BB02-DE65D7AA53A2.dita"><apiname>RNetDatabase</apiname></xref> </p> </entry> |
|
67 <entry><p>ES_SOCK.H </p> </entry> |
|
68 <entry><p>Interface for network database access. </p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p> <xref href="GUID-DDD32F28-BA89-3CA1-93B0-355CDD9CD92D.dita"><apiname>RServiceResolver</apiname></xref> </p> </entry> |
|
72 <entry><p>ES_SOCK.H </p> </entry> |
|
73 <entry><p>Provides an interface to resolve service names and ports. </p> </entry> |
|
74 </row> |
|
75 <row> |
|
76 <entry><p> <xref href="GUID-55FE59B7-4FA9-3B1A-BD4C-9B7611FE75C2.dita"><apiname>RConnectionServ</apiname></xref> </p> </entry> |
|
77 <entry/> |
|
78 <entry><p>ES_SOCK.H </p> </entry> |
|
79 <entry><p>Provides access to the Comms Management Plane, including Access |
|
80 Point queries. </p> </entry> |
|
81 </row> |
|
82 </tbody> |
|
83 </tgroup> |
|
84 </table> |
|
85 |
|
86 <section id="GUID-2214B4F9-FC01-4B86-B9CB-3A9A3769CE9C"><p>Bearer Mobility APIs </p> </section> |
|
87 <table id="GUID-DDBADF88-8197-5C9A-AC0E-42099252DC93"> |
|
88 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
89 <thead> |
|
90 <row> |
|
91 <entry>Bearer mobility APIs</entry> |
|
92 <entry>Header</entry> |
|
93 <entry>Description</entry> |
|
94 </row> |
|
95 </thead> |
|
96 <tbody> |
|
97 <row> |
|
98 <entry><p> <xref href="GUID-6CA83252-4D0C-3B72-83ED-B5152B666C83.dita"><apiname>CActiveCommsMobilityApiExt</apiname></xref> </p> </entry> |
|
99 <entry><p>es_mobility_apiext.h </p> </entry> |
|
100 <entry><p>Comms Mobility API extension for application client running an Active |
|
101 Scheduler. </p> </entry> |
|
102 </row> |
|
103 <row> |
|
104 <entry><p> <xref href="GUID-D5F43DFB-5143-3563-8655-16E245A9735F.dita"><apiname>RCommsMobilityApiExt</apiname></xref> </p> </entry> |
|
105 <entry><p>es_mobility_apiext.h </p> </entry> |
|
106 <entry><p>Comms Mobility API extension for application client not running |
|
107 an Active Scheduler. </p> </entry> |
|
108 </row> |
|
109 <row> |
|
110 <entry><p> <xref href="GUID-9A3979A9-F882-3053-B5B1-E0E125774271.dita"><apiname>MMobilityProtocolResp</apiname></xref> </p> </entry> |
|
111 <entry><p>es_mobility_apiext.h </p> </entry> |
|
112 <entry><p>Interface to be implemented by the application client to support |
|
113 mobility API extension. See <xref href="GUID-CB1E1921-9CF7-55B7-9F70-6AD61A961208.dita">Bearer |
|
114 Mobility Client</xref>. </p> </entry> |
|
115 </row> |
|
116 </tbody> |
|
117 </tgroup> |
|
118 </table> |
|
119 |
|
120 <section id="GUID-3CBE467D-11B7-40F7-B681-D40F4D48D18F"><p>How APIs related to the 3-Plane Comms Architecture. </p> <fig id="GUID-FC69453E-CA12-5CDB-A7E6-B2FA542BBE06"> |
|
121 <title> Figure 1 - How ESock APIs related to the 3-Plane Comms Architecture |
|
122 </title> |
|
123 <image href="GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e120838_href.png" placement="inline"/> |
|
124 </fig> <p>The Sockets Client API also defines a number of support classes |
|
125 used in conjunction with the above interfaces. These encapsulate: </p> <ul> |
|
126 <li id="GUID-A1132B04-61D5-53E5-85A5-E7BBFA598B72"><p> <i>Addresses</i>: a |
|
127 base address class <xref href="GUID-66228064-B6E7-3CE9-8F5E-5DED4CD9A49B.dita"><apiname>TSockAddr</apiname></xref> is defined. Specific protocol |
|
128 address classes are derived from this. Each address can be identified by its |
|
129 Protocol Family, an integer which identifies protocol suites from others. </p> </li> |
|
130 <li id="GUID-BBD21B5C-20EE-5BC9-BEE4-00CB1565DE1E"><p> <i>Resolution queries</i>: |
|
131 queries made through <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> objects are packaged |
|
132 in <xref href="GUID-C625E339-6726-3FB9-8F8A-F4DB0CAC15FF.dita"><apiname>TNameEntry</apiname></xref> descriptors. These are packages for <xref href="GUID-567CF5B5-464F-37B7-A91E-6A672C39BA44.dita"><apiname>TNameRecord</apiname></xref> objects |
|
133 that contain <xref href="GUID-66228064-B6E7-3CE9-8F5E-5DED4CD9A49B.dita"><apiname>TSockAddr</apiname></xref> objects to pass in addresses. </p> </li> |
|
134 <li id="GUID-EFB76FB6-00D2-5C01-BE59-B748CAAAC61E"><p> <i>Protocol information</i>: |
|
135 a comprehensive description of a protocol’s capabilities and properties can |
|
136 be dynamically obtained through the <xref href="GUID-0FB20F20-67EE-3948-B9F6-E1D679AC3D0F.dita"><apiname>TProtocolDesc</apiname></xref> class. |
|
137 Capabilities are identified by constants. </p> </li> |
|
138 <li id="GUID-4BD6B3AA-4711-55BE-8F34-88B28EC2657F"><p> <i>Endian issues</i>: <xref href="GUID-8183BE9B-6118-3472-A271-8409751CA5EF.dita"><apiname>BigEndian</apiname></xref>, <xref href="GUID-55FDB45E-2759-3192-AEE2-D600B232682B.dita"><apiname>LittleEndian</apiname></xref>, |
|
139 and <xref href="GUID-A934C24D-0E90-3D33-B4FC-654FB9004CFC.dita"><apiname>ByteOrder</apiname></xref> can be used to order integers to and from |
|
140 network order. </p> </li> |
|
141 </ul> </section> |
|
142 <section id="GUID-7803B89A-6ABF-529C-A0B8-CA06BA410F3B"><title>RSubConnection |
|
143 Events</title> <p> <b>CSubConGenEventDataClientJoined</b>, <b>CSubConGenEventDataClientLeft</b> </p> <p>These |
|
144 two events derive from <xref href="GUID-1C0CC85E-38A7-3E7A-9246-940DCCE44EB0.dita"><apiname>CSubConGenEventDataClientBase</apiname></xref>, which |
|
145 provides the functionality for both. The source and destination end points |
|
146 of the data client are presented with this event, along with the IAP ID of |
|
147 the connection on which it was created. </p> <p> <b>CSubConNotificationEvent</b> </p> <p>Both |
|
148 generic and extension sub-connection events derive from this class. The rules |
|
149 for generic and extension events are the same as for parameter sets. That |
|
150 is, a generic event MUST be able to be understood by all technologies. </p> <p>The <codeph>IsGeneric()</codeph> method |
|
151 identifies whether the event is generic. </p> <p>The <codeph>GroupId()</codeph> method |
|
152 returns the UID of the factory that contains the event, and <codeph>Id()</codeph> returns |
|
153 the class type Id within that factory. These two pieces of information comprise |
|
154 the <xref href="GUID-FEE87408-3FAA-31BB-A0C2-4BDEB279D4BA.dita"><apiname>STypeId</apiname></xref> of the event. </p> <p> <b>CSubConGenEventParamsGranted</b> </p> <p>Notification |
|
155 of this event occurs after a request to <codeph>SetParameters()</codeph> has |
|
156 been made and negotiation with the network has been completed. A notification |
|
157 will be received for each family contained in the parameter bundle that was |
|
158 negotiated successfully. This event presents a generic set and zero or more |
|
159 extension sets (providing they are supported by the underlying sub-connection |
|
160 provider technology) of the parameter family identified by the Id returned |
|
161 from <codeph>GetFamily()</codeph>. </p> <p> <b>CSubConGenEventParamsRejected</b> </p> <p>Notification |
|
162 of this event occurs after a request to <codeph>SetParameters()</codeph> has |
|
163 been made and negotiation with the network has failed for some reason. It |
|
164 could be an error within the handset software/configuration, or that the network |
|
165 could not provide the acceptable (minimum) level of QoS. The reason for failure |
|
166 and the parameter family are presented by the accessor methods <codeph>Error()</codeph> and <codeph>FamilyId()</codeph>. |
|
167 Like the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> event, a notification |
|
168 for <xref href="GUID-7103CFA3-2119-3356-9460-B26D88036FEB.dita"><apiname>CSubConGenEventParamsRejected</apiname></xref> is received for each |
|
169 family in the parameter bundle that could not be negotiated successfully. </p> <p> <b>CSubConGenEventParamsChanged</b> </p> <p>This |
|
170 event occurs when the properties of a parameter family has been renegotiated |
|
171 due to some event on the network. It is not sent in response to a request |
|
172 to change the properties. The change could be the result of an error or just |
|
173 that the level of QoS has improved/worsened. If a new set of parameters are |
|
174 available they’ll be presented as with the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> event. |
|
175 The error status is presented via the <codeph>Error()</codeph> method. </p> <p> <b>CSubConGenEventSubConDown</b> </p> <p>This |
|
176 event occurs when the underlying sub-connection has been lost. This could |
|
177 be due to request for it to be closed, or some error on the network. The error |
|
178 status is presented via the <codeph>Error()</codeph> method. </p> </section> |
|
179 <section id="GUID-7F057E16-0E56-5989-8647-7DAFF6E343D3"><title>RSubConnection |
|
180 QoS Parameters</title> <p> <b>CSubConQosGenericParamSet</b> </p> <table id="GUID-227CFC6C-C38B-516F-AB6D-C3C2D51EA4A3"> |
|
181 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
182 <thead> |
|
183 <row> |
|
184 <entry> Parameter </entry> |
|
185 <entry> Description </entry> |
|
186 <entry>Directions</entry> |
|
187 </row> |
|
188 </thead> |
|
189 <tbody> |
|
190 <row> |
|
191 <entry><p>Bandwidth </p> </entry> |
|
192 <entry><p>Bandwidth the client requires </p> </entry> |
|
193 <entry><p>Uplink / Downlink </p> </entry> |
|
194 </row> |
|
195 <row> |
|
196 <entry><p>Maximum Burst Size </p> </entry> |
|
197 <entry><p>Maximum size of a burst of data the client can handle </p> </entry> |
|
198 <entry><p>Uplink / Downlink </p> </entry> |
|
199 </row> |
|
200 <row> |
|
201 <entry><p>Average Packet Size </p> </entry> |
|
202 <entry><p>Average packet size required (e.g. codec use) </p> </entry> |
|
203 <entry><p>Uplink / Downlink </p> </entry> |
|
204 </row> |
|
205 <row> |
|
206 <entry><p>Maximum Packet Size </p> </entry> |
|
207 <entry><p>Maximum packet size the client can handle </p> </entry> |
|
208 <entry><p>Uplink / Downlink </p> </entry> |
|
209 </row> |
|
210 <row> |
|
211 <entry><p>Delay </p> </entry> |
|
212 <entry><p>Acceptable Delay/Latency </p> </entry> |
|
213 <entry><p>Uplink / Downlink </p> </entry> |
|
214 </row> |
|
215 <row> |
|
216 <entry><p>Delay Variation </p> </entry> |
|
217 <entry><p>Acceptable variation in delay (also known as jitter) </p> </entry> |
|
218 <entry><p>Uplink / Downlink </p> </entry> |
|
219 </row> |
|
220 <row> |
|
221 <entry><p>Priority </p> </entry> |
|
222 <entry><p>Relative priority the client expects to give this channel compared |
|
223 to it’s other channels </p> </entry> |
|
224 <entry><p>Uplink / Downlink </p> </entry> |
|
225 </row> |
|
226 <row> |
|
227 <entry><p>Header mode </p> </entry> |
|
228 <entry><p>Specify whether the header size should be calculated by the QoS |
|
229 module or specified by the client. Default is to let the QoS module calculate |
|
230 it. </p> </entry> |
|
231 <entry><p>N/A </p> </entry> |
|
232 </row> |
|
233 <row> |
|
234 <entry><p>Name </p> </entry> |
|
235 <entry><p>Identity of a “well known” set of QoS Parameters. </p> </entry> |
|
236 <entry><p>N/A </p> </entry> |
|
237 </row> |
|
238 </tbody> |
|
239 </tgroup> |
|
240 </table> <p>If an extension parameter set is added to the family that contains |
|
241 conceptually identical parameters to those in the generic set, it is recommended |
|
242 that you set both instances (generic and extension) of those parameters. </p> <p> <b>CSubConQosIPLinkR99ParamSet</b> / <b>CSubConQosR99ParamSet</b> </p> <p>Getter and setter methods are provided for each parameter. </p> <p> <b>Note: </b> The |
|
243 constants used for it are <xref href="GUID-04E17A74-BFAB-3DB7-998B-5BCB8A5FB4CC.dita"><apiname>KSubConIPParamsUid</apiname></xref> and <xref href="GUID-41202CC9-3547-3404-AF6C-678A36BAE7D9.dita"><apiname>KSubConQosIPLinkR99ParamsType</apiname></xref>. </p> <p>The |
|
244 following parameter sets are available in Symbian platform. </p> <p> <b>CSubConQosR5ParamSet</b> </p> <p>It |
|
245 inherits from the release 4/99 set <codeph>CSubConQosR99ParamSet</codeph>. |
|
246 Although it is possible to add both this parameter set and the R4/R99 one, |
|
247 it is not necessary and should not be done. </p> <p> <b>CSubConIMSExtParamSet</b> </p> <p>This |
|
248 class contains the IM CN Signalling Indicator flag. </p> </section> |
|
249 |
|
250 <section id="GUID-8797CEEF-CC6D-4B72-9C85-1B0E0188AA58"><title>Test programs</title> <p>None </p> </section> |
|
251 |
|
252 </refbody></reference> |