RConnection Class Reference

#include <es_sock.h>

Link against: esock.lib

class RConnection : public RCommsSubSession

Inherits from

Public Member Enumerations
enumTConnAttachType { EAttachTypeNormal, EAttachTypeMonitor }
enumTConnStopType { EStopNormal, EStopAuthoritative }
Public Member Functions
RConnection()
virtual ~RConnection()
IMPORT_C voidAllInterfaceNotification(TDes8 &, TRequestStatus &)
IMPORT_C voidAllSubConnectionNotification(TSubConnectionNotificationBuf &, TRequestStatus &)
IMPORT_C TIntAttach(const TDesC8 &, TConnAttachType)
IMPORT_C voidCancelAllInterfaceNotification()
IMPORT_C voidCancelAllSubConnectionNotification()
IMPORT_C voidCancelIoctl()
IMPORT_C voidCancelProgressNotification()
IMPORT_C voidCancelProgressNotification(TSubConnectionUniqueId)
IMPORT_C voidCancelServiceChangeNotification()
IMPORT_C voidCancelWaitForIncoming()
IMPORT_C voidClose()
IMPORT_C TIntControl(TUint, TUint, TDes8 &)
IMPORT_C voidDataReceivedNotificationCancel()
IMPORT_C voidDataReceivedNotificationCancel(TSubConnectionUniqueId)
IMPORT_C voidDataReceivedNotificationRequest(TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C voidDataReceivedNotificationRequest(TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C voidDataSentNotificationCancel()
IMPORT_C voidDataSentNotificationCancel(TSubConnectionUniqueId)
IMPORT_C voidDataSentNotificationRequest(TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C voidDataSentNotificationRequest(TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C voidDataTransferredCancel()
IMPORT_C voidDataTransferredCancel(TSubConnectionUniqueId)
IMPORT_C voidDataTransferredRequest(TPckg< TUint > &, TPckg< TUint > &, TRequestStatus &)
IMPORT_C voidDataTransferredRequest(TSubConnectionUniqueId, TPckg< TUint > &, TPckg< TUint > &, TRequestStatus &)
IMPORT_C TIntEnumerateConnections(TUint &)
IMPORT_C TIntEnumerateSubConnections(TUint &)
IMPORT_C TIntGetBoolSetting(const TDesC &, TBool &)
IMPORT_C TIntGetConnectionInfo(TUint, TDes8 &)
IMPORT_C TIntGetDesSetting(const TDesC &, TDes8 &)
IMPORT_C TIntGetDesSetting(const TDesC &, TDes16 &)
IMPORT_C TIntGetIntSetting(const TDesC &, TUint32 &)
IMPORT_C TIntGetLongDesSetting(const TDesC &, TDes &)
IMPORT_C TIntGetOpt(TUint, TUint, TInt &)
IMPORT_C TIntGetParameters(ESock::CCommsDataObjectBase &)
IMPORT_C TIntGetSubConnectionInfo(TDes8 &)
IMPORT_C TIntGetSubConnectionInfo(TUint, TDes8 &)
IMPORT_C voidIoctl(TUint, TUint, TRequestStatus &, TDes8 *)
IMPORT_C voidIoctl(TUint, TUint, TRequestStatus &)
IMPORT_C voidIsConnectionActiveCancel()
IMPORT_C voidIsConnectionActiveRequest(TUint, TPckg< TBool > &, TRequestStatus &)
IMPORT_C voidIsSubConnectionActiveCancel(TSubConnectionUniqueId)
IMPORT_C voidIsSubConnectionActiveRequest(TSubConnectionUniqueId, TUint, TPckg< TBool > &, TRequestStatus &)
IMPORT_C TIntLastProgressError(TNifProgress &)
IMPORT_C TIntName(TName &)
IMPORT_C TIntOpen(RSocketServ &, TUint)
IMPORT_C TIntOpen(RSocketServ &, TName &)
IMPORT_C TIntProgress(TNifProgress &)
IMPORT_C TIntProgress(TSubConnectionUniqueId, TNifProgress &)
IMPORT_C voidProgressNotification(TNifProgressBuf &, TRequestStatus &, TUint)
IMPORT_C voidProgressNotification(TSubConnectionUniqueId, TNifProgressBuf &, TRequestStatus &, TUint)
TBool SameSession(TInt)
IMPORT_C voidServiceChangeNotification(TUint32 &, TDes &, TRequestStatus &)
IMPORT_C TIntSetOpt(TUint, TUint, TInt)
IMPORT_C TIntSetParameters(ESock::CCommsDataObjectBase &)
IMPORT_C voidStart(TRequestStatus &)
IMPORT_C voidStart(TConnPref &, TRequestStatus &)
IMPORT_C TIntStart()
IMPORT_C TIntStart(TConnPref &)
IMPORT_C TIntStop()
IMPORT_C TIntStop(TConnStopType)
IMPORT_C TIntStop(TSubConnectionUniqueId)
IMPORT_C TIntStop(TSubConnectionUniqueId, TConnStopType)
IMPORT_C voidWaitForIncoming(RSubConnection &, TRequestStatus &)
IMPORT_C TIntWaitForIncoming(RSubConnection &)
Inherited Functions
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const

Detailed 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. since v7.0s

Member Enumeration Documentation

Enum TConnAttachType

Identifies the intended use of the connection.

EnumeratorValueDescription
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.

Enum TConnStopType

Identifies the type of requirement for stopping the connection.

EnumeratorValueDescription
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.

Constructor & Destructor Documentation

RConnection ( )

IMPORT_CRConnection()

Connection Management Interface

Empty constructor.

~RConnection ( )

IMPORT_C~RConnection()[virtual]

Empty destructor.

Member Function Documentation

AllInterfaceNotification ( TDes8 &, TRequestStatus & )

IMPORT_C voidAllInterfaceNotification(TDes8 &aNotification,
TRequestStatus &aStatus
)

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
aNotificationOn return, a wrapped interface change notification (TInterfaceNotification).
aStatusOn return, the status of the request.

AllSubConnectionNotification ( TSubConnectionNotificationBuf &, TRequestStatus & )

IMPORT_C voidAllSubConnectionNotification(TSubConnectionNotificationBuf &aSubConnectionEvent,
TRequestStatus &aStatus
)

Requests notification of any change in the state of any of the subconnections belonging to this RConnection.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()

No outstanding request for subconnection notifications for this subconnection on this RConnection

Parameters
aStatusOn return, the status of the request.

Attach ( const TDesC8 &, TConnAttachType )

IMPORT_C TIntAttach(const TDesC8 &aConnectionInfo,
TConnAttachTypeaAttachType
)

Attaches the RConnection object to an existing interface.

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

Parameters
aConnectionInfoIdentity of the connection to attach to. This is a TPckg<TConnectionInfo>& (possibly obtained from a call to GetConnectionInfo()).
aAttachTypeIdentifies the intended use of the connection.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
dependenton the type of connection so deferred to PRT

CancelAllInterfaceNotification ( )

IMPORT_C voidCancelAllInterfaceNotification()

Cancels a change notification request previously issued by a call to AllInterfaceNotification().

CancelAllSubConnectionNotification ( )

IMPORT_C voidCancelAllSubConnectionNotification()

Cancels the request for notification to changes to the state of subconnections, made using the AllSubConnectionNotification().

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()

An outstanding request for notification about changes to the state of subconnections.

CancelIoctl ( )

IMPORT_C voidCancelIoctl()

Cancel any outstanding Ioctl request

CancelProgressNotification ( )

IMPORT_C voidCancelProgressNotification()

Cancels a request for progress notification for the connection, as issued by ProgressNotification().

CancelProgressNotification ( TSubConnectionUniqueId )

IMPORT_C voidCancelProgressNotification(TSubConnectionUniqueIdaSubConnectionUniqueId)

Cancels a request for progress notification for a specified subconnection, as issued by ProgressNotification().

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()

An outstanding request for a progress notification on the subconnection on this RConnection

Parameters
aSubConnectionUniqueIdThe identifier for the subconnection used to make the request.

CancelServiceChangeNotification ( )

IMPORT_C voidCancelServiceChangeNotification()

Cancels a request for notification of change of service for the connection, as issued by ServiceChangeNotification(). Nothing happens if called without having called "RConnection::ServiceChangeNotification(...)" before. Important: It Panics if used BEFORE "RConnecion::Open(...)" being called.

CancelWaitForIncoming ( )

IMPORT_C voidCancelWaitForIncoming()

Cancel the previous subscription for an incoming session.

since v9.2

See also: WaitForIncoming()

Pre-condition
Must be attached to a connection by performing a Start().

Close ( )

IMPORT_C voidClose()

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, Close(), not Stop(), needs to be used after shutting down the socket.

Control ( TUint, TUint, TDes8 & )

IMPORT_C TIntControl(TUintaOptionLevel,
TUintaOptionName,
TDes8 &aOption
)

Gets detailed information on connection clients and sockets.

More likely to be used by system control type applications.

Parameters
aOptionLevelOption level to be used.
aOptionNameOption name to be used.
aOptionOn return, the option value.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

DataReceivedNotificationCancel ( )

IMPORT_C voidDataReceivedNotificationCancel()

Cancels a request (issued by DataReceivedNotificationRequest ()) for the amount of data received by the entire connection.

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for the amount of data received on this connection made using DataReceivedNotificationRequest()

DataReceivedNotificationCancel ( TSubConnectionUniqueId )

IMPORT_C voidDataReceivedNotificationCancel(TSubConnectionUniqueIdaSubConnectionUniqueId)

Cancels a request (issued by DataReceivedNotificationRequest ()) for the amount of data received by the specified subconnection.

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::CancelDataReceivedNotificationRequest
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for the amount of data received on this subconnection made using DataReceivedNotificationRequest()

Parameters
aSubConnectionUniqueIdThe identifier for the subconnection used to make the request.

DataReceivedNotificationRequest ( TUint, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataReceivedNotificationRequest(TUintaThreshold,
TPckg< TUint > &aDownlinkVolume,
TRequestStatus &aStatus
)

Requests a notification after an additional aThreshold bytes have been received by this connection.

Completes when an amount of data equal to aThreshold has been received, starting from when the request is posted.

Making this request with an aThreshold of zero will result in the server reading the value in aDownlinkVolume, and producing a notification when the absolute amount of data specified here has been sent.

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for data received notifications for this connection on this RConnection

Parameters
aThresholdThe number of additional bytes to be received by this connection before the request completes.
aDownlinkVolumeThe total number of bytes received by this connection so far
aStatusOn return, the status of the request.

DataReceivedNotificationRequest ( TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataReceivedNotificationRequest(TSubConnectionUniqueIdaSubConnectionUniqueId,
TUintaThreshold,
TPckg< TUint > &aDownlinkVolume,
TRequestStatus &aStatus
)

Requests notification after an additional aThreshold bytes have been received by a specified subconnection.

Completes when an amount of data equal to aThreshold has been received, starting from when the request is posted.

Making this request with an aThreshold of zero will result in the server reading the value in aDownlinkVolume, and producing a notification when the absolute amount of data specified here has been sent.

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::RequestDataReceivedNotification
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for data received notifications for this subconnection on this RConnection

Parameters
aSubConnectionUniqueIdA valid identifier for a subconnection.
aThresholdThe number of additional bytes to be received by this connection before the request completes.
aDownlinkVolumeOn return, the total number of bytes received by this connection so far.
aStatusOn return, the status of the request.

DataSentNotificationCancel ( )

IMPORT_C voidDataSentNotificationCancel()

Cancels a request for the amount of data sent on this connection, as issued by DataSentNotificationRequest().

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for the amount of data transferred on this connection, made using DataSentNotificationRequest()

DataSentNotificationCancel ( TSubConnectionUniqueId )

IMPORT_C voidDataSentNotificationCancel(TSubConnectionUniqueIdaSubConnectionUniqueId)

Cancels a request for the amount of data sent by the specified subconnection.

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::CancelDataSentNotificationRequest
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for the amount of data transferred on this subconnection, made using DataSentNotificationRequest()

Parameters
aSubConnectionUniqueIdThe identifier for the subconnection used to make the request.

DataSentNotificationRequest ( TUint, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataSentNotificationRequest(TUintaThreshold,
TPckg< TUint > &aUplinkVolume,
TRequestStatus &aStatus
)

Requests a notification after an additional aThreshold bytes have been sent by the entire connection.

Making this request with an aThreshold of zero will result in the server reading the value in aUplinkVolume and producing a notification when the absolute amount of data specified here has been sent.

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for data sent notifications on this RConnection

Parameters
aThresholdThe number of additional bytes to be sent by this connection before the request completes.
aUplinkVolumeThe total number of bytes sent by this connection so far.
aStatusOn return, the status of the request.

DataSentNotificationRequest ( TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataSentNotificationRequest(TSubConnectionUniqueIdaSubConnectionUniqueId,
TUintaThreshold,
TPckg< TUint > &aUplinkVolume,
TRequestStatus &aStatus
)

Requests a notification after an additional aThreshold bytes have been sent on a specified subconnection.

Making this request with an aThreshold of zero will result in the server reading the value in aUplinkVolume and producing a notification when the absolute amount of data specified here has been sent.

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::RequestDataSentNotification
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for data sent notifications for this subconnection on this RConnection

Parameters
aSubConnectionUniqueIdA valid identifier for the subconnection of interest.
aThresholdThe number of additional bytes to be sent by this connection before the request completes.
aUplinkVolumeThe total number of bytes sent by this connection so far.
aStatusOn return, the status of the request.

DataTransferredCancel ( )

IMPORT_C voidDataTransferredCancel()

Cancels a request for the amount of data transferred on the entire connection, issued by DataTransferredRequest().

since v7.0s
Pre-condition
An attached connection; either as a result of performing a Start() or an Attach()

An outstanding request for the amount of data transferred on this connection made using GetDataTransferred()

DataTransferredCancel ( TSubConnectionUniqueId )

IMPORT_C voidDataTransferredCancel(TSubConnectionUniqueIdaSubConnectionUniqueId)

Cancels a request for the amount of data transferred on a specified subconnection, issued by DataTransferredRequest().

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::CancelDataTransferredRequest
Pre-condition
An attached connection; either as a result of performing a Start() or an Attach()

An outstanding request for the amount of data transferred on this connection made using GetDataTransferred()

Parameters
aSubConnectionUniqueIdThe identifier for the subconnection used to make the request.

DataTransferredRequest ( TPckg< TUint > &, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataTransferredRequest(TPckg< TUint > &aUplinkVolume,
TPckg< TUint > &aDownlinkVolume,
TRequestStatus &aStatus
)

Gets the amount of data that has been transferred by the entire connection.

since v7.0s

Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()
Parameters
aUplinkVolumeOn return, contains the amount of data in bytes transferred by this connection to the remote endpoint.
aDownlinkVolumeOn return, contains the amount of data in bytes transferred by this connection from the remote endpoint.
aStatusOn return, the status of the request.

DataTransferredRequest ( TSubConnectionUniqueId, TPckg< TUint > &, TPckg< TUint > &, TRequestStatus & )

IMPORT_C voidDataTransferredRequest(TSubConnectionUniqueIdaSubConnectionUniqueId,
TPckg< TUint > &aUplinkVolume,
TPckg< TUint > &aDownlinkVolume,
TRequestStatus &aStatus
)

Gets the amount of data that has been transferred by the specified subconnection.

Deprecatedsince v9.5. Replaced with RCommsDataMonitoringApiExt::RequestDataTransferred
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()
Parameters
aSubConnectionUniqueIdA valid identifier for the subconnection being queried.
aUplinkVolumeOn return, contains the amount of data in bytes transferred by this connection to the remote endpoint.
aDownlinkVolumeOn return, contains the amount of data in bytes transferred by this connection from the remote endpoint.
aStatusOn return, the status of the request.

EnumerateConnections ( TUint & )

IMPORT_C TIntEnumerateConnections(TUint &aCount)

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
aCountOn return, contains the number of currently active interfaces on the server.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

EnumerateSubConnections ( TUint & )

IMPORT_C TIntEnumerateSubConnections(TUint &aCount)

Asks the server to gather information on the currently active subconnections.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Note:

Unlike EnumerateConnections(), EnumerateSubConnections() does not cache the information about subconnections, so it is possible for a greater or fewer number of records to be returned through GetSubConnectionInfo()

Parameters
aCountOn return, contains the number of currently active connections.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

GetBoolSetting ( const TDesC &, TBool & )

IMPORT_C TIntGetBoolSetting(const TDesC &aSettingName,
TBool &aValue
)

DeprecatedSince SymbianOS v9.5

Reads current CommDb settings for the active connection.

DeprecatedSince 9.5 - For replacement functionality see GetParameters
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSettingNameThe CommDb table name and field name to be accessed. Of the form "<table name>\<field name>". (for example "IAP\Id" or "ModemBearer\PortName").
aValueOn return, the value of the table/field pair.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton table - deferred to RDBMS

GetConnectionInfo ( TUint, TDes8 & )

IMPORT_C TIntGetConnectionInfo(TUintaIndex,
TDes8 &aConnectionInfo
)

Gets information about one of the currently active connections.

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

Parameters
aIndexThe index of the connection - must be between 1 and the value of aCount returned in EnumerateConnections().
aConnectionInfoOn return, contains a TPckg<TConnectionInfo> containing information about the connection.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

GetDesSetting ( const TDesC &, TDes8 & )

IMPORT_C TIntGetDesSetting(const TDesC &aSettingName,
TDes8 &aValue
)

DeprecatedSince SymbianOS v9.5

Reads current CommDb settings for the active connection.

DeprecatedSince 9.5 - For replacement functionality see GetParameters
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSettingNameThe CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName").
aValueOn return, the value of the table/field pair.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton table - deferred to RDBMS

GetDesSetting ( const TDesC &, TDes16 & )

IMPORT_C TIntGetDesSetting(const TDesC &aSettingName,
TDes16 &aValue
)

DeprecatedSince SymbianOS v9.5

Reads current CommDb settings for the active connection.

DeprecatedSince 9.5 - For replacement functionality see GetParameters
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSettingNameThe CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName").
aValueOn return, the value of the table/field pair.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton table - deferred to RDBMS

GetIntSetting ( const TDesC &, TUint32 & )

IMPORT_C TIntGetIntSetting(const TDesC &aSettingName,
TUint32 &aValue
)

DeprecatedSince SymbianOS v9.5

Reads current CommDb settings for the active connection.

DeprecatedSince 9.5 - For replacement functionality see GetParameters
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSettingNameThe CommDb table name and field name to be accessed. Of the form "<table name>\<field name>" (for example "IAP\Id" or "ModemBearer\PortName").
aValueOn return, the value of the table/field pair.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton table - deferred to RDBMS

GetLongDesSetting ( const TDesC &, TDes & )

IMPORT_C TIntGetLongDesSetting(const TDesC &aSettingName,
TDes &aValue
)

DeprecatedSince SymbianOS v9.5

Reads current CommDb settings for the active connection.

DeprecatedSince 9.5 - For replacement functionality see GetParameters
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSettingNameThe CommDb table name and field name to be accessed. Of the form "<table name>\<field name>". (for example "IAP\Id" or "ModemBearer\PortName").
aValueOn return, the value of the table/field pair.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton table - deferred to RDBMS

GetOpt ( TUint, TUint, TInt & )

IMPORT_C TIntGetOpt(TUintaOptionLevel,
TUintaOptionName,
TInt &aOption
)

Gets an option.

Parameters
aOptionLevelOption level to be queried.
aOptionNameOption name to be queried.
aOptionOn return, the option value.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

GetParameters ( ESock::CCommsDataObjectBase & )

IMPORT_C TIntGetParameters(ESock::CCommsDataObjectBase &aDataObject)

Return Value
KErrNone - The get parameters call was serviced successfully KErrNotReady - This error will most likely indicate that the connection has not been started KErrNoMemory - Failure to allocate the required memory for the retrieved query bundle KErrNotFound - The interface required by the data object was not found in the connection stack Other system-wide error codes dependent on specific data object implementations

GetSubConnectionInfo ( TDes8 & )

IMPORT_C TIntGetSubConnectionInfo(TDes8 &aSubConnectionInfo)

Gets information about one of the currently active subconnections.

This function is used when a valid TSubConnectionUniqueId has been discovered using the alternative form of GetSubConnectionInfo(), and the client wishes to update its TSubConnectionInfo-derived structure with the latest subconnection information.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSubConnectionInfoA TPckg<TSubConnectionInfo-derived class>: the actual class depends upon the type of subconnection, eg. GPRS context, PPP, NCP. On entry, must contain a valid TSubConnectionUniqueId to indicate which of the subconnections it wishes to gather information about. On return, contains information about the subconnection.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

GetSubConnectionInfo ( TUint, TDes8 & )

IMPORT_C TIntGetSubConnectionInfo(TUintaIndex,
TDes8 &aSubConnectionInfo
)

Gets information about one of the currently active subconnections.

This function is intended for the initial enumeration of connections, when no TSubConnectionUniqueIds are available, so the client must iterate through the list of subconnections.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aIndexThe index of the connection - must be between 1 and the value of aCount returned in EnumerateSubConnections().
aSubConnectionInfoOn return, contains a TPckg<TSubConnectionInfo-derived class> containing information about the subconnection; the actual class depends upon the type of subconnection, eg. GPRS context, PPP NCP.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

Ioctl ( TUint, TUint, TRequestStatus &, TDes8 * )

IMPORT_C voidIoctl(TUintaOptionLevel,
TUintaOptionName,
TRequestStatus &aStatus,
TDes8 *aDesc
)

Get information on the connection in an asynchronous manner

Parameters
aOptionLevelOption level to be used.
aOptionNameOption name to be used.
Capability
Dependenton the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

Ioctl ( TUint, TUint, TRequestStatus & )

IMPORT_C voidIoctl(TUintaOptionLevel,
TUintaOptionName,
TRequestStatus &aStatus
)

Get information on the connection in an asynchronous manner

Parameters
aOptionLevelOption level to be used.
aOptionNameOption name to be used.
Capability
Dependenton the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

IsConnectionActiveCancel ( )

IMPORT_C voidIsConnectionActiveCancel()
Cancels a request for activity notifications on the connection since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for activity notification on this connection made using IsConnectionActiveRequest()

IsConnectionActiveRequest ( TUint, TPckg< TBool > &, TRequestStatus & )

IMPORT_C voidIsConnectionActiveRequest(TUintaSecs,
TPckg< TBool > &aState,
TRequestStatus &aStatus
)

Checks whether the connection is active or inactive.

Notes whether any data is passed for aSecs after the time of call before responding. If data is passed the connection is considered active; otherwise it is considered inactive.

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for activity notifications for this connection on this RConnection

See also: IsSubConnectionActiveRequest() for details of when this method will return.

Parameters
aSecsThe period for checking whether the connection is active. The maximum period allowed is approximately 35 mins.
aStateOn entry, the state the client believes the subconnection is currently in; on return, contains the current state of the subconnection.
aStatusOn return, the status of the request

IsSubConnectionActiveCancel ( TSubConnectionUniqueId )

IMPORT_C voidIsSubConnectionActiveCancel(TSubConnectionUniqueIdaSubConnectionUniqueId)
Cancels a request for activity notifications on the specified subconnection since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

An outstanding request for an activity notification on this subconnection made using IsSubConnectionActiveRequest()

Parameters
aSubConnectionUniqueIdThe identifier for the subconnection used to make the request

IsSubConnectionActiveRequest ( TSubConnectionUniqueId, TUint, TPckg< TBool > &, TRequestStatus & )

IMPORT_C voidIsSubConnectionActiveRequest(TSubConnectionUniqueIdaSubConnectionUniqueId,
TUintaSecs,
TPckg< TBool > &aState,
TRequestStatus &aStatus
)

Checks whether the subconnection is active or has changed state (active/inactive)

since v7.0s
Pre-condition
An attached connection, as a result of performing either a Start() or an Attach()

No outstanding request for activity notifications for this subconnection on this RConnection

Note:

The request will be completed when the aState passed in by the client is not the same as the current state, but this transition can only occur in quantised periods of aSecs

The maximum period allowed is approximately 35 mins

Parameters
aSubConnectionUniqueIdA valid identifier for a subconnection
aSecsThe quantisation period for checking whether the subconnection is active
aStateThe state the client believes the subconnection is currently in; on return, contains the current state of the subconnection
aStatusOn return, the status of the request

LastProgressError ( TNifProgress & )

IMPORT_C TIntLastProgressError(TNifProgress &aProgress)

Obtains information about the last Progress() call which failed with an error.

Parameters
aProgressA buffer to receive progress information.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

Name ( TName & )

IMPORT_C TIntName(TName &aName)

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
aNameOn return, the unique name of the RConnection.
Return Value
KErrNone if succesful, or another of the system-wide error codes.

Open ( RSocketServ &, TUint )

IMPORT_C TIntOpen(RSocketServ &aSocketServer,
TUintaConnectionType =  KConnectionTypeDefault
)

Opens a new RConnection instance.

Parameters
aSocketServerSocket Server session.
aConnectionTypeReserved.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

Open ( RSocketServ &, TName & )

IMPORT_C TIntOpen(RSocketServ &aSocketServer,
TName &aName
)

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

Parameters
aSocketServerSocket Server session.
aNameName of an existing RConnection (obtainable via Name() method).
Return Value
KErrNone if successful, otherwise another of the system wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

Progress ( TNifProgress & )

IMPORT_C TIntProgress(TNifProgress &aProgress)

Obtains the current progress information for the connection.

Parameters
aProgressA buffer to receive progress information.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

Progress ( TSubConnectionUniqueId, TNifProgress & )

IMPORT_C TIntProgress(TSubConnectionUniqueIdaSubConnectionUniqueId,
TNifProgress &aProgress
)

Obtains the current progress information on a specified subconnection.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSubConnectionUniqueIdA valid identifier for the subconnection of interest.
aProgressOn return, progress information.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

ProgressNotification ( TNifProgressBuf &, TRequestStatus &, TUint )

IMPORT_C voidProgressNotification(TNifProgressBuf &aProgress,
TRequestStatus &aStatus,
TUintaSelectedProgress =  KConnProgressDefault
)

Requests asynchronous progress notification for the connection.

Parameters
aProgressA buffer to receive progress notification.
aStatusOn return, the status of the request.
aSelectedProgressThe 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.

ProgressNotification ( TSubConnectionUniqueId, TNifProgressBuf &, TRequestStatus &, TUint )

IMPORT_C voidProgressNotification(TSubConnectionUniqueIdaSubConnectionUniqueId,
TNifProgressBuf &aProgress,
TRequestStatus &aStatus,
TUintaSelectedProgress =  KConnProgressDefault
)

Requests asynchronous progress notification for a subconnection.

NOTE: This function is not supported and will correctly return KErrNotSupported.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()

No outstanding request for progress notifications for this subconnection on this RConnection

Parameters
aSubConnectionUniqueIdA valid identifier for a subconnection.
aProgressA buffer to receive progress notification.
aStatusOn return, the status of the request.
aSelectedProgressThe 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.

SameSession ( TInt )

TBool SameSession(TIntaSessionHandle)

Checks that the Session Handle passed is the same as that of this RConnection.

Use to verify the RConnection argument passed to the RSocket and RHostResolver Open(..., RConnection& aConnection) methods.

Parameters
aSessionHandleThe handle which is to be checked against that of this RConnection
Return Value
ETrue if handle is the same, else EFalse

ServiceChangeNotification ( TUint32 &, TDes &, TRequestStatus & )

IMPORT_C voidServiceChangeNotification(TUint32 &aNewISPId,
TDes &aNewServiceType,
TRequestStatus &aStatus
)

Requests service change notification from the agent. This call completes if the underlying service changes (i.e. ISP, GPRS APN or LAN Service). Important: It Panics if used BEFORE "RConnecion::Open(...)" being called.

Parameters
aNewISPIdOn completion, the new ISP Id.
aNewServiceTypeOn completion, the new service type.
aStatusOn completion, "KErrNone" if succesful, "KErrNotReady" if called before "RConnection::Start(...)" being called, "KErrInUse" if called twice. Otherwise another of the system wide error codes.

SetOpt ( TUint, TUint, TInt )

IMPORT_C TIntSetOpt(TUintaOptionLevel,
TUintaOptionName,
TIntaOption = 0
)

Sets an option.

Parameters
aOptionLevelOption level to be set.
aOptionNameOption name to be set
aOptionOption value.
Return Value
KErrNone if succesful, or another of the system-wide error codes.
Capability
Dependenton the type of operation so deferred to PRT. See documentation of constant values used in aOptionName and aOptionLevel for more information

SetParameters ( ESock::CCommsDataObjectBase & )

IMPORT_C TIntSetParameters(ESock::CCommsDataObjectBase &aDataObject)

Speculative method - Not yet supported Do not call this function, it has ony been introduced for symmetry with RConnection::GetParameters and will be completed at a later date.

Return Value
KErrNotSupported

Start ( TRequestStatus & )

IMPORT_C voidStart(TRequestStatus &aStatus)

Start a connection asynchonously using the default connection preferences.

The request completes once the connection is fully up or an error has occurred. Successful completion will be accompanied by a KConnectionUp progress.

If an RConnection has been stopped or has gone down, any subsequent start will act in the same way as a start with a new RConnection. i.e. The preferences from previous starts will not be used.

Parameters
aStatusOn return, the status of the request, e.g. KErrNone, KErrAlreadyExists.
Capability
Dependenton the access point implementation

Start ( TConnPref &, TRequestStatus & )

IMPORT_C voidStart(TConnPref &aPref,
TRequestStatus &aStatus
)

Start a connection asynchonously using the connection preferences specified.

The connection preferences can be of type TConnSnapPref, TCommDbConnPref, TCommDbMultiConnPref or TConnPrefList. See the definitions of these classes to see their usage.

The request completes once the connection is fully up or an error has occurred. Successful completion will be accompanied by a KConnectionUp progress.

If an RConnection has been stopped or has gone down, any subsequent start will act in the same way as a start with a new RConnection. i.e. The preferences from previous starts will not be used.

See also: TConnSnapPref TCommDbConnPref TCommDbMultiConnPref TConnPrefList

Parameters
aPrefConnection preferences.
aStatusOn return, the status of the request, e.g. KErrNone, KErrAlreadyExists.
Capability
Dependenton the access point implementation

Start ( )

IMPORT_C TIntStart()

Start a connection synchonously using the default connection preferences.

The request completes once the connection is fully up or an error has occurred. Successful completion will be accompanied by a KConnectionUp progress.

If an RConnection has been stopped or has gone down, any subsequent start will act in the same way as a start with a new RConnection. i.e. The preferences from previous starts will not be used.

Return Value
KErrNone if successful or the connection already exists, otherwise another of the system wide error codes.
Capability
Dependenton the access point implementation

Start ( TConnPref & )

IMPORT_C TIntStart(TConnPref &aPref)

Start a connection synchonously using the connection preferences specified.

The connection preferences can be of type TConnSnapPref, TCommDbConnPref, TCommDbMultiConnPref or TConnPrefList. See the definitions of these classes to see their usage.

The request completes once the connection is fully up or an error has occurred. Successful completion will be accompanied by a KConnectionUp progress.

If an RConnection has been stopped or has gone down, any subsequent start will act in the same way as a start with a new RConnection. i.e. The preferences from previous starts will not be used.

See also: TConnSnapPref TCommDbConnPref TCommDbMultiConnPref TConnPrefList

Parameters
aPrefConnection preferences.
Return Value
KErrNone if successful or the connection already exists, otherwise another of the system wide error codes.
Capability
Dependenton the access point implementation

Stop ( )

IMPORT_C TIntStop()

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
KErrNone if successful, otherwise another of the system wide error codes.

Stop ( TConnStopType )

IMPORT_C TIntStop(TConnStopTypeaStopType)

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 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
aStopTypeThe type of stop which is being requested.
Return Value
KErrNone or another of the system wide error codes; in particular KErrArgument if the stop type is unrecognised.

Stop ( TSubConnectionUniqueId )

IMPORT_C TIntStop(TSubConnectionUniqueIdaSubConnectionUniqueId)

Stops a subconnection.

Applications will be sent a socket error code to indicate that they must perform clean up operations.

since v7.0s
Pre-condition
An attached connection: as a result of performing either a Start() or an Attach()
Parameters
aSubConnectionUniqueIdA valid identifier for a subconnection.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.

Stop ( TSubConnectionUniqueId, TConnStopType )

IMPORT_C TIntStop(TSubConnectionUniqueIdaSubConnectionUniqueId,
TConnStopTypeaStopType
)

Stop a subconnection on an interface

since v7.0s
Pre-condition
Must be attached to a connection; either by performing a Start(), or using Attach()
Parameters
aSubConnectionUniqueIdA valid identifier for a subconnection
aStopTypeThe kind of stop to do (controls what error code is reported to interface clients)
Return Value
KErrNone if successful, otherwise one of the system-wide error codes

WaitForIncoming ( RSubConnection &, TRequestStatus & )

IMPORT_C voidWaitForIncoming(RSubConnection &aIncomingSubConnection,
TRequestStatus &aStatus
)

Subscribe for an incoming session on this connection.

since v9.2
Pre-condition
Must be attached to a connection by performing a Start().
Parameters
aIncomingSubConnectionOn completion, the subconnection representing the incoming session. The incoming session can be accepted (by calling RSubConnection::Accept) or rejected (by calling RSubConnection::Stop) The subconnection is implicitly started (no need to call RSubConnection::Start). aIncomingSubConnection must not be open prior to calling this method.
aStatusOn completion, the status of the request, e.g. KErrNone or another of the system wide error codes.

WaitForIncoming ( RSubConnection & )

IMPORT_C TIntWaitForIncoming(RSubConnection &aIncomingSubConnection)

Synchronously wait for an incoming session on this connection.

since v9.2
Pre-condition
Must be attached to a connection by performing a Start().
Parameters
aIncomingSubConnectionOn completion, the subconnection representing the incoming session. The incoming session can be accepted (by calling RSubConnection::Accept) or rejected (by calling RSubConnection::Stop) The subconnection is implicitly started (no need to call RSubConnection::Start). aIncomingSubConnection must not be open prior to calling this method.
Return Value
KErrNone if successful, otherwise another of the system wide error codes.