42
drivers for its built-in serial hardware. However, this doesn’t implement a truly generic interface,
which can be mapped to any serial device, and also doesn’t allow ports to be shared. Only
programs which require very fast and primitive access to hardware specific features should use
RDevComm
, and it should be noted that the API is subject to change in future EPOC
releases.
Access to the full power of EPOC’s generic serial communications can only be obtained by using
the serial communications server, C32, which offers its clients an abstraction of a serial device
which can be layered over any type of hardware, together with port sharing and additional features
such as time-outs.
C32 APIS
8.4.2.1 Communications Server Provider API
The serial service provider API, defined in
cs_port.h
, consists of two abstract classes:
CSerial
, representing a serial service and
CPort
, representing an open and potentially
shareable serial port.
Real serial services consist of dynamically loaded Communication Server Modules, which are
implemented using a polymorphic DLL whose extension is conventionally
.csy
and whose
second UID is 0x10000049. The first export from this DLL is a factory function for a
CSerial
-
derived class, the main virtual function of which is
NewPortL()
, which creates a
CPort
-
derived class. The virtual functions of
CPort
provide implementations of all functions required
by the client API.
EPOC machines with built-in serial ports drive them using the
ecuart.csy
serial service.
Machines with infrared ports drive them using
ircomm.csy.
Other serial port type services can
be implemented as CSYs as needed. Typically, clients need no knowledge of individual CSY
modules, since they ask the communications server to load whichever is defined as active in the
Comms Database.
8.4.2.2 Communications Server Client API
C32’s client API, defined in
c32comm.h
, consists of
RcommServ,
which gives the client a
session to the server, and
RComm
, which provides an API to a serial port.
The facilities offered by
RCommServ
are used in a logical sequence. The client starts by
calling
Connect()
to open a session with the server. Once this has been done,
LoadCommModule()
is used to load up the required CSY by name.
NumPorts()
returns the number of CSY modules currently loaded, while
GetPortInfo()
allows clients to
find the details of all the ports that the CSY supports.
RComm
provides many functions to access a serial port.
Open()
requires that a port be
specified by name. There are several
Read()
and
Write()
functions with corresponding
cancels, with all i/o functions capable of being set to complete on any of a number of conditions.
Reading and setting serial port lines and breaks are supported, and the size of both transmit and
receive buffers can be configured.
RComm
also provides several mode-setting and capability
functions, and the API provides special classes to return port capabilities.
