RConnection Class Reference

#include <es_sock.h>

Link against: esock.lib

class RConnection : public RCommsSubSession

Inherits from

RConnection
- RCommsSubSession
  - RSubSessionBase

Public Member Enumerations
enum	TConnAttachType { EAttachTypeNormal, EAttachTypeMonitor }
enum	TConnStopType { EStopNormal, EStopAuthoritative }

Public Member Functions
	RConnection()
virtual	~RConnection()
IMPORT_C void	AllInterfaceNotification(TDes8 &, TRequestStatus &)
IMPORT_C void	AllSubConnectionNotification(TSubConnectionNotificationBuf &, TRequestStatus &)
IMPORT_C TInt	Attach(const TDesC8 &, TConnAttachType)
IMPORT_C void	CancelAllInterfaceNotification()
IMPORT_C void	CancelAllSubConnectionNotification()
IMPORT_C void	CancelIoctl()
IMPORT_C void	CancelProgressNotification()
IMPORT_C void	CancelProgressNotification(TSubConnectionUniqueId)
IMPORT_C void	CancelServiceChangeNotification()
IMPORT_C void	CancelWaitForIncoming()
IMPORT_C void	Close()
IMPORT_C TInt	Control(TUint, TUint, TDes8 &)
IMPORT_C void	DataReceivedNotificationCancel()
IMPORT_C void	DataReceivedNotificationCancel(TSubConnectionUniqueId)
IMPORT_C void	DataReceivedNotificationRequest(TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C void	DataReceivedNotificationRequest(TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C void	DataSentNotificationCancel()
IMPORT_C void	DataSentNotificationCancel(TSubConnectionUniqueId)
IMPORT_C void	DataSentNotificationRequest(TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C void	DataSentNotificationRequest(TSubConnectionUniqueId, TUint, TPckg< TUint > &, TRequestStatus &)
IMPORT_C void	DataTransferredCancel()
IMPORT_C void	DataTransferredCancel(TSubConnectionUniqueId)
IMPORT_C void	DataTransferredRequest(TPckg< TUint > &, TPckg< TUint > &, TRequestStatus &)
IMPORT_C void	DataTransferredRequest(TSubConnectionUniqueId, TPckg< TUint > &, TPckg< TUint > &, TRequestStatus &)
IMPORT_C TInt	EnumerateConnections(TUint &)
IMPORT_C TInt	EnumerateSubConnections(TUint &)
IMPORT_C TInt	GetBoolSetting(const TDesC &, TBool &)
IMPORT_C TInt	GetConnectionInfo(TUint, TDes8 &)
IMPORT_C TInt	GetDesSetting(const TDesC &, TDes8 &)
IMPORT_C TInt	GetDesSetting(const TDesC &, TDes16 &)
IMPORT_C TInt	GetIntSetting(const TDesC &, TUint32 &)
IMPORT_C TInt	GetLongDesSetting(const TDesC &, TDes &)
IMPORT_C TInt	GetOpt(TUint, TUint, TInt &)
IMPORT_C TInt	GetParameters(ESock::CCommsDataObjectBase &)
IMPORT_C TInt	GetSubConnectionInfo(TDes8 &)
IMPORT_C TInt	GetSubConnectionInfo(TUint, TDes8 &)
IMPORT_C void	Ioctl(TUint, TUint, TRequestStatus &, TDes8 *)
IMPORT_C void	Ioctl(TUint, TUint, TRequestStatus &)
IMPORT_C void	IsConnectionActiveCancel()
IMPORT_C void	IsConnectionActiveRequest(TUint, TPckg< TBool > &, TRequestStatus &)
IMPORT_C void	IsSubConnectionActiveCancel(TSubConnectionUniqueId)
IMPORT_C void	IsSubConnectionActiveRequest(TSubConnectionUniqueId, TUint, TPckg< TBool > &, TRequestStatus &)
IMPORT_C TInt	LastProgressError(TNifProgress &)
IMPORT_C TInt	Name(TName &)
IMPORT_C TInt	Open(RSocketServ &, TUint)
IMPORT_C TInt	Open(RSocketServ &, TName &)
IMPORT_C TInt	Progress(TNifProgress &)
IMPORT_C TInt	Progress(TSubConnectionUniqueId, TNifProgress &)
IMPORT_C void	ProgressNotification(TNifProgressBuf &, TRequestStatus &, TUint)
IMPORT_C void	ProgressNotification(TSubConnectionUniqueId, TNifProgressBuf &, TRequestStatus &, TUint)
TBool	SameSession(TInt)
IMPORT_C void	ServiceChangeNotification(TUint32 &, TDes &, TRequestStatus &)
IMPORT_C TInt	SetOpt(TUint, TUint, TInt)
IMPORT_C TInt	SetParameters(ESock::CCommsDataObjectBase &)
IMPORT_C void	Start(TRequestStatus &)
IMPORT_C void	Start(TConnPref &, TRequestStatus &)
IMPORT_C TInt	Start()
IMPORT_C TInt	Start(TConnPref &)
IMPORT_C TInt	Stop()
IMPORT_C TInt	Stop(TConnStopType)
IMPORT_C TInt	Stop(TSubConnectionUniqueId)
IMPORT_C TInt	Stop(TSubConnectionUniqueId, TConnStopType)
IMPORT_C void	WaitForIncoming(RSubConnection &, TRequestStatus &)
IMPORT_C TInt	WaitForIncoming(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.

Enumerator	Value	Description
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.

Enumerator	Value	Description
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_C

RConnection

(

)

Connection Management Interface

Empty constructor.

~RConnection ( )

IMPORT_C

~RConnection

(

)

[virtual]

Empty destructor.

Member Function Documentation

AllInterfaceNotification ( TDes8 &, TRequestStatus & )

IMPORT_C void	AllInterfaceNotification	(	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
aNotification	On return, a wrapped interface change notification (TInterfaceNotification).
aStatus	On return, the status of the request.

AllSubConnectionNotification ( TSubConnectionNotificationBuf &, TRequestStatus & )

IMPORT_C void	AllSubConnectionNotification	(	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
aStatus	On return, the status of the request.

Attach ( const TDesC8 &, TConnAttachType )

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

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
aConnectionInfo	Identity of the connection to attach to. This is a TPckg<TConnectionInfo>& (possibly obtained from a call to GetConnectionInfo()).
aAttachType	Identifies the intended use of the connection.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
dependent	on the type of connection so deferred to PRT

CancelAllInterfaceNotification ( )

IMPORT_C void

CancelAllInterfaceNotification

(

)

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

CancelAllSubConnectionNotification ( )

IMPORT_C void

CancelAllSubConnectionNotification

(

)

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 void

CancelIoctl

(

)

Cancel any outstanding Ioctl request

CancelProgressNotification ( )

IMPORT_C void

CancelProgressNotification

(

)

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

CancelProgressNotification ( TSubConnectionUniqueId )

IMPORT_C void

CancelProgressNotification

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	The identifier for the subconnection used to make the request.

CancelServiceChangeNotification ( )

IMPORT_C void

CancelServiceChangeNotification

(

)

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 void

CancelWaitForIncoming

(

)

Cancel the previous subscription for an incoming session.

since v9.2

Close ( )

IMPORT_C void

(

)

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 TInt	Control	(	TUint	aOptionLevel,
			TUint	aOptionName,
			TDes8 &	aOption
		)

Gets detailed information on connection clients and sockets.

More likely to be used by system control type applications.

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

Return Value: 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

DataReceivedNotificationCancel ( )

IMPORT_C void

DataReceivedNotificationCancel

(

)

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 void

DataReceivedNotificationCancel

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	The identifier for the subconnection used to make the request.

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

IMPORT_C void	DataReceivedNotificationRequest	(	TUint	aThreshold,
			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
aThreshold	The number of additional bytes to be received by this connection before the request completes.
aDownlinkVolume	The total number of bytes received by this connection so far
aStatus	On return, the status of the request.

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

IMPORT_C void	DataReceivedNotificationRequest	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			TUint	aThreshold,
			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.

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
aSubConnectionUniqueId	A valid identifier for a subconnection.
aThreshold	The number of additional bytes to be received by this connection before the request completes.
aDownlinkVolume	On return, the total number of bytes received by this connection so far.
aStatus	On return, the status of the request.

DataSentNotificationCancel ( )

IMPORT_C void

DataSentNotificationCancel

(

)

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 void

DataSentNotificationCancel

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	The identifier for the subconnection used to make the request.

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

IMPORT_C void	DataSentNotificationRequest	(	TUint	aThreshold,
			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
aThreshold	The number of additional bytes to be sent by this connection before the request completes.
aUplinkVolume	The total number of bytes sent by this connection so far.
aStatus	On return, the status of the request.

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

IMPORT_C void	DataSentNotificationRequest	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			TUint	aThreshold,
			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
aSubConnectionUniqueId	A valid identifier for the subconnection of interest.
aThreshold	The number of additional bytes to be sent by this connection before the request completes.
aUplinkVolume	The total number of bytes sent by this connection so far.
aStatus	On return, the status of the request.

DataTransferredCancel ( )

IMPORT_C void

DataTransferredCancel

(

)

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 void

DataTransferredCancel

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	The identifier for the subconnection used to make the request.

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

IMPORT_C void	DataTransferredRequest	(	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
aUplinkVolume	On return, contains the amount of data in bytes transferred by this connection to the remote endpoint.
aDownlinkVolume	On return, contains the amount of data in bytes transferred by this connection from the remote endpoint.
aStatus	On return, the status of the request.

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

IMPORT_C void	DataTransferredRequest	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			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
aSubConnectionUniqueId	A valid identifier for the subconnection being queried.
aUplinkVolume	On return, contains the amount of data in bytes transferred by this connection to the remote endpoint.
aDownlinkVolume	On return, contains the amount of data in bytes transferred by this connection from the remote endpoint.
aStatus	On return, the status of the request.

EnumerateConnections ( TUint & )

IMPORT_C TInt

EnumerateConnections

(

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
aCount	On 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 TInt

EnumerateSubConnections

(

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
aCount	On 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 TInt	GetBoolSetting	(	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
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").
aValue	On return, the value of the table/field pair.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
Dependent	on table - deferred to RDBMS

GetConnectionInfo ( TUint, TDes8 & )

IMPORT_C TInt	GetConnectionInfo	(	TUint	aIndex,
			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
aIndex	The index of the connection - must be between 1 and the value of aCount returned in EnumerateConnections().
aConnectionInfo	On 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 TInt	GetDesSetting	(	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
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").
aValue	On return, the value of the table/field pair.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
Dependent	on table - deferred to RDBMS

GetDesSetting ( const TDesC &, TDes16 & )

IMPORT_C TInt	GetDesSetting	(	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
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").
aValue	On return, the value of the table/field pair.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
Dependent	on table - deferred to RDBMS

GetIntSetting ( const TDesC &, TUint32 & )

IMPORT_C TInt	GetIntSetting	(	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
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").
aValue	On return, the value of the table/field pair.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
Dependent	on table - deferred to RDBMS

GetLongDesSetting ( const TDesC &, TDes & )

IMPORT_C TInt	GetLongDesSetting	(	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
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").
aValue	On return, the value of the table/field pair.

Return Value: KErrNone if succesful, or another of the system-wide error codes.

Capability
Dependent	on table - deferred to RDBMS

GetOpt ( TUint, TUint, TInt & )

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

Gets an option.

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

Return Value: 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

GetParameters ( ESock::CCommsDataObjectBase & )

IMPORT_C TInt

GetParameters

(

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 TInt

GetSubConnectionInfo

(

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
aSubConnectionInfo	A 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 TInt	GetSubConnectionInfo	(	TUint	aIndex,
			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
aIndex	The index of the connection - must be between 1 and the value of aCount returned in EnumerateSubConnections().
aSubConnectionInfo	On 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 void	Ioctl	(	TUint	aOptionLevel,
			TUint	aOptionName,
			TRequestStatus &	aStatus,
			TDes8 *	aDesc
		)

Get information on the connection in an asynchronous manner

Parameters
aOptionLevel	Option level to be used.
aOptionName	Option name to be used.

Capability
Dependent	on 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 void	Ioctl	(	TUint	aOptionLevel,
			TUint	aOptionName,
			TRequestStatus &	aStatus
		)

Get information on the connection in an asynchronous manner

Parameters
aOptionLevel	Option level to be used.
aOptionName	Option name to be used.

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

IsConnectionActiveCancel ( )

IMPORT_C void

IsConnectionActiveCancel

(

)

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 void	IsConnectionActiveRequest	(	TUint	aSecs,
			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
aSecs	The period for checking whether the connection is active. The maximum period allowed is approximately 35 mins.
aState	On entry, the state the client believes the subconnection is currently in; on return, contains the current state of the subconnection.
aStatus	On return, the status of the request

IsSubConnectionActiveCancel ( TSubConnectionUniqueId )

IMPORT_C void

IsSubConnectionActiveCancel

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	The identifier for the subconnection used to make the request

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

IMPORT_C void	IsSubConnectionActiveRequest	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			TUint	aSecs,
			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
aSubConnectionUniqueId	A valid identifier for a subconnection
aSecs	The quantisation period for checking whether the subconnection is active
aState	The state the client believes the subconnection is currently in; on return, contains the current state of the subconnection
aStatus	On return, the status of the request

LastProgressError ( TNifProgress & )

IMPORT_C TInt

LastProgressError

(

TNifProgress &

aProgress

)

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

Parameters
aProgress	A buffer to receive progress information.

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

Name ( TName & )

IMPORT_C TInt

Name

(

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
aName	On 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 TInt	Open	(	RSocketServ &	aSocketServer,
			TUint	aConnectionType = KConnectionTypeDefault
		)

Opens a new RConnection instance.

Parameters
aSocketServer	Socket Server session.
aConnectionType	Reserved.

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

Open ( RSocketServ &, TName & )

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

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

Parameters
aSocketServer	Socket Server session.
aName	Name of an existing RConnection (obtainable via Name() method).

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

Capability
Dependent	on the type of connection so deferred to PRT

Progress ( TNifProgress & )

IMPORT_C TInt

Progress

(

TNifProgress &

aProgress

)

Obtains the current progress information for the connection.

Parameters
aProgress	A buffer to receive progress information.

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

Progress ( TSubConnectionUniqueId, TNifProgress & )

IMPORT_C TInt	Progress	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			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
aSubConnectionUniqueId	A valid identifier for the subconnection of interest.
aProgress	On return, progress information.

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

ProgressNotification ( TNifProgressBuf &, TRequestStatus &, TUint )

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

Requests asynchronous progress notification for the connection.

Parameters
aProgress	A buffer to receive progress notification.
aStatus	On return, the status of the request.
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.

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

IMPORT_C void	ProgressNotification	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			TNifProgressBuf &	aProgress,
			TRequestStatus &	aStatus,
			TUint	aSelectedProgress = 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
aSubConnectionUniqueId	A valid identifier for a subconnection.
aProgress	A buffer to receive progress notification.
aStatus	On return, the status of the request.
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.

SameSession ( TInt )

TBool

SameSession

(

TInt

aSessionHandle

)

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
aSessionHandle	The 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 void	ServiceChangeNotification	(	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
aNewISPId	On completion, the new ISP Id.
aNewServiceType	On completion, the new service type.
aStatus	On 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 TInt	SetOpt	(	TUint	aOptionLevel,
			TUint	aOptionName,
			TInt	aOption = 0
		)

Sets an option.

Parameters
aOptionLevel	Option level to be set.
aOptionName	Option name to be set
aOption	Option value.

Return Value: 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

SetParameters ( ESock::CCommsDataObjectBase & )

IMPORT_C TInt

SetParameters

(

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 void

Start

(

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
aStatus	On return, the status of the request, e.g. KErrNone, KErrAlreadyExists.

Capability
Dependent	on the access point implementation

Start ( TConnPref &, TRequestStatus & )

IMPORT_C void	Start	(	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
aPref	Connection preferences.
aStatus	On return, the status of the request, e.g. KErrNone, KErrAlreadyExists.

Capability
Dependent	on the access point implementation

Start ( )

IMPORT_C TInt

Start

(

)

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
Dependent	on the access point implementation

Start ( TConnPref & )

IMPORT_C TInt

Start

(

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
aPref	Connection preferences.

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

Capability
Dependent	on the access point implementation

Stop ( )

IMPORT_C TInt

Stop

(

)

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 TInt

Stop

(

TConnStopType

aStopType

)

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
aStopType	The 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 TInt

Stop

(

TSubConnectionUniqueId

aSubConnectionUniqueId

)

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
aSubConnectionUniqueId	A valid identifier for a subconnection.

Return Value: KErrNone if successful, otherwise another of the system wide error codes.

Stop ( TSubConnectionUniqueId, TConnStopType )

IMPORT_C TInt	Stop	(	TSubConnectionUniqueId	aSubConnectionUniqueId,
			TConnStopType	aStopType
		)

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
aSubConnectionUniqueId	A valid identifier for a subconnection
aStopType	The 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 void	WaitForIncoming	(	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
aIncomingSubConnection	On 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.
aStatus	On completion, the status of the request, e.g. KErrNone or another of the system wide error codes.

WaitForIncoming ( RSubConnection & )

IMPORT_C TInt

WaitForIncoming

(

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
aIncomingSubConnection	On 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.