Class CPort

class CPort : public CObject;

Description

Base class for implementations of serial protocol module ports. Its functions are called by the comms server in response to client calls to RComm.

The class implements CObject to obtain reference counting behaviour. The reference count is incremented when a port is first created, and, for ports in shared mode, on every later opening.

CPort is an abstract class which defines many pure virtual functions which derived classes must implement. Most of these pure virtual functions correspond to the client interface of the RComm class.

Created when the first client does an Open request passing its name. Destroyed only when it deletes itself (following a call to Destruct).

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CObject - Implements reference counting to track concurrent references to itself

• CPort - Base class for implementations of serial protocol module ports

Members

Defined in CPort:
Break(), BreakCancel(), BreakCompleted(), BreakNotifyCompleted(), CPort(), CPort_Reserved1(), Close(), ConfigChangeCompleted(), Destruct(), FlowControlChangeCompleted(), FreeMemory(), GetCaps(), GetConfig(), GetFlowControlStatus(), GetReceiveBufferLength(), GetRole(), GetServerConfig(), GetSignals(), IPCRead(), IPCWrite(), NotifyBreak(), NotifyBreakCancel(), NotifyConfigChange(), NotifyConfigChangeCancel(), NotifyDataAvailable(), NotifyDataAvailableCancel(), NotifyDataAvailableCompleted(), NotifyFlowControlChange(), NotifyFlowControlChangeCancel(), NotifyOutputEmpty(), NotifyOutputEmptyCancel(), NotifyOutputEmptyCompleted(), NotifySignalChange(), NotifySignalChangeCancel(), QueryReceiveBuffer(), ReadCancel(), ReadCompleted(), ResetBuffers(), SetConfig(), SetReceiveBufferLength(), SetRole(), SetServerConfig(), SetSignalsToMark(), SetSignalsToSpace(), SignalChangeCompleted(), StartRead(), StartWrite(), TAccess, WriteCancel(), WriteCompleted(), ~CPort()

Inherited from CBase:
Delete(), operator new()

Inherited from CObject:
AccessCount(), Dec(), Extension_(), FullName(), Inc(), Name(), Open(), Owner(), SetName(), SetNameL(), SetOwner(), UniqueID()

IMPORT_C CPort();

Description

Default constructor. Derived classes should implement a NewL() function to perform their two-phase construction.

See also:

• TSerialNewL

virtual IMPORT_C ~CPort();

Description

Destructor.

Closes the owner (which is our CSerial) and removes any timers.

Derived classes can implement the destructor but must only call synchronous functions within it. Any cleanup requiring asynchronous operations must be done in Destruct().

IMPORT_C TInt IPCRead(const TAny *aPtr, TDes8 &aDes, TInt aOffset=0) const;

Description

Reads data from the client's (the user of the port's) address space.

The client address space pointer is obtained from the aClientBuffer argument to StartRead().

Note:

This function is normally called by the CSY

Note:

Used as part of RComm::Write

Parameters

const TAny *aPtr Not Used. The client data is now obtained from iBlockedWrite. TDes8 &aDes A descriptor (8 bit variant) into which the result of the client address space read operation will be stored TInt aOffset The read offset from the start of the client's descriptor data.

Return value

TInt TInt KErrNone: success KErrNotReady: there is no read or write request outstanding KErrBadDescriptor: the client's descriptor is not valid.

IMPORT_C TInt IPCWrite(const TAny *aPtr, const TDesC8 &aDes, TInt aOffset=0) const;

Description

Writes into the client's (the user of the port's) address space.

The client address space pointer is obtained from the aClientBuffer argument to StartWrite().

Note:

This function is normally called by the CSY

Note:

Used as part of RComm::Read

Parameters

const TAny *aPtr Client address space pointer const TDesC8 &aDes A descriptor (8 bit variant) into which the result of the client address space read will be stored TInt aOffset The offset from aPtr at which to start reading

Return value

TInt TInt KErrNone: success KErrNotReady: there is no read or write request outstanding KErrBadDescriptor: the client's descriptor is not valid.

IMPORT_C void ReadCompleted(TInt anError);

Description

Tells the comms server that a read request initiated through StartRead() is complete.

The comms server will then notify the client that its read request is complete.

Called by C32 server or CSY.

Parameters

TInt anError Return code to be passed back to the client through its TRequestStatus argument.

IMPORT_C void WriteCompleted(TInt anError);

Description

Tells the comms server that a write request initiated through StartWrite() is complete.

The comms server will then notify the client that its write request is complete.

Called by C32 server or CSY.

Parameters

TInt anError Return code to be passed back to the client through its TRequestStatus argument.

IMPORT_C void BreakCompleted(TInt anError);

Description

Tells the comms server that a break request initiated through Break() is complete.

The comms server will then notify the client that its break request is complete.

Called by C32 server or CSY.

Parameters

TInt anError Return code to be passed back to the client through its TRequestStatus argument.

virtual IMPORT_C void Close();

Description

Closes the port.

The base class implements CObject::Close() to handle reference counting on the port. It decrements the reference count, and calls Destruct() if the count is 0.

IMPORT_C void SignalChangeCompleted(const TUint &aSignals, TInt anError);

Description

Tells the comms server that a request initiated through NotifySignalChange() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

const TUint &aSignals The new signals value to pass to the client. TInt anError An error code.

IMPORT_C void ConfigChangeCompleted(const TDesC8 &aNewConfig, TInt anError);

Description

Tells the comms server that a request initiated through NotifyConfigChange() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

const TDesC8 &aNewConfig Configuration value to pass to client TInt anError Error code

IMPORT_C void FlowControlChangeCompleted(const TFlowControl &aFlowControl, TInt anError);

Description

Tells the comms server that a request initiated through NotifyFlowControlChange() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

const TFlowControl &aFlowControl Flow control to pass to client TInt anError Error code

IMPORT_C void BreakNotifyCompleted(TInt anError);

Description

Tells the comms server that a request initiated through NotifyBreak() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

TInt anError Error code

IMPORT_C void NotifyDataAvailableCompleted(TInt anError);

Description

Tells the comms server that a request initiated through NotifyDataAvailable() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

TInt anError Error code

IMPORT_C void NotifyOutputEmptyCompleted(TInt anError);

Description

Tells the comms server that a request initiated through NotifyOutputEmpty() is complete.

The comms server will then notify the client that its request is complete.

Called by the CSY module.

Parameters

TInt anError Error code

virtual void Destruct()=0;

Description

Called by manager when access count is 0 - CSY port must call 'delete this'.

Specifies the protocol for port destruction. It is called by the comms server when the last client-side reference to a CPort object has been closed and the CPort must be deleted. The comms server will not delete a CPort other than by calling Destruct().

The implementation should perform any asynchronous shutdown operations on its own resources and, when these operations have completed, should delete this.

virtual void StartRead(const TAny *aClientBuffer, TInt aLength)=0;

Description

Specifies the protocol for reading from the port. It is called by the comms server in response to a RComm::Read() or RComm::ReadOneOrMore() request from the client.

A negative value for aLength is used to flag that the read request was from RComm::ReadOneOrMore() rather than from RComm::Read(). The maximum length of data to be read is the absolute value of aLength.

The implementation should use IPCWrite() to write the data to the client's buffer. When all the data has been read, the function should call ReadCompleted().

Parameters

const TAny *aClientBuffer Pointer into client address space to the descriptor containing the client's buffer TInt aLength The amount of data to be read

virtual void ReadCancel()=0;

Description

Cancel a pending read.

Specifies the protocol for cancelling reading from the port. It is called by the comms server in response to a RComm::ReadCancel() request from the client or when the iReadTimer timer expires.

The implementation should abort any processing which was taking place as a result of the read request. Do not call ReadCompleted().

virtual TInt QueryReceiveBuffer(TInt &aLength) const=0;

Description

Get the size of the receive buffer from the real serial port.

Specifies a protocol for requesting the number of bytes that are currently waiting in the port's receive buffer. It is called by the comms server in response to a RComm::QueryReceiveBuffer() request from the client.

Parameters

TInt &aLength On return, the number of bytes currently waiting to be read from the receive buffer.

Return value

TInt A system wide error code.

virtual void ResetBuffers(TUint aFlags)=0;

Description

reset Tx and Rx buffers

Specifies a protocol for resetting the receive and/or transmit buffers to zero length. It is called by the comms server in response to a RComm::ResetBuffers() request from the client.

Parameters

TUint aFlags Bitmask of the following flags: KCommResetRx to reset the receive buffer; KCommResetTx to reset the transmit buffer

virtual void StartWrite(const TAny *aClientBuffer, TInt aLength)=0;

Description

Queue a write - called by CPort when client wants to write.

Specifies the protocol for writing to the port. It is called by the comms server in response to a RComm::Write() request from the client.

The implementation should use IPCRead() to get the data to write from the client's buffer. When all the data has been written, the function should call WriteCompleted().

Parameters

const TAny *aClientBuffer Pointer into client address space to the descriptor containing the client's buffer TInt aLength The amount of data to be written

virtual void WriteCancel()=0;

Description

Cancel a pending write.

Specifies the protocol for cancelling writing to the port. It is called by the comms server in response to a RComm::WriteCancel() request from the client.

The implementation should abort any processing which was taking place as a result of the write request. Do not call WriteCompleted().

virtual void Break(TInt aTime)=0;

Description

Queue a break.

Specifies the protocol for setting a break condition at the port. It is called by the comms server in response to a RComm::Break() request from the client.

When the break is complete, the function should call BreakCompleted().

Parameters

TInt aTime Time period to break for in microseconds

virtual void BreakCancel()=0;

Description

Cancel a pending break.

Specifies the protocol for cancelling a break request. It is called by the comms server in response to a RComm::BreakCancel() request from the client.

The implementation should abort any processing which was taking place as a result of the break request. Do not call BreakCompleted().

virtual TInt GetConfig(TDes8 &aPackage) const=0;

Description

Pass a config request - return in descriptor.

Specifies a protocol for getting the current configuration of the serial port. It is called by the comms server in response to a RComm::GetConfig() request from the client.

Parameters

TDes8 &aPackage A packaged TCommConfig buffer, set on return to the current configuration of the serial port

Return value

TInt A system wide error code

virtual TInt SetConfig(const TDesC8 &aPackage)=0;

Description

Set config with package in the descriptor.

Specifies a protocol for setting the configuration of the port. It is called by the comms server in response to a RComm::SetConfig() request from the client.

Parameters

const TDesC8 &aPackage A packaged TCommConfig buffer holding the new configuration values

Return value

TInt A system error code

virtual TInt SetServerConfig(const TDesC8 &aPackage)=0;

Description

Set the port to use partial reads/writes.

Specifies a protocol for setting the buffer mode. It is called by the comms server in response to a RComm::SetMode() request from the client.

Parameters

const TDesC8 &aPackage A TCommServerConfig package buffer holding the mode settings

Return value

TInt A system-wide error code

virtual TInt GetServerConfig(TDes8 &aPackage)=0;

Description

Get the server configs from the CSY.

Specifies a protocol for getting the buffer mode. It is called by the comms server in response to a RComm::Mode() request from the client.

Parameters

TDes8 &aPackage A TCommServerConfig package buffer that, on return, holds the current buffer mode settings

Return value

TInt A system error code

virtual TInt GetCaps(TDes8 &aPackage)=0;

Description

Read capabilities from the driver.

Specifies a protocol for getting the port capabilities. It is called by the comms server in response to a RComm::Caps() request from the client.

Parameters

TDes8 &aPackage A TCommCaps package buffer that, on return, holds the port capabilities

Return value

TInt A system error code

virtual TInt GetSignals(TUint &aSignals)=0;

Description

Get the status of the signal pins.

Specifies a protocol for getting the status of the serial port control lines. It is called by the comms server in response to a RComm::GetSignals() request from the client.

Parameters

TUint &aSignals An integer with the bits set to reflect the status of the handshaking lines.

Return value

TInt A system error code

virtual TInt SetSignalsToMark(TUint aSignals)=0;

Description

Set selected signals to high (logical 1).

Specifies a protocol for setting serial port control lines. It is called by the comms server in response to a RComm::SetSignals() request from the client.

Parameters

TUint aSignals A bitmask of the handshaking lines to set

Return value

TInt A system error code

virtual TInt SetSignalsToSpace(TUint aSignals)=0;

Description

Set selected signals to low (logical 0).

Specifies a protocol for clearing serial port control lines. It is called by the comms server in response to a RComm::SetSignals() request from the client.

Parameters

TUint aSignals A bitmask of the handshaking lines to clear

Return value

TInt A system error code

virtual TInt GetReceiveBufferLength(TInt &aLength) const=0;

Description

Get size of Tx and Rx buffer.

Specifies a protocol for requesting the size of the serial port buffers. It is called by the comms server in response to a RComm::ReceiveBufferLength() request from the client.

Parameters

TInt &aLength The current size of the serial port buffers in bytes

Return value

TInt A system error code

virtual TInt SetReceiveBufferLength(TInt aLength)=0;

Description

Set size of Tx and Rx buffer.

Specifies a protocol for setting the size of the serial port buffers. It is called by the comms server in response to a RComm::SetReceiveBufferLength() request from the client.

Parameters

TInt aLength Requested size of the serial port buffers in bytes

Return value

TInt A system error code

virtual void FreeMemory();

Description

Specifies a protocol by which the comms server can request the protocol to release memory. Typically, an implementation may be able to do this by reducing internal buffers.

The default behaviour is to do nothing.

virtual void NotifySignalChange(TUint aSignalMask)=0;

Description

Notify client when the signals change.

Specifies the protocol for setting a signal change notification. It is called by the comms server in response to a RComm::NotifySignalChange() request from the client.

Parameters

TUint aSignalMask Signal mask passed by client

virtual void NotifySignalChangeCancel()=0;

Description

Cancel an outstanding signal change notification.

Specifies the protocol for cancelling a signal change notification. It is called by the comms server in response to a RComm::NotifySignalChangeCancel() request from the client.

virtual void NotifyConfigChange()=0;

Description

Notify client when the configation changes.

Specifies the protocol for setting a configuration change notification. It is called by the comms server in response to a RComm::NotifyConfigChange() request from the client.

virtual void NotifyConfigChangeCancel()=0;

Description

Cancel an outstanding config change notification.

Specifies the protocol for cancelling a configuration change notification. It is called by the comms server in response to a RComm::NotifyConfigChangeCancel() request from the client.

virtual void NotifyFlowControlChange()=0;

Description

Notify client when the flow control changes.

Specifies the protocol for setting a flow control change notification. It is called by the comms server in response to a RComm::NotifyFlowControlChange() request from the client.

virtual void NotifyFlowControlChangeCancel()=0;

Description

Cancel an outstanding flow control change notification.

Specifies the protocol for cancelling a flow control change notification. It is called by the comms server in response to a RComm::NotifyFlowControlChangeCancel() request from the client.

virtual void NotifyBreak()=0;

Description

Notify client when a break occurs.

Specifies the protocol for setting a break notification. It is called by the comms server in response to a RComm::NotifyBreak() request from the client.

virtual void NotifyBreakCancel()=0;

Description

Cancel an outstanding break notification.

Specifies the protocol for cancelling a break notification. It is called by the comms server in response to a RComm::NotifyBreakCancel() request from the client.

virtual void NotifyDataAvailable()=0;

Description

Notify client when data is available.

Specifies the protocol for setting a data available notification. It is called by the comms server in response to a RComm::NotifyDataAvailable() request from the client.

virtual void NotifyDataAvailableCancel()=0;

Description

Cancel an outstanding data availalbe notification.

Specifies the protocol for cancelling a data available notification. It is called by the comms server in response to a RComm::NotifyDataAvailableCancel() request from the client.

virtual void NotifyOutputEmpty()=0;

Description

Notify client when output buffer is empty.

Specifies the protocol for setting a transmit buffer empty notification. It is called by the comms server in response to a RComm::NotifyOutputEmpty() request from the client.

virtual void NotifyOutputEmptyCancel()=0;

Description

Cancel an outstanding output empty notification.

Specifies the protocol for cancelling a transmit buffer empty notification. It is called by the comms server in response to a RComm::NotifyOutputEmptyCancel() request from the client.

virtual TInt GetFlowControlStatus(TFlowControl &aFlowControl)=0;

Description

Get the flow control status.

Gets flow control status. It is called by the comms server in response to a RComm::SetMode() request from the client.

Parameters

TFlowControl &aFlowControl Flow control status to return to the client

Return value

TInt A system-wide error code

virtual TInt GetRole(TCommRole &aRole)=0;

Description

Get the role of this port unit.

Gets DCE/DTE role. It is called by the comms server in response to a RComm::GetRole() request from the client.

Parameters

TCommRole &aRole On return, DCE/DTE role to return to the client

Return value

TInt A system-wide error code

virtual TInt SetRole(TCommRole aRole)=0;

Description

Set the role of this port unit.

Sets DCE/DTE role. It is called by the comms server in response to a RComm::Open() request from the client.

Parameters

TCommRole aRole DCE/DTE role

Return value

TInt A system-wide error code

private: virtual IMPORT_C void CPort_Reserved1();

Description

Reserved virtual function.

typedef TCommAccess CPort::TAccess;

Description