|
|
|
|
|
|
Section contents
ccomms.oxh
Direct use of DevComm by applications is not encouraged
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 DevComm to be opened. The serial device can be queried about its functionality — 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).
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.
this& = NewDevComm&:
Creates a comms server object and returns a handle which allows the object to be manipulated.
this& |
An value which represents the created object |
If the object could not be created then an error is generated
which should be trapped by an ONERR
handler.
LOCAL this& this& = NewDevComm&: DeleteDevComm:(this&)
DeleteDevComm:(BYREF this&)
Destroys the serial device object.
BYREF this& |
A handle to a serial device object |
LOCAL this& this& = NewDevComm&: DeleteDevComm:(this&)
DevCommBreakA:(this&,time&,BYREF status&)
Use this function to perform a break.
this& |
A handle to a serial device object |
time& |
A time period to break for |
BYREF status& |
The request status used to contain completion information for the function. |
The current EPOC serial driver does not support breaking.
DevCommBreakCancel:(this&)
Use this function to perform a break.
this& |
A handle to a serial device object |
The current EPOC serial driver does not support breaking.
DevCommCaps:(this&,caps&)
Use this function to retrieve the capabilities of the serial port.
this& |
A handle to a serial device object |
caps& |
A handle to a Serial Capabilities object |
DevCommClose:(this&)
Use this function to close an open serial port.
this& |
A handle to a serial device object |
DevCommConfig:(this&,config&)
Use this function to read the current configuration of the serial port.
this& |
A handle to a serial device object |
config& |
A handle to a Comm Configuration object |
result% = DevCommOpen%:(this&,unit&)
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.
this& |
A handle to a serial device object |
unit& |
The unit number of the serial device required |
result% |
An error code |
count& = DevCommQueryReceiveBuffer&:(this&)
Use this function to read the number of characters in the receive buffer
this& |
A handle to a serial device object |
count& |
The number of characters currently in the receive buffer |
DevCommReceiveBufferLength, DevCommResetBuffers, DevCommSetReceiveBufferLength
DevCommQueryReadA:(this&,des&,length&,BYREF
status&)
Use this function to read the number of characters in the receive buffer
this& |
A handle to a serial device object |
des& |
A descriptor to store the incoming data. The length of the descriptor is the default for the number of bytes to be read. |
length& |
If not -1 an optional explicit length of data to be read. If present, this overrides the length of the descriptor default |
BYREF status& |
The request status used to contain completion information for the function. |
If a read is issued with a data length of zero (either explicitly or implicit in the descriptor) the ReadA will complete immediately with the side effect that the serial hardware will have been powered up.
DevCommReadCancel, DevCommReadOneOrMoreA
DevCommQueryReadCancel:(this&)
Cancels any pending ReadA() or ReadOneOrMore() operation.
this& |
A handle to a serial device object |
DevCommReadA, DevCommReadOneOrMoreA
DevCommQueryReadA:(this&,des&,length&,BYREF
status&)
Use this function to read the number of characters in the receive buffer
this& |
A handle to a serial device object |
des& |
A descriptor to store the incoming data. The length of the descriptor is the default for the number of bytes to be read. |
length& |
If not -1 an optional explicit length of data to be read. If present, this overrides the length of the descriptor default |
BYREF status& |
The request status used to contain completion information for the function. |
If there is data in the serial driver’s buffer when ReadOneOrMoreA 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.
DevConfigReadA, DevConfigReadCancel
DevCommQueryResetBuffers:(this&)
Use this function to discard all data in the receive buffers.
this& |
A handle to a serial device object |
length& = DevCommReceiveBufferLength&:(this&)
Use this function to read the number of characters in the receive buffer
this& |
A handle to a serial device object |
length& |
The length of the receive buffer |
result% = DevCommSetConfig%:(this&,config&)
Use this function to set the configuration of the serial port.
this& |
A handle to a serial device object |
config& |
A handle to a CommConfig object |
result% |
An error code |
result% = DevCommSetReceiveBufferLength%:(this&,length&)
Use this function to set the length of the receive buffer.
this& |
A handle to a serial device object |
length& |
The length of the receive buffer |
result% |
An error code |
DevCommSetSignals%:(this&,setMake&,clearMask&)
Use this function to set or clear the indicated signal lines. All other lines are left in their current state.
this& |
A handle to a serial device object |
setMask& |
A bitmask indicating the control lines to set |
clearMask& |
A bitmask indicating the control lines to clear |
result% |
An error code |
signals& = DevCommSignals&:(this&)
Returns the serial control lines.
this& |
A handle to a serial device object |
signals& |
A bitmap containing the current control line status |
DevCommQueryWriteA:(this&,des&,length&,BYREF
status&)
Use this function to write data to a serial port.
this& |
A handle to a serial device object |
des& |
A descriptor to a buffer containing the data to be written to the serial port |
length& |
An optional explicit length of data to be written. If not -1, this overrides the length of the descriptor default |
BYREF status& |
The request status used to contain completion information for the function. |
If a write is issued with a data length of zero (either explicitly or implicit in the descriptor) the WriteA 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.
DevCommQueryWriteCancel:(this&)
Cancel any pending WriteA operation.
this& |
A handle to a serial device object |
|
|
|
|
|
|