![[Index]](../../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../a_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
||
Location:
c32comm.h
Link against: c32.lib
class RComm : public RSubSessionBase;
A sub-session to the C32 Serial Server used for addressing a serial port.
All the necessary functions are provided by this class for communicating via a port, including functions for opening, closing, reading, writing, port configuration and capability checking. An RComm session represents a single serial port and once opened cannot be altered to represent another port.
Ports are referenced by a character string whose format is referred to as Port Prefix format. This format is also known as the CSY internal name, and the ports "short" name in older releases.
RSubSessionBase - Client-side handle to a sub-session
RComm - A sub-session to the C32 Serial Server used for addressing a serial port
Defined in RComm:
Break(), BreakCancel(), Cancel(), Caps(), Close(), Config(), DebugState(), GetFlowControlStatus(), GetRole(), Mode(), NotifyBreak(), NotifyBreakCancel(), NotifyConfigChange(), NotifyConfigChangeCancel(), NotifyDataAvailable(), NotifyDataAvailableCancel(), NotifyFlowControlChange(), NotifyFlowControlChangeCancel(), NotifyOutputEmpty(), NotifyOutputEmptyCancel(), NotifySignalChange(), NotifySignalChangeCancel(), Open(), Open(), OpenWhenAvailable(), OpenWhenAvailable(), OpenWhenAvailableCancel(), QueryReceiveBuffer(), RComm(), Read(), Read(), Read(), Read(), ReadCancel(), ReadOneOrMore(), ReceiveBufferLength(), ResetBuffers(), SetAccessMode(), SetConfig(), SetMode(), SetReceiveBufferLength(), SetSignals(), SetSignalsToMark(), SetSignalsToSpace(), Signals(), Write(), Write(), Write(), Write(), WriteCancel()
Inherited from RSubSessionBase:
CloseSubSession(),
CreateAutoCloseSubSession(),
CreateSubSession(),
Send(),
SendReceive(),
Session(),
SubSessionHandle()
|
|
| Capability: | Dependent |
IMPORT_C TInt Open(RCommServ &aServer, const TDesC &aName, TCommAccess aMode);
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.
|
|
| Capability: | Dependent |
IMPORT_C TInt Open(RCommServ &aServer, const TDesC &aName, TCommAccess aMode, TCommRole aRole);
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.
|
|
| Capability: | Dependent |
IMPORT_C void OpenWhenAvailable(TRequestStatus &aStatus, RCommServ &aServer, const TDesC &aName);
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.
|
| Capability: | Dependent |
IMPORT_C void OpenWhenAvailable(TRequestStatus &aStatus, RCommServ &aServer, const TDesC &aName, TCommRole aRole);
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.
|
| Capability: | Illegal |
IMPORT_C void OpenWhenAvailableCancel();
Cancels an OpenWhenAvailable() pending request.
| Capability: | Illegal |
IMPORT_C void Read(TRequestStatus &aStatus, TDes8 &aDes);
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.
|
| Capability: | Illegal |
IMPORT_C void Read(TRequestStatus &aStatus, TDes8 &aDes, TInt aLength);
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.
|
| Capability: | Illegal |
IMPORT_C void Read(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8 &aDes);
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.
|
| Capability: | Illegal |
IMPORT_C void Read(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut, TDes8 &aDes, TInt aLength);
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.
|
| Capability: | Illegal |
IMPORT_C void ReadOneOrMore(TRequestStatus &aStatus, TDes8 &aDes);
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.
|
| Capability: | Illegal |
IMPORT_C TInt ReadCancel();
Cancels any pending Read() or ReadOneOrMore() 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.
|
| Capability: | Illegal |
IMPORT_C TInt QueryReceiveBuffer() const;
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 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.
|
| Capability: | Illegal |
IMPORT_C TInt ResetBuffers(TUint aFlags=(KCommResetRx|KCommResetTx));
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.
|
|
| Capability: | Illegal |
IMPORT_C void Write(TRequestStatus &aStatus, const TDesC8 &aDes);
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 KConfigWriteBufferedComplete is set).
|
| Capability: | Illegal |
IMPORT_C void Write(TRequestStatus &aStatus, const TDesC8 &aDes, TInt aLength);
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 KConfigWriteBufferedComplete is set).
|
| Capability: | Illegal |
IMPORT_C void Write(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8 &aDes);
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 KConfigWriteBufferedComplete is set).
|
| Capability: | Illegal |
IMPORT_C void Write(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut, const TDesC8 &aDes, TInt aLength);
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 KConfigWriteBufferedComplete
is set).
|
| Capability: | Illegal |
IMPORT_C TInt WriteCancel();
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.
|
| Capability: | Illegal |
IMPORT_C void Break(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTime);
Sets a break condition for a specified time.
A break condition on a line is when a data line is held permanently high for an indeterminate period which must be greater than the time normally taken to transmit two characters. It is sometimes used as an error signal between computers and other devices attached to them over RS232 lines.
Notes:
Setting breaks is not supported on the integral ARM serial hardware. EPOC has no support for detecting received breaks. There
is no way to detects whether setting a break is supported using Caps().
|
| Capability: | Illegal |
IMPORT_C TInt BreakCancel();
Cancels any pending Break() operations.
|
| Capability: | Illegal |
IMPORT_C TInt Cancel();
Cancels any pending reads and writes.
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 Cancel() before closing a port as this is done automatically.
|
| Capability: | Illegal |
IMPORT_C TInt Config(TDes8 &aConfig) const;
Reads the current configuration of the serial port.
It isn't essential to read an existing configuration in order to set a new one. However, calling this function is a useful way of initializing a TCommConfig structure and thus avoiding the overhead of having to explicitly set every member. If a port were being shared between difference processes, it would also be good manners to save an existing configuration before using the port in order than it might be restored when you have finished with it.
|
|
| Capability: | Illegal |
IMPORT_C TInt SetConfig(const TDesC8 &aConfig);
Sets the configuration of the serial port.
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.
|
|
| Capability: | Illegal |
IMPORT_C TInt Caps(TDes8 &aCaps) const;
Reads the capabilities of the serial port.
As the serial driver can control a range of different physical devices with differing capabilities, it could be considered important from the point of view of the operating system to be able to read these capabilities before attempting to configure the port. In practice however, program development is likely to be targeted at a specific hardware configuration, and interrogation of a device to ascertain its capabilities isn't normally necessary.
|
|
| Capability: | Illegal |
IMPORT_C TInt SetMode(const TCommServerConfig &aConfig);
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.
|
|
| Capability: | Illegal |
IMPORT_C TInt Mode(TCommServerConfig &aConfig) const;
Gets server buffering mode.
|
|
| Capability: | Illegal |
IMPORT_C TUint Signals(TUint aSignalMask=0x3F) const;
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.
|
|
| Capability: | Illegal |
IMPORT_C TInt SetSignalsToMark(TUint aSignalMask);
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.
|
|
| Capability: | Illegal |
IMPORT_C TInt SetSignalsToSpace(TUint aSignalMask);
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.
|
|
| Capability: | Illegal |
IMPORT_C TInt ReceiveBufferLength() const;
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.
|
| Capability: | Illegal |
IMPORT_C TInt SetReceiveBufferLength(TInt aLength);
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.
|
|
| Capability: | Illegal |
IMPORT_C void Close();
Closes a serial port. If the session is closed without having closed all the open ports via calls to this function, then the session close will close all remaining ports opened by the session.
inline void SetSignals(TUint aSetMask, TUint aClearMask);
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.
|
| Capability: | Illegal |
IMPORT_C void NotifySignalChange(TRequestStatus &aStatus, TUint &aSignals, TUint aSignalMask=0x3F);
Notifies the client when one of the signals change.
|
| Capability: | Illegal |
IMPORT_C TInt NotifySignalChangeCancel() const;
Cancels a NotifySignalChange() request.
|
| Capability: | Illegal |
IMPORT_C void NotifyConfigChange(TRequestStatus &aStatus, TDes8 &aNewConfig) const;
Notifies the client when the port configuration (data rate, character width, stop bits, handshaking, or parity) of the remote end changes.
|
| Capability: | Illegal |
IMPORT_C TInt NotifyConfigChangeCancel() const;
Cancels a NotifyConfigChange() request.
|
| Capability: | Illegal |
IMPORT_C void NotifyFlowControlChange(TRequestStatus &aStatus, TFlowControl &aFlowControl);
Notifies the client when the flow control between the CSY and the external device changes.
|
| Capability: | Illegal |
IMPORT_C TInt NotifyFlowControlChangeCancel() const;
Cancels a NotifyFlowControlChange() request.
|
| Capability: | Illegal |
IMPORT_C void NotifyBreak(TRequestStatus &aStatus) const;
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.
|
| Capability: | Illegal |
IMPORT_C TInt NotifyBreakCancel() const;
Cancels a NotifyBreak() request.
|
| Capability: | Illegal |
IMPORT_C void NotifyDataAvailable(TRequestStatus &aStatus) const;
Notifies the client when data is available to be read from the input buffer.
|
| Capability: | Illegal |
IMPORT_C TInt NotifyDataAvailableCancel() const;
Cancels a NotifyDataAvailable() request.
|
| Capability: | Illegal |
IMPORT_C void NotifyOutputEmpty(TRequestStatus &aStatus) const;
Notifies the client when the transmit buffer is emptied.
|
| Capability: | Illegal |
IMPORT_C TInt NotifyOutputEmptyCancel() const;
Cancels a NotifyOutputEmpty() request.
|
| Capability: | Illegal |
IMPORT_C TInt GetFlowControlStatus(TFlowControl &aFlowControl) const;
Gets the current status of flow control between the port and the third party (external PC or internal signalling stack).
|
|
| Capability: | Illegal |
IMPORT_C TInt GetRole(TCommRole &aRole) const;
Gets current DCE/DTE role.
|
|
| Capability: | Illegal |
IMPORT_C TInt SetAccessMode(TCommAccess aNewMode);
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.
|
|
IMPORT_C TInt DebugState(TCommDebugInfo &);
Debug state information. Only implemented for DEBUG builds.
|
|
|
Copyright ©2008 Symbian Software Ltd. |
|
![[Top]](../../../../a_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../../a_stock/btn_top.gif)
![[Next]](../../../../a_stock/btn_next.gif){kind=small}