--- a/Symbian3/PDK/Source/GUID-782AA56A-D3CF-5239-AB62-9AE6741964E8.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-782AA56A-D3CF-5239-AB62-9AE6741964E8.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,130 +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>
-<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>
+<?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