--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-782AA56A-D3CF-5239-AB62-9AE6741964E8.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,127 @@
+<?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 &aBuffer,TUint
+ someFlags,TRequestStatus &aStatus)</apiname></xref> </p> <p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Recv(TDes8 &aBuffer,TUint someFlags,TRequestStatus
+&aStatus,TSockXfrLength &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 &aBuffer,TSockAddr
+ &anAddr,TUint someFlags,TRequestStatus &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 &aBuffer,TRequestStatus
+ &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 &aBuffer,TUint
+someFlags,TRequestStatus &aStatus,TSockXfrLength &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 &aBuffer,TUint
+someFlags,TRequestStatus &aStatus)</apiname></xref> </p> <p> <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita"><apiname>RSocket::Read(TDes8
+&aBuffer,TRequestStatus &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 &aBuffer,TUint
+someFlags,TRequestStatus &aStatus,TSockXfrLength &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 &aDesc,
+TUint flags, TRequestStatus &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 &aLen</codeph> parameter and reads a datagram
+in parts. </p> <p>For example <codeph>RSocket::Recv(TDes8& aDesc,TUint
+ flags,TRequestStatus& aStatus,TSockXfrLength& 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>
+</conbody></concept>
\ No newline at end of file