<?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-D043376C-29D2-5196-96F4-15E99CFB5639" xml:lang="en"><title> RSubConnection
API Tutorial</title><shortdesc>How to use an <codeph>RSubConnection</codeph>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-254081A7-16C0-45C5-B964-4B47D6EB4590"><title>Procedure</title> <ol id="GUID-C81387B5-9ED3-59ED-A5DC-C6FE807B2E1C">
<li id="GUID-46077726-D57D-5A89-A022-D1EDD45FFE3C"><p>Use the <codeph>Open()</codeph> method
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
already be active. A sub-connection type is passed as a parameter to this
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>,
or creates a sub-connection. When an application calls the <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> API,
a system wide error code is returned. When it is successful, it returns <codeph>KErrNone</codeph>. </p> </li>
<li id="GUID-32926A01-B170-5413-8FAC-0022F80EE1D1"><p>Use the <codeph>Add()</codeph> method
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>
<li id="GUID-BD4E28EF-3DAA-5DC5-8F68-2889C4B826B9"><p>The <codeph>Remove()</codeph> method
returns the socket to the default sub-connection. </p> </li>
<li id="GUID-49044666-971D-59E6-8FBB-3AD1410726B7"><p>Use the <codeph>GetParameters()</codeph> and <codeph>SetParameters()</codeph> methods
are to retrieve and set bundles of properties on the sub-connection. </p> </li>
<li id="GUID-FC5ABE8D-AA9C-502B-8E9F-BC8F2ECB2D1F"><p>The <codeph>GetParameters()</codeph> returns <codeph>KErrNotReady</codeph> if
properties are not negotiated. </p> </li>
<li id="GUID-1B1C7EE8-2B94-5BC9-9797-9D560C5F8E39"><p>The <codeph>SetParameters()</codeph> method,
like the <codeph>Add()</codeph> and <codeph>Remove()</codeph> methods returns
an error code indicating the success or failure of the request to perform
the action. </p> </li>
<li id="GUID-CB745754-DF5D-5392-BA7C-79CB5DA2F708"><p>When the properties
are negotiated either the <codeph>CSubConGenEventParamsGranted</codeph> or <codeph>CSubConGenEventParamsRejected</codeph> event
is notified for each family within the parameter bundle. </p> </li>
<li id="GUID-4D290B37-0C6D-5794-A8C7-3CCDF872FCA8"><p>Use the <codeph>EventNotification()</codeph> methods
to asynchronously register for event notifications. </p> <p>The methods support
filtering of events in two different ways, through a Boolean flag to receive
notification of generic or all events, and through an array of <codeph>TEventFilter</codeph>. </p> </li>
<li id="GUID-9728A1AA-E0AC-589D-A251-B46CB369F90E"><p>Use <xref href="GUID-B25D68E9-BAD2-358F-9FB0-956E3A2AEDCE.dita"><apiname>CancelEventNotification()</apiname></xref> method
cancel the registration for event notifications. </p> </li>
</ol> </section>
<example><title>Connecting to the default SubConnection example</title> <p>In
the following example, the application connects to the default sub-connection
to set the properties. When it has set properties on the default sub-connection,
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;
RConnection conn;
RSubConnection subconn;
RSocket sock;
TRequestStatus status;

// Connect to ESOCK
ss.Connect();

// Open a Connection
conn.Open(ss, KAfInet);

// Start the connection
conn.Start(status);
User::WaitForRequest(status);

// Attach to the default sub-connection
subconn.Open(ss, RSubConnection::EAttachToDefault, conn);

// Set Properties of the default sub-connection
subconn.SetParameters(…);

// Open a TCP socket on the connection (this is the same as using the default sub-connection)
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, conn);

_LIT(KRasAddr,"10.159.24.13");
const TInt KEchoPort = 7;

TInetAddr destAddr;
destAddr.Input(KRasAddr);
destAddr.SetPort(KEchoPort);

// Request the Socket to connect to the destination over the default sub-connection
sock.Connect(destAddr, status);
</codeblock> </example>
<section id="GUID-D707232A-A1B5-4F8F-98D4-D6EBC253DF94"><title>Creating a
sub-connection - Socket connected over the           SubConnection example</title> <p>The
following example shows how an application can use a sub-connection through
an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> instance. It attaches an <codeph>RSocket</codeph> to
the sub-connection. </p> <codeblock id="GUID-F7E8A10E-4A1C-5547-A2F5-783D0A914EA3" xml:space="preserve">RSocketServ ss;
RConnection conn;
RSubConnection subconn;
RSocket sock;
TRequestStatus status;

// Connect to ESOCK
ss.Connect();

// Open an Connection
conn.Open(ss, KAfInet);

// Start the connection
conn.Start(status);
User::WaitForRequest(status);

// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

// Set Properties of the sub-connection
subconn.SetParameters(…);

// Open a TCP socket on the sub-connection
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn);

_LIT(KRasAddr,"10.159.24.13");
const TInt KEchoPort = 7;

TInetAddr destAddr;
destAddr.Input(KRasAddr);
destAddr.SetPort(KEchoPort);

// Request the Socket to connect to the destination over the sub-connection
sock.Connect(destAddr, status);
</codeblock> </section>
<section id="GUID-0766B25A-8073-47E7-A86E-4D172D050064"><title>Creating a
new sub-connection - Adding an already connected           socket example</title> <p>The
following example shows how an application can use a sub-connection through
an <xref href="GUID-0AFDA357-EE44-3788-9CAB-162B874134BF.dita"><apiname>RSubConnection</apiname></xref> instance. 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;
RConnection conn;
RSubConnection subconn;
RSocket sock;
TRequestStatus status;

// Connect to ESOCK
ss.Connect();

// Open a Connection
conn.Open(ss, KAfInet);

// Start the connection
conn.Start(status);
User::WaitForRequest(status);

// Open a TCP socket on the connection
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, conn);

_LIT(KRasAddr,"10.159.24.13");
const TInt KEchoPort = 7;

TInetAddr destAddr;
destAddr.Input(KRasAddr);
destAddr.SetPort(KEchoPort);

// Connect the Socket to the destination over the connection (default sub-connection)
sock.Connect(destAddr, status);

// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

// Set Properties of the sub-connection
subconn.SetParameters(…);

// Move the connected socket onto the new sub-connection
TRequestStatus status;
subconn.Add(sock, status);

// Wait for socket to added
User::WaitForRequest(status);
</codeblock> </section>
<section id="GUID-BC00A713-123E-401D-9E99-BE52C920D71B"><title>Creating and
setting properties for a SubConnection           example</title> <p>The following
example shows how an application creates 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
RSubConParameterBundle subconParams;
CleanupClosePushL(subconParams);

// Create a container for QoS sub connection parameters (Param bundle takes ownership)
CSubConParameterFamily* qosFamily = CSubConParameterFamily::NewL(subconParams,
    KSubConQoSFamily);

// Create the requested generic parameter set for QoS (Qos family takes ownership)
CSubConQosGenericParamSet* reqGenericParams = CSubConQosGenericParamSet::NewL(*qosFamily,                               
    CSubConParameterFamily::ERequested);

// Set the requested Generic Parameters
reqGenericParams-&gt;SetDownlinkBandwidth(128);
reqGenericParams-&gt;SetUplinkBandwidth(64);

// Create the acceptable generic parameter set for QoS (Qos family takes ownership)
CSubConQosGenericParamSet* accGenericParams = CSubConQosGenericParamSet::NewL(*qosFamily,                               
    CSubConParameterFamily::EAcceptable);

// Set the acceptable Generic Parameters
accGenericParams-&gt;SetDownlinkBandwidth(48);
accGenericParams-&gt;SetUplinkBandwidth(32);

// Create a requested technology specific parameter set for QoS (Qos family takes ownership)
CSubConQosR99ParamSet* reqRel99Params = CSubConQosR99ParamSet::NewL(*qosFamily,
    CSubConParameterFamily::ERequested);

// Set the requested Technology Specific Params
reqRel99Params-&gt;SetMaxSDUSize(1024);

// Create a acceptable technology specific parameter set for QoS (Qos family takes ownership)
CSubConQosR99ParamSet* accRel99Params = CSubConQosR99ParamSet::NewL(*qosFamily,
    CSubConParameterFamily::EAcceptable);

// Set the acceptable Technology Specific Params
accRel99Params-&gt;SetMaxSDUSize(512);

// Now open the sub-connection as normal…
………
………
// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

// Set Properties of the sub-connection
subconn.SetParameters(subconParams);

// Destroy parameters
CleanupStack::PopAndDestroy();         // subconParams

// Open a TCP socket on the sub-connection
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn);

_LIT(KRasAddr,"10.159.24.13");
const TInt KEchoPort = 7;

TInetAddr destAddr;
destAddr.Input(KRasAddr);
destAddr.SetPort(KEchoPort);

// Connect the Socket to the destination over the sub-connection
sock.Connect(destAddr, status);
User::WaitForRequest(status);

// Fetch the granted qos
RSubConParameterBundle grantedParams;
subconn.GetParameters(grantedParams);
</codeblock> </section>
<section id="GUID-781F3343-94E7-4BF5-8840-0CDFFB0B99B2"><title>Registering
for events example</title> <p>The following example shows how an application
can register events that occur on a sub-connection. 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
RSubConParameterBundle subconParams;
CleanupClosePushL(subconParams);

………
………
// Create and initialise parameters sets as above
………
………

// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

TNotificationEventBuf eventBuffer;
TRequestStatus eventStatus;
subconn.EventNotification(eventBuffer, EFalse, eventStatus);

// Set Properties of the sub-connection
subconn.SetParameters(subconParams);

// Destroy parameters
CleanupStack::PopAndDestroy();         // subconParams

// Open and connect a TCP socket on the sub-connection
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn);
sock.Connect(destAddr, status);
User::WaitForRequest(status);

// Negotiation may not occur until a socket is assigned to the sub-connection
// First event should be cSubConGenEventDataClientJoining
User::WaitForRequest(eventStatus);

// Next we’d expect a CSubconGenEventParamsGranted/ CSubconGenEventParamsRejected
subconn.EventNotification(eventBuffer, EFalse, eventStatus);
User::WaitForRequest(eventStatus);
</codeblock> <p><b>Registering for events – Using filters</b> </p> <p>The
following example code shows how to register for specific events using filters.
In this example the application registers for notification when sub-connection
parameters are granted or rejected. Each <xref href="GUID-FDE12D94-17D3-3646-B645-26A08926F86C.dita"><apiname>TEventFilter</apiname></xref> contains
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
RSubConParameterBundle subconParams;
CleanupClosePushL(subconParams);

………
………
// Create and initialise parameters sets as above
………
………

// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

// Create event filter
TEventFilter filter;
filter.iEventGroupUid = KSubConnGenericEventsImplUid;
filter.iEventMask = KSubConGenericEventParamsRejected | KSubConGenericEventParamsGranted;

// Register for event
TNotificationEventBuf eventBuffer;
TRequestStatus eventStatus;
subconn.EventNotification(eventBuffer, &amp;filter, 1, eventStatus);

// Set Properties of the sub-connection
subconn.SetParameters(subconParams);

// Destroy parameters
CleanupStack::PopAndDestroy();         // subconParams

// Open and connect a TCP socket on the sub-connection
sock.Open(ss, KAfInet, KSockStream, KProtocolInetTcp, subconn);
sock.Connect(destAddr, status);
User::WaitForRequest(status);

// Event should be CSubconGenEventParamsGranted/CSubconGenEventParamsRejected
User::WaitForRequest(eventStatus);
</codeblock> </section>
<section id="GUID-6FDFB388-B265-4A7B-9752-AC75DF6C3995"><title>Extracting
information from received events example</title> <p>The following example
code shows how to extract the information contained within 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
RSubConParameterBundle subconParams;
CleanupClosePushL(subconParams);

………
………
// Create and initialise parameters sets as above
………
………

// Create a new sub-connection
subconn.Open(ss, RSubConnection::ECreateNew, conn);

// Create filter, register for events, and set parameters as above
……
subconn.EventNotification(eventBuffer, &amp;filter, 1, eventStatus);
……

// Open and connect a TCP socket on the sub-connection
……

// Receive the event notification
User::WaitForRequest(eventStatus);

CSubConNotificationEvent* event;
event = CSubConNotificationEvent::NewL(eventBuffer);
CleanupStack::PushL (event);

if (event-&gt;GroupId() == KSubConnGenericEventsImplUid
    &amp;&amp; event-&gt;Id() == CSubConGenEventParamsRejected)
    {
    CSubConGenEventParamsRejected* rejectedEvent =
        static_cast&lt; CSubConGenEventParamsRejected*&gt;(event);

    TInt error = rejectedEvent-&gt;Error();
    ……
    // Do something with the error
    ……
    }

CleanupStack::PopAndDestroy (event);
</codeblock> </section>
</conbody></concept>