<?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 concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-8E158109-AE22-5216-90E8-63A4BD4CC90B" xml:lang="en"><title> Opening
a Socket Server connection: Tutorial</title><shortdesc>This tutorial describes how an application can open and manage
a connection to the Socket Server. Other Socket Server tutorials build upon
this tutorial. The Socket Server is also known as ESock. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Connecting to the Socket Server</title><p>The <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocketServ</apiname></xref> class
provides the <xref href="GUID-408D4D7E-FCD1-3ECF-AD62-6DA52E9580F5.dita"><apiname>Connect()</apiname></xref> function to create a session to
the socket server. </p></section>
<section><title>Procedure</title><p>The steps to connect and then close a
session with the Socket Server are: </p><ul>
<li><p>   Call one of the <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita#GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449/GUID-C9E237C5-DCFB-3F66-87E5-63425156995C"><apiname>RSocketServ::Connect()</apiname></xref>    functions.
 </p> </li>
<li><p>   Perform socket operations  </p> </li>
<li><p>   Call <codeph>Close</codeph> to end the session with the Socket Server
   </p> </li>
</ul></section>
<section><title>Example</title><codeblock xml:space="preserve">RSocketServ ss;

// Connect to ESOCK
ss.Connect();

// Perform operations on the socket server
...

// Close the connection
ss.Close();
</codeblock></section>
<section><title>Further considerations</title><p> The <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita#GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449/GUID-C9E237C5-DCFB-3F66-87E5-63425156995C"><apiname>RSocketServ::Connect()</apiname></xref> function
allows optional extra information to be sent to the Socket Server to change
the performance of the connection. Two optional parameters are available:
 </p><ol>
<li id="GUID-A41FB7DA-2EE4-460F-9698-70A50FB682EB"><p><b>Message Slots</b> - If the client application expects to   keep
a large number of requests open at the same time, then the client   application
can increase the message slots available to the connection.</p></li>
<li id="GUID-FDEF0A30-F872-49DF-A7EC-3B975040E5DC"><p><b>Protocol Preference</b> - If the client application will   use the
connection to interact with only one protocol, then this protocol   should
be specified. The Socket Server uses the preferred protocol to improve   the
efficiency of the messages between the client application and the protocol</p></li>
</ol></section>
<section id="GUID-5AA882EF-269B-54A6-8CDB-B1E9F26BB7D5"><p>The <codeph>RSocketServ</codeph> connection
allows a number of <xref href="GUID-D0D27AEA-FDDB-5F6F-94F6-ADDF5910DC47.dita">sub-connections</xref> that
offer more functionality. The sub-connections available are: </p> <ul>
<li id="GUID-8C317F12-D19A-5B61-A88E-E1BC10BBFE78"><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RConnection</apiname></xref>  </p> </li>
<li id="GUID-DA08493B-DB72-57F0-9CB9-CF4BE80A94E9"><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSubConnection</apiname></xref>  </p> </li>
<li id="GUID-28A3F706-7A81-5F72-8E66-0D236EDE6A40"><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RSocket</apiname></xref>  </p> </li>
<li id="GUID-F0D169F8-7C22-5AC1-BF22-EAC4D07B9E21"><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RHostResolver</apiname></xref>  </p> </li>
<li id="GUID-3A4ADFEA-4FCD-54DD-8367-0A42D21A67A6"><p> <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita"><apiname>RNetDatabase</apiname></xref>  </p> </li>
</ul> <p>The purpose of each of these sub-connections is described in the
. </p> <p><b>Procedure</b> </p> <p>The
procedure to attach any of these sub-connections is: </p> <ol id="GUID-E146CDDE-DE2C-579C-901F-073C63C61F6D">
<li id="GUID-E67862A6-17E4-5F5D-8A45-F7F8BEA01E04"><p>Create or use an existing <codeph>RSocketServ</codeph> session. </p> </li>
<li id="GUID-C2AD2B55-F247-5D27-B368-4467E05D5800"><p>Call the <codeph>Open()</codeph> function
on the object for the sub-connection class. Pass into the <codeph>Open()</codeph> function
a reference to the <codeph>RSocketServ</codeph> session. </p> </li>
<li id="GUID-18FF884F-8930-5851-9ECD-6B9BA55A48B2"><p>Perform sub-connection
operations </p> </li>
<li id="GUID-0A21C702-5125-55D1-8313-E1E7D1949C54"><p>Call <codeph>Close</codeph> to
end the sub-session </p> </li>
</ol> <p id="GUID-F5AEE180-B9A9-542E-84C9-2C505FD75AA4-GENID-1-10-1-8-1-1-10-1-5-1-4-1-3-1-3-5-7"><b>Example 1: Socket (RSocket)</b> </p> <codeblock id="GUID-FB43255E-E22E-5818-B00D-9351DA7B1BFF" xml:space="preserve">RSocketServ ss;
RSocket sock;

// Connect to the Sockets Server
ss.Connect();

// open a socket
sock.Open(ss);

// Perform operations on the socket
...

// Close the socket connection
sock.Close();
</codeblock> <p id="GUID-F5AEE180-B9A9-542E-84C9-2C505FD75AA4-GENID-1-10-1-8-1-1-10-1-5-1-4-1-3-1-3-5-9"><b>Example 2: Connection Management
(RConnection)</b> </p> <codeblock id="GUID-BA4575AA-B370-594C-AAE0-8D2D970CA4E0" xml:space="preserve">RSocketServ ss;
RConnection conn;

// Connect to the Sockets Server
ss.Connect();

// Open the Connection Management sub-connection
conn.Open(ss);

// Perform operations on the connection
...

// Close the sub-connection and connection
ss.Close();
</codeblock> <p>This example shows that you do not need to close sub-connections
explicitly. If you close the RSocketServ connection, the Comms Framework closes
all attached sub-connections. </p> </section>
</conbody><related-links>
<link href="GUID-E34D0F11-4B34-575C-BE78-8EAD13E9CD64.dita"><linktext>How to  
              Start and Close a Management Plane session: Tutorial</linktext>
</link>
<link href="GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita"><linktext>Socket Server
Reference</linktext></link>
</related-links></concept>