<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-782AA56A-D3CF-5239-AB62-9AE6741964E8" xml:lang="en"><title> Reading

from a Socket: Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This partial tutorial explains the behaviour of the different functions

available to read data from a socket. </p>

<table id="GUID-2F5824A3-D900-5CC3-96CD-39F11D3F62DD">

<tgroup cols="5"><colspec colname="COLSPEC1" colwidth="1.00*"/><colspec colname="col1" colwidth="1.01*"/><colspec colname="col2" colwidth="1.03*"/><colspec colname="col3" colwidth="0.99*"/><colspec colname="col4" colwidth="0.99*"/>

<thead>

<row>

<entry>Type of Socket</entry>

<entry>Type of Wait</entry>

<entry>Must socket be connected?</entry>

<entry>Lose Data on Overflow?</entry>

<entry>APIs</entry>

</row>

</thead>

<tbody>

<row>

<entry morerows="2"><p>Datagram </p></entry>

<entry morerows="1"><p>Return on first Data </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Recv(TDes8 &amp;aBuffer,TUint

                someFlags,TRequestStatus &amp;aStatus)</apiname></xref>  </p> <p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Recv(TDes8 &amp;aBuffer,TUint                 someFlags,TRequestStatus

&amp;aStatus,TSockXfrLength &amp;aLen)</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>No -socket can be in unknown state </p> </entry>

<entry><p>No </p> </entry>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::RecvFrom(TDes8 &amp;aBuffer,TSockAddr

                &amp;anAddr,TUint someFlags,TRequestStatus &amp;aStatus)</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>Wait until buffer full </p> </entry>

<entry/>

<entry/>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Read(TDes8 &amp;aBuffer,TRequestStatus

                &amp;aStatus)</apiname></xref>  </p> </entry>

</row>

<row>

<entry morerows="2"><p>Stream </p></entry>

<entry><p>Return on first Data </p> </entry>

<entry align="justify"><p>Yes </p> </entry>

<entry/>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::RecvOneOrMore(TDes8 &amp;aBuffer,TUint

someFlags,TRequestStatus &amp;aStatus,TSockXfrLength &amp;aLen)</apiname></xref>  </p> </entry>

</row>

<row>

<entry morerows="1"><p>Wait until buffer full </p> </entry>

<entry align="justify"><p>Yes </p></entry>

<entry><p>Yes </p> </entry>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Recv(TDes8 &amp;aBuffer,TUint

someFlags,TRequestStatus &amp;aStatus)</apiname></xref>  </p> <p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Read(TDes8

&amp;aBuffer,TRequestStatus &amp;aStatus)</apiname></xref>  </p> </entry>

</row>

<row>

<entry/>

<entry><p>No </p> </entry>

<entry><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Recv(TDes8 &amp;aBuffer,TUint

someFlags,TRequestStatus &amp;aStatus,TSockXfrLength &amp;aLen)</apiname></xref>  </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<p>The following <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket</apiname></xref> functions read

data from a socket: </p>

<ul>

<li id="GUID-4FB26DCD-9852-5AED-AD07-0B71BBF28325"><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname> Recv()</apiname></xref> and <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RecvFrom()</apiname></xref> each have two versions: </p> <ul>

<li id="GUID-AAF3AE2B-47D1-5868-A0F2-E2582C6705C1"><p>A version which only

completes when the full amount of requested data is received, or the connection

is disconnected. </p> <p>For example <codeph>RSocket::Recv(TDes8 &amp;aDesc,

TUint flags,                   TRequestStatus &amp;aStatus)</codeph>. </p> <p>The

amount of data requested is specified by the <xref href="GUID-6D1A830E-F0F1-5C0F-8EEB-70922C0EF6B8.dita">maximum

length</xref> of the descriptor which receives the data. If the amount of

data to read is not known until run-time, use a <codeph>HBufC8</codeph> or <codeph>RBuf</codeph> descriptor. </p> <p>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. </p> </li>

<li id="GUID-31B36AAE-0E65-570E-84D1-C6EC2B9FDE2C"><p>A version which takes

the <codeph>TSockXfrLength &amp;aLen</codeph> parameter and reads a datagram

in parts. </p> <p>For example <codeph>RSocket::Recv(TDes8&amp; aDesc,TUint

                  flags,TRequestStatus&amp; aStatus,TSockXfrLength&amp; aLen)</codeph>. </p> <p>This

version completes with a count of the remaining bytes of the datagram in the <codeph>TSockXfrLength</codeph> 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 <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>KSockReadContinuation</apiname></xref> flag.

To set the <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>KSockReadContinuation</apiname></xref> flag

the client must use the <i>binary OR</i> operator with the <i>flags</i> field.

The bytes which remain are discarded if the client uses the function and does

not set the <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>KSockReadContinuation</apiname></xref> flag. </p> <p>Clients

who need to read the datagrams as a "stream" can set the <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>KSockReadContinuation</apiname></xref> flag.

When the <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>KSockReadContinuation</apiname></xref> flag is

set and there is no remaining data, new data is read. </p> </li>

</ul> </li>

<li id="GUID-9D0FEAA4-3C27-594A-B582-CE3F445ADB7D"><p> <codeph>Read()</codeph> only

completes when the full amount of requested data is received, or the connection

is disconnected. </p> <p>The amount of data requested is specified by the <xref href="GUID-6D1A830E-F0F1-5C0F-8EEB-70922C0EF6B8.dita">maximum length</xref> of

the descriptor which receives the data. If the amount of data to read is not

known until run-time, use a <codeph>HBufC8</codeph> or <codeph>RBuf</codeph> descriptor. </p> <p>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. </p> </li>

<li id="GUID-B31DE8AB-8F0E-5D72-97FF-2362E013E551"><p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RecvOneOrMore()</apiname></xref> reads

at least one byte of data and completes with the available data. The amount

of data received is returned in the <codeph>TSockXfrLength</codeph> argument. </p> </li>

<li id="GUID-9A43EC4E-F053-55DE-9024-76562A899E63"><p> <codeph>RecvFrom()</codeph> 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. </p> </li>

<li id="GUID-DA868C8C-2165-5430-9E28-8A304423925D"><p> <codeph>Recv()</codeph>, <codeph>Read()</codeph>,

and <codeph>RecvOneOrMore()</codeph> are designed for use with connected sockets. </p> </li>

</ul>

<section><title>Historical Note</title> <p>The protocol plug-in (PRT) must

use the PRT 1.5 interface for the <codeph>TSockXfrLength</codeph> parameter

to operate. The PRT 1.5 interface was added in Symbian OS 8.0. </p> </section>

</conbody></concept>