<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>Comm</title>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="400" height="40"> </td>
<td width="30" height="40"><a
href="../../../epoc32/doc/group/sdk.html"><img
src="../../../epoc32/doc/group/library.gif"
alt="SDK Home" align="top" border="0" width="30"
height="30"></a></td>
<td width="30" height="40"><a
href="../../../epoc32/doc/glossary/glossary.html"><img
src="../../../epoc32/doc/group/glossary.gif"
alt="Glossary" align="top" border="0" width="30"
height="30"></a></td>
<td width="30" height="40"><a
href="../../../epoc32/doc/index/id-toc.html"><img
src="../../../epoc32/doc/group/index.gif" alt="Index"
align="top" border="0" width="30" height="30"></a></td>
<td width="30" height="40"><a href="general.htm"><b><img
src="../../../epoc32/doc/group/stoneleft.gif" alt="Left"
align="top" border="0" width="30" height="30"></b></a></td>
<td width="30" height="40"><a href="commcaps.htm"><b><img
src="../../../epoc32/doc/group/stoneright.gif"
alt="Right" align="top" border="0" width="30" height="30"></b></a></td>
<td width="30" height="40"><a href="programm.htm"><b><img
src="../../../epoc32/doc/group/stoneup.gif" alt="Up"
align="top" border="0" width="30" height="30"></b></a></td>
</tr>
</table>
<hr>
<h1>Comm Class</h1>
<hr>
<p><em>Section contents</em></p>
<ul>
<li><a href="#Overview"><strong>Overview</strong></a></li>
<li><a href="#Construction"><strong>Construction /
destruction</strong></a><ul>
<li><a href="#NewServ"><strong>NewComm - Constructor</strong></a></li>
<li><a href="#DeleteComm"><strong>DeleteComm -
Destructor</strong></a></li>
</ul>
</li>
<li><a href="#Methods provided"><strong>Methods provided</strong></a><ul>
<li><a href="#BreakA"><strong>CommBreakA - set a
break condition on a serial port</strong></a></li>
<li><a href="#BreakCancel"><strong>CommBreakCancel -
cancel a break condition on a serial port</strong></a></li>
<li><a href="#Cancel"><strong>CommCancel - cancel any
pending reads and writes</strong></a></li>
<li><a href="#Caps"><strong>CommCaps - read serial
port capabilities</strong></a></li>
<li><a href="#Close"><strong>CommClose - close a
serial port</strong></a></li>
<li><a href="#Config"><strong>CommConfig - read
serial port configuration</strong></a></li>
<li><a href="#Mode"><strong>CommMode - retrieve
server buffering mode</strong></a></li>
<li><a href="#Open"><strong>CommOpen - open a serial
port</strong></a></li>
<li><a href="#QueryReceiveBuffer"><strong>CommQueryReceiveBuffer
- number of bytes waiting in receive buffer</strong></a></li>
<li><a href="#ReadA"><strong>CommReadA - read data
from serial port</strong></a></li>
<li><a href="#ReadCancel"><strong>CommReadCancel -
cancel pending read</strong></a></li>
<li><a href="#ReadOneOrMoreA"><strong>CommReadOneOrMoreA
- read data from serial port</strong></a></li>
<li><a href="#ReceiveBufferLength"><strong>CommReceiveBufferLength
- get size of serial port buffers</strong></a></li>
<li><a href="#ResetBuffers"><strong>CommResetBuffers
- reset serial port buffers</strong></a></li>
<li><a href="#SetConfig"><strong>CommSetConfig - set
serial port configuration</strong></a></li>
<li><a href="#SetMode"><strong>CommSetMode - set
server buffering mode</strong></a></li>
<li><a href="#SetReceiveBufferLength"><strong>CommSetReceiveBufferLength
- set size of serial port buffers</strong></a></li>
<li><a href="#SetSignals"><strong>CommSetSignals -
set serial port control lines</strong></a></li>
<li><a href="#Signals"><strong>CommSignals - read
serial port control lines</strong></a></li>
<li><a href="#WriteA"><strong>CommWriteA - write data
to a serial port</strong></a></li>
<li><a href="#WriteCancel"><strong>CommWriteCancel -
cancel a pending write</strong></a></li>
</ul>
</li>
</ul>
<hr>
<h2><a name="Overview">Overview</a></h2>
<h5>Defined in</h5>
<p><code>ccomms.oxh</code></p>
<h5><font color="#000000"><tt>Description</tt></font></h5>
<p><font color="#000000"><tt>Comm</tt></font> represents a serial
port. It provides all the necessary functions for communicating
via a port, including functions for opening, closing, reading,
writing, together with port configuration and capability checking.</p>
<hr>
<h2><a name="Construction">Construction / destruction</a></h2>
<hr size="1">
<h3><a name="NewServ">NewComm - Constructor</a></h3>
<h5>Usage</h5>
<p><code>this& = NewComm&:</code></p>
<h5>Description</h5>
<p>Creates a comm object and returns a handle which allows the
object to be manipulated.</p>
<h5>Return Value</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>An value which represents the created comm object</td>
</tr>
</table>
<h5>Error Handling</h5>
<p>If the object could not be created then an error is generated
which should be trapped by an <font face="Times New Roman"><code>ONERR</code></font>
handler.</p>
<h5>Example</h5>
<pre> LOCAL this&
<strong>this& = NewComm&:</strong>
DeleteComm:(this&) </pre>
<hr size="1">
<h3><a name="DeleteComm">DeleteComm - Destructor</a></h3>
<h5>Usage</h5>
<p><code>DeleteComm:(BYREF this&)</code></p>
<h5>Description</h5>
<p>Destroys the comm object.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>BYREF this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>Example</h5>
<pre> LOCAL this&
this& = NewComm&:()
<strong>DeleteComm:(this&)</strong> </pre>
<hr>
<h2><a name="Methods provided">Methods provided</a></h2>
<hr size="1">
<h3><a name="BreakA">CommBreakA - set a break condition at a
serial port</a></h3>
<h5>Usage</h5>
<p><code>CommBreakA:(this&,time&,BYREF status&)</code></p>
<h5>Description</h5>
<p> </p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>time&</code></td>
<td>A timed break period in microseconds</td>
</tr>
<tr>
<td><code>BYREF status&</code></td>
<td> </td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#BreakCancel">CommBreakCancel</a></p>
<hr size="1">
<h3><a name="BreakCancel">CommBreakCancel - cancel a break
condition at a serial port</a></h3>
<h5>Usage</h5>
<p><code>CommBreakCancel:(this&)</code></p>
<h5>Description</h5>
<p> </p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#BreakA">CommBreakA</a></p>
<hr size="1">
<h3><a name="Cancel">CommCancel - cancel any pending reads and
writes</a></h3>
<h5>Usage</h5>
<p><code>CommCancel:(this&)</code></p>
<h5>Description</h5>
<p>A panic will result if an attempt is made to reconfigure a
port if there are any pending reads or writes. Use this function
before configuring a port if there is any doubt as to whether it
is safe to do so. It isn’t necessary to call <tt>CommCancel</tt>
before closing a port as this is done automatically</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#ReadA">CommReadA</a>, <a href="#WriteA">CommWriteA</a>,
<a href="#WriteCancel">CommWriteCancel</a></p>
<hr size="1">
<h3><a name="Caps">CommCaps - read serial port capabilities</a></h3>
<h5>Usage</h5>
<p><code>CommCaps:(this&,caps&)</code></p>
<h5>Description</h5>
<p>Use this function to retrieve the capabilities of the serial
port.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>caps&</code></td>
<td>A handle to a <a href="commcaps.htm">Serial
Capabilities</a> object</td>
</tr>
</table>
<hr size="1">
<h3><a name="Close">CommClose - close a serial port</a></h3>
<h5>Usage</h5>
<p><code>CommClose:(this&)</code></p>
<h5>Description</h5>
<p>Use this function to close a serial port.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Open">CommOpen</a></p>
<hr size="1">
<h3><a name="Config">CommConfig - read serial port configuration</a></h3>
<h5>Usage</h5>
<p><code>CommConfig:(this&,config&)</code></p>
<h5>Description</h5>
<p>Use this function to read the current configuration of the
serial port..</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>config&</code></td>
<td>A handle to a <a href="commcfg1.htm">Comm
Configuration</a> object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#SetConfig">CommSetConfig</a></p>
<hr size="1">
<h3><a name="Mode">CommMode - retrieve server buffering mode</a></h3>
<h5>Usage</h5>
<p><code>CommMode:(this&,config&)</code></p>
<h5>Description</h5>
<p>This function enables the comms server buffering mode to be
retrieved. If partial buffering is being used, then <tt>iBufSize</tt>
will hold the size of the buffer used by the server.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>config&</code></td>
<td>A handle to a <a href="commservcfg.htm"><tt>CommServerConfig</tt></a>
object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#SetMode">CommSetMode</a></p>
<hr size="1">
<h3><a name="Open">CommOpen - open a serial port</a></h3>
<h5>Usage</h5>
<p><code>result% = CommOpen%:(this&,server&,name$,mode%)</code></p>
<h5>Description</h5>
<p>Use this function to open a serial port, either for exclusive
use of this <font color="#000000"><tt>Comm</tt></font> or giving
permission for the port to be shared by other <font
color="#000000"><tt>Comm</tt></font>s. The request will fail if
the port does not exist, or if it has been opened in exclusive
mode elsewhere. If the port has been opened in shared mode
elsewhere, the request will fail if a subsequent attempt is made
to open it exclusive mode.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>server&</code></td>
<td>The <a href="commserv.htm">comms server</a> session</td>
</tr>
<tr>
<td><code>name$</code></td>
<td>The name of the port</td>
</tr>
<tr>
<td><code>mode%</code></td>
<td>The <a href="../Documentation/port.htm">mode</a> in
which the port is opened. There is no default.</td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>result%</code></td>
<td>An error code</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Close">CommClose</a>, <a
href="../Documentation/serialin.htm#Name">SerialInfoName</a></p>
<hr size="1">
<h3><a name="QueryReceiveBuffer">CommQueryReceiveBuffer - number
of bytes waiting in receive buffer</a></h3>
<h5>Usage</h5>
<p><code>count& = CommQueryReceiveBuffer&:(this&)</code></p>
<h5>Description</h5>
<p>Use this function to find out how many bytes are currently
waiting in the driver’s input buffer. A return value of zero
means the buffer is empty.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>count&</code></td>
<td>The number of bytes currently waiting to be read from
the receive buffer.</td>
</tr>
</table>
<h5>Notes</h5>
<p>It is not possible to find out exactly how many bytes are
currently in the driver’s <i>output</i> buffer waiting to be
transmitted. However, this is not an issue since it is easy to
ensure that the output buffer is empty. If <a
href="CSAPI-017.html#commapi.constant.KConfigWriteBufferedComplete"><font
color="#000000"><tt>KConfigWriteBufferedComplete&</tt></font></a>
is clear then all write requests will delay completion until the
data has completely cleared the driver’s output buffer. If <a
href="CSAPI-017.html#commapi.constant.KConfigWriteBufferedComplete"><font
color="#000000"><tt>KConfigWriteBufferedComplete&</tt></font></a>
is set, a write of zero bytes to a port which has data in the
output buffer is guaranteed to delay completion until the buffer
has been fully drained.</p>
<h5>See Also</h5>
<p><a href="#ReceiveBufferLength">CommReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="ReadA">CommReadA - read data from a serial port</a></h3>
<h5>Usage</h5>
<p><code>CommReadA:(this&,des&,length&,timeout&,BYREF
status&)</code></p>
<h5>Description</h5>
<p>Use this function to request data from a serial port. All
reads from the serial device use 8-bit descriptors as data
buffers, even on a Unicode system.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>des&</code></td>
<td>A <a href="../../CDescriptor/Documentation/des.htm">descriptor</a>
to store the incoming data. The length of the descriptor
is the default for the number of bytes to be read.</td>
</tr>
<tr>
<td><code>length&</code></td>
<td>If not -1 an optional explicit length of data to be
read. If present, this overrides the length of the
descriptor default</td>
</tr>
<tr>
<td><code>timeout&</code></td>
<td>If not 0, the read will terminate after <code><tt>timeout&</tt></code>
microseconds if the data requested has not arrived</td>
</tr>
<tr>
<td><code>BYREF status&</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Notes</h5>
<ol>
<li>The length of the <a
href="../e32/eudscmod-001.html#e32.class.TDes8"><font
color="#000000"><tt>descriptor</tt></font></a> is set to
zero on entry, which means that buffers can be reused
without having to be zeroed first. </li>
<li>The amount of data to be read from the serial driver
depends upon which overload of <tt>Read()</tt> is used.
Normally the length used is the maximum length of the
descriptor. In the version which takes an explicit length
this value is used in preference to the descriptor’s
maximum length. </li>
<li>If a read is issued with a data length of zero (either
explicitly or implicit in the descriptor) the <tt>Read()</tt>
will complete immediately with the side effect that the
serial hardware will have been powered up. </li>
<li>If a read terminates with <a
href="../e32/eupdev.html#e32.constant.KErrTimedOut"><font
color="#000000"><tt>K32ErrTimedOut&</tt></font></a>
and the descriptor is not empty, it will contain valid
data. Its length should therefore be tested. </li>
</ol>
<h5>See Also</h5>
<p><a href="#Cancel">CommCancel</a>, <a href="#ReadCancel">CommReadCancel</a>,
<a href="#ReadOneOrMoreA">CommReadOneOrMoreA</a></p>
<hr size="1">
<h3><a name="ReadCancel">CommReadCancel - cancel pending read</a></h3>
<h5>Usage</h5>
<p><code>CommReadCancel:(this&)</code></p>
<h5>Description</h5>
<p>Causes any pending <tt>CommReadA</tt> or <tt>CommReadOneOrMoreA</tt>
operation to complete immediately.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>Note</h5>
<p>The cancelled request will still terminate with its status&
set, to any value other than K32ErrPending&. While this is
most likely to be K32ErrCancel&, it is nevertheless possible
for the cancellation to have been issued after the asynchronous
request had already terminated for some other reason.</p>
<h5>See Also</h5>
<p><a href="#Cancel">CommCancel</a>, <a href="#ReadA">CommReadA</a>,
<a href="#ReadOneOrMoreA">CommReadOneOrMoreA</a></p>
<hr size="1">
<h3><a name="ReadOneOrMoreA">CommReadOneOrMoreA - read data from
a serial port</a></h3>
<h5>Usage</h5>
<p><code>CommReadOneOrMoreA:(this&,des&,BYREF status&)</code></p>
<h5>Description</h5>
<p>Use this function to request data from a serial port. All
reads from the serial device use 8-bit descriptors as data
buffers, even on a Unicode system.</p>
<p>If there is data in the serial driver’s buffer when <tt>CommReadOneOrMoreA</tt>
is called, it will read as much data as possible (up to the
maximum length of the supplied buffer) and return immediately. If
there is no data in the buffer, the request will complete as soon
as the first character arrives at the serial hardware.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>des&</code></td>
<td>A <a href="../../CDescriptor/Documentation/des.htm">descriptor</a>
to store the incoming data. The length of the descriptor
is the default for the number of bytes to be read.</td>
</tr>
<tr>
<td><code>BYREF status&</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Cancel">CommCancel</a>, <a href="#ReadA">CommReadA</a>,
<a href="#ReadCancel">CommReadCancel</a></p>
<hr size="1">
<h3><a name="ReceiveBufferLength">CommReceiveBufferLength - get
size of serial port buffers</a></h3>
<h5>Usage</h5>
<p><code>length& = CommReceiveBufferLength&:(this&)</code></p>
<h5>Description</h5>
<p>Use this function to find out the size of the serial port
buffers. Despite its name, this function returns the size of both
the receive and transmit buffers, which are (obviously) always
the same size.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>length&</code></td>
<td>The current size of both the receive and transmit
buffers in bytes</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#QueryReceiveBuffer">CommQueryReceiveBuffer</a>, <a
href="#SetReceiveBufferLength">CommSetReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="ResetBuffers">CommResetBuffers - reset serial port
buffers</a></h3>
<h5>Usage</h5>
<p><code>CommResetBuffers:(this&,flags&)</code></p>
<h5>Description</h5>
<p>Either buffer can be reset independently and all data in the
them is lost. This function should not be called when there are
pending reads or writes. </p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>flags&</code></td>
<td><tt>KCommResetRx&</tt> to reset the receive
buffer<p><tt>KCommResetTx&</tt> to reset the transmit
buffer</p>
</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Mode">CommMode</a>, <a href="#QueryReceiveBuffer">CommQueryReceiveBuffer</a>,
<a href="#ReceiveBufferLength">CommReceiveBufferLength</a>, <a
href="#SetMode">CommSetMode</a></p>
<hr size="1">
<h3><a name="SetConfig">CommSetConfig - set serial port
configuration</a></h3>
<h5>Usage</h5>
<p><code>result% = CommSetConfig%:(this&,config&)</code></p>
<h5>Description</h5>
<p>Use this function to open a serial port, either for exclusive
use of this <font color="#000000"><tt>Comm</tt></font> or giving
permission for the port to be shared by other <font
color="#000000"><tt>Comm</tt></font>s. The request will fail if
the port does not exist, or if it has been opened in exclusive
mode elsewhere. If the port has been opened in shared mode
elsewhere, the request will fail if a subsequent attempt is made
to open it exclusive mode.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>config&</code></td>
<td><font color="#000000"><tt>A handle to a </tt></font><a
href="../Documentation/commcfg1.htm"><font
color="#000000"><tt>CommConfig</tt></font></a><font
color="#000000"><tt> object</tt></font></td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>result%</code></td>
<td>An error code</td>
</tr>
</table>
<h5>Notes</h5>
<p>It is not possible to reconfigure the capabilities of ports
while they are being used. In particular, the comms server will
panic any client that attempts to reconfigure a port when there
are pending reads or writes.</p>
<h5>See Also</h5>
<p><a href="#Config">CommConfig</a></p>
<hr size="1">
<h3><a name="SetMode">CommSetMode - set server buffering mode</a></h3>
<h5>Usage</h5>
<p><code>result% = CommSetMode%:(this&,config&)</code></p>
<h5>Description</h5>
<p>The comms server copies data, between the descriptors provided
by the client and the buffers used by the serial port drivers,
for each read and write request. There are two methods by which
this can be accomplished. Full buffering means that the comms
server will always attempt to allocate enough memory to satisfy
any reads or writes in a single copy, while partial buffering
means that the comms server will allocate a static buffer and use
partial copies to transfer data to the serial driver. </p>
<p>This function can be used to set either buffering mode, and if
partial buffering is being used, it can also set the size of the
buffer that the server will use. These items are packaged up into
the <tt>CommServerConfigV01</tt> descriptor.</p>
<p>When a port is opened, the default is full buffering</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>config&</code></td>
<td><font color="#000000"><tt>A handle to a </tt></font><a
href="CSAPI-004.html#commapi.typedef.TCommConfig"><font
color="#000000"><tt>CommServerConfig</tt></font></a><font
color="#000000"><tt> object</tt></font></td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>result%</code></td>
<td>An error code</td>
</tr>
</table>
<h5>Notes</h5>
<p>The default of full buffering is nearly always going to be the
quicker option, as only a single client-server data transfer is
ever needed. The mode should not be changed by an application
without a very good reason (such as memory constraints) otherwise
performance is liable to suffer.</p>
<h5>See Also</h5>
<p><a href="#Mode">CommMode</a>, <a href="#QueryReceiveBuffer">CommQueryReceiveBuffer</a>,
<a href="#ReceiveBufferLength">CommReceiveBufferLength</a>, <a
href="#ResetBuffers">CommResetBuffers</a></p>
<hr size="1">
<h3><a name="SetReceiveBufferLength">CommSetReceiveBufferLength -
set size of serial port buffers</a></h3>
<h5>Usage</h5>
<p><code>CommSetReceiveBufferLength:(this&,length&)</code></p>
<h5>Description</h5>
<p>Use this function to change the size of the serial port
receive and transmit buffers.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>length&</code></td>
<td>The required size of the receive and transmit buffers
in bytes.</td>
</tr>
</table>
<h5>Notes</h5>
<ol>
<li>There is no error code returned by this function. If the
buffer is set to too large a figure, the request is
simply ignored. If you are in any doubt about the success
of a <tt>CommSetReceiveBufferLength</tt> request, you
should examine the returned value from <tt>CommReceiveBufferLength</tt>.
</li>
<li>It isn’t always essential to set a buffer size as
there is a generous default of 1024. </li>
<li>Changing the size of the receive buffer is the only way
to tailor the operation of flow control in EPOC32 as the
exact position of the high water mark is not configurable.
</li>
</ol>
<h5>See Also</h5>
<p><a href="#ReceiveBufferLength">CommReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="SetSignals">CommSetSignals - set serial port control
line</a></h3>
<h5>Usage</h5>
<p><code>CommSetSignals:(this&,setmask&,clearmask&)</code></p>
<h5>Description</h5>
<p>Using this inline function, either of the RS232 output lines (DTR
and RTS) can be set or cleared manually as needed.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>setmask&</code></td>
<td>Set the handshaking lines in the mask as specified in
<a href="../Documentation/signal.htm">Signal line
constants</a></td>
</tr>
<tr>
<td><code>clearmask&</code></td>
<td>Set the handshaking lines in the mask as specified in
<a href="../Documentation/signal.htm">Signal line
constants</a></td>
</tr>
</table>
<h5>Notes</h5>
<p>For many applications, these lines will be read and set under
driver control as determined by the handshaking options selected.</p>
<h5>See Also</h5>
<p><a href="#Signals">CommSignals</a></p>
<hr size="1">
<h3><a name="Signals">CommSignals - read serial port control
lines</a></h3>
<h5>Usage</h5>
<p><code>signals& = CommSignals&:(this&,mask&)</code></p>
<h5>Description</h5>
<p>Use this function to read the status of the RS232 input and
output lines (RTS, CTS, DSR, DCD, DTR). They are bit-mapped into
a single integer and one or all of them can be read at any time.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>mask&</code></td>
<td>This defaults to <tt>0x3f</tt> as only the top six
bits of this integer are valid.</td>
</tr>
</table>
<h5>Return value</h5>
<table border="1">
<tr>
<td><code>signals&</code></td>
<td>An integer with the bits set to reflect the status of
the handshaking lines according to the values defined in <a
href="../Documentation/signal.htm">Signal line constants</a></td>
</tr>
</table>
<h5>Notes</h5>
<ol>
<li>Not all of the input lines are guaranteed to be available
on all serial devices. In particular, the integral UART
built in the ARM does not support the Ring Indicate (RI)
input line. </li>
<li>A different value to <tt>0x3f</tt> can be specified as <tt>aSignalMask</tt>
if specific information is required - for instance, <tt>CommSignals(KSignalDSR&)</tt>
could be used to find out if a modem were connected to
the serial port. </li>
</ol>
<h5>See Also</h5>
<p><a href="#SetSignals">CommSetSignals</a></p>
<hr size="1">
<h3><a name="WriteA">CommWriteA - write data to a serial port</a></h3>
<h5>Usage</h5>
<p><code>CommWriteA:(this&,des&,length&,timeout&,BYREF
status&)</code></p>
<h5>Description</h5>
<p>Use this function to write data to a serial port. All writes
to the serial device use 8-bit descriptors as data buffers, even
on a Unicode system.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
<tr>
<td><code>des&</code></td>
<td>A <a href="../../CDescriptor/Documentation/des.htm">descriptor</a>
to a buffer containing the data to be written to the
serial port</td>
</tr>
<tr>
<td><code>length&</code></td>
<td>An optional explicit length of data to be written. If
not -1, this overrides the length of the descriptor
default</td>
</tr>
<tr>
<td><code>timeout&</code></td>
<td>If not 0, the read will terminate after <code><tt>timeout&</tt></code>
microseconds if the data requested has not been sent.</td>
</tr>
<tr>
<td><code>BYREF status&</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Notes</h5>
<ol>
<li>If a write is issued with a data length of zero (either
explicitly or implicit in the descriptor) the <tt>CommWrite</tt>
will complete when the current handshaking configuration
and the state of input control lines would allow any data
to be immediately written to the serial line. This
functionality is useful to determine when serial devices
come on line, and to check that the output buffer is
empty if <a
href="CSAPI-017.html#commapi.constant.KConfigWriteBufferedComplete"><font
color="#000000"><tt>KConfigWriteBufferedComplete&</tt></font></a>
is set. </li>
</ol>
<h5>See Also</h5>
<p><a href="#Cancel">CommCancel</a>, <a href="#WriteCancel">CommWriteCancel</a></p>
<hr size="1">
<h3><a name="WriteCancel">CommWriteCancel - cancel a pending
write</a></h3>
<h5>Usage</h5>
<p><code>CommWriteCancel:(this&)</code></p>
<h5>Description</h5>
<p>Causes any pending <tt>CommWrite</tt> operation to complete
immediately.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&</code></td>
<td>A handle to a comm object</td>
</tr>
</table>
<h5>Note</h5>
<p>The cancelled request will still terminate with its status&
set, to any value other than K32ErrPending&. While this is
most likely to be K32ErrCancel&, it is nevertheless possible
for the cancellation to have been issued after the asynchronous
request had already terminated for some other reason.</p>
<h5>See Also</h5>
<p><a href="#Cancel">CommCancel</a>, <a href="#WriteA">CommWriteA</a></p>
<hr>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="400" height="40"> </td>
<td width="30" height="40"><a
href="../../../epoc32/doc/group/sdk.html"><img
src="../../../epoc32/doc/group/library.gif"
alt="SDK Home" align="top" border="0" width="30"
height="30"></a></td>
<td width="30" height="40"><a
href="../../../epoc32/doc/glossary/glossary.html"><img
src="../../../epoc32/doc/group/glossary.gif"
alt="Glossary" align="top" border="0" width="30"
height="30"></a></td>
<td width="30" height="40"><a
href="../../../epoc32/doc/index/id-toc.html"><img
src="../../../epoc32/doc/group/index.gif" alt="Index"
align="top" border="0" width="30" height="30"></a></td>
<td width="30" height="40"><a href="general.htm"><b><img
src="../../../epoc32/doc/group/stoneleft.gif" alt="Left"
align="top" border="0" width="30" height="30"></b></a></td>
<td width="30" height="40"><a href="commcaps.htm"><b><img
src="../../../epoc32/doc/group/stoneright.gif"
alt="Right" align="top" border="0" width="30" height="30"></b></a></td>
<td width="30" height="40"><a href="programm.htm"><b><img
src="../../../epoc32/doc/group/stoneup.gif" alt="Up"
align="top" border="0" width="30" height="30"></b></a></td>
</tr>
</table>
</body>
</html>