RComm Class Reference

#include <c32comm.h>

Link against: c32.lib

class RComm : public RSubSessionBase

Inherits from

Public Member Functions
RComm()
IMPORT_C voidBreak(TRequestStatus &, TTimeIntervalMicroSeconds32)
IMPORT_C TIntBreakCancel()
IMPORT_C TIntCancel()
IMPORT_C TIntCaps(TDes8 &)
IMPORT_C voidClose()
IMPORT_C TIntConfig(TDes8 &)
IMPORT_C TIntDebugState(TCommDebugInfo &)
IMPORT_C TIntGetFlowControlStatus(TFlowControl &)
IMPORT_C TIntGetRole(TCommRole &)
IMPORT_C TIntMode(TCommServerConfig &)
IMPORT_C voidNotifyBreak(TRequestStatus &)
IMPORT_C TIntNotifyBreakCancel()
IMPORT_C voidNotifyConfigChange(TRequestStatus &, TDes8 &)
IMPORT_C TIntNotifyConfigChangeCancel()
IMPORT_C voidNotifyDataAvailable(TRequestStatus &)
IMPORT_C TIntNotifyDataAvailableCancel()
IMPORT_C voidNotifyFlowControlChange(TRequestStatus &, TFlowControl &)
IMPORT_C TIntNotifyFlowControlChangeCancel()
IMPORT_C voidNotifyOutputEmpty(TRequestStatus &)
IMPORT_C TIntNotifyOutputEmptyCancel()
IMPORT_C voidNotifySignalChange(TRequestStatus &, TUint &, TUint)
IMPORT_C TIntNotifySignalChangeCancel()
IMPORT_C TIntOpen(RCommServ &, const TDesC &, TCommAccess)
IMPORT_C TIntOpen(RCommServ &, const TDesC &, TCommAccess, TCommRole)
IMPORT_C voidOpenWhenAvailable(TRequestStatus &, RCommServ &, const TDesC &)
IMPORT_C voidOpenWhenAvailable(TRequestStatus &, RCommServ &, const TDesC &, TCommRole)
IMPORT_C voidOpenWhenAvailableCancel()
IMPORT_C TIntQueryReceiveBuffer()
IMPORT_C voidRead(TRequestStatus &, TDes8 &)
IMPORT_C voidRead(TRequestStatus &, TDes8 &, TInt)
IMPORT_C voidRead(TRequestStatus &, TTimeIntervalMicroSeconds32, TDes8 &)
IMPORT_C voidRead(TRequestStatus &, TTimeIntervalMicroSeconds32, TDes8 &, TInt)
IMPORT_C TIntReadCancel()
IMPORT_C voidReadOneOrMore(TRequestStatus &, TDes8 &)
IMPORT_C TIntReceiveBufferLength()
IMPORT_C TIntResetBuffers(TUint)
IMPORT_C TIntSetAccessMode(TCommAccess)
IMPORT_C TIntSetConfig(const TDesC8 &)
IMPORT_C TIntSetMode(const TCommServerConfig &)
IMPORT_C TIntSetReceiveBufferLength(TInt)
voidSetSignals(TUint, TUint)
IMPORT_C TIntSetSignalsToMark(TUint)
IMPORT_C TIntSetSignalsToSpace(TUint)
IMPORT_C TUintSignals(TUint)
IMPORT_C voidWrite(TRequestStatus &, const TDesC8 &)
IMPORT_C voidWrite(TRequestStatus &, const TDesC8 &, TInt)
IMPORT_C voidWrite(TRequestStatus &, TTimeIntervalMicroSeconds32, const TDesC8 &)
IMPORT_C voidWrite(TRequestStatus &, TTimeIntervalMicroSeconds32, const TDesC8 &, TInt)
IMPORT_C TIntWriteCancel()
Inherited Functions
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const

Detailed Description

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.

Constructor & Destructor Documentation

RComm ( )

IMPORT_CRComm()

Constructor

Member Function Documentation

Break ( TRequestStatus &, TTimeIntervalMicroSeconds32 )

IMPORT_C voidBreak(TRequestStatus &aStatus,
TTimeIntervalMicroSeconds32aTime
)

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().

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aTimeA timed break period in microseconds.
Capability
None

BreakCancel ( )

IMPORT_C TIntBreakCancel()
Cancels any pending Break() operations.
Capability
None

Cancel ( )

IMPORT_C TIntCancel()

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
None

Caps ( TDes8 & )

IMPORT_C TIntCaps(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.

Parameters
aCapsOn return this descriptor will contain either a packaged TCommCapsV01 structure or a packaged TCommCapsV02 structure corresponding to the capabilities of the serial device and of the CSY module, depending on the size of the descriptor passed in to the function.
Capability
None

Close ( )

IMPORT_C voidClose()
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.
Capability
None

Config ( TDes8 & )

IMPORT_C TIntConfig(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.

Parameters
aConfigOn return, a TCommConfig package buffer holding the configuration settings
Capability
None

DebugState ( TCommDebugInfo & )

IMPORT_C TIntDebugState(TCommDebugInfo &)

Debug state information. Only implemented for DEBUG builds.

GetFlowControlStatus ( TFlowControl & )

IMPORT_C TIntGetFlowControlStatus(TFlowControl &aFlowControl)const

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

Parameters
aFlowControlOn return, flow control status
Return Value
System-wide error code
Capability
None

GetRole ( TCommRole & )

IMPORT_C TIntGetRole(TCommRole &aRole)const

Gets current DCE/DTE role.

Parameters
aRoleOn return, current DCE/DTE role
Return Value
System-wide error code
Capability
None

Mode ( TCommServerConfig & )

IMPORT_C TIntMode(TCommServerConfig &aConfig)const

Gets server buffering mode.

Parameters
aConfigA packaged TCommServerConfigV01 structure which will hold the required information on return.
Capability
None

NotifyBreak ( TRequestStatus & )

IMPORT_C voidNotifyBreak(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.

Parameters
aStatusOn return, system wide error code for asynchronous function.
Capability
None

NotifyBreakCancel ( )

IMPORT_C TIntNotifyBreakCancel()const
Cancels a NotifyBreak() request.
Capability
None

NotifyConfigChange ( TRequestStatus &, TDes8 & )

IMPORT_C voidNotifyConfigChange(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.

Parameters
aStatusOn return, system wide error code for asynchronous function.
aNewConfigOn completion, a packaged TCommNotificationV01.
Capability
None

NotifyConfigChangeCancel ( )

IMPORT_C TIntNotifyConfigChangeCancel()const
Cancels a NotifyConfigChange() request.
Capability
None

NotifyDataAvailable ( TRequestStatus & )

IMPORT_C voidNotifyDataAvailable(TRequestStatus &aStatus)const

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.

Parameters
aStatusOn return, a system wide error code.
Capability
None

NotifyDataAvailableCancel ( )

IMPORT_C TIntNotifyDataAvailableCancel()const
Cancels a NotifyDataAvailable() request.
Capability
None

NotifyFlowControlChange ( TRequestStatus &, TFlowControl & )

IMPORT_C voidNotifyFlowControlChange(TRequestStatus &aStatus,
TFlowControl &aFlowControl
)

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

Parameters
aStatusOn return, system wide error code for asynchronous function.
aFlowControlOn completion, new flow control status.
Capability
None

NotifyFlowControlChangeCancel ( )

IMPORT_C TIntNotifyFlowControlChangeCancel()const
Cancels a NotifyFlowControlChange() request.
Capability
None

NotifyOutputEmpty ( TRequestStatus & )

IMPORT_C voidNotifyOutputEmpty(TRequestStatus &aStatus)const

Notifies the client when the transmit buffer is emptied.

Parameters
aStatusOn return, system wide error code for asynchronous function.
Capability
None

NotifyOutputEmptyCancel ( )

IMPORT_C TIntNotifyOutputEmptyCancel()const
Cancels a NotifyOutputEmpty() request.
Capability
None

NotifySignalChange ( TRequestStatus &, TUint &, TUint )

IMPORT_C voidNotifySignalChange(TRequestStatus &aStatus,
TUint &aSignals,
TUintaSignalMask = 0x3F
)

Notifies the client when one of the signals change.

Parameters
aStatusAsynchronous completion status
aSignalsOn return, the new set of signals. The bottom five bits contain a mask of the signals that are set (using the Signal line constants). The top four bits store which signal has changed (using the Signal line changed constants).
aSignalMaskBitmaks of the signals to monitor. The default is all signals. See also KSignalDTEOutputs and KSignalDTEInputs.
Capability
None

NotifySignalChangeCancel ( )

IMPORT_C TIntNotifySignalChangeCancel()const
Cancels a NotifySignalChange() request.
Capability
None

Open ( RCommServ &, const TDesC &, TCommAccess )

IMPORT_C TIntOpen(RCommServ &aServer,
const TDesC &aName,
TCommAccessaMode
)

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.

Parameters
aServerThe comms server session.
aNameThe name of the port (e.g. "COMM::0")
aModeThe mode in which the port is opened. There is no default.
Return Value
System-wide error code: KErrNone if successful; KErrPermissionDenied if the port given in aName is wrong or if the request fails the CSY's own security check; KErrNotSupported if this port is not supported by the CSY or the hardware; KErrLocked if the port has already been opened; KErrAccessDenied if the device driver encounteres a problem opening the hardware port.
Capability
Dependent

Open ( RCommServ &, const TDesC &, TCommAccess, TCommRole )

IMPORT_C TIntOpen(RCommServ &aServer,
const TDesC &aName,
TCommAccessaMode,
TCommRoleaRole
)

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.

Parameters
aServerThe comms server session
aNameThe name of the port
aModeThe mode in which the port is opened. There is no default.
aRoleDTE/DCE role
Return Value
System-wide error code: KErrNone if successful; KErrPermissionDenied if the port given in aName is wrong; KErrNotSupported if this port is not supported by the CSY or the hardware; KErrLocked if the port has already been opened in the opposite role elsewhere.
Capability
Dependent

OpenWhenAvailable ( TRequestStatus &, RCommServ &, const TDesC & )

IMPORT_C voidOpenWhenAvailable(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.

Parameters
aStatusThe request status used to contain completion information for the function.
aServerThe comms server session.
aNameThe name of the port.
Return Value
System wide error code: see return values of RComm::Open().
Capability
Dependent

OpenWhenAvailable ( TRequestStatus &, RCommServ &, const TDesC &, TCommRole )

IMPORT_C voidOpenWhenAvailable(TRequestStatus &aStatus,
RCommServ &aServer,
const TDesC &aName,
TCommRoleaRole
)

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.

Parameters
aStatusThe request status used to contain completion information for the function.
aServerThe comms server session.
aNameThe name of the port.
aRolePreferred role (DTE or DCE).
Return Value
TInt A system wide error code: see return values of RComm::Open().
Capability
Dependent

OpenWhenAvailableCancel ( )

IMPORT_C voidOpenWhenAvailableCancel()
Cancels an OpenWhenAvailable() pending request.
Capability
None

QueryReceiveBuffer ( )

IMPORT_C TIntQueryReceiveBuffer()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 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.

Return Value
The number of bytes currently waiting to be read from the receive buffer.
Capability
None

Read ( TRequestStatus &, TDes8 & )

IMPORT_C voidRead(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.

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.

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aDesA buffer to store the incoming data. The maximum length of the descriptor is the number of bytes to be read.
Capability
None

Read ( TRequestStatus &, TDes8 &, TInt )

IMPORT_C voidRead(TRequestStatus &aStatus,
TDes8 &aDes,
TIntaLength
)

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.

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aDesA buffer to store the incoming data.
aLengthAn explicit length of data to be read. This length must be between 0 and the MaxLength of the descriptor both included.
Capability
None

Read ( TRequestStatus &, TTimeIntervalMicroSeconds32, TDes8 & )

IMPORT_C voidRead(TRequestStatus &aStatus,
TTimeIntervalMicroSeconds32aTimeOut,
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.

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.

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aTimeOutThe time-out value for reads in microseconds. If data fails to arrive before the specified number of microseconds, a KErrTimedOut status is returned.
aDesA buffer to store the incoming data. The maximum length of the descriptor is the default for the number of bytes to be read.
Capability
None

Read ( TRequestStatus &, TTimeIntervalMicroSeconds32, TDes8 &, TInt )

IMPORT_C voidRead(TRequestStatus &aStatus,
TTimeIntervalMicroSeconds32aTimeOut,
TDes8 &aDes,
TIntaLength
)

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.

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aTimeOutThe time-out value for reads in microseconds. If data fails to arrive before the specified number of microseconds, a KErrTimedOut status is returned.
aDesA buffer to store the incoming data.
aLengthAn explicit length of data to be read This length must be between 0 and the MaxLength of the descriptor both included.
Capability
None

ReadCancel ( )

IMPORT_C TIntReadCancel()

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
None

ReadOneOrMore ( TRequestStatus &, TDes8 & )

IMPORT_C voidReadOneOrMore(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.

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.

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code
aDesA buffer to store the incoming data. The maximum length of the descriptor is the default for the number of bytes to be read. When the request completes this will hold data read from the input buffer.
Capability
None

ReceiveBufferLength ( )

IMPORT_C TIntReceiveBufferLength()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.

Return Value
The current size of both the receive and transmit buffers in bytes.
Capability
None

ResetBuffers ( TUint )

IMPORT_C TIntResetBuffers(TUintaFlags = (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.

Parameters
aFlagsKCommResetRx to reset the receive buffer KCommResetTx to reset the transmit buffer
Capability
None

SetAccessMode ( TCommAccess )

IMPORT_C TIntSetAccessMode(TCommAccessaNewMode)

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.

Parameters
aNewModeThe value of the new port mode, either ECommShared or ECommExclusive.
Return Value
System-wide error code.
Capability
None

SetConfig ( const TDesC8 & )

IMPORT_C TIntSetConfig(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, if any client attempts to reconfigure a port when there are pending reads or writes a KErrInUse error code will be returned.

Parameters
aConfigNew configuration settings packaged in a TCommConfig
Return Value
System-wide error code: KErrInUse if there is a pending read or write on the port, otherwise system-wide error codes
Capability
None

SetMode ( const TCommServerConfig & )

IMPORT_C TIntSetMode(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.

Parameters
aConfigA packaged TCommServerConfigV01 structure to be set.
Return Value
System-wide error code
Capability
None

SetReceiveBufferLength ( TInt )

IMPORT_C TIntSetReceiveBufferLength(TIntaLength)

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.

Parameters
aLengthThe required size of the receive and transmit buffers in bytes.
Capability
None

SetSignals ( TUint, TUint )

voidSetSignals(TUintaSetMask,
TUintaClearMask
)[inline]

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.

Parameters
aSetMaskSet the handshaking lines in the mask.
aClearMaskClear the handshaking lines in the mask.

SetSignalsToMark ( TUint )

IMPORT_C TIntSetSignalsToMark(TUintaSignalMask)

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.

Parameters
aSignalMaskBitmask of handshaking lines
Capability
None

SetSignalsToSpace ( TUint )

IMPORT_C TIntSetSignalsToSpace(TUintaSignalMask)

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.

Parameters
aSignalMaskBitmask of handshaking lines
Capability
None

Signals ( TUint )

IMPORT_C TUintSignals(TUintaSignalMask = 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.

Parameters
aSignalMaskBitmask of lines to read. It defaults to all lines (0x3f as only the top six bits of this integer are valid). A different value can be specified as aSignalMask if specific information is required: for instance, Signals(KSignalDSR) could be used to find out if a modem were connected to the serial port.
Return Value
An integer with the bits set to reflect the status of the handshaking lines
Capability
None

Write ( TRequestStatus &, const TDesC8 & )

IMPORT_C voidWrite(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 the KConfigWriteBufferedComplete bit is set).

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aDesA descriptor containing the data to be written to the serial port.
Capability
None

Write ( TRequestStatus &, const TDesC8 &, TInt )

IMPORT_C voidWrite(TRequestStatus &aStatus,
const TDesC8 &aDes,
TIntaLength
)

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

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aDesA descriptor containing the data to be written to the serial port.
aLengthThe number of bytes to write. This length must be between 0 and the length of the descriptor both included.
Capability
None

Write ( TRequestStatus &, TTimeIntervalMicroSeconds32, const TDesC8 & )

IMPORT_C voidWrite(TRequestStatus &aStatus,
TTimeIntervalMicroSeconds32aTimeOut,
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 the KConfigWriteBufferedComplete bit is set).

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code.
aTimeOutThe write will terminate after aTimeout microseconds if the data requested has not been sent. A KErrTimedOut status is returned.
aDesA descriptor containing the data to be written to the serial port.
Capability
None

Write ( TRequestStatus &, TTimeIntervalMicroSeconds32, const TDesC8 &, TInt )

IMPORT_C voidWrite(TRequestStatus &aStatus,
TTimeIntervalMicroSeconds32aTimeOut,
const TDesC8 &aDes,
TIntaLength
)

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

Parameters
aStatusThe request status used to contain completion information for the function. On completion, contains a system-wide error code
aTimeOutThe write will terminate after aTimeout microseconds if the data requested has not been sent. A KErrTimedOut status is returned.
aDesA descriptor containing the data to be written to the serial port.
aLengthThe number of bytes to write. This length must be between 0 and the maximum length of the descriptor both included.
Capability
None

WriteCancel ( )

IMPORT_C TIntWriteCancel()

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
None