Reading from a Socket: Tutorial

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

The following [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]RSocket functions read data from a socket:

• [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]] Recv() and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]KSockReadContinuation flag. To set the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]KSockReadContinuation flag.

    Clients who need to read the datagrams as a "stream" can set the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]KSockReadContinuation flag. When the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]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.

• [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RSocket']]]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.