RComm Class Reference

Gets the current status of flow control between the port and the third party (external PC or internal signalling stack).

Gets current DCE/DTE role.

Gets server buffering mode.

Notifies the client when a break occurs: the remote end has held the communication line high for a certain number of bits to indicate a break condition.

Notifies the client when the port configuration (data rate, character width, stop bits, handshaking, or parity) of the remote end changes.

Notifies the client when data is available to be read from the input buffer.

This API allows the client to delay creation of the buffer receiving the data until the data has arrived. This allows the client to query the size of the data waiting before creating the buffer, and simplifies the client's buffer management since it is only needed during the subsequent Read() calls.

The behaviour of this API after a call to Read() or ReadOneOrMore() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to Read() or readOneOrMore(), while ECUART and ECACM will complete the request with KErrInUse.

Notifies the client when the flow control between the CSY and the external device changes.

Notifies the client when the transmit buffer is emptied.

Notifies the client when one of the signals change.

Opens a serial port, for one of the three modes indicated by the TCommAccess argument.

The TCommAccess argument may dictate exclusive use of the RComm, shared use (thereby giving permission for the port to be shared by other RComm objects) or pre-emptable use (allowing another client to pre-empt this session with an open request in one of the other two modes). 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 in exclusive mode. A client opening a port in pre-emptive mode must be prepared to have its outstanding requests errored with KErrCancel if another client opens the port in either ECommShared or ECommExclusive mode. In this case the port handle will effectively be transferred from the pre-emptable client to the new client.

The first variant (this) will open the port in DTE role, that is, the lines are configured as for a port of a computer. For instance, the signal lines DTR and RTS are outputs while the other signals (DCD,CTS,DSR,RING) are inputs.

The second variant allows the port to be opened in either DTE role or DCE role. This latter role means that the lines are configured as for a port of a modem. DTR and RTS are inputs while the other signals are outputs.

The request to open in either role will fail with KErrLocked if the port has already been opened in the opposite role elsewhere.

Signal constant    DTE role     DCE role
----------------------------------------
KSignalCTS         input        output
KSignalDSR         input        output
KSignalDCD         input        output
KSignalRNG         input        output
KSignalRTS         output       input
KSignalDTR         output       input

Note:

1. On some earlier versions of C32 the port number was limited to one digit, i.e. from 0 to 9. This restriction is now removed, and the number of ports is now only limited by the CSY and/or the Device Drivers up to a maximum of KMaxTUint ports.

2. This API checks that the client has the correct capabilities to open the port, while the RCommServ APIs do not. So a CSY that allowed the client to interrogate it via RCommServ::GetPortInfo() and load it via RCommServ::LoadCommModule() may still reject the same client's call to this API.

3. There are a number of distinct steps that must be performed before being able to issue an Open() request for a serial port. For convenience these are listed here:

a. Load the physical device driver, which interacts directly with the hardware at the lowest level (usually via User::LoadPhysicalDevice()).

b. Load the logical device driver, which provides the comms server with a consistent interface to the hardware (usually via User::LoadLogicalDevice()).

c. Connect to the C32 Serial Server using RCommServ

d. Load a specific Comms Module (.CSY) by filename via RCommServ::LoadCommModule.

In some environments the physical and logical device drivers are loaded as part of device boot.

Opens a serial port, as described for the other Open() variant.

This variant allows the port to be opened in either DTE role or DCE role. DCE role means that the lines are configured as for a port of a modem. DTR and RTS are inputs while the other signals are outputs.

Opens a serial port when it is freed by another client.

When a client has a port open in either exclusive or shared mode, another client may use this function to gain access to the port when the owning client closes its handle. Upon closure, the asynchronous OpenWhenAvailable() function will complete. The port role, DTE or DCE, will not be changed by this request and so the role will be inherited from the previous session. Furthermore, the port will automatically opened in ECommPreemptable mode. This can be subsequently upgraded to ECommShared or ECommExclusive mode using the SetAccessMode() function.

If client submits an OpenWhenAvailable() request and then attempts to execute an action, for example a read or write request, before the OpenWhenAvailable has completed, the action will fail with the KErrNotReady error code.

The server can only support one OpenWhenAvailable request per port. For example, if client A has a port open in exclusive mode and client B has an OpenWhenAvailable request pending, then client C's OpenWhenAvailable request will fail with the KErrAccessDenied error code.

The server is designed to support the OpenWhenAvailable request dispatched from a different RCommServ session than the one actively using the port. This is not viewed as a major disadvantage since, in practice, the two clients will normally be running in different threads, and quite probably different processes.

If the port is available immediately, it will be opened with DTE role.

Opens a serial port when freed.

Same as the other OpenWhenAvailable() but here you can specify the preferred role in case the port is free when you want to open it. If the port is already opened by another client, you will get the same role when it becomes available.

Gets the number of bytes currently waiting in the driver's input buffer. A return value of zero means the buffer is empty.

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 the KConfigWriteBufferedComplete bit (set via the TCommConfigV01 structure's iHandshake field) is clear, then all write requests will delay completion until the data has completely cleared the driver's output buffer. If the KConfigWriteBufferedComplete bit 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.

Reads data from a serial port.

All reads from the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The length of the TDes8 is set to zero on entry, which means that buffers can be reused without having to be zeroed first.

The number of bytes to read is set to the maximum length of the descriptor.

If a read is issued with a data length of zero the Read() completes immediately with the side effect that the serial hardware is powered up.

If a read terminates with KErrTimedOut and the descriptor is not empty, it will contain valid data. Its length should therefore be tested.

The behaviour of this API after a call to NotifyDataAvailable() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

Reads a specified number of bytes from a serial port.

Overloaded version of Read() with explicit length.

All reads from the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The length of the TDes8 is set to zero on entry, which means that buffers can be reused without having to be zeroed first.

The number of bytes to read is set to aLength.

If a read is issued with a data length of zero (aLength=0) the Read() completes immediately with the side effect that the serial hardware is powered up.

If a read terminates with KErrTimedOut and the descriptor is not empty, it will contain valid data. Its length should therefore be tested.

The behaviour of this API after a call to NotifyDataAvailable() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

Reads data from a serial port only if it arrives before a specified time-out.

Overloaded version of Read() with timeout.

All reads from the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The length of the TDes8 is set to zero on entry, which means that buffers can be reused without having to be zeroed first.

The number of bytes to read is set to the maximum length of the descriptor.

If a read is issued with a data length of zero the Read() completes immediately but with the side effect that the serial hardware is powered up.

When a Read() terminates with KErrTimedOut, different protocol modules can show different behaviours. Some may write any data received into the aDes buffer, while others may return just an empty descriptor. In the case of a returned empty descriptor use ReadOneOrMore() to read any data left in the buffer.

The behaviour of this API after a call to NotifyDataAvailable() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

Read data from a serial port (before the time-out).

Reads a specified number of bytes from a serial port only if they arrive before a specified time-out. Overloaded version of Read() with timeout and explicit length.

All reads from the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The length of the TDes8 is set to zero on entry, which means that buffers can be reused without having to be zeroed first.

The number of bytes to read is set to aLength.

If a read is issued with a data length of zero the Read() completes immediately but with the side effect that the serial hardware is powered up.

When a Read() terminates with KErrTimedOut, different protocol modules can show different behaviours. Some may write any data received into the aDes buffer, while others may return just an empty descriptor. In the case of a returned empty descriptor use ReadOneOrMore() to read any data left in the buffer.

The behaviour of this API after a call to NotifyDataAvailable() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

Cancels any pending Read() or ReadOneOrMore() operations.

Read any bytes in the buffer or wait until one arrives.

Reads data from a serial port, but with slightly different behaviour to Read(). If there is data in the serial driver's buffer when ReadOneOrMore() 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 one or more bytes arrive at the serial hardware.

The behaviour of this API after a call to NotifyDataAvailable() is not prescribed and so different CSY's behave differently. IrComm will allow a successful completion of this API after a call to NotifyDataAvailable(), while ECUART and ECACM will complete the request with KErrInUse.

Gets 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.

Resets the transmit and receive serial port buffers independently.

aFlags is a bitmask, so setting KCommResetRx|KCommResetTx (the default) resets both buffers and all data in them is lost. This is the default value, so this is what happens if the function is called without a parameter.

This function should not be called when there are pending reads or writes.

Upgrades the mode of a port handle from pre-emptive mode to shared or exclusive mode.

Notes:

If a client attempts to change the mode of a port that is already in either shared or exclusive modes, the request will fail with the KErrNotSupported error code.

Clients should not attempt to change the access mode to pre-emptive, the behaviour in this case is unpredictable.

Sets the configuration of the serial port.

It is not possible to reconfigure the capabilities of ports while they are being used. In particular, if any client attempts to reconfigure a port when there are pending reads or writes a KErrInUse error code will be returned.

Sets the server buffering mode.

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 TCommServerConfig descriptor.

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.

Sets the size of the serial port receive and transmit buffers.

Notes:

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 SetReceiveBufferLength request, you should examine the returned value from ReceiveBufferLength.

It isn't always essential to set a buffer size as there is a generous default of 1024.

Changing the size of the receive buffer is the only way to tailor the operation of flow control in Symbian OS as the exact position of the high water mark is not configurable.

Sets or clears RS232 output lines (DTR and RTS).

For many applications, these lines will be read and set under driver control as determined by the handshaking options selected.

Sets the specified RS232 output lines.

Using this function, either of the RS232 output lines (DTR and RTS) can be set manually.

For many applications, these lines will be read and set under driver control as determined by the handshaking options selected.

Clears RS232 output lines.

Using this function, either of the RS232 output lines (DTR and RTS) can be cleared manually.

For many applications, these lines will be read and set under driver control as determined by the handshaking options selected.

Reads the serial port control lines.

Reads the status of the RS232 input and output lines (RTS, CTS, DSR, DCD, DTR). They are bit-masked into a single integer and one or all of them can be read at any time.

Not all of the input lines are guaranteed to be available on all serial devices.

Writes data to a serial port.

All writes to the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The number of bytes to write is set to the maximum length of the descriptor.

When a Write() is issued with a data length of zero it cannot complete until the current handshaking configuration and the state of input control lines indicate that it is possible for data to be immediately written to the serial line, even though no data is to be written. This functionality is useful when determining when serial devices come on line, and checking that the output buffer is empty (if the KConfigWriteBufferedComplete bit is set).

Writes a specified number of bytes to a serial port.

All writes to the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The number of bytes to write is set to aLength.

When a Write() is issued with a data length of zero it cannot complete until the current handshaking configuration and the state of input control lines indicate that it is possible for data to be immediately written to the serial line, even though no data is to be written. This functionality is useful when determining when serial devices come on line, and checking that the output buffer is empty (if the KConfigWriteBufferedComplete bit is set).

Writes data to a serial port within a specified time-out.

All writes to the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The number of bytes to write is set to the maximum length of the descriptor.

When a Write() is issued with a data length of zero it cannot complete until the current handshaking configuration and the state of input control lines indicate that it is possible for data to be immediately written to the serial line, even though no data is to be written. This functionality is useful when determining when serial devices come on line, and checking that the output buffer is empty (if the KConfigWriteBufferedComplete bit is set).

Writes a specified number of bytes to a serial port within a specified time-out.

All writes to the serial device use 8-bit descriptors as data buffers, even on a Unicode system.

The number of bytes to write is set to aLength.

When a Write() is issued with a data length of zero it cannot complete until the current handshaking configuration and the state of input control lines indicate that it is possible for data to be immediately written to the serial line. This functionality is useful when determining when serial devices come on line, and checking that the output buffer is empty (if the KConfigWriteBufferedComplete bit is set).

Cancels any pending Write() operations.

The cancelled request will still terminate with its TRequestStatus set, to any value other than KErrPending. While this is most likely to be KErrCancel, it is nevertheless possible for the cancellation to have been issued after the asynchronous request had already terminated for some other reason.