Class RConnection

class RConnection : public RCommsSubSession;

Description

The management interface for a network connection or subconnection.

Provides clients with the following functionality:

Opening and closing the connection

Starting a connection, which means associating it with a new underlying interface

Attaching the RConnection instance to an existing interface

Stopping the connection, which means disassociating it from the underlying interface

Obtaining progress information and notification during connection start-up

Notifying when subconnections come up and go down

Notifying when there is a service change for the connection

Notifying when a given amount of data has been sent or received on a connection or subconnection

Reading CommDB fields specific to an active connection

Collecting statistical information on the network connection and subconnections. A UI component can display the collected statistical information in order to allow the user to examine the status of connections. The information that can be gathered is the following:

All available internet access point names and internet access point 'friendly' names as appropriate for each network (GPRS/UMTS) connection

Enumerating the currently active connections and subconnections

The current status of all network connections e.g. active/suspended

The amount of data (in bytes) transferred uplink and downlink by the network connection and subconnections

The amount of time each network connection has been active (in seconds)

The current status of the connection and subconnections with respect to data transfer, i.e. active/inactive

The Quality of Service profile associated with each Packet Data Protocol (GPRS/UMTS) context, e.g. low/medium/high

Note that several of the new functions are asynchronous. It is essential for these calls that the client ensures that the parameters they pass to the RConnection API remain in scope for the duration of the asynchronous call.

Derivation

• RSubSessionBase - Client-side handle to a sub-session.

• RCommsSubSession - (No abstract)

• RConnection - The management interface for a network connection or subconnection.

Members

Defined in RConnection:

• AllInterfaceNotification(TDes8 &,TRequestStatus &)Requests asynchronous change notification for all interfaces.
• Attach(const TDesC8 &,TConnAttachType)Attaches the RConnection object to an existing interface.
• CancelAllInterfaceNotification()Cancels a change notification request previously issued by a call to RConnection...
• CancelProgressNotification()Cancels a request for progress notification for the connection, as issued by RCo...
• CancelServiceChangeNotification()Cancels a request for notification of change of service for the connection, as i...
• Close()Closes the connection.
• Control(TUint,TUint,TDes8 &)Gets detailed information on connection clients and sockets.
• EAttachTypeMonitorThe system control type of application wishes to monitor the state of the connec...
• EAttachTypeNormalThe application wishes to use the connection for normal data transfer, and the i...
• EStopAuthoritativeAny sockets or host/service resolvers associated with this interface will be err...
• EStopNormalAny sockets or host/service resolvers associated with this interface will be err...
• EnumerateConnections(TUint &)Enumerates the number of currently active interfaces.
• GetBoolSetting(const TDesC &,TBool &)Reads current CommDb settings for the active connection.
• GetConnectionInfo(TUint,TDes8 &)Gets information about one of the currently active connections.
• GetDesSetting(const TDesC &,TDes16 &)Reads current CommDb settings for the active connection.
• GetDesSetting(const TDesC &,TDes8 &)Reads current CommDb settings for the active connection.
• GetIntSetting(const TDesC &,TUint32 &)Reads current CommDb settings for the active connection.
• GetLongDesSetting(const TDesC &,TDes &)Reads current CommDb settings for the active connection.
• GetOpt(TUint,TUint,TInt &)Gets an option.
• LastProgressError(TNifProgress &)Obtains information about the last RConnection::Progress(TNifProgress &) cal...
• Name(TName &)Gets the unique name of an RConnection.
• Open(RSocketServ &,TName &)Opens a new RConnection instance cloned from an existing RConnection instance.
• Open(RSocketServ &,TUint)Opens a new RConnection instance.
• Progress(TNifProgress &)Obtains the current progress information for the connection.
• ProgressNotification(TNifProgressBuf &,TRequestStatus &,TUint)Requests asynchronous progress notification for the connection.
• RConnection()Connection Management Interface
• ServiceChangeNotification(TUint32 &,TDes &,TRequestStatus &)Requests service change notification from the agent.
• SetOpt(TUint,TUint,TInt)Sets an option.
• Start()Starts a connection synchronously using the connection preference settings in Co...
• Start(TConnPref &)Starts a connection synchronously by overriding connection preference settings i...
• Start(TConnPref &,TRequestStatus &)Starts a connection asynchronously by overriding connection preference settings ...
• Start(TRequestStatus &)Starts a connection asynchronously using the existing connection preferences in ...
• Stop()Stops the entire connection by disconnecting the underlying network interface im...
• Stop(TConnStopType)Stops the entire connection by disconnecting the underlying network interface im...
• TConnAttachTypeIdentifies the intended use of the connection.
• TConnStopTypeIdentifies the type of requirement for stopping the connection.
• ~RConnection()Empty destructor.

Inherited from RSubSessionBase:

• CloseSubSession(TInt)Closes the sub-session.
• CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session. The new sub-session takes ...
• CreateSubSession(const RSessionBase &,TInt)Creates a new sub-session within an existing session.
• CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session.
• Send(TInt)constSends a blind message to the server - no reply is expected.
• Send(TInt,const TIpcArgs &)constSends a blind message to the server - no reply is expected.
• SendReceive(TInt)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• SendReceive(TInt,const TIpcArgs &)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• Session()constReturns a copy of the session associated with this sub-session.
• SubSessionHandle()constGets the sub-session handle number.

Related Topics

 » Symbian OS v9.4 » Examples » Multimedia Protocols example code » RTPExample: RTP packet streaming

• RTPExample: RTP packet streaming » Class Summary

 » Symbian OS v9.4 » Symbian OS guide » Short Link Services » Short Link Services » Short Link Collection » Bluetooth Profiles » Bluetooth PAN Profile » PAN-NAP Role Guide

• PAN-NAP Role Guide » See also » Related Items

IMPORT_C RConnection();

Description

Connection Management Interface

IMPORT_C virtual ~RConnection();

Description

Empty destructor.

IMPORT_C TInt Open(RSocketServ &aSocketServer, TUint aConnectionType=KConnectionTypeDefault);

Description

Opens a new RConnection instance.

Parameters

RSocketServ &aSocketServer Socket Server session. TUint aConnectionType Reserved.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C TInt Open(RSocketServ &aSocketServer, TName &aName);

Description

Opens a new RConnection instance cloned from an existing RConnection instance.

Parameters

RSocketServ &aSocketServer Socket Server session. TBuf &aName Name of an existing RConnection (obtainable via RConnection::Name(TName &) method).

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C void Close();

Description

Closes the connection.

The connection will not be dropped immediately: it will be dropped when there is no more data traffic on the connection. So if a client needs to graciously shutdown the connection, RConnection::Close(), not RConnection::Stop(), needs to be used after shutting down the socket.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C void Start(TRequestStatus &aStatus);

Description

Starts a connection asynchronously using the existing connection preferences in CommDb.

Note that this may or may not result in a dialog prompt, depending on the connection preference settings.

The request will complete once the connection is fully up (i.e. has has reached the KLinkLayerOpen stage), or if an error occurs during any stage of connection startup.

Parameters

TRequestStatus &aStatus On return, the status of the request, e.g. KErrNone, KErrAlreadyExists.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C void Start(TConnPref &aPref, TRequestStatus &aStatus);

Description

Starts a connection asynchronously by overriding connection preference settings in CommDb.

The settings which can be overridden are: IAP Id, Network Id, Dialog Preference, Direction, Bearer Set.

The request will complete once the connection is fully up (i.e. has has reached the KLinkLayerOpen stage), or if an error occurs during any stage of connection startup.

Parameters

TConnPref &aPref Connection preferences. TRequestStatus &aStatus On return, the status of the request, e.g. KErrNone, KErrAlreadyExists.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C TInt Start();

Description

Starts a connection synchronously using the connection preference settings in CommDb.

There is no overriding of settings (such as IAP Id, Network Id, Dialog Preference, Direction, Bearer Set).

This may or may not result in a dialog prompt, depending on the connection preference settings.

The request will complete once the connection is fully up (i.e. has has reached the KLinkLayerOpen stage), or if an error occurred during any stage of connection startup.

Return value

TInt KErrNone if successful or the connection already exists, otherwise another of the system wide error codes.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C TInt Start(TConnPref &aPref);

Description

Starts a connection synchronously by overriding connection preference settings in CommDb.

The settings which can be overridden are: IAP Id, Network Id, Dialog Preference, Direction, Bearer Set.

The request will complete once the connection is fully up (i.e. has has reached the KLinkLayerOpen stage), or if an error occurred during any stage of connection startup.

Parameters

TConnPref &aPref Connection preferences.

Return value

TInt KErrNone if successful or the connection already exists, otherwise another of the system wide error codes.

IMPORT_C TInt Stop();

Description

Stops the entire connection by disconnecting the underlying network interface immediately, regardless of whether other clients are using it or not.

Applications using the connection will be sent the socket error code KErrCancel. The application generally responds with clean up operations and pop-up boxes alerting the user to the termination of the application.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C TInt Stop(TConnStopType aStopType);

Description

Stops the entire connection by disconnecting the underlying network interface immediately, regardless of whether other clients are using it or not.

If the argument is EStopNormal this is identical to calling RConnection::Stop() with no argument. If it is EStopAuthoritative then applications using the connection will be sent the socket error code KErrConnectionTerminated, which generally results in the applications closing quietly (without pop-up boxes).

Parameters

RConnection::TConnStopType aStopType The type of stop which is being requested.

Return value

TInt KErrNone or another of the system wide error codes; in particular KErrArgument if the stop type is unrecognised.

IMPORT_C void ProgressNotification(TNifProgressBuf &aProgress, TRequestStatus &aStatus, TUint aSelectedProgress=KConnProgressDefault);

Description

Requests asynchronous progress notification for the connection.

Parameters

TPckgBuf &aProgress A buffer to receive progress notification. TRequestStatus &aStatus On return, the status of the request. TUint aSelectedProgress The type of progress to report. If set, report only the particular progress specified and any progress in error. If not set, report all progress normally.

IMPORT_C void CancelProgressNotification();

Description

Cancels a request for progress notification for the connection, as issued by RConnection::ProgressNotification(TNifProgressBuf &,TRequestStatus &,TUint).

IMPORT_C TInt Progress(TNifProgress &aProgress);

Description

Obtains the current progress information for the connection.

Parameters

TNifProgress &aProgress A buffer to receive progress information.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C TInt LastProgressError(TNifProgress &aProgress);

Description

Obtains information about the last RConnection::Progress(TNifProgress &) call which failed with an error.

Parameters

TNifProgress &aProgress A buffer to receive progress information.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C void ServiceChangeNotification(TUint32 &aNewISPId, TDes &aNewServiceType, TRequestStatus &aStatus);

Description

Requests service change notification from the agent.

This call completes if the underlying service changes (i.e. ISP, GPRS APN or LAN Service).

Parameters

TUint32 &aNewISPId On completion, the new ISP Id. TDes16 &aNewServiceType On completion, the new service type. TRequestStatus &aStatus On completion, KErrNone if succesful, otherwise another of the system wide error codes.

IMPORT_C void CancelServiceChangeNotification();

Description

Cancels a request for notification of change of service for the connection, as issued by RConnection::ServiceChangeNotification(TUint32 &,TDes &,TRequestStatus &).

Capability:

Dependent

on table - deferred to RDBMS

IMPORT_C TInt GetIntSetting(const TDesC &aSettingName, TUint32 &aValue);

Pre-Condition

An attached connection: as a result of performing either a RConnection::Start() or an RConnection::Attach(const TDesC8 &,TConnAttachType)

Description

Reads current CommDb settings for the active connection.

Parameters

const TDesC16 &aSettingName The CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName"). TUint32 &aValue On return, the value of the table/field pair.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on table - deferred to RDBMS

IMPORT_C TInt GetBoolSetting(const TDesC &aSettingName, TBool &aValue);

Pre-Condition

An attached connection: as a result of performing either a RConnection::Start() or an RConnection::Attach(const TDesC8 &,TConnAttachType)

Description

Reads current CommDb settings for the active connection.

Parameters

const TDesC16 &aSettingName The CommDb table name and field name to be accessed. Of the form "<table name>\<field name>". (for example "IAP\Id" or "ModemBearer\PortName"). TBool &aValue On return, the value of the table/field pair.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on table - deferred to RDBMS

IMPORT_C TInt GetDesSetting(const TDesC &aSettingName, TDes8 &aValue);

Pre-Condition

An attached connection: as a result of performing either a RConnection::Start() or an RConnection::Attach(const TDesC8 &,TConnAttachType)

Description

Reads current CommDb settings for the active connection.

Parameters

const TDesC16 &aSettingName The CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName"). TDes8 &aValue On return, the value of the table/field pair.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on table - deferred to RDBMS

IMPORT_C TInt GetDesSetting(const TDesC &aSettingName, TDes16 &aValue);

Pre-Condition

An attached connection: as a result of performing either a RConnection::Start() or an RConnection::Attach(const TDesC8 &,TConnAttachType)

Description

Reads current CommDb settings for the active connection.

Parameters

const TDesC16 &aSettingName The CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName"). TDes16 &aValue On return, the value of the table/field pair.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on table - deferred to RDBMS

IMPORT_C TInt GetLongDesSetting(const TDesC &aSettingName, TDes &aValue);

Pre-Condition

An attached connection: as a result of performing either a RConnection::Start() or an RConnection::Attach(const TDesC8 &,TConnAttachType)

Description

Reads current CommDb settings for the active connection.

Parameters

const TDesC16 &aSettingName The CommDb table name and field name to be accessed. Of the form "<table name>\<field name>". (for example "IAP\Id" or "ModemBearer\PortName"). TDes16 &aValue On return, the value of the table/field pair.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

IMPORT_C TInt Name(TName &aName);

Description

Gets the unique name of an RConnection.

Used to create an RConnection which is a clone of an existing RConnection (possibly in a different process).

Parameters

TBuf &aName On return, the unique name of the RConnection.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

IMPORT_C TInt EnumerateConnections(TUint &aCount);

Description

Enumerates the number of currently active interfaces.

Note: This does not count the number of RConnections but the number of underlying interfaces. These may be attached to by varying numbers of RConnections, RSockets etc.

Parameters

TUint &aCount On return, contains the number of currently active interfaces on the server.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C TInt GetConnectionInfo(TUint aIndex, TDes8 &aConnectionInfo);

Description

Gets information about one of the currently active connections.

Note that the actual connection information is gathered on a call to RConnection::EnumerateConnections(TUint &) and RConnection::GetConnectionInfo(TUint,TDes8 &) is simply used to return the information to the client. Therefore, if the state of the connections change after the RConnection::EnumerateConnections(TUint &) call, then the information returned by RConnection::GetConnectionInfo(TUint,TDes8 &) may be out of date.

Parameters

TUint aIndex The index of the connection - must be between 1 and the value of aCount returned in RConnection::EnumerateConnections(TUint &). TDes8 &aConnectionInfo On return, contains a TPckg<TConnectionInfo> containing information about the connection.

Return value

TInt KErrNone if successful, otherwise another of the system wide error codes.

IMPORT_C void AllInterfaceNotification(TDes8 &aNotification, TRequestStatus &aStatus);

Description

Requests asynchronous change notification for all interfaces.

This allows a client to receive a notification whenever a connection in the system goes up or down.

This allows the automatic update of the list of active network connections.

Parameters

TDes8 &aNotification On return, a wrapped interface change notification (TInterfaceNotification). TRequestStatus &aStatus On return, the status of the request.

IMPORT_C void CancelAllInterfaceNotification();

Description

Cancels a change notification request previously issued by a call to RConnection::AllInterfaceNotification(TDes8 &,TRequestStatus &).

Capability:	Dependent	on the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information
Capability:	NetworkControl	Conditional on: KCoGetConnectionSocketInfo
Capability:	NetworkControl	Conditional on: KCoGetConnectionClientInfo
Capability:	NetworkControl	Conditional on: KConnDisableTimers
Capability:	NetworkControl	Conditional on: KCOLAgent
Capability:	NetworkControl	Conditional on: KCoEnumerateConnectionClients
Capability:	NetworkControl	Conditional on: KCOLInterface

IMPORT_C TInt Control(TUint aOptionLevel, TUint aOptionName, TDes8 &aOption);

Description

Gets detailed information on connection clients and sockets.

More likely to be used by system control type applications.

Parameters

TUint aOptionLevel Option level to be used. TUint aOptionName Option name to be used. TDes8 &aOption On return, the option value.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

IMPORT_C TInt GetOpt(TUint aOptionLevel, TUint aOptionName, TInt &aOption);

Description

Gets an option.

Parameters

TUint aOptionLevel Option level to be queried. TUint aOptionName Option name to be queried. TInt &aOption On return, the option value.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

IMPORT_C TInt SetOpt(TUint aOptionLevel, TUint aOptionName, TInt aOption=0);

Description

Sets an option.

Parameters

TUint aOptionLevel Option level to be set. TUint aOptionName Option name to be set TInt aOption Option value.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C TInt Attach(const TDesC8 &aConnectionInfo, TConnAttachType aAttachType);

Description

Attaches the RConnection object to an existing interface.

This operation will not start an interface, as RConnection::Start() does, but attaches to an existing interface if it exists.

Parameters

const TDesC8 &aConnectionInfo Identity of the connection to attach to. This is a TPckg<TConnectionInfo>& (possibly obtained from a call to RConnection::GetConnectionInfo(TUint,TDes8 &)). RConnection::TConnAttachType aAttachType Identifies the intended use of the connection.

Return value

TInt KErrNone if succesful, or another of the system-wide error codes.

TConnAttachType

Description

Identifies the intended use of the connection.

EAttachTypeNormal The application wishes to use the connection for normal data transfer, and the idle timers will take that into account. EAttachTypeMonitor The system control type of application wishes to monitor the state of the connection without otherwise affecting it. In particular, the interface idle timers will not be affected.

TConnStopType

Description

Identifies the type of requirement for stopping the connection.

EStopNormal Any sockets or host/service resolvers associated with this interface will be errored with KErrCancel. EStopAuthoritative Any sockets or host/service resolvers associated with this interface will be errored with KErrConnectionTerminated and should clean up quietly without prompting the user.