RSubConnection -API Tutorial

Procedure

Use the Open() method -to open an RSubConnection object on an ESOCK session.

The RConnection 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 RConnection, -or creates a sub-connection. When an application calls the RSubConnection API, -a system wide error code is returned. When it is successful, it returns KErrNone.
Use the Add() method -to move the socket from the default sub-connection to the RSubConnection.
The Remove() method -returns the socket to the default sub-connection.
Use the GetParameters() and SetParameters() methods -are to retrieve and set bundles of properties on the sub-connection.
The GetParameters() returns KErrNotReady if -properties are not negotiated.
The SetParameters() method, -like the Add() and Remove() methods returns -an error code indicating the success or failure of the request to perform -the action.
When the properties -are negotiated either the CSubConGenEventParamsGranted or CSubConGenEventParamsRejected event -is notified for each family within the parameter bundle.
Use the EventNotification() methods -to asynchronously register for event notifications.

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 TEventFilter.
Use CancelEventNotification() method -cancel the registration for event notifications.

-Connecting to the default SubConnection example

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.

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); - -

Creating a -sub-connection - Socket connected over the SubConnection example

The -following example shows how an application can use a sub-connection through -an RSubConnection instance. It attaches an RSocket to -the sub-connection.

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); -

Creating a -new sub-connection - Adding an already connected socket example

The -following example shows how an application can use a sub-connection through -an RSubConnection instance. It attaches a connected RSocket to -the sub-connection.

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); -

Creating and -setting properties for a SubConnection example

The following -example shows how an application creates and sets the QoS properties. It assigns -the properties to a sub-connection.

// 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); -

Registering -for events example

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.

// 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); -

Registering for events – Using filters

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 TEventFilter contains -events of the factory UID and mask of event IDs.

// 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); -

Extracting -information from received events example

The following example -code shows how to extract the information contained within an event notification -when it is received.

// 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); -

+ + + + + + RSubConnection +API TutorialHow to use an RSubConnection. +

Procedure

Use the Open() method +to open an RSubConnection object on an ESOCK session.

The RConnection 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 RConnection, +or creates a sub-connection. When an application calls the RSubConnection API, +a system wide error code is returned. When it is successful, it returns KErrNone.
Use the Add() method +to move the socket from the default sub-connection to the RSubConnection.
The Remove() method +returns the socket to the default sub-connection.
Use the GetParameters() and SetParameters() methods +are to retrieve and set bundles of properties on the sub-connection.
The GetParameters() returns KErrNotReady if +properties are not negotiated.
The SetParameters() method, +like the Add() and Remove() methods returns +an error code indicating the success or failure of the request to perform +the action.
When the properties +are negotiated either the CSubConGenEventParamsGranted or CSubConGenEventParamsRejected event +is notified for each family within the parameter bundle.
Use the EventNotification() methods +to asynchronously register for event notifications.

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 TEventFilter.
Use CancelEventNotification() method +cancel the registration for event notifications.

+Connecting to the default SubConnection example

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.

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); + +

Creating a +sub-connection - Socket connected over the SubConnection example

The +following example shows how an application can use a sub-connection through +an RSubConnection instance. It attaches an RSocket to +the sub-connection.

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); +

Creating a +new sub-connection - Adding an already connected socket example

The +following example shows how an application can use a sub-connection through +an RSubConnection instance. It attaches a connected RSocket to +the sub-connection.

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); +

Creating and +setting properties for a SubConnection example

The following +example shows how an application creates and sets the QoS properties. It assigns +the properties to a sub-connection.

// 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); +

Registering +for events example

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.

// 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); +

Registering for events – Using filters

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 TEventFilter contains +events of the factory UID and mask of event IDs.

// 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); +

Extracting +information from received events example

The following example +code shows how to extract the information contained within an event notification +when it is received.

// 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); +

\ No newline at end of file