1144 lines
34 KiB
HTML
1144 lines
34 KiB
HTML
<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>
|