ccoms-html/devcomm.htm

871 lines
23 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>DevComm</title>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="400" height="40">&nbsp;</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="../DOCUME~1/commservcfg.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="serialin.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="../DOCUME~1/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>DevComm 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="#NewCommServ"><strong>NewDevComm -
Constructor</strong></a></li>
<li><a href="#DeleteCommServ"><strong>DeleteDevComm -
Destructor</strong></a></li>
</ul>
</li>
<li><a href="#Methods provided"><strong>Methods provided</strong></a><ul>
<li><a href="#Close"><strong>DevCommBreakA</strong></a></li>
<li><a href="#BreakCancel"><strong>DevCommBreakCancel</strong></a></li>
<li><a href="#Caps"><strong>DevCommCaps</strong></a></li>
<li><a href="#Close"><strong>DevCommClose</strong></a></li>
<li><a href="#Config"><strong>DevCommConfig</strong></a></li>
<li><a href="#Open"><strong>DevCommOpen</strong></a></li>
<li><a href="#QueryReceiveBuffer"><strong>DevCommQueryReceiveBuffer</strong></a></li>
<li><a href="#Read"><strong>DevCommReadA</strong></a></li>
<li><a href="#ReadCancel"><strong>DevCommReadCancel</strong></a></li>
<li><a href="#ReadOneOrMore"><strong>DevCommReadOneOrMoreA</strong></a></li>
<li><a href="#ResetBuffers"><strong>DevCommResetBuffers</strong></a></li>
<li><a href="#ReceiveBufferLength"><strong>DevCommReceiveBufferLength</strong></a></li>
<li><a href="#SetReceiveBufferLength"><strong>DevCommSetReceiveBufferLength</strong></a></li>
<li><a href="#SetSignals"><strong>DevCommSetSignals</strong></a></li>
<li><a href="#Signals"><strong>DevCommSignals</strong></a></li>
<li><a href="#Write"><strong>DevCommWriteA</strong></a></li>
<li><a href="#WriteCancel"><strong>DevCommWriteCancel</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>Description</h5>
<p><i>Direct use of DevComm by applications is not encouraged</i></p>
<p>A single serial device driver can control many different
instances of serial hardware. For a single driver the different
instances are specified by providing unit numbers when the
channel is opened. Unit numbers are 0 based. Each different piece
of serial hardware requires a new <font color="#000000" size="4"><tt>DevComm</tt></font>
to be opened. The serial device can be queried about its
functionality &#151; this includes such things as character
framing, a range of data rates, whether it has a FIFO buffer or
if it supports SIR (serial infra red - the physical layer of the
IrDA standard).</p>
<p>In order to conserve battery power the serial hardware is kept
switched off until the first read or write is issued. As this
might lead to deadlock between two devices which are both waiting
for a control line to go high, the serial hardware can be powered
up by reading zero bytes from it.</p>
<hr>
<h2><a name="Construction">Construction / destruction</a></h2>
<hr size="1">
<h3><a name="NewDevComm">NewDevComm - Constructor</a></h3>
<h5>Usage</h5>
<p><code>this&amp; = NewDevComm&amp;:</code></p>
<h5>Description</h5>
<p>Creates a comms server object and returns a handle which
allows the object to be manipulated.</p>
<h5>Return Value</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>An value which represents the created 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&amp;
<strong>this&amp; = NewDevComm&amp;:</strong>
DeleteDevComm:(this&amp;) </pre>
<hr size="1">
<h3><a name="DeleteDevComm">DeleteDevComm - Destructor</a></h3>
<h5>Usage</h5>
<p><code>DeleteDevComm:(BYREF this&amp;)</code></p>
<h5>Description</h5>
<p>Destroys the serial device object.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>BYREF this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>Example</h5>
<pre> LOCAL this&amp;
this&amp; = NewDevComm&amp;:
<strong>DeleteDevComm:(this&amp;)</strong> </pre>
<hr>
<h2><a name="Methods provided">Methods provided</a></h2>
<hr size="1">
<h3><a name="Break">DevCommBreakA</a></h3>
<h5>Usage</h5>
<p><code>DevCommBreakA:(this&amp;,time&amp;,BYREF status&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to perform a break.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>time&amp;</code></td>
<td>A time period to break for</td>
</tr>
<tr>
<td><code>BYREF status&amp;</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Note</h5>
<p>The current EPOC serial driver does not support breaking.</p>
<h5>See Also</h5>
<p><a href="#BreakCancel">DevCommBreakCancel</a></p>
<hr size="1">
<h3><a name="BreakCancel">DevCommBreakCancel</a></h3>
<h5>Usage</h5>
<p><code>DevCommBreakCancel:(this&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to perform a break.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>Note</h5>
<p>The current EPOC serial driver does not support breaking.</p>
<h5>See Also</h5>
<p><a href="#Break">DevCommBreakA</a></p>
<hr size="1">
<h3><a name="Caps">DevCommCaps</a></h3>
<h5>Usage</h5>
<p><code>DevCommCaps:(this&amp;,caps&amp;)</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&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>caps&amp;</code></td>
<td>A handle to a <a href="../DOCUME~1/commcaps.htm">Serial
Capabilities</a> object</td>
</tr>
</table>
<hr size="1">
<h3><a name="Close">DevCommClose</a></h3>
<h5>Usage</h5>
<p><code>DevCommClose:(this&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to close an open serial port.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Open">DevCommOpen</a></p>
<hr size="1">
<h3><a name="Config">DevCommConfig</a></h3>
<h5>Usage</h5>
<p><code>DevCommConfig:(this&amp;,config&amp;)</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&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>config&amp;</code></td>
<td>A handle to a <a href="../DOCUME~1/commcfg1.htm">Comm
Configuration</a> object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#SetConfig">DevCommSetConfig</a></p>
<hr size="1">
<h3><a name="Open">DevCommOpen</a></h3>
<h5>Usage</h5>
<p><code>result% = DevCommOpen%:(this&amp;,unit&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to open a channel to the device driver. A
single serial device driver may be able to control more than one
device. The device driver can only be opened by a single process.
While a process has a device handle to the channel, all further
requests to open the same unit number will fail.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>unit&amp;</code></td>
<td>The unit number of the serial device required</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">DevCommClose</a></p>
<hr size="1">
<h3><a name="QueryReceiveBuffer">DevCommQueryReceiveBuffer</a></h3>
<h5>Usage</h5>
<p><code>count&amp; = DevCommQueryReceiveBuffer&amp;:(this&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to read the number of characters in the
receive buffer</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>Return Value</h5>
<table border="1">
<tr>
<td><code>count&amp;</code></td>
<td>The number of characters currently in the receive
buffer</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#ReceiveBufferLength">DevCommReceiveBufferLength</a>,
<a href="#ResetBuffers">DevCommResetBuffers</a>, <a
href="#SetReceiveBufferLength">DevCommSetReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="Read">DevCommReadA</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryReadA:(this&amp;,des&amp;,length&amp;,BYREF
status&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to read the number of characters in the
receive buffer</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>des&amp;</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&amp;</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>BYREF status&amp;</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Notes</h5>
<p>If a read is issued with a data length of zero (either
explicitly or implicit in the descriptor) the <font size="4"><tt>ReadA</tt></font>
will complete immediately with the side effect that the serial
hardware will have been powered up.</p>
<h5>See Also</h5>
<p><a href="#ReadCancel">DevCommReadCancel</a>, <a
href="#ReadOneOrMore">DevCommReadOneOrMoreA</a></p>
<hr size="1">
<h3><a name="ReadCancel">DevCommReadCancel</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryReadCancel:(this&amp;)</code></p>
<h5>Description</h5>
<p>Cancels any pending <font size="4"><tt>ReadA()</tt></font> or <font
size="4"><tt>ReadOneOrMore()</tt></font> operation.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Read">DevCommReadA</a>, <a href="#ReadOneOrMore">DevCommReadOneOrMoreA</a></p>
<hr size="1">
<h3><a name="ReadOneOrMore">DevCommReadOneOrMoreA</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryReadA:(this&amp;,des&amp;,length&amp;,BYREF
status&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to read the number of characters in the
receive buffer</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>des&amp;</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&amp;</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>BYREF status&amp;</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Notes</h5>
<p>If there is data in the serial driver&#146;s buffer when <font
size="4"><tt>ReadOneOrMoreA</tt></font> 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>See Also</h5>
<p><a href="#Read">DevConfigReadA</a>, <a href="#ReadCancel">DevConfigReadCancel</a></p>
<hr size="1">
<h3><a name="ResetBuffers">DevCommResetBuffers</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryResetBuffers:(this&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to discard all data in the receive buffers.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#QueryReceiveBuffer">DevCommQueryReceiveBuffer</a></p>
<hr size="1">
<h3><a name="ReceiveBufferLength">DevCommReceiveBufferLength</a></h3>
<h5>Usage</h5>
<p><code>length&amp; = DevCommReceiveBufferLength&amp;:(this&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to read the number of characters in the
receive buffer</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>Return Value</h5>
<table border="1">
<tr>
<td><code>length&amp;</code></td>
<td>The length of the receive buffer</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#SetReceiveBufferLength">DevCommSetReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="SetConfig">DevCommSetConfig</a></h3>
<h5>Usage</h5>
<p><code>result% = DevCommSetConfig%:(this&amp;,config&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to set the configuration of the serial port.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>config&amp;</code></td>
<td><font color="#000000"><tt>A handle to a </tt></font><a
href="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>See Also</h5>
<p><a href="#Config">DevCommConfig</a></p>
<hr size="1">
<h3><a name="SetReceiveBufferLength">DevCommSetReceiveBufferLength</a></h3>
<h5>Usage</h5>
<p><code>result% = DevCommSetReceiveBufferLength%:(this&amp;,length&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to set the length of the receive buffer.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>length&amp;</code></td>
<td>The length of the receive buffer</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="#ReceiveBufferLength">DevCommReceiveBufferLength</a></p>
<hr size="1">
<h3><a name="SetSignals">DevCommSetSignals</a></h3>
<h5>Usage</h5>
<p><code>DevCommSetSignals%:(this&amp;,setMake&amp;,clearMask&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to set or clear the indicated signal lines.
All other lines are left in their current state.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>setMask&amp;</code></td>
<td>A bitmask indicating the control lines to set</td>
</tr>
<tr>
<td><code>clearMask&amp;</code></td>
<td>A bitmask indicating the control lines to clear</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="#Signals">DevCommSignals</a></p>
<hr size="1">
<h3><a name="Signals">DevCommSignals</a></h3>
<h5>Usage</h5>
<p><code>signals&amp; = DevCommSignals&amp;:(this&amp;)</code></p>
<h5>Description</h5>
<p>Returns the serial control lines.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>Return Value</h5>
<table border="1">
<tr>
<td><code>signals&amp;</code></td>
<td>A bitmap containing the current control line status</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#SetSignals">DevCommSetSignals</a></p>
<hr size="1">
<h3><a name="Write">DevCommWriteA</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryWriteA:(this&amp;,des&amp;,length&amp;,BYREF
status&amp;)</code></p>
<h5>Description</h5>
<p>Use this function to write data to a serial port.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
<tr>
<td><code>des&amp;</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&amp;</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>BYREF status&amp;</code></td>
<td>The request status used to contain completion
information for the function.</td>
</tr>
</table>
<h5>Notes</h5>
<p>If a write is issued with a data length of zero (either
explicitly or implicit in the descriptor) the <font size="4"><tt>WriteA</tt></font>
will complete when the current handshaking configuration and the
state of input control lines would allow any data to be actually
written to the serial line. This functionality is useful to
determine when serial devices come on line.</p>
<h5>See Also</h5>
<p><a href="#WriteCancel">DevCommWriteCancel</a></p>
<hr size="1">
<h3><a name="WriteCancel">DevCommWriteCancel</a></h3>
<h5>Usage</h5>
<p><code>DevCommQueryWriteCancel:(this&amp;)</code></p>
<h5>Description</h5>
<p>Cancel any pending <font size="4"><tt>WriteA</tt></font>
operation.</p>
<h5>Arguments</h5>
<table border="1">
<tr>
<td><code>this&amp;</code></td>
<td>A handle to a serial device object</td>
</tr>
</table>
<h5>See Also</h5>
<p><a href="#Write">DevCommWriteA</a></p>
<hr>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="400" height="40">&nbsp;</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="../DOCUME~1/commservcfg.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="serialin.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="../DOCUME~1/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>