<?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 <apiname>RSubConnection</apiname>. </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->SetDownlinkBandwidth(128);

reqGenericParams->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->SetDownlinkBandwidth(48);

accGenericParams->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->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->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, &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, &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->GroupId() == KSubConnGenericEventsImplUid

    && event->Id() == CSubConGenEventParamsRejected)

    {

    CSubConGenEventParamsRejected* rejectedEvent =

        static_cast< CSubConGenEventParamsRejected*>(event);

    TInt error = rejectedEvent->Error();

    ……

    // Do something with the error

    ……

    }

CleanupStack::PopAndDestroy (event);

</codeblock> </section>

</conbody></concept>