![[Index]](../../../../_stock/btn_index.gif){kind=small}
![[Glossary]](../../../../_stock/btn_glossary.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev.gif){kind=small}
![[Next]](../../../../_stock/btn_next.gif){kind=small}
|
|
|
|
|
Location:
es_sock.h
Link against: euser.lib
class RSocket : public RSubSessionBase;
Supported from 5.0
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.
|
Defined in RSocket:
Accept(), Accept(), Bind(), CancelAccept(), CancelAll(), CancelConnect(), CancelIoctl(), CancelRead(), CancelRecv(), CancelSend(), CancelWrite(), Close(), Connect(), Connect(), EImmediate, ENormal, EStopInput, EStopOutput, GetDisconnectData(), GetOpt(), GetOpt(), Info(), Ioctl(), Listen(), Listen(), LocalName(), LocalPort(), Name(), Open(), Open(), Open(), Read(), Recv(), Recv(), RecvFrom(), RecvFrom(), RecvOneOrMore(), RemoteName(), Send(), Send(), SendTo(), SendTo(), SetLocalPort(), SetOpt(), SetOpt(), Shutdown(), Shutdown(), TShutdown, Transfer(), Write()
Inherited from RSubSessionBase:
CloseSubSession(),
CreateSubSession(),
SendReceive(),
SubSessionHandle(),
operator=()
TInt Open(RSocketServ& aServer,TUint addrFamily,TUint sockType,TUint protocol);
Opens a socket.
Opens a channels 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.
|
|
TInt Open(RSocketServ& aServer,const TDesC& aName);
Opens a socket.
Openings 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.
|
|
TInt Open(RSocketServ& aServer);
Opens a socket.
The is providing 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.
|
|
void 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().
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.
|
TInt 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.
|
|
TInt 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.
|
|
void LocalName(TSockAddr& anAddr);
Gets the local address of a socket. The local address is set either by
calling
Bind() or it 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.
|
TUint LocalPort();
Gets the local port of a socket. Getting the local port is similar to
getting the local name—see
LocalName() for a description.
|
|
void Connect(TSockAddr& anAddr,TRequestStatus& aStatus);
Connects to a remote host. 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.
|
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
Connect() may be
used to set the address for all data sent from the socket, in which case
KSIConnectData in its protocol
information.void Connect(TSockAddr& anAddr,const TDesC8& aDataOut,TDes8& aDataIn, TRequestStatus& aStatus);
Connects to a remote host. 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() may be
used to set the address for all data sent from the socket, in which case
KSIConnectData in its protocol
information.void CancelConnect();
Cancels an outstanding connect operation. Calling it 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.
|
TInt 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.
|
|
TInt Listen(TUint qSize,const TDesC8& aDataOut);
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.
|
|
void Accept(RSocket& aBlankSocket,TRequestStatus& aStatus);
Facilitates a client/server connection from a remote socket. The call
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
void Accept(RSocket& aBlankSocket,TDes8& aConnectData,TRequestStatus& aStatus);
Facilitates a client/server connection from a remote socket. The call
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).
Thisvariant 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
void CancelAccept()
Cancels an outstanding accept operation. Calling it will cause any outstanding accept operation to complete prematurely.
|
void RemoteName(TSockAddr& anAddr);
Gets the remote name of a 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().
|
|
TInt Info(TProtocolDesc& aProtocol);
Gets information in the protocol description for the protocol which a socket is opened on.
|
|
|
TInt 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.
|
|
TInt 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.
|
|
TInt 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.
|
|
TInt 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.
|
|
|
void Write(const TDesC8& aDesc,TRequestStatus& aStatus);
Sends data to a remote host.
Write() should only be used with connected sockets.
|
void Send(const TDesC8& aDesc,TUint someFlags,TRequestStatus& aStatus);
Sends data to a remote host 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.
|
Send(). All other flags are protocol specific.void Send(const TDesC8& aDesc,TUint someFlags,TRequestStatus& aStatus,TSockXfrLength& aLen);
Sends data to a remote host 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.
|
Send(). All other flags are protocol specific.void SendTo(const TDesC8& aDesc,TSockAddr& anAddr,TUint flags,TRequestStatus& aStatus);
Sends data to a remote host through an 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.
|
void SendTo(const TDesC8& aDesc,TSockAddr& anAddr,TUint flags,TRequestStatus& aStatus,TSockXfrLength& aLen);
Sends data to a remote host through an 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.
|
void 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.
void 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.
|
void 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-interfaced, 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.
|
void Recv(TDes8& aDesc,TUint flags,TRequestStatus& aStatus);
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 connection-oriented datagram-interfaced, the function completes when a datagram arrives even if it is not sufficient to fill the buffer.
Recv() should only be used with connected sockets.
A socket may only have one receive operation outstanding at any one time.
|
Recv(). All other flags are protocol specific.void 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 connection-oriented datagram-interfaced, the function completes when a datagram arrives even if it is not sufficient to fill the buffer.
Recv() should only be used with
connected sockets.
A socket may only have one receive operation outstanding at any one time.
|
Recv(). All other flags are protocol specific.void 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.
|
void RecvFrom(TDes8& aDesc,TSockAddr& anAddr,TUint flags,TRequestStatus& aStatus);
Receives data from a remote host with unconnected sockets 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.
|
void RecvFrom(TDes8& aDesc,TSockAddr& anAddr,TUint flags,TRequestStatus& aStatus,TSockXfrLength& aLen);
Receives data from a remote host with unconnected sockets 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.
|
void 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.
void 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.
|
void Ioctl(TUint aCommand,TRequestStatus& aStatus,TDes8* aDesc=NULL,TUint aLevel=KLevelUnspecified);
Applies an asynchronous 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.
|
void CancelConnect()
Cancels an outstanding
Ioctl() operation. Calling it 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.
|
TInt 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().
|
|
TInt 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.
|
|
|
void Shutdown(TShutdown aHow,TRequestStatus& aStatus);
Shuts down a connected socket - asynchronous. The shutdown 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
void Shutdown(TShutdown aHow,const TDesC8& aDataOut,TDes8& aDataIn,TRequestStatus& aStatus);
Shuts down a connected socket - asynchronous. The shutdown 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
TInt GetDisconnectData(TDes8& aDesc);
Collects pending data which has been received in a protocol disconnect message.
|
|
KSIConnectData in its protocol information.
|
void CancelAll()
Cancels all outstanding operations. Calling it 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.
|
TShutdown
Used in structure
TProtocolDesc to describes the endianness of a
protocol.
|
©2002 Symbian Ltd. |
|
![[Top]](../../../../_stock/arrow_up.gif){kind=icon}