Collapse all Symbian^3 Product Developer Library

How to Write a Serial Protocol Module: Tutorial

This topic gives a summary of the APIs that must be implemented for a new Serial Protocol Module.

Create a new DLL project with a .csy extension and a UID 2 of 0x10000049.
Create a class which derives from the CPort class. This class implements the Serial service provider. Requests are delivered by the Serial Communications Server to the CPort class using pure virtual functions. These functions include:
1. CPort::StartRead(), which must be implemented to handle client requests to read data from the port
  CPort::IPCWrite() can be used to send the data to the client
2. CPort::StartWrite(), which must be implemented to handle client requests to write data to the port
  CPort::IPCRead() can be used to get the data from the client
Create a class which derives from the CSerial class. This class implements the Serial protocol factory. The CSerial::NewPortL() function must return a new instance of the Serial service provider. The CSerial::Info() function must return a complete TSerialInfo record with information for the Serial Protocol Module.

The flexibility of the Comms Architecture allows a Serial protocol module to use the Socket API to use a protocol stack and the protocol stack then uses the Serial Communications Server API ( RCommServ and RComm APIs) to use a serial protocol. In some cases this re-entrant configuration causes a deadlock.

A Serial protocol module can avoid deadlock when the following conditions are met:

The serial protocol module never uses code which causes an RComm request on the same serial protocol module
The serial protocol module must be in a different thread to the other serial protocol module.

Other tips:

Always call RSocketServ::StartProtocol() which is asynchronous before calling RSocket::Open() which is synchronous, but may cause an RComm class to be instantiated.
The Serial protocol module must correctly implement the CPort::Destruct() function. A standard C++ destructor must run synchronously, so CPort::Destruct() allows the Serial protocol module to complete asynchronous operations during the close of the port. For example, a Serial protocol module that needs to close an RComm object must do this asynchronously.

Parent topic: Serial Protocol Modules (CSYs) Developer Tutorial

Related concepts

How to Configure Multithreaded C32 Serial Comms: Tutorial