Reading from a Socket: Tutorial

This partial tutorial explains the behaviour of the different functions available to read data from a socket.

Type of Socket	Type of Wait	Must socket be connected?	Lose Data on Overflow?	APIs
Datagram	Return on first Data	Yes	Yes	`RSocket::Recv(TDes8 &aBuffer,TUint someFlags,TRequestStatus &aStatus)` `RSocket::Recv(TDes8 &aBuffer,TUint someFlags,TRequestStatus &aStatus,TSockXfrLength &aLen)`
	Return on first Data	No -socket can be in unknown state	No	`RSocket::RecvFrom(TDes8 &aBuffer,TSockAddr &anAddr,TUint someFlags,TRequestStatus &aStatus)`
	Wait until buffer full			`RSocket::Read(TDes8 &aBuffer,TRequestStatus &aStatus)`
Stream	Return on first Data	Yes		`RSocket::RecvOneOrMore(TDes8 &aBuffer,TUint someFlags,TRequestStatus &aStatus,TSockXfrLength &aLen)`
	Wait until buffer full	Yes	Yes	`RSocket::Recv(TDes8 &aBuffer,TUint someFlags,TRequestStatus &aStatus)` `RSocket::Read(TDes8 &aBuffer,TRequestStatus &aStatus)`
	Wait until buffer full		No	`RSocket::Recv(TDes8 &aBuffer,TUint someFlags,TRequestStatus &aStatus,TSockXfrLength &aLen)`

The following RSocket functions read data from a socket:

Recv() and RecvFrom() each have two versions:
- A version which only completes when the full amount of requested data is received, or the connection is disconnected.
  
  For example RSocket::Recv(TDes8 &aDesc, TUint flags, TRequestStatus &aStatus).
  
  The amount of data requested is specified by the maximum length of the descriptor which receives the data. If the amount of data to read is not known until run-time, use a HBufC8 or RBuf descriptor.
  
  If the datagram is larger than the requested amount, the protocol plug-in (PRT) will truncate the datagram and return the requested amount of data (counted in bytes). The function will not indicate to the client that the data was truncated.
- A version which takes the TSockXfrLength &aLen parameter and reads a datagram in parts.
  
  For example RSocket::Recv(TDes8& aDesc,TUint flags,TRequestStatus& aStatus,TSockXfrLength& aLen).
  
  This version completes with a count of the remaining bytes of the datagram in the TSockXfrLength parameter. The client can repeat the use of the function to read the remaining bytes. To read the bytes which remain, the client sets the KSockReadContinuation flag. To set the KSockReadContinuation flag the client must use the binary OR operator with the flags field. The bytes which remain are discarded if the client uses the function and does not set the KSockReadContinuation flag.
  
  Clients who need to read the datagrams as a "stream" can set the KSockReadContinuation flag. When the KSockReadContinuation flag is set and there is no remaining data, new data is read.
Read() only completes when the full amount of requested data is received, or the connection is disconnected.

The amount of data requested is specified by the maximum length of the descriptor which receives the data. If the amount of data to read is not known until run-time, use a HBufC8 or RBuf descriptor.

If the datagram is larger than the requested amount, the protocol plug-in (PRT) will truncate the datagram and return the requested amount of data (counted in bytes). The function will not indicate to the client that the data was truncated.
RecvOneOrMore() reads at least one byte of data and completes with the available data. The amount of data received is returned in the TSockXfrLength argument.
RecvFrom() is designed for use when the client does not know if the socket is connected. If the socket is not connected, a source address is returned.
Recv(), Read(), and RecvOneOrMore() are designed for use with connected sockets.