<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280" xml:lang="en"><title>Socket
Server Reference</title><shortdesc>This topic provides a summary of related documentation for the
ESock APIs. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>

<section id="GUID-0D8CE9A1-7056-4A0B-A3D7-8469F9029341"><p>Socket Server APIs: </p> </section>
<table id="GUID-C269B63A-A1D7-5A4B-8608-65462143CBA6">
<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<thead>
<row>
<entry>Server session APIs</entry>
<entry/>
<entry>Header</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>

<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>
<entry><p> </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>RSocketServ establishes and reserves resources for the base communication
session to the socket server. All other client interfaces require a valid
session to be opened </p> </entry>
</row>
<row>

<entry><p> <b>RSocketServ Subsession APIs</b>  </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>End point for all socket-based communications. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Makes host name resolution queries. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Used to startup and manage active connections. It is possible to
start a connection either implicitly, via the RSocket or RHostResolver APIs,
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>
</row>
<row>
<entry><p> <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Used to organise channels within a connection and manage Quality
of Service. Multihoming-aware applications must use this API. Only valid in
the context of an RConnection. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-7489739B-3608-3F9F-BB02-DE65D7AA53A2.dita"><apiname>RNetDatabase</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Interface for network database access. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-DDD32F28-BA89-3CA1-93B0-355CDD9CD92D.dita"><apiname>RServiceResolver</apiname></xref>  </p> </entry>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Provides an interface to resolve service names and ports. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-55FE59B7-4FA9-3B1A-BD4C-9B7611FE75C2.dita"><apiname>RConnectionServ</apiname></xref>  </p> </entry>
<entry/>
<entry><p>ES_SOCK.H </p> </entry>
<entry><p>Provides access to the Comms Management Plane, including Access
Point queries. </p> </entry>
</row>
</tbody>
</tgroup>
</table>

<section id="GUID-2214B4F9-FC01-4B86-B9CB-3A9A3769CE9C"><p>Bearer Mobility APIs </p> </section>
<table id="GUID-DDBADF88-8197-5C9A-AC0E-42099252DC93">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Bearer mobility APIs</entry>
<entry>Header</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-6CA83252-4D0C-3B72-83ED-B5152B666C83.dita"><apiname>CActiveCommsMobilityApiExt</apiname></xref>  </p> </entry>
<entry><p>es_mobility_apiext.h </p> </entry>
<entry><p>Comms Mobility API extension for application client running an Active
Scheduler. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-D5F43DFB-5143-3563-8655-16E245A9735F.dita"><apiname>RCommsMobilityApiExt</apiname></xref>  </p> </entry>
<entry><p>es_mobility_apiext.h </p> </entry>
<entry><p>Comms Mobility API extension for application client not running
an Active Scheduler. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-9A3979A9-F882-3053-B5B1-E0E125774271.dita"><apiname>MMobilityProtocolResp</apiname></xref>  </p> </entry>
<entry><p>es_mobility_apiext.h </p> </entry>
<entry><p>Interface to be implemented by the application client to support
mobility API extension. See <xref href="GUID-CB1E1921-9CF7-55B7-9F70-6AD61A961208.dita">Bearer
Mobility Client</xref>. </p> </entry>
</row>
</tbody>
</tgroup>
</table>

<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">
<title>           Figure 1 - How ESock APIs related to the 3-Plane Comms Architecture
         </title>
<image href="GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e114300_href.png" placement="inline"/>
</fig> <p>The Sockets Client API also defines a number of support classes
used in conjunction with the above interfaces. These encapsulate: </p> <ul>
<li id="GUID-A1132B04-61D5-53E5-85A5-E7BBFA598B72"><p> <i>Addresses</i>: a
base address class <xref href="GUID-66228064-B6E7-3CE9-8F5E-5DED4CD9A49B.dita"><apiname>TSockAddr</apiname></xref> is defined. Specific protocol
address classes are derived from this. Each address can be identified by its
Protocol Family, an integer which identifies protocol suites from others. </p> </li>
<li id="GUID-BBD21B5C-20EE-5BC9-BEE4-00CB1565DE1E"><p> <i>Resolution queries</i>:
queries made through <xref href="GUID-B16CAD6D-85B1-3482-AAC0-9BADEDB6ABDD.dita"><apiname>RHostResolver</apiname></xref> objects are packaged
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
that contain <xref href="GUID-66228064-B6E7-3CE9-8F5E-5DED4CD9A49B.dita"><apiname>TSockAddr</apiname></xref> objects to pass in addresses. </p> </li>
<li id="GUID-EFB76FB6-00D2-5C01-BE59-B748CAAAC61E"><p> <i>Protocol information</i>:
a comprehensive description of a protocol’s capabilities and properties can
be dynamically obtained through the <xref href="GUID-0FB20F20-67EE-3948-B9F6-E1D679AC3D0F.dita"><apiname>TProtocolDesc</apiname></xref> class.
Capabilities are identified by constants. </p> </li>
<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>,
and <xref href="GUID-A934C24D-0E90-3D33-B4FC-654FB9004CFC.dita"><apiname>ByteOrder</apiname></xref> can be used to order integers to and from
network order. </p> </li>
</ul> </section>
<section id="GUID-7803B89A-6ABF-529C-A0B8-CA06BA410F3B"><title>RSubConnection
Events</title> <p> <b>CSubConGenEventDataClientJoined</b>, <b>CSubConGenEventDataClientLeft</b>  </p> <p>These
two events derive from <xref href="GUID-1C0CC85E-38A7-3E7A-9246-940DCCE44EB0.dita"><apiname>CSubConGenEventDataClientBase</apiname></xref>, which
provides the functionality for both. The source and destination end points
of the data client are presented with this event, along with the IAP ID of
the connection on which it was created. </p> <p> <b>CSubConNotificationEvent</b>  </p> <p>Both
generic and extension sub-connection events derive from this class. The rules
for generic and extension events are the same as for parameter sets. That
is, a generic event MUST be able to be understood by all technologies. </p> <p>The <codeph>IsGeneric()</codeph> method
identifies whether the event is generic. </p> <p>The <codeph>GroupId()</codeph> method
returns the UID of the factory that contains the event, and <codeph>Id()</codeph> returns
the class type Id within that factory. These two pieces of information comprise
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
of this event occurs after a request to <codeph>SetParameters()</codeph> has
been made and negotiation with the network has been completed. A notification
will be received for each family contained in the parameter bundle that was
negotiated successfully. This event presents a generic set and zero or more
extension sets (providing they are supported by the underlying sub-connection
provider technology) of the parameter family identified by the Id returned
from <codeph>GetFamily()</codeph>. </p> <p> <b>CSubConGenEventParamsRejected</b>  </p> <p>Notification
of this event occurs after a request to <codeph>SetParameters()</codeph> has
been made and negotiation with the network has failed for some reason. It
could be an error within the handset software/configuration, or that the network
could not provide the acceptable (minimum) level of QoS. The reason for failure
and the parameter family are presented by the accessor methods <codeph>Error()</codeph> and <codeph>FamilyId()</codeph>.
Like the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> event, a notification
for <xref href="GUID-7103CFA3-2119-3356-9460-B26D88036FEB.dita"><apiname>CSubConGenEventParamsRejected</apiname></xref> is received for each
family in the parameter bundle that could not be negotiated successfully. </p> <p> <b>CSubConGenEventParamsChanged</b>  </p> <p>This
event occurs when the properties of a parameter family has been renegotiated
due to some event on the network. It is not sent in response to a request
to change the properties. The change could be the result of an error or just
that the level of QoS has improved/worsened. If a new set of parameters are
available they’ll be presented as with the <xref href="GUID-AA6CFA1E-0B17-3603-9065-34D05322C0A5.dita"><apiname>CSubConGenEventParamsGranted</apiname></xref> event.
The error status is presented via the <codeph>Error()</codeph> method. </p> <p> <b>CSubConGenEventSubConDown</b>  </p> <p>This
event occurs when the underlying sub-connection has been lost. This could
be due to request for it to be closed, or some error on the network. The error
status is presented via the <codeph>Error()</codeph> method. </p> </section>
<section id="GUID-7F057E16-0E56-5989-8647-7DAFF6E343D3"><title>RSubConnection
QoS Parameters</title> <p> <b>CSubConQosGenericParamSet</b>  </p> <table id="GUID-227CFC6C-C38B-516F-AB6D-C3C2D51EA4A3">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry> Parameter </entry>
<entry> Description </entry>
<entry>Directions</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Bandwidth </p> </entry>
<entry><p>Bandwidth the client requires </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Maximum Burst Size </p> </entry>
<entry><p>Maximum size of a burst of data the client can handle </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Average Packet Size </p> </entry>
<entry><p>Average packet size required (e.g. codec use) </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Maximum Packet Size </p> </entry>
<entry><p>Maximum packet size the client can handle </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Delay </p> </entry>
<entry><p>Acceptable Delay/Latency </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Delay Variation </p> </entry>
<entry><p>Acceptable variation in delay (also known as jitter) </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Priority </p> </entry>
<entry><p>Relative priority the client expects to give this channel compared
to it’s other channels </p> </entry>
<entry><p>Uplink / Downlink </p> </entry>
</row>
<row>
<entry><p>Header mode </p> </entry>
<entry><p>Specify whether the header size should be calculated by the QoS
module or specified by the client. Default is to let the QoS module calculate
it. </p> </entry>
<entry><p>N/A </p> </entry>
</row>
<row>
<entry><p>Name </p> </entry>
<entry><p>Identity of a “well known” set of QoS Parameters. </p> </entry>
<entry><p>N/A </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>If an extension parameter set is added to the family that contains
conceptually identical parameters to those in the generic set, it is recommended
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
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
following parameter sets are available in Symbian platform. </p> <p> <b>CSubConQosR5ParamSet</b>  </p> <p>It
inherits from the release 4/99 set <codeph>CSubConQosR99ParamSet</codeph>.
Although it is possible to add both this parameter set and the R4/R99 one,
it is not necessary and should not be done. </p> <p> <b>CSubConIMSExtParamSet</b>  </p> <p>This
class contains the IM CN Signalling Indicator flag. </p> </section>

<section id="GUID-8797CEEF-CC6D-4B72-9C85-1B0E0188AA58"><title>Test programs</title> <p>None </p> </section>

</refbody></reference>