--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-D043376C-29D2-5196-96F4-15E99CFB5639.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,356 @@
+<?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-&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>
\ No newline at end of file