RComm Class Reference

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.

Inherits from

Public Member Functions
RComm ()
IMPORT_C void Break ( TRequestStatus &, TTimeIntervalMicroSeconds32 )
IMPORT_C TInt BreakCancel ()
IMPORT_C TInt Cancel ()
IMPORT_C TInt Caps ( TDes8 &)
IMPORT_C void Close ()
IMPORT_C TInt Config ( TDes8 &)
IMPORT_C TInt DebugState ( TCommDebugInfo &)
IMPORT_C TInt GetFlowControlStatus ( TFlowControl &)
IMPORT_C TInt GetRole ( TCommRole &)
IMPORT_C TInt Mode ( TCommServerConfig &)
IMPORT_C void NotifyBreak ( TRequestStatus &)
IMPORT_C TInt NotifyBreakCancel ()
IMPORT_C void NotifyConfigChange ( TRequestStatus &, TDes8 &)
IMPORT_C TInt NotifyConfigChangeCancel ()
IMPORT_C void NotifyDataAvailable ( TRequestStatus &)
IMPORT_C TInt NotifyDataAvailableCancel ()
IMPORT_C void NotifyFlowControlChange ( TRequestStatus &, TFlowControl &)
IMPORT_C TInt NotifyFlowControlChangeCancel ()
IMPORT_C void NotifyOutputEmpty ( TRequestStatus &)
IMPORT_C TInt NotifyOutputEmptyCancel ()
IMPORT_C void NotifySignalChange ( TRequestStatus &, TUint &, TUint )
IMPORT_C TInt NotifySignalChangeCancel ()
IMPORT_C TInt Open ( RCommServ &, const TDesC &, TCommAccess )
IMPORT_C TInt Open ( RCommServ &, const TDesC &, TCommAccess , TCommRole )
IMPORT_C void OpenWhenAvailable ( TRequestStatus &, RCommServ &, const TDesC &)
IMPORT_C void OpenWhenAvailable ( TRequestStatus &, RCommServ &, const TDesC &, TCommRole )
IMPORT_C void OpenWhenAvailableCancel ()
IMPORT_C TInt QueryReceiveBuffer ()
IMPORT_C void Read ( TRequestStatus &, TDes8 &)
IMPORT_C void Read ( TRequestStatus &, TDes8 &, TInt )
IMPORT_C void Read ( TRequestStatus &, TTimeIntervalMicroSeconds32 , TDes8 &)
IMPORT_C void Read ( TRequestStatus &, TTimeIntervalMicroSeconds32 , TDes8 &, TInt )
IMPORT_C TInt ReadCancel ()
IMPORT_C void ReadOneOrMore ( TRequestStatus &, TDes8 &)
IMPORT_C TInt ReceiveBufferLength ()
IMPORT_C TInt ResetBuffers ( TUint )
IMPORT_C TInt SetAccessMode ( TCommAccess )
IMPORT_C TInt SetConfig (const TDesC8 &)
IMPORT_C TInt SetMode (const TCommServerConfig &)
IMPORT_C TInt SetReceiveBufferLength ( TInt )
void SetSignals ( TUint , TUint )
IMPORT_C TInt SetSignalsToMark ( TUint )
IMPORT_C TInt SetSignalsToSpace ( TUint )
IMPORT_C TUint Signals ( TUint )
IMPORT_C void Write ( TRequestStatus &, const TDesC8 &)
IMPORT_C void Write ( TRequestStatus &, const TDesC8 &, TInt )
IMPORT_C void Write ( TRequestStatus &, TTimeIntervalMicroSeconds32 , const TDesC8 &)
IMPORT_C void Write ( TRequestStatus &, TTimeIntervalMicroSeconds32 , const TDesC8 &, TInt )
IMPORT_C TInt WriteCancel ()
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
Private Attributes
TPtr8 iFlowNotification
TPtr8 iSignalsNotification

Constructor & Destructor Documentation

RComm()

IMPORT_C RComm ( )

Constructor

Member Functions Documentation

Break(TRequestStatus &, TTimeIntervalMicroSeconds32)

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
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TTimeIntervalMicroSeconds32 aTime A timed break period in microseconds.

BreakCancel()

IMPORT_C TInt BreakCancel ( )
Cancels any pending Break() operations.
capability
None

Cancel()

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
None

Caps(TDes8 &)

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
None

Parameters

TDes8 & aCaps On 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.

Close()

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.
capability
None

Config(TDes8 &)

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
None

Parameters

TDes8 & aConfig On return, a TCommConfig package buffer holding the configuration settings

DebugState(TCommDebugInfo &)

IMPORT_C TInt DebugState ( TCommDebugInfo & )

Debug state information. Only implemented for DEBUG builds.

Parameters

TCommDebugInfo &

GetFlowControlStatus(TFlowControl &)

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
None

Parameters

TFlowControl & aFlowControl On return, flow control status

GetRole(TCommRole &)

IMPORT_C TInt GetRole ( TCommRole & aRole ) const

Gets current DCE/DTE role.

capability
None

Parameters

TCommRole & aRole On return, current DCE/DTE role

Mode(TCommServerConfig &)

IMPORT_C TInt Mode ( TCommServerConfig & aConfig ) const

Gets server buffering mode.

capability
None

Parameters

TCommServerConfig & aConfig A packaged TCommServerConfigV01 structure which will hold the required information on return.

NotifyBreak(TRequestStatus &)

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
None

Parameters

TRequestStatus & aStatus On return, system wide error code for asynchronous function.

NotifyBreakCancel()

IMPORT_C TInt NotifyBreakCancel ( ) const
Cancels a NotifyBreak() request.
capability
None

NotifyConfigChange(TRequestStatus &, TDes8 &)

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
None

Parameters

TRequestStatus & aStatus On return, system wide error code for asynchronous function.
TDes8 & aNewConfig On completion, a packaged TCommNotificationV01.

NotifyConfigChangeCancel()

IMPORT_C TInt NotifyConfigChangeCancel ( ) const
Cancels a NotifyConfigChange() request.
capability
None

NotifyDataAvailable(TRequestStatus &)

IMPORT_C void NotifyDataAvailable ( 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.

capability
None

Parameters

TRequestStatus & aStatus On return, a system wide error code.

NotifyDataAvailableCancel()

IMPORT_C TInt NotifyDataAvailableCancel ( ) const
Cancels a NotifyDataAvailable() request.
capability
None

NotifyFlowControlChange(TRequestStatus &, TFlowControl &)

IMPORT_C void NotifyFlowControlChange ( TRequestStatus & aStatus,
TFlowControl & aFlowControl
)

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

capability
None

Parameters

TRequestStatus & aStatus On return, system wide error code for asynchronous function.
TFlowControl & aFlowControl On completion, new flow control status.

NotifyFlowControlChangeCancel()

IMPORT_C TInt NotifyFlowControlChangeCancel ( ) const
Cancels a NotifyFlowControlChange() request.
capability
None

NotifyOutputEmpty(TRequestStatus &)

IMPORT_C void NotifyOutputEmpty ( TRequestStatus & aStatus ) const

Notifies the client when the transmit buffer is emptied.

capability
None

Parameters

TRequestStatus & aStatus On return, system wide error code for asynchronous function.

NotifyOutputEmptyCancel()

IMPORT_C TInt NotifyOutputEmptyCancel ( ) const
Cancels a NotifyOutputEmpty() request.
capability
None

NotifySignalChange(TRequestStatus &, TUint &, TUint)

IMPORT_C void NotifySignalChange ( TRequestStatus & aStatus,
TUint & aSignals,
TUint aSignalMask = 0x3F
)

Notifies the client when one of the signals change.

capability
None

Parameters

TRequestStatus & aStatus Asynchronous completion status
TUint & aSignals On 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).
TUint aSignalMask = 0x3F Bitmaks of the signals to monitor. The default is all signals. See also KSignalDTEOutputs and KSignalDTEInputs.

NotifySignalChangeCancel()

IMPORT_C TInt NotifySignalChangeCancel ( ) const
Cancels a NotifySignalChange() request.
capability
None

Open(RCommServ &, const TDesC &, TCommAccess)

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

Parameters

RCommServ & aServer The comms server session.
const TDesC & aName The name of the port (e.g. "COMM::0")
TCommAccess aMode The mode in which the port is opened. There is no default.

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

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

Parameters

RCommServ & aServer The comms server session
const TDesC & aName The name of the port
TCommAccess aMode The mode in which the port is opened. There is no default.
TCommRole aRole DTE/DCE role

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

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

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function.
RCommServ & aServer The comms server session.
const TDesC & aName The name of the port.

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

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
Dependent

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function.
RCommServ & aServer The comms server session.
const TDesC & aName The name of the port.
TCommRole aRole Preferred role (DTE or DCE).

OpenWhenAvailableCancel()

IMPORT_C void OpenWhenAvailableCancel ( )
Cancels an OpenWhenAvailable() pending request.
capability
None

QueryReceiveBuffer()

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

capability
None

Read(TRequestStatus &, TDes8 &)

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.

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.

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TDes8 & aDes A buffer to store the incoming data. The maximum length of the descriptor is the number of bytes to be read.

Read(TRequestStatus &, TDes8 &, TInt)

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.

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.

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TDes8 & aDes A buffer to store the incoming data.
TInt aLength An explicit length of data to be read. This length must be between 0 and the MaxLength of the descriptor both included.

Read(TRequestStatus &, TTimeIntervalMicroSeconds32, TDes8 &)

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.

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.

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TTimeIntervalMicroSeconds32 aTimeOut The time-out value for reads in microseconds. If data fails to arrive before the specified number of microseconds, a KErrTimedOut status is returned.
TDes8 & aDes A buffer to store the incoming data. The maximum length of the descriptor is the default for the number of bytes to be read.

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

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.

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.

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TTimeIntervalMicroSeconds32 aTimeOut The time-out value for reads in microseconds. If data fails to arrive before the specified number of microseconds, a KErrTimedOut status is returned.
TDes8 & aDes A buffer to store the incoming data.
TInt aLength An explicit length of data to be read This length must be between 0 and the MaxLength of the descriptor both included.

ReadCancel()

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
None

ReadOneOrMore(TRequestStatus &, TDes8 &)

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.

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.

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code
TDes8 & aDes A 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.

ReceiveBufferLength()

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
None

ResetBuffers(TUint)

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
None

Parameters

TUint aFlags = ( KCommResetRx | KCommResetTx ) KCommResetRx to reset the receive buffer KCommResetTx to reset the transmit buffer

SetAccessMode(TCommAccess)

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.

capability
None

Parameters

TCommAccess aNewMode The value of the new port mode, either ECommShared or ECommExclusive.

SetConfig(const TDesC8 &)

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

capability
None

Parameters

const TDesC8 & aConfig New configuration settings packaged in a TCommConfig

SetMode(const TCommServerConfig &)

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
None

Parameters

const TCommServerConfig & aConfig A packaged TCommServerConfigV01 structure to be set.

SetReceiveBufferLength(TInt)

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
None

Parameters

TInt aLength The required size of the receive and transmit buffers in bytes.

SetSignals(TUint, TUint)

void SetSignals ( TUint aSetMask,
TUint aClearMask
) [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

TUint aSetMask Set the handshaking lines in the mask.
TUint aClearMask Clear the handshaking lines in the mask.

SetSignalsToMark(TUint)

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
None

Parameters

TUint aSignalMask Bitmask of handshaking lines

SetSignalsToSpace(TUint)

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
None

Parameters

TUint aSignalMask Bitmask of handshaking lines

Signals(TUint)

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
None

Parameters

TUint aSignalMask = 0x3F Bitmask 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.

Write(TRequestStatus &, const TDesC8 &)

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

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
const TDesC8 & aDes A descriptor containing the data to be written to the serial port.

Write(TRequestStatus &, const TDesC8 &, TInt)

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

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
const TDesC8 & aDes A descriptor containing the data to be written to the serial port.
TInt aLength The number of bytes to write. This length must be between 0 and the length of the descriptor both included.

Write(TRequestStatus &, TTimeIntervalMicroSeconds32, const TDesC8 &)

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

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code.
TTimeIntervalMicroSeconds32 aTimeOut The write will terminate after aTimeout microseconds if the data requested has not been sent. A KErrTimedOut status is returned.
const TDesC8 & aDes A descriptor containing the data to be written to the serial port.

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

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

capability
None

Parameters

TRequestStatus & aStatus The request status used to contain completion information for the function. On completion, contains a system-wide error code
TTimeIntervalMicroSeconds32 aTimeOut The write will terminate after aTimeout microseconds if the data requested has not been sent. A KErrTimedOut status is returned.
const TDesC8 & aDes A descriptor containing the data to be written to the serial port.
TInt aLength The number of bytes to write. This length must be between 0 and the maximum length of the descriptor both included.

WriteCancel()

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
None

Member Data Documentation

TPtr8 iFlowNotification

TPtr8 iFlowNotification [private]

TPtr8 iSignalsNotification

TPtr8 iSignalsNotification [private]