Provides a client endpoint to a protocol. More...

#include <es_sock.h>

Inheritance diagram for RSocket:

Public Types
enum	TShutdown { ENormal , EStopInput , EStopOutput , EImmediate }
	Argument to RSocket::Shutdown() specifying how abruptly the shutdown occurs. More...

Public Member Functions
IMPORT_C	RSocket ()
	Default Constructor.

IMPORT_C TInt	Open (RSocketServ &aServer, TUint addrFamily, TUint sockType, TUint protocol)
	Opens an implicit socket by creating a new subsession to the socket server.

IMPORT_C TInt	Open (RSocketServ &aServer, TUint addrFamily, TUint sockType, TUint protocol, RConnection &aConnection)
	Opens an explicit socket by creating a new subsession to the socket server.

IMPORT_C TInt	Open (RSocketServ &aServer, TUint addrFamily, TUint sockType, TUint protocol, RSubConnection &aSubConnection)
	Opens an explicit socket by creating a new subsession to the socket server.

IMPORT_C TInt	Open (RSocketServ &aServer, const TDesC &aName)
	Opens an implicit socket by creating a new subsession to the socket server.

IMPORT_C TInt	Open (RSocketServ &aServer)
	Opens an implicit socket by creating a new subsession to the socket server.

IMPORT_C void	Send (const TDesC8 &aDesc, TUint someFlags, TRequestStatus &aStatus)
	Sends data to a remote host on a connected socket with options set by protocol specific flags.

IMPORT_C void	Send (const TDesC8 &aDesc, TUint someFlags, TRequestStatus &aStatus, TSockXfrLength &aLen)
	Sends data to a remote host on a connected socket with options set by protocol specific flags.

IMPORT_C void	CancelSend ()
	Cancels an outstanding Send() operation.

IMPORT_C void	Recv (TDes8 &aDesc, TUint flags, TRequestStatus &aStatus)
	Receives data from a remote host, allowing flags for protocol specific information.

IMPORT_C void	Recv (TDes8 &aDesc, TUint flags, TRequestStatus &aStatus, TSockXfrLength &aLen)
	Receives data from a remote host, allowing flags for protocol specific information.

IMPORT_C void	RecvOneOrMore (TDes8 &aDesc, TUint flags, TRequestStatus &aStatus, TSockXfrLength &aLen)
	Receives data from a remote host and completes when data is available.

IMPORT_C void	RecvOneOrMore (TDes8 &aDesc, TUint flags, TRequestStatus &aStatus)
	Receives data from a remote host and completes when data is available.

IMPORT_C void	CancelRecv ()
	Cancels an outstanding Recv() operation.

IMPORT_C void	Read (TDes8 &aDesc, TRequestStatus &aStatus)
	Receives data from a remote host.

IMPORT_C void	CancelRead ()
	Cancels an outstanding Read() operation.

IMPORT_C void	Write (const TDesC8 &aDesc, TRequestStatus &aStatus)
	Sends data to a remote host.

IMPORT_C void	CancelWrite ()
	Cancels an outstanding Write() operation.

IMPORT_C void	SendTo (const TDesC8 &aDesc, TSockAddr &anAddr, TUint flags, TRequestStatus &aStatus)
	Sends data to a remote host through a (possibly) unconnected socket to a specified destination address.

IMPORT_C void	SendTo (const TDesC8 &aDesc, TSockAddr &anAddr, TUint flags, TRequestStatus &aStatus, TSockXfrLength &aLen)
	Sends data to a remote host through a (possibly) unconnected socket to a specified destination address.

IMPORT_C void	RecvFrom (TDes8 &aDesc, TSockAddr &anAddr, TUint flags, TRequestStatus &aStatus)
	Receives data from a remote host through a (possibly) unconnected socket and returns a source address.

IMPORT_C void	RecvFrom (TDes8 &aDesc, TSockAddr &anAddr, TUint flags, TRequestStatus &aStatus, TSockXfrLength &aLen)
	Receives data from a remote host through a (possibly) unconnected socket where a source address is returned.

IMPORT_C void	Connect (TSockAddr &anAddr, TRequestStatus &aStatus)
	Connects to a remote host asynchronously.

IMPORT_C void	Connect (TSockAddr &anAddr, const TDesC8 &aConnectDataOut, TDes8 &aConnectDataIn, TRequestStatus &aStatus)
	Connects to a remote host asynchronously.

IMPORT_C void	CancelConnect ()
	Cancels an outstanding connect operation.

IMPORT_C TInt	Bind (TSockAddr &anAddr)
	Sets the local address of a socket.

IMPORT_C TInt	SetLocalPort (TInt aPort)
	Sets the local port of a socket.

IMPORT_C void	Accept (RSocket &aBlankSocket, TRequestStatus &aStatus)
	Facilitates a client/server connection from a remote socket.

IMPORT_C void	Accept (RSocket &aBlankSocket, TDes8 &aConnectData, TRequestStatus &aStatus)
	Facilitates a client/server connection from a remote socket.

IMPORT_C void	CancelAccept ()
	Cancels an outstanding accept operation.

IMPORT_C TInt	Listen (TUint qSize)
	Sets up a socket to listen for incoming connections.

IMPORT_C TInt	Listen (TUint qSize, const TDesC8 &aConnectData)
	Sets up a socket to listen for incoming connections.

IMPORT_C TInt	SetOpt (TUint anOptionName, TUint anOptionLevel, const TDesC8 &anOption=TPtrC8(NULL, 0))
	Sets a socket option.

IMPORT_C TInt	SetOpt (TUint anOptionName, TUint anOptionLevel, TInt anOption)
	Sets a socket option.

IMPORT_C TInt	GetOpt (TUint anOptionName, TUint anOptionLevel, TDes8 &anOption)
	Gets a socket option.

IMPORT_C TInt	GetOpt (TUint anOptionName, TUint anOptionLevel, TInt &anOption)
	Gets a socket option.

IMPORT_C void	Ioctl (TUint aCommand, TRequestStatus &aStatus, TDes8 *aDesc=NULL, TUint aLevel=KLevelUnspecified)
	Applies an asynchronous I/O control operation on a socket.

IMPORT_C void	CancelIoctl ()
	Cancels an outstanding Ioctl() operation.

IMPORT_C TInt	GetDisconnectData (TDes8 &aDesc)
	Gets data for use in the disconnection of a socket, namely the remote name of the connected socket.

IMPORT_C void	LocalName (TSockAddr &anAddr)
	Gets the local address of a bound socket.

IMPORT_C TUint	LocalPort ()
	Gets the local port number of a bound socket.

IMPORT_C void	RemoteName (TSockAddr &anAddr)
	Gets the remote name of a connected socket.

IMPORT_C void	Close ()
	Closes a socket.

IMPORT_C void	Shutdown (TShutdown aHow, TRequestStatus &aStatus)
	Shuts down a connected socket - asynchronous.

IMPORT_C void	Shutdown (TShutdown aHow, const TDesC8 &aDisconnectDataOut, TDes8 &aDisconnectDataIn, TRequestStatus &aStatus)
	Shuts down a connected socket with disconnect data - asynchronous.

IMPORT_C void	CancelAll ()
	Cancels all outstanding operations.

IMPORT_C TInt	Info (TProtocolDesc &aProtocol)
	Gets information in the protocol description for the protocol which a socket is opened on.

IMPORT_C TInt	Name (TName &aName)
	Gets a unique system name for the socket.

IMPORT_C TInt	Transfer (RSocketServ &aServer, const TDesC &aName)
	Transfers a socket from one socket server session to another.

Friends
class	RSocketServ

Detailed Description

Provides a client endpoint to a protocol.

It provides functions for socket creation, reading, writing, passive connection, active connection, setting addresses and querying addresses. Use this class as an endpoint for network type communications. It provides the following services:

reading from and writing to protocol

binding to addresses

active connecting

passive connection through the listen/accept model

Before using any of these services, a connection to a socket server session must have been made and the socket must be open.

API status: Published to all clients. Released API. Since v5.0

Definition at line 834 of file es_sock.h.

Member Enumeration Documentation

◆ TShutdown

enum RSocket::TShutdown

Argument to RSocket::Shutdown() specifying how abruptly the shutdown occurs.

Enumerator
ENormal	Complete when socket output/input stopped.
EStopInput	Stop socket input and complete when output is stopped.
EStopOutput	Stop socket output and complete when input is stopped.
EImmediate	Stop socket input/output and complete (abortive close).

Definition at line 860 of file es_sock.h.

Constructor & Destructor Documentation

◆ RSocket()

IMPORT_C RSocket::RSocket ( )

Default Constructor.

(generated from Symbian Developer Library)

Member Function Documentation

◆ Accept() [1/2]

IMPORT_C void RSocket::Accept	(	RSocket &	aBlankSocket,
		TDes8 &	aConnectData,
		TRequestStatus &	aStatus
	)

Facilitates a client/server connection from a remote socket.

Extracts the first pending connection on a queue of sockets, the queue size being previously specified by Listen(). On successful completion the blank socket is given the handle of the new socket and it may then be used to transfer data. After completion the accept socket may be used to make further connections with new blank sockets (see Open() on how to open a blank socket).

This variant provides an additional descriptor argument to receive data which may have been sent in a connect request. If there is a pending connection in the listen queue when Accept() is called, the call will complete immediately. Otherwise it will wait until a socket becomes available in the queue and complete asynchronously.

Accept() may be used for protocols which do not have the KSIConnectionLess flag in their protocol information.

To receive data-in accepting, a protocol must have the flag KSIConnectData in its protocol information.

Parameters

aBlankSocket	A socket opened as a blank socket.
aConnectData	Data which may have been received in connection.
aStatus	On completion, will contain an error code: see the system-wide error codes.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Accept() [2/2]

IMPORT_C void RSocket::Accept	(	RSocket &	aBlankSocket,
		TRequestStatus &	aStatus
	)

Facilitates a client/server connection from a remote socket.

Extracts the first pending connection on a queue of sockets, the queue size being previously specified by Listen(). On successful completion the blank socket is given the handle of the new socket and it may then be used to transfer data. After completion the accept socket may be used to make further connections with new blank sockets (see Open() on how to open a blank socket).

Accept() may be used for protocols which do not have the KSIConnectionLess flag in their protocol information.

Parameters

aBlankSocket	A socket opened as a blank socket.
aStatus	On completion, will contain an error code: see the system-wide error codes.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Bind()

IMPORT_C TInt RSocket::Bind ( TSockAddr & anAddr )

Sets the local address of a socket.

When a socket is opened it has no name associated with it, and binding is required so data can be routed to the socket.

Bind() should be called before Listen() or Connect(). The address supplied should be a derived class specific to the particular protocol the socket was opened on.

Parameters

anAddr Desired local address of socket.

(generated from Symbian Developer Library)

◆ CancelAccept()

IMPORT_C void RSocket::CancelAccept ( )

Cancels an outstanding accept operation.

Will cause any outstanding accept operation to complete prematurely.

(generated from Symbian Developer Library)

◆ CancelAll()

IMPORT_C void RSocket::CancelAll ( )

Cancels all outstanding operations.

Will cause all outstanding operations to complete prematurely.

Outstanding operations for a socket include: read, write, Ioctl, connect, accept and shutdown. All of these operations will be completed by this call.

(generated from Symbian Developer Library)

◆ CancelConnect()

IMPORT_C void RSocket::CancelConnect ( )

Cancels an outstanding connect operation.

Will cause any outstanding connect operation to complete prematurely.

The state of a socket after a connect is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ CancelIoctl()

IMPORT_C void RSocket::CancelIoctl ( )

Cancels an outstanding Ioctl() operation.

Will cause any outstanding Ioctl operation to complete prematurely.

The state of a socket after a connect is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ CancelRead()

IMPORT_C void RSocket::CancelRead ( )

Cancels an outstanding Read() operation.

Calling this function will cause any outstanding Read() operation to complete prematurely. The state of a socket after a receive is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ CancelRecv()

IMPORT_C void RSocket::CancelRecv ( )

Cancels an outstanding Recv() operation.

Calling this function will cause any outstanding receive operation to complete prematurely. The state of a socket after a receive is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ CancelSend()

IMPORT_C void RSocket::CancelSend ( )

Cancels an outstanding Send() operation.

Calling the function will cause any outstanding send operation to complete prematurely. The state of a socket after a send is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ CancelWrite()

IMPORT_C void RSocket::CancelWrite ( )

Cancels an outstanding Write() operation.

Calling the function will cause any outstanding Write() operation to complete prematurely. The state of a socket after a send is cancelled is defined by the characteristics of the protocol.

(generated from Symbian Developer Library)

◆ Close()

IMPORT_C void RSocket::Close ( )

Closes a socket.

If a socket has been opened using Open() then it should be closed using Close(). This will ensure all associated resources are released.

Closing serves two distinct purposes:

To release resources associated with the IPC channel to the socket server.

To disconnect a socket if it is connected.

If a socket is connected, then calling close is equivalent to calling Shutdown() with an argument of RSocket::ENormal, synchronously waiting for the request to complete, and then closing the IPC channel. If asynchronous or alternative methods of disconnecting are required then Shutdown() should be called before Close().

If the RSocketServ session on which a protocol was opened is closed, then all sockets associated with that session will be abortively closed and any further requests on the sockets will result in panics.

If a protocol has the flag KSIGracefulClose in its protocol information, when Close() is called on a connected socket, the socket will synchronously block until a response to a close request has been received or some other protocol condition causes the call to complete.

(generated from Symbian Developer Library)

◆ Connect() [1/2]

IMPORT_C void RSocket::Connect	(	TSockAddr &	anAddr,
		const TDesC8 &	aConnectDataOut,
		TDes8 &	aConnectDataIn,
		TRequestStatus &	aStatus
	)

Connects to a remote host asynchronously.

The address provided specifies the address of the remote host.

Some protocols allow data to be sent in connect request packets which may be provided in the data-out descriptor. Some protocols may allow data to be sent in connect responses which may be collected in the data-in descriptor.

A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound - i.e. Bind() has not been called yet - then it will automatically have a local address allocated.

Connect() is always required for protocols which do not have the KSIConnectionLess flag in their protocol information. If a protocol has the KSIConnectionLess flag, then Connect() may be used to set the address for all data sent from the socket, in which case Send()/Write() may be used in addition to SendTo().

To use data in connection a protocol must have the flag KSIConnectData in its protocol information.

To cancel a connect use CancelConnect().

Parameters

anAddr	Address of remote host.
aStatus	On completion, will contain an error code. KErrBadHandle if the socket has already been closed by the client; KErrAlreadyExists if the socket is already connected and it isn't a blocking connection; otherwise one of the system-wide error codes.

Panic condition: EConnectingAlready if the socket is connection-oriented and a blocking connection is already in progress for the socket

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Connect() [2/2]

IMPORT_C void RSocket::Connect	(	TSockAddr &	anAddr,
		TRequestStatus &	aStatus
	)

Connects to a remote host asynchronously.

The address provided specifies the address of the remote host.

A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound - i.e. Bind() has not been called yet - then it will automatically have a local address allocated.

Connect() is always required for protocols which do not have the KSIConnectionLess flag in their protocol information. If a protocol has the KSIConnectionLess flag, then Connect() may be used to set the address for all data sent from the socket, in which case Send()/Write() may be used in addition to SendTo().

To use data in connection a protocol must have the flag KSIConnectData in its protocol information.

To cancel a connect use CancelConnect().

Parameters

anAddr	Address of remote host.
aStatus	On completion, will contain an error code, see the system-wide error codes.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ GetDisconnectData()

IMPORT_C TInt RSocket::GetDisconnectData ( TDes8 & aDesc )

Gets data for use in the disconnection of a socket, namely the remote name of the connected socket.

This data has been received in a protocol disconnect message.

To use the data in disconnection, a protocol must have the flagKSIConnectData in its protocol information.

Parameters

aDesc A descriptor to receive data.

(generated from Symbian Developer Library)

◆ GetOpt() [1/2]

IMPORT_C TInt RSocket::GetOpt	(	TUint	anOptionName,
		TUint	anOptionLevel,
		TDes8 &	anOption
	)

Gets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be got with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

anOptionName	An integer constant which identifies an option.
anOptionLevel	An integer constant which identifies level of an option.
anOption	On return, option value packaged in a descriptor.

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

(generated from Symbian Developer Library)

◆ GetOpt() [2/2]

IMPORT_C TInt RSocket::GetOpt	(	TUint	anOptionName,
		TUint	anOptionLevel,
		TInt &	anOption
	)

Gets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be got with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

anOptionName	An integer constant which identifies an option.
anOptionLevel	An integer constant which identifies level of an option.
anOption	On return, option value as an integer.

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

(generated from Symbian Developer Library)

◆ Info()

IMPORT_C TInt RSocket::Info ( TProtocolDesc & aProtocol )

Gets information in the protocol description for the protocol which a socket is opened on.

Parameters

aProtocol A protocol description type to hold protocol information.

(generated from Symbian Developer Library)

◆ Ioctl()

IMPORT_C void RSocket::Ioctl	(	TUint	aCommand,
		TRequestStatus &	aStatus,
		TDes8 *	aDesc = `NULL`,
		TUint	aLevel = `KLevelUnspecified`
	)

Applies an asynchronous I/O control operation on a socket.

Data may be passed and received if a descriptor address is provided as an argument. Only one Ioctl() operation may be outstanding for each socket.

Commands available for all protocols can be set withaLevel set to KSOLSocket. See individual protocol notes for other commands.

Parameters

aCommand	Ioctl command.
aStatus	On completion, will contain an error code: see the system-wide error codes.
aDesc	Pointer to a descriptor in which data may be sent and received on completion
aLevel	Control operation level

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

(generated from Symbian Developer Library)

◆ Listen() [1/2]

IMPORT_C TInt RSocket::Listen ( TUint qSize )

Sets up a socket to listen for incoming connections.

Before calling this procedure a socket should be opened on a specific protocol using Open() and the socket should be bound to a local address using Bind().

Listen() creates a queue to hold incoming connections which can be married with blank sockets using Accept(). The call also allows data to be sent back to connecting peers if a protocol allows data to be passed in connect responses. Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

Parameters

qSize Size of listen queue.

(generated from Symbian Developer Library)

◆ Listen() [2/2]

IMPORT_C TInt RSocket::Listen	(	TUint	qSize,
		const TDesC8 &	aConnectData
	)

Sets up a socket to listen for incoming connections.

Before calling this procedure a socket should be opened on a specific protocol using Open() and the socket should be bound to a local address using Bind().

Listen() creates a queue to hold incoming connections which can be married with blank sockets using Accept(). The call also allows data to be sent back to connecting peers if a protocol allows data to be passed in connect responses. Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

To use data-in listening, a protocol must have the flag KSIConnectData in its protocol information.

Parameters

qSize Size of listen queue.

(generated from Symbian Developer Library)

◆ LocalName()

IMPORT_C void RSocket::LocalName ( TSockAddr & anAddr )

Gets the local address of a bound socket.

The local address is set either by calling Bind(), or is automatically set when Connect() is called.

If a socket is created through Accept() then a socket will inherit the port of its parent unless otherwise specified by a protocol's behaviour.

Depending on a protocol implementation, additional information may be gained through this call.

Parameters

anAddr Local address which is filled in on return.

(generated from Symbian Developer Library)

◆ LocalPort()

IMPORT_C TUint RSocket::LocalPort ( )

Gets the local port number of a bound socket.

Getting the local port is similar to getting the local name.

LocalName() for a description.

(generated from Symbian Developer Library)

◆ Name()

IMPORT_C TInt RSocket::Name ( TName & aName )

Gets a unique system name for the socket.

The purpose of this is to identify the socket in a call to Transfer().

Parameters

aName System name for the socket

(generated from Symbian Developer Library)

◆ Open() [1/5]

IMPORT_C TInt RSocket::Open ( RSocketServ & aServer )

Opens an implicit socket by creating a new subsession to the socket server.

Implicit socket is not explicitly associated with any connection. The socket will choose the default connection for sending the packets.

Implicit socket accepts packets routed through any connection.

Provides a blank channel to the socket server which has no protocol associated. A socket opened in this manner is suitable as an argument to Accept(), which will marry the blank socket to a protocol when a connection is established to a remote endpoint.

Parameters

aServer The socket server session.

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Open() [2/5]

IMPORT_C TInt RSocket::Open	(	RSocketServ &	aServer,
		const TDesC &	aName
	)

Opens an implicit socket by creating a new subsession to the socket server.

Implicit socket is not explicitly associated with any connection. The socket will choose the default connection for sending the packets.

Implicit socket accepts packets routed through any connection.

Opens a channel to a protocol identified by a name. If a socket is the first to be opened for a protocol it will have the additional effect of loading the protocol in the socket server.

The default connection scenario is where an application holding one started RConnection opens a socket without explicitly associating it with the RConnection. The explicit association can be made by passing the RConnection or a derived RSubConnection to an appropriate overload of RSocket::Open(...) (not this method).
The implicit connection scenario is where an application holding either none or many started RConnections (to different access points) opens a socket without explicitly associating it an RConnection.
The explicit connection scenario is where an application holding started RConnections opens a socket explicitly associating it with one of its RConnections.

Applications attempting to exercise the default connection scenario shall (from 9.3 onwards) receive an error from RSocket::Open(...). The actual error code is yet to be defined.

Parameters

aServer	The socket server session.
aName	Name of a protocol.

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Open() [3/5]

IMPORT_C TInt RSocket::Open	(	RSocketServ &	aServer,
		TUint	addrFamily,
		TUint	sockType,
		TUint	protocol
	)

Opens an implicit socket by creating a new subsession to the socket server.

Implicit socket is not explicitly associated with any connection. The socket will choose the default connection for sending the packets.

Implicit socket accepts packets routed through any connection.

Opens a channel to a protocol identified by a tuple of constants. If a socket is the first to be opened for a protocol it will have the additional effect of loading the protocol in the socket server.

The default connection scenario is where an application holding one started RConnection opens a socket without explicitly associating it with the RConnection. The explicit association can be made by passing the RConnection or a derived RSubConnection to an appropriate overload of RSocket::Open(...) (not this method).
The implicit connection scenario is where an application holding either none or many started RConnections (to different access points) opens a socket without explicitly associating it an RConnection.
The explicit connection scenario is where an application holding started RConnections opens a socket explicitly associating it with one of its RConnections.

Applications attempting to exercise the default connection scenario shall (from 9.3 onwards) receive an error from RSocket::Open(...). The actual error code is yet to be defined.

Parameters

aServer	The socket server session.
addrFamily	A valid address constant for a protocol family.
sockType	A valid socket type for the protocol.
protocol	A protocol constant which identifies a specific protocol.

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Open() [4/5]

IMPORT_C TInt RSocket::Open	(	RSocketServ &	aServer,
		TUint	addrFamily,
		TUint	sockType,
		TUint	protocol,
		RConnection &	aConnection
	)

Opens an explicit socket by creating a new subsession to the socket server.

The socket is explicitly associated with the same underlying connection as an existing RConnection instance.

Socket traffic is directed to and from the specified connection only.

The association is instantaneous, in that the socket is associated with the interface that the RConnection is associated with at the present time. This association terminates when the underlying interface goes down.

Parameters

aServer	The socket server session.
addrFamily	A valid address constant for a protocol family.
sockType	A valid socket type for the protocol.
protocol	A protocol constant which identifies a specific protocol.
aConnection	Existing RConnection whose interface this socket will be associated with.

capability: Dependent Capability required depends on the type of connection so deferred to PRT

(generated from Symbian Developer Library)

◆ Open() [5/5]

IMPORT_C TInt RSocket::Open	(	RSocketServ &	aServer,
		TUint	addrFamily,
		TUint	sockType,
		TUint	protocol,
		RSubConnection &	aSubConnection
	)

Opens an explicit socket by creating a new subsession to the socket server.

The socket is explicitly associated with the same underlying connection as an existing RSubConnection instance.

Socket traffic is directed to and from the specified connection only.

since 7.0S

Parameters

aServer	The socket server session.
addrFamily	A valid address constant for a protocol family.
sockType	A valid socket type for the protocol.
protocol	A protocol constant which identifies a specific protocol.
aSubConnection	Existing RSubConnection this socket will be associated with.

capability: Dependent Capability required depends on the type of connection so deferred to PRT

(generated from Symbian Developer Library)

◆ Read()

IMPORT_C void RSocket::Read	(	TDes8 &	aDesc,
		TRequestStatus &	aStatus
	)

Receives data from a remote host.

For a stream-interfaced sockets, the function only completes when the full amount of requested data has been received (or the connection breaks). This means when the descriptor has been filled to its maximum length (not its current length). For a connection-oriented datagram-interface, the function completes when a datagram arrives even if it is not sufficient to fill the buffer.

Read() should only be used with connected sockets.

A socket may only have one receive operation outstanding at any one time.

Parameters

aDesc	A descriptor where data read will be placed.
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Recv() [1/2]

IMPORT_C void RSocket::Recv	(	TDes8 &	aDesc,
		TUint	flags,
		TRequestStatus &	aStatus
	)

Receives data from a remote host, allowing flags for protocol specific information.

For a stream-interfaced socket the function only completes when the full amount of requested data has been received (or the connection breaks). This means when the descriptor has been filled to its maximum length (not its current length).

For a datagram-interface socket, the function completes when one datagram arrives - even if it is not sufficient to fill the buffer. If the datagram does not fit in the buffer supplied then the remaining data will be lost.

Recv() should only be used with connected sockets.

A socket may only have one receive operation outstanding at any one time.

If a protocol's information flag is marked with KSIPeekData, then KSockReadPeek may be provided as a flag to Recv(). All other flags are protocol specific.

Parameters

aDesc	A descriptor where data received will be placed.
flags	Flags for protocol specific information.
aStatus	On return, KErrNone if successful, otherwise another of the system-wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Recv() [2/2]

IMPORT_C void RSocket::Recv	(	TDes8 &	aDesc,
		TUint	flags,
		TRequestStatus &	aStatus,
		TSockXfrLength &	aLen
	)

Receives data from a remote host, allowing flags for protocol specific information.

For a stream-interfaced sockets, the function only completes when the full amount of requested data has been received (or the connection breaks). This means when the descriptor has been filled to its maximum length (not its current length).

For a datagram-interface socket, the function completes when one datagram arrives - even if it is not sufficient to fill the buffer. If the datagram does not fit in the buffer supplied, remaining data may be retrieved using the Datagram Continuation feature.

This function implements the Datagram Continuation feature for PRTs implementing PRT1.5: the ability to read a datagram in parts. For a client request to read a datagram, using the TSockXfrLength parameter, remaining unread octets of the datagram are returned in the TSockXfrLength parameter. The client can then read the remaining octets by further reads with the 'KSockReadContinuation' flag OR'd into the flags field. Remaining octets are discarded upon the next read without the KSockReadContinuation flag set.

Recv() should only be used with connected sockets.

A socket may only have one receive operation outstanding at any one time.

If a protocol's information flag is marked with KSIPeekData, then KSockReadPeek may be provided as a flag to Recv(). All other flags are protocol specific.

Parameters

aDesc	A descriptor where data received will be placed.
flags	Flags for protocol specific information.
aStatus	Reference to the request status object. On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.
aLen	For non-datagram sockets, on return, a length which indicates how much data was read. This is the same as length of the returned aDesc. For datagram sockets, this parameter returns the number of remaining unread octets.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ RecvFrom() [1/2]

IMPORT_C void RSocket::RecvFrom	(	TDes8 &	aDesc,
		TSockAddr &	anAddr,
		TUint	flags,
		TRequestStatus &	aStatus
	)

Receives data from a remote host through a (possibly) unconnected socket and returns a source address.

Flags are provided to add protocol specific information.

A socket may only have one receive operation outstanding at any one time.

Parameters

aDesc	A descriptor where data read will be placed.
anAddr	A remote source address for unconnected receives. Returns KAfInet6 in TSockAddr::Family() for IPv4 ICMP packets. Returns KAfInet for IPv4 TCP and UDP sockets.
flags	Flags which are passed through to protocol.
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ RecvFrom() [2/2]

IMPORT_C void RSocket::RecvFrom	(	TDes8 &	aDesc,
		TSockAddr &	anAddr,
		TUint	flags,
		TRequestStatus &	aStatus,
		TSockXfrLength &	aLen
	)

Receives data from a remote host through a (possibly) unconnected socket where a source address is returned.

Flags are provided to add protocol specific information.

A socket may only have one receive operation outstanding at any one time.

Parameters

aDesc	A descriptor where data read will be placed
anAddr	A remote source address for unconnected receives. Returns KAfInet6 in TSockAddr::Family() for IPv4 ICMP packets. Returns KAfInet for IPv4 TCP and UDP sockets.
flags	Flags which are passed through to protocol
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.
aLen	For non-datagram sockets, on return, a length which indicates how much data was read. This is the same as length of the returned aDesc. For datagram sockets, this parameter is not used.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ RecvOneOrMore() [1/2]

IMPORT_C void RSocket::RecvOneOrMore	(	TDes8 &	aDesc,
		TUint	flags,
		TRequestStatus &	aStatus
	)

Receives data from a remote host and completes when data is available.

The function reads at least one byte of data, but will complete as soon as any data is available. The amount of data received is returned via the TSockXfrLength argument.

RecvOneOrMore() can only be used with stream-interfaced connected sockets; datagram interface sockets will return KErrNotSupported.

A socket may only have one receive operation outstanding at any one time.

Parameters

aDesc	A descriptor where data read will be placed.
flags	Flags which are passed through to protocol.
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ RecvOneOrMore() [2/2]

IMPORT_C void RSocket::RecvOneOrMore	(	TDes8 &	aDesc,
		TUint	flags,
		TRequestStatus &	aStatus,
		TSockXfrLength &	aLen
	)

Receives data from a remote host and completes when data is available.

The function reads at least one byte of data, but will complete as soon as any data is available. The amount of data received is returned via the TSockXfrLength argument.

RecvOneOrMore() can only be used with stream-interfaced connected sockets; datagram interface sockets will return KErrNotSupported.

A socket may only have one receive operation outstanding at any one time.

Parameters

aDesc	A descriptor where data read will be placed.
flags	Flags which are passed through to protocol.
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates either that a remote connection is closed, and that no more data is available for reading, or the socket has been shutdown with option RSocket::EStopInput.
aLen	For non-datagram sockets, on return, a length which indicates how much data was read. This is the same as length of the returned aDesc. For datagram sockets, this parameter is not used.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ RemoteName()

IMPORT_C void RSocket::RemoteName ( TSockAddr & anAddr )

Gets the remote name of a connected socket.

The remote name of a socket is associated with the remote host a socket is connected to. The remote name is only valid for a connected socket. A socket is either connected through calling Connect() or Accept().

Parameters

anAddr Remote address which is filled in on return.

(generated from Symbian Developer Library)

◆ Send() [1/2]

IMPORT_C void RSocket::Send	(	const TDesC8 &	aDesc,
		TUint	someFlags,
		TRequestStatus &	aStatus
	)

Sends data to a remote host on a connected socket with options set by protocol specific flags.

A socket may only have one send operation in progress at any one time. Send() should only be used with connected sockets.

If a protocol's information flag is marked with KSIUrgentData, then KSockWriteUrgent may be provided as a flag to Send(). All other flags are protocol specific.

Parameters

aDesc	The data to be sent.
someFlags	Flags which are passed through to protocol
aStatus	On return KErrNone if successful, otherwise another of the system-wide error codes. Note that KErrEof indicates that the socket has been shutdown with option EStopOutput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Send() [2/2]

IMPORT_C void RSocket::Send	(	const TDesC8 &	aDesc,
		TUint	someFlags,
		TRequestStatus &	aStatus,
		TSockXfrLength &	aLen
	)

Sends data to a remote host on a connected socket with options set by protocol specific flags.

The length of the descriptor indicates the amount of data to be sent. The TSockXfrLength argument will return the amount of data actually sent.

A socket may only have one send operation in progress at any one time.

Send() should only be used with connected sockets.

If a protocol's information flag is marked with KSIUrgentData, then KSockWriteUrgent may be provided as a flag to Send(). All other flags are protocol specific.

Parameters

aDesc	The data to be sent.
someFlags	Flags which are passed through to protocol
aStatus	On return KErrNone if successful, otherwise another of the system-wide error codes. Note that KErrEof indicates that the socket has been shutdown with option EStopOutput
aLen	Filled in with amount of data sent before completion

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ SendTo() [1/2]

IMPORT_C void RSocket::SendTo	(	const TDesC8 &	aDesc,
		TSockAddr &	anAddr,
		TUint	flags,
		TRequestStatus &	aStatus
	)

Sends data to a remote host through a (possibly) unconnected socket to a specified destination address.

Flags are provided to add protocol specific information. The length of the descriptor indicates the amount of data to be sent. A socket may only have one send operation in progress at any one time.

Parameters

aDesc	The data to be sent.
anAddr	A remote destination address for unconnected sends
flags	Flags which are passed through to protocol
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates that the socket has been shutdown with option EStopOutput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ SendTo() [2/2]

IMPORT_C void RSocket::SendTo	(	const TDesC8 &	aDesc,
		TSockAddr &	anAddr,
		TUint	flags,
		TRequestStatus &	aStatus,
		TSockXfrLength &	aLen
	)

Sends data to a remote host through a (possibly) unconnected socket to a specified destination address.

Flags are provided to add protocol specific information. The length of the descriptor indicates the amount of data to be sent. A socket may only have one send operation in progress at any one time. The TSockXfrLength argument will return the amount of data sent.

Parameters

aDesc	The data to be sent.
anAddr	A remote destination address for unconnected sends
flags	Flags which are passed through to protocol
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates that the socket has been shutdown with option EStopOutput. In the case of KSONonBlockingIO & writeFlowedoff, it has to return KerrWouldBlock, but it returns KErrNone for compatibiity
aLen	Filled in with amount of data sent before completion

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ SetLocalPort()

IMPORT_C TInt RSocket::SetLocalPort ( TInt aPort )

Sets the local port of a socket.

Setting the local port is equivalent to calling Bind() with only the port set in the address.

Parameters

aPort Desired local port of socket.

(generated from Symbian Developer Library)

◆ SetOpt() [1/2]

IMPORT_C TInt RSocket::SetOpt	(	TUint	anOptionName,
		TUint	anOptionLevel,
		const TDesC8 &	anOption = `TPtrC8(NULL,0)`
	)

Sets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be set with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

anOptionName	An integer constant which identifies an option.
anOptionLevel	An integer constant which identifies level of an option: i.e. an option level groups related options together.
anOption	Option value packaged in a descriptor.

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

(generated from Symbian Developer Library)

◆ SetOpt() [2/2]

IMPORT_C TInt RSocket::SetOpt	(	TUint	anOptionName,
		TUint	anOptionLevel,
		TInt	anOption
	)

Sets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be set with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

anOptionName	An integer constant which identifies an option.
anOptionLevel	An integer constant which identifies level of an option: i.e. an option level groups related options together.
anOption	Option value as an integer.

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

(generated from Symbian Developer Library)

◆ Shutdown() [1/2]

IMPORT_C void RSocket::Shutdown	(	TShutdown	aHow,
		const TDesC8 &	aDisconnectDataOut,
		TDes8 &	aDisconnectDataIn,
		TRequestStatus &	aStatus
	)

Shuts down a connected socket with disconnect data - asynchronous.

This method is asynchronous as non emergency shutdown may take a while.

The shut down method allows input and output to be individually stopped for a protocol endpoint. For protocols which support data-in disconnect message, additional arguments are provided.

Shutdown() can be used for protocols which do not have the KSIConnectionLess flag in their protocol information.

To use data in disconnection a protocol must have the flag KSIConnectData in its protocol information.

There is no way to cancel a socket shutdown once it has started.

Parameters

aHow	Shutdown option. All variants complete when a socket is disconnected.
aDisconnectDataOut	A descriptor containing data to be sent.
aDisconnectDataIn	A descriptor to receive data.
aStatus	On return KErrNone if successful, otherwise another of the system-wide error codes.

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Shutdown() [2/2]

IMPORT_C void RSocket::Shutdown	(	TShutdown	aHow,
		TRequestStatus &	aStatus
	)

Shuts down a connected socket - asynchronous.

This method is asynchronous as non emergency shutdown may take a while.

The shut down method allows input and output to be individually stopped for a protocol endpoint. For protocols which support data-in disconnect message, additional arguments are provided.

Shutdown() can be used for protocols which do not have the KSIConnectionLess flag in their protocol information.

To use data in disconnection a protocol must have the flag KSIDisconnectData in its protocol information.

There is no way to cancel a socket shutdown once it has started.

Parameters

aHow Shutdown option. All variants complete when a socket is disconnected. If the parameter is within the range of TShutdown values, pending read and write operations are cancelled. If the parameter is outside the range of TShutdown values, then the behaviour is as if ENormal were specified except that pending read and write operations are not cancelled. Note that the behaviour of using parameters outside the range of TShutdown values may change in a future release and should not be relied upon.

aStatus On return KErrNone if successful, otherwise another of the system-wide error codes.

capability: Dependent Capability required depends on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

◆ Transfer()

IMPORT_C TInt RSocket::Transfer	(	RSocketServ &	aServer,
		const TDesC &	aName
	)

Transfers a socket from one socket server session to another.

It creates the socket in the target session, and removes the socket from the source session. The call is made on an uninitialised RSocket object. The socket system name is used to identify the socket to transfer.

If the call fails, the socket that is being transferred remains with the original session. Success or failure can be checked on the originating socket by calling Info(), which returns KErrNone if the transfer failed, and KErrBadHandle if it succeeded.

Platsec considerations require that the source socket must set itself transferable before any attempt to transfer the socket to the destination socket. This is done using a setopt in the following way

_LIT_SECURITY_POLICY_Cn(KProcPolicy, cap1, cap2, ... capn);

ret = destsock.SetOpt(KSOEnableTransfer, KSOLSocket, KProcPolicy().Package());

KSOLSocket

const TInt KSOLSocket

Generic socket options/commands.

Definition es_sock.h:308

KSOEnableTransfer

const TUint KSOEnableTransfer

Setting only.

Definition es_sock.h:391

where cap1,cap2...capn are the capabilities that the destination process MUST have in order to affect the transfer.

An example is:

_LIT_SECURITY_POLICY_C2(KProcPolicy, ECapabilityNetworkServices,
                        ECapabilityNetworkControl);
ret = destsock.SetOpt(KSOEnableTransfer, KSOLSocket, KProcPolicy().Package());

If the setOpt is not set or the destination process does not have sufficient capabilities then the function will return KErrPermissionDenied

Parameters

aServer	The session into which to transfer the socket.
aName	The system name, as obtained from a call to Name(), of the socket that you want to transfer.

capability: Dependent on the capabilities defined in the setOpt by the source Socket

(generated from Symbian Developer Library)

◆ Write()

IMPORT_C void RSocket::Write	(	const TDesC8 &	aDesc,
		TRequestStatus &	aStatus
	)

Sends data to a remote host.

Write() should only be used with connected sockets.

Parameters

aDesc	The data to be sent.
aStatus	On completion, KErrNone if successful, otherwise one of the system wide error codes. Note that KErrEof indicates that the socket has been shutdown with option EStopOutput.

capability: Dependent on the type of socket so deferred to PRT

(generated from Symbian Developer Library)

Friends And Related Symbol Documentation

◆ RSocketServ

friend class RSocketServ

friend

Definition at line 856 of file es_sock.h.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ TShutdown

Constructor & Destructor Documentation

◆ RSocket()

Member Function Documentation

◆ Accept() [1/2]

◆ Accept() [2/2]

◆ Bind()

◆ CancelAccept()

◆ CancelAll()

◆ CancelConnect()

◆ CancelIoctl()

◆ CancelRead()

◆ CancelRecv()

◆ CancelSend()

◆ CancelWrite()

◆ Close()

◆ Connect() [1/2]

◆ Connect() [2/2]

◆ GetDisconnectData()

◆ GetOpt() [1/2]

◆ GetOpt() [2/2]

◆ Info()

◆ Ioctl()

◆ Listen() [1/2]

◆ Listen() [2/2]

◆ LocalName()

◆ LocalPort()

◆ Name()

◆ Open() [1/5]

◆ Open() [2/5]

◆ Open() [3/5]

◆ Open() [4/5]

◆ Open() [5/5]

◆ Read()

◆ Recv() [1/2]

◆ Recv() [2/2]

◆ RecvFrom() [1/2]

◆ RecvFrom() [2/2]

◆ RecvOneOrMore() [1/2]

◆ RecvOneOrMore() [2/2]

◆ RemoteName()

◆ Send() [1/2]

◆ Send() [2/2]

◆ SendTo() [1/2]

◆ SendTo() [2/2]

◆ SetLocalPort()

◆ SetOpt() [1/2]

◆ SetOpt() [2/2]

◆ Shutdown() [1/2]

◆ Shutdown() [2/2]

◆ Transfer()

◆ Write()

Friends And Related Symbol Documentation

◆ RSocketServ