<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-DB6AF6D3-38B6-51EF-A830-388961A3BF04"><title>How to Write a Serial Protocol Module: Tutorial</title><shortdesc>This topic gives a summary of the APIs that must be implemented for a new Serial Protocol Module. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><steps id="GUID-68872B97-1FC9-58A3-86D3-D7C815CCF215"><step id="GUID-18B80EE7-46D0-58D3-8C2E-361C34AE4EE6"><cmd/><info>Create a new DLL project with a <filepath>.csy</filepath> extension and a <keyword>UID</keyword> 2 of <codeph>0x10000049</codeph>. </info> </step> <step id="GUID-369B15AD-FC60-5B79-B4E8-3EBD8D8B240E"><cmd/><info>Create a class which derives from the <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita"><apiname>CPort</apiname></xref> class. This class implements the Serial service provider. Requests are delivered by the Serial Communications Server to the <codeph>CPort</codeph> class using pure virtual functions. These functions include: </info> <substeps id="GUID-394FEAFC-CEC3-522C-9E3D-943CC8023B4E"><substep id="GUID-0C9B671E-EE13-51E7-86D4-C41859A6AD32"><cmd> <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita#GUID-5CEF7907-E485-3626-8587-53CAC2A06544/GUID-6794366E-3E5F-3ABA-B650-56968B261E89"><apiname>CPort::StartRead()</apiname></xref>, which must be implemented to handle client requests to read data from the port </cmd> <info> <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita#GUID-5CEF7907-E485-3626-8587-53CAC2A06544/GUID-F35F3290-A99A-3FF2-AAFA-240F23D422E4"><apiname>CPort::IPCWrite()</apiname></xref> can be used to send the data to the client </info> </substep> <substep id="GUID-74799819-3C48-543A-BBD1-C9E0109E0FE5"><cmd> <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita#GUID-5CEF7907-E485-3626-8587-53CAC2A06544/GUID-99D433D7-6AFC-3A1D-B53A-AB875CF21D17"><apiname>CPort::StartWrite()</apiname></xref>, which must be implemented to handle client requests to write data to the port </cmd> <info> <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita#GUID-5CEF7907-E485-3626-8587-53CAC2A06544/GUID-479BBBC4-BB04-3C59-A09B-68957FE69A7E"><apiname>CPort::IPCRead()</apiname></xref> can be used to get the data from the client </info> </substep> </substeps> </step> <step id="GUID-DCECA07A-DAA4-5509-AE91-BF57FE06F2C2"><cmd/><info>Create a class which derives from the <xref href="GUID-D8C11F99-7452-35BB-B53E-440968D4C1A3.dita"><apiname>CSerial</apiname></xref> class. This class implements the Serial protocol factory. The <xref href="GUID-D8C11F99-7452-35BB-B53E-440968D4C1A3.dita#GUID-D8C11F99-7452-35BB-B53E-440968D4C1A3/GUID-59F200BD-B75D-3D3C-AE01-FD6B85525B9C"><apiname>CSerial::NewPortL()</apiname></xref> function must return a new instance of the Serial service provider. The <xref href="GUID-D8C11F99-7452-35BB-B53E-440968D4C1A3.dita#GUID-D8C11F99-7452-35BB-B53E-440968D4C1A3/GUID-B53A32A7-8AB0-31D2-ACAA-69DA0EF2DD23"><apiname>CSerial::Info()</apiname></xref> function must return a complete <xref href="GUID-A6E4627A-A3AE-3B64-9E5C-710EE15C5595.dita"><apiname>TSerialInfo</apiname></xref> record with information for the Serial Protocol Module. </info> </step> </steps> <result><p>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 ( <xref href="GUID-6B3CA99B-ABF2-32EA-935D-23AE5AE2C306.dita"><apiname>RCommServ</apiname></xref> and <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RComm</apiname></xref> APIs) to use a serial protocol. In some cases this re-entrant configuration causes a deadlock. </p> <p>A Serial protocol module can avoid deadlock when the following conditions are met: </p> <ul><li id="GUID-C65EE183-6B11-5654-AD1C-21DD7BD9ED57"><p>The serial protocol module never uses code which causes an <codeph>RComm</codeph> request on the same serial protocol module </p> </li> <li id="GUID-C13CEC2A-0203-5A38-AA82-092C2614D63C"><p>The serial protocol module must be in a different thread to the other serial protocol module. </p> </li> </ul> <p>Other tips: </p> <ul><li id="GUID-4FA03E52-C9A2-52B1-804B-76784D43D270"><p>Always call <xref href="GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449.dita#GUID-EF29C1D7-B1E5-370F-AE37-66231A6BE449/GUID-68A206F1-3E5C-3B74-9E83-0EE2E0D4F448"><apiname>RSocketServ::StartProtocol()</apiname></xref> which is asynchronous before calling <xref href="GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0.dita#GUID-D4F08503-F1EF-3531-9C3C-4AF24A6255F0/GUID-3491CE2A-A94D-34E0-B0DD-D476EE3334D7"><apiname>RSocket::Open()</apiname></xref> which is synchronous, but may cause an <codeph>RComm</codeph> class to be instantiated. </p> </li> <li id="GUID-88A8DD6F-8620-596A-AB8E-37C7B4890DD8"><p>The Serial protocol module must correctly implement the <xref href="GUID-5CEF7907-E485-3626-8587-53CAC2A06544.dita#GUID-5CEF7907-E485-3626-8587-53CAC2A06544/GUID-6C3DE0B7-5B94-3998-A0E5-B17124986A33"><apiname>CPort::Destruct()</apiname></xref> function. A standard C++ destructor must run synchronously, so <codeph>CPort::Destruct()</codeph> 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 <codeph>RComm</codeph> object must do this asynchronously. </p> </li> </ul> </result> </taskbody><related-links><link href="GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita"><linktext> How