|
|
|
|
|
|
Section contents
ccomms.oxh
Comm 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.
this& = NewComm&:
Creates a comm object and returns a handle which allows the object to be manipulated.
this& |
An value which represents the created comm object |
If the object could not be created then an error is generated
which should be trapped by an ONERR
handler.
LOCAL this& this& = NewComm&: DeleteComm:(this&)
DeleteComm:(BYREF this&)
Destroys the comm object.
BYREF this& |
A handle to a comm object |
LOCAL this& this& = NewComm&:() DeleteComm:(this&)
CommBreakA:(this&,time&,BYREF status&)
this& |
A handle to a comm object |
time& |
A timed break period in microseconds |
BYREF status& |
CommBreakCancel:(this&)
this& |
A handle to a comm object |
CommCancel:(this&)
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 CommCancel before closing a port as this is done automatically
this& |
A handle to a comm object |
CommReadA, CommWriteA, CommWriteCancel
CommCaps:(this&,caps&)
Use this function to retrieve the capabilities of the serial port.
this& |
A handle to a comm object |
caps& |
A handle to a Serial Capabilities object |
CommClose:(this&)
Use this function to close a serial port.
this& |
A handle to a comm object |
CommConfig:(this&,config&)
Use this function to read the current configuration of the serial port..
this& |
A handle to a comm object |
config& |
A handle to a Comm Configuration object |
CommMode:(this&,config&)
This function enables the comms server buffering mode to be retrieved. If partial buffering is being used, then iBufSize will hold the size of the buffer used by the server.
this& |
A handle to a comm object |
config& |
A handle to a CommServerConfig object |
result% = CommOpen%:(this&,server&,name$,mode%)
Use this function to open a serial port, either for exclusive use of this Comm or giving permission for the port to be shared by other Comms. 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.
this& |
A handle to a comm object |
server& |
The comms server session |
name$ |
The name of the port |
mode% |
The mode in which the port is opened. There is no default. |
result% |
An error code |
count& = CommQueryReceiveBuffer&:(this&)
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.
this& |
A handle to a comm object |
count& |
The number of bytes currently waiting to be read from the receive buffer. |
It is not possible to find out exactly how many bytes are currently in the driver’s output buffer waiting to be transmitted. However, this is not an issue since it is easy to ensure that the output buffer is empty. If KConfigWriteBufferedComplete& is clear then all write requests will delay completion until the data has completely cleared the driver’s output buffer. If KConfigWriteBufferedComplete& 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.
CommReadA:(this&,des&,length&,timeout&,BYREF
status&)
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.
this& |
A handle to a comm 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 |
timeout& |
If not 0, the read will terminate after timeout&
microseconds if the data requested has not arrived |
BYREF status& |
The request status used to contain completion information for the function. |
CommCancel, CommReadCancel, CommReadOneOrMoreA
CommReadCancel:(this&)
Causes any pending CommReadA or CommReadOneOrMoreA operation to complete immediately.
this& |
A handle to a comm object |
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.
CommCancel, CommReadA, CommReadOneOrMoreA
CommReadOneOrMoreA:(this&,des&,BYREF status&)
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.
If there is data in the serial driver’s buffer when CommReadOneOrMoreA 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.
this& |
A handle to a comm 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. |
BYREF status& |
The request status used to contain completion information for the function. |
CommCancel, CommReadA, CommReadCancel
length& = CommReceiveBufferLength&:(this&)
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.
this& |
A handle to a comm object |
length& |
The current size of both the receive and transmit buffers in bytes |
CommQueryReceiveBuffer, CommSetReceiveBufferLength
CommResetBuffers:(this&,flags&)
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.
this& |
A handle to a comm object |
flags& |
KCommResetRx& to reset the receive
buffer KCommResetTx& to reset the transmit buffer |
CommMode, CommQueryReceiveBuffer, CommReceiveBufferLength, CommSetMode
result% = CommSetConfig%:(this&,config&)
Use this function to open a serial port, either for exclusive use of this Comm or giving permission for the port to be shared by other Comms. 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.
this& |
A handle to a comm object |
config& |
A handle to a CommConfig object |
result% |
An error code |
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.
result% = CommSetMode%:(this&,config&)
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.
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 CommServerConfigV01 descriptor.
When a port is opened, the default is full buffering
this& |
A handle to a comm object |
config& |
A handle to a CommServerConfig object |
result% |
An error code |
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.
CommMode, CommQueryReceiveBuffer, CommReceiveBufferLength, CommResetBuffers
CommSetReceiveBufferLength:(this&,length&)
Use this function to change the size of the serial port receive and transmit buffers.
this& |
A handle to a comm object |
length& |
The required size of the receive and transmit buffers in bytes. |
CommSetSignals:(this&,setmask&,clearmask&)
Using this inline function, either of the RS232 output lines (DTR and RTS) can be set or cleared manually as needed.
this& |
A handle to a comm object |
setmask& |
Set the handshaking lines in the mask as specified in Signal line constants |
clearmask& |
Set the handshaking lines in the mask as specified in Signal line constants |
For many applications, these lines will be read and set under driver control as determined by the handshaking options selected.
signals& = CommSignals&:(this&,mask&)
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.
this& |
A handle to a comm object |
mask& |
This defaults to 0x3f as only the top six bits of this integer are valid. |
signals& |
An integer with the bits set to reflect the status of the handshaking lines according to the values defined in Signal line constants |
CommWriteA:(this&,des&,length&,timeout&,BYREF
status&)
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.
this& |
A handle to a comm 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 |
timeout& |
If not 0, the read will terminate after timeout&
microseconds if the data requested has not been sent. |
BYREF status& |
The request status used to contain completion information for the function. |
CommWriteCancel:(this&)
Causes any pending CommWrite operation to complete immediately.
this& |
A handle to a comm object |
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.
|
|
|
|
|
|