![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
c32comm.h
Link against: c32.lib
RComm
Supported from 5.0
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.
|
Defined in RComm:
OpenWhenAvailableCancel(), Break(), BreakCancel(), Cancel(), Caps(), Close(), Config(), GetFlowControlStatus(), GetRole(), Mode(), NotifyBreak(), NotifyBreakCancel(), NotifyConfigChange(), NotifyConfigChangeCancel(), NotifyDataAvailable(), NotifyDataAvailableCancel(), NotifyFlowControlChange(), NotifyFlowControlChangeCancel(), NotifyOutputEmpty(), NotifyOutputEmptyCancel(), NotifySignalChange(), NotifySignalChangeCancel(), Open(), OpenWhenAvailable(), QueryReceiveBuffer(), Read(), ReadCancel(), ReadOneOrMore(), ReceiveBufferLength(), ResetBuffers(), SetAccessMode(), SetConfig(), SetMode(), SetReceiveBufferLength(), SetSignals(), SetSignalsToMark(), SetSignalsToSpace(), Signals(), Write(), WriteCancel()
Inherited from RSubSessionBase:
CloseSubSession(),
CreateSubSession(),
Send(),
SendReceive(),
SubSessionHandle(),
operator=()
TInt Open(RCommServ &aServer, const TDesC &aName,TCommAccess aMode);
Opens a serial port, for one of the three modes indicated by
the TCommAccess argument. This may dictate exclusive use of the
RComm, shared use (giving permission for the port to be shared by
other RComms) 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.
|
|
TInt Open(RCommServ &aServer, const TDesC &aName,TCommAccess aMode,TCommRole aRole);
Supported from 6.0
Opens a serial port, as described for the previous function. It 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.
|
|
void OpenWhenAvailable(TRequestStatus& aStatus, RCommServ &aServer, const TDesC &aName);
Supported from 6.0
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, is not be changed by this
request and so the role will be inherited from the previous session. The port
is automatically opened in pre-emptive mode. This can be subsequently upgraded
to shared or exclusive mode using the SetAccessMode()
function.
Notes:
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.
|
|
void OpenWhenAvailableCancel();
Supported from 6.0
Cancels an OpenWhenAvailable()
request.
|
|
void 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.
void Caps(TDes8& aCaps);
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.
|
void 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
aTCommConfig 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.
|
TInt SetAccessMode(TCommAccess aNewMode);
Supported from 6.0
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
theKErrNotSupported error code.
Clients should not attempt to change the access mode to pre-emptive, the behaviour in this case is unpredictable.
|
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.
|
|
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.
|
void SetSignalsToMark(TUint aSignalMask);
Sets the specified RS232 output lines.
|
void SetSignalsToSpace(TUint aSignalMask);
Clears RS232 output lines.
|
TUint Signals(TUint aSignalMask=0x3F) const;
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.
|
|
|
void Read(TRequestStatus &aStatus, TDes8 &aDes);
void Read(TRequestStatus &aStatus, TDes8 &aDes, TInt aLength);
void Read(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut,TDes8 &aDes);
void Read(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut,TDes8 &aDes, TInt aLength);
Reads data from a serial port. All reads from the serial device use 8-bit descriptors as data buffers, even on a Unicode system.
Note:
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 amount of data to be read from the serial driver depends upon which
overload of Read() is used. Normally the length used is the
maximum length of the descriptor. In the version which takes an explicit length
this value is used in preference to the descriptor’s maximum
length.
If a read is issued with a data length of zero (either explicitly or
implicit in the descriptor) the Read() will complete immediately
with the side effect that the serial hardware will have been powered up.
In the case of a read terminating with KErrTimedOut,
different protocol modules may show different behavior. Some may write any data
received into the aDes buffer. Others may always return an empty
descriptor: in that case, any data in the buffer can be read
throughReadOneOrMore().
|
void ReadCancel();
Cancels any
pendingRead()orReadOneOrMore()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.
void ReadOneOrMore(TRequestStatus &aStatus,TDes8 &aDes);
Reads data from a serial port, but with slightly different behaviour
toRead(). If there is data in the serial driver’s buffer
whenReadOneOrMore() 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.
|
|
void Write(TRequestStatus &aStatus,const TDesC8 &aDes);
void Write(TRequestStatus &aStatus,const TDesC8 &aDes, TInt aLength);
void Write(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut,const TDesC8 &aDes);
void Write(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTimeOut,const TDesC8 &aDes, TInt aLength);
Writes data to a serial port. All writes to the serial device use 8-bit descriptors as data buffers, even on a Unicode system.
Note:
The amount of data to be written to the serial driver depends upon which
overload of Write() is used. Normally the length used is the
current length of the descriptor. In the version which takes an explicit
length, this value is used in preference to the descriptor's length.
If a write is issued with a data length of zero (either explicitly or
implicit in the descriptor) the Write() will complete when the
current handshaking configuration and the state of input control lines would
allow any data to be immediately written to the serial line. This functionality
is useful to determine when serial devices come on line, and to check that the
output buffer is empty if KConfigWriteBufferedComplete is
set.
|
void 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.
|
void Mode(TCommServerConfig &aConfig)const;
Gets server buffering mode.
|
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.
IfKConfigWriteBufferedComplete 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.
|
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.
|
void ResetBuffers();
void ResetBuffers(TUint aFlags);
Resets the serial port buffers. By default, if no argument is passed, both the receive and transmit buffers are reset to zero length, and all data in the them is lost. Alternatively, either buffer can be reset independently.
Note:
aFlags is a bitmask, so
settingKCommResetRx|KCommResetTx (the default) resets both
buffers
this function should not be called when there are pending reads or writes
|
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.
|
|
void SetReceiveBufferLength(TInt aLength);
Sets the size of the serial port receive and transmit buffers.
Note:
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 EPOC as the exact position of the high water mark is not configurable.
|
|
Note:
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.
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
usingCaps().
void Break(TRequestStatus &aStatus, TTimeIntervalMicroSeconds32 aTime);
Sets a break condition for a specified time.
|
|
void NotifySignalChange(TRequestStatus& aStatus, TUint& aSignals, TUint aSignalMask=0x3F);
Supported from 6.0
Notifies the client when one of the signals change.
|
void NotifySignalChangeCancel() const;
Supported from 6.0
Cancels a NotifySignalChange() request.
void NotifyConfigChange(TRequestStatus& aStatus, TDes8& aNewConfig) const;
Supported from 6.0
Notifies the client when the port configuration (data rate, character width, stop bits, handshaking, or parity) of the remote end changes.
|
void NotifyConfigChangeCancel() const;
Supported from 6.0
Cancels a NotifyConfigChangeCancel() request.
void NotifyFlowControlChange(TRequestStatus& aStatus, TFlowControl& aFlowControl);
Supported from 6.0
Notifies the client when the flow control between the CSY and the external device changes.
|
void NotifyFlowControlChangeCancel() const;
Supported from 6.0
Cancels a NotifyFlowControlChangeCancel() request.
void NotifyBreak(TRequestStatus& aStatus) const;
Supported from 6.0
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
|
void NotifyBreakCancel() const;
Supported from 6.0
Cancels a NotifyBreakCancel() request.
void NotifyDataAvailable(TRequestStatus& aStatus) const;
Supported from 6.0
Notifies the client when data is available to be read from the input buffer.
|
void NotifyDataAvailableCancel() const;
Supported from 6.0
Cancels a NotifyDataAvailableCancel() request.
void NotifyOutputEmpty(TRequestStatus& aStatus) const;
Supported from 6.0
Notifies the client when the transmit buffer is emptied.
|
void NotifyOutputEmptyCancel() const;
Supported from 6.0
Cancels a NotifyOutputEmptyCancel() request.
|
TInt GetFlowControlStatus(TFlowControl& aFlowControl) const;
Supported from 6.0
Gets the current status of flow control between the port and the third party (external PC or internal signalling stack).
|
|
TInt GetRole(TCommRole& aRole) const;
Supported from 6.0
Gets current DCE/DTE role.
|
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}