用PDD、BLM和MTX诱导化疗晚期头颈部癌——无效--《中国放射肿瘤学》1988年03期
用PDD、BLM和MTX诱导化疗晚期头颈部癌——无效
【摘要】：正 诱导化疗对Ⅳ期头颈部癌的治疗是否有价值,各个文献报道不同。从理论上讲,在放疗或手术改变血供前,使用化疗药物最大限度地杀伤肿瘤细胞,有利于随后的局部治疗,并可减少局部治疗野外的微小病灶转移。 本文报道用诱导化疗治疗70例患者,原发于不同部位,N_3占70％(49例)的Ⅳ期头颈部癌的非随机研究结果,患者平均年龄53岁,男65例、女
【关键词】：
【正文快照】：
诱导化疗对W期头颈部癌的治疗是否有价值,各个文献报道不同。从理论上讲,在放疗或手术改变血供前,使用化疗药物最大限度地杀伤肿瘤细胞,有利于随后的局部治疗,并可减少局部治疗野外的微小病灶转移。 本文报道用诱导化疗治疗70例患者,原发于不同部位,N.占70%(49例)的F期头颈部
欢迎：、、)
支持CAJ、PDF文件格式，仅支持PDF格式
【相似文献】
中国期刊全文数据库
张书怡;陈永辉;;[J];齐齐哈尔医学院学报;2011年12期
张鑫;李可竹;程璐;;[J];中国科技信息;2011年14期
陶华;陆进成;李枫;;[J];中国现代医药杂志;2011年06期
罗金红;林昀;周俊;李琦;林根来;高勇;;[J];肿瘤;2011年06期
孙志华;郑红敏;张凌云;;[J];现代肿瘤医学;2011年07期
王伟;周晓;戴捷;陈森林;肖腾飞;汪安兰;李俊军;;[J];中华肿瘤防治杂志;2011年04期
马静静;张云波;赵美红;宋玉秀;赵玉华;杜静波;;[J];安徽医药;2011年10期
周丽文;梁少环;何梅;;[J];医学理论与实践;2011年15期
何云燕;罗建明;蒋玉凤;;[J];重庆医学;2011年23期
曹浩;叶茂昌;李容新;王来平;李黎丽;马骏;;[J];口腔颌面外科杂志;2011年04期
中国重要会议论文全文数据库
徐鹭英;潘建基;吴君心;潘才柱;张喻;林少俊;杨凌;陈传本;张春;;[A];中华医学会放射肿瘤治疗学分会六届二次暨中国抗癌协会肿瘤放疗专业委员会二届二次学术会议论文集[C];2009年
罗伟;余湛;张钦华;周琦超;康德华;黄绍敏;卢泰祥;邓小武;马骏;刘孟忠;;[A];中华医学会放射肿瘤治疗学分会六届二次暨中国抗癌协会肿瘤放疗专业委员会二届二次学术会议论文集[C];2009年
谢方云;邹国荣;圾伟汉;亓姝楠;彭苗;李济时;;[A];2007第六届全国放射肿瘤学学术年会论文集[C];2007年
王孝深;胡超苏;章英剑;施伟;王新村;冯炎;;[A];中华医学会放射肿瘤治疗学分会六届二次暨中国抗癌协会肿瘤放疗专业委员会二届二次学术会议论文集[C];2009年
吴润晖;石慧文;张蕊;马洁;;[A];中华医学会第十四次全国儿科学术会议论文汇编[C];2006年
刘宝国;刘松龄;陈荣锐;李明强;张乃嵩;王建军;魏巍;孙俊勇;;[A];第四届中国肿瘤学术大会暨第五届海峡两岸肿瘤学术会议论文集[C];2006年
叶茂昌;陈柯;洪礼琳;武瑾;罗永祥;;[A];中华口腔医学会成立大会暨第六次全国口腔医学学术会议论文汇编[C];1996年
余荣;石安辉;张敏;朱广迎;;[A];2007第六届全国放射肿瘤学学术年会论文集[C];2007年
吴少雄;孙瑞;赵充;崔甜甜;邓美玲;卢泰祥;崔念基;;[A];2007第六届全国放射肿瘤学学术年会论文集[C];2007年
金芳玲;张大海;蔡忠芳;;[A];2009年浙江省放射肿瘤治疗学学术年会论文汇编[C];2009年
中国重要报纸全文数据库
朱温　译;[N];中国医药报;2008年
冯琳;[N];中国医药报;2002年
;[N];医药经济报;2005年
天津市肿瘤医院妇科肿瘤科主任
郝权;[N];健康时报;2007年
钟南山 杨玲 李连弟 高文 石远凯;[N];健康报;2005年
屠规益;[N];健康报;2006年
余志平;[N];中国医药报;2004年
王伦?肖绍文;[N];中国医药报;2007年
辛勇　张先稳;[N];中国中医药报;2004年
本报特约撰稿人
陆志城;[N];医药经济报;2004年
中国博士学位论文全文数据库
徐伟;[D];中国协和医科大学;2002年
孙忠实;[D];山东中医药大学;2011年
高静;[D];山东大学;2005年
陈鸥;[D];吉林大学;2006年
周爱萍;[D];中国协和医科大学;2001年
袁智勇;[D];中国协和医科大学;2005年
吴冠青;[D];中国协和医科大学;1991年
周水洪;[D];浙江大学;2005年
罗克桓;[D];中国协和医科大学;1994年
李妍涵;[D];中国协和医科大学;2001年
中国硕士学位论文全文数据库
徐国增;[D];广西医科大学;2010年
毛振卫;[D];广西医科大学;2010年
孙丕云;[D];广西医科大学;2011年
杜清华;[D];广西医科大学;2012年
李培;[D];河北医科大学;2011年
郑军;[D];新疆医科大学;2011年
周世秋;[D];重庆医科大学;2012年
尼罗帕尔·吐尔逊;[D];新疆医科大学;2007年
曹庆堂;[D];河北医科大学;2005年
冯春晓;[D];广西医科大学;2012年
&快捷付款方式
&订购知网充值卡
400-819-9993
《中国学术期刊（光盘版）》电子杂志社有限公司
同方知网数字出版技术股份有限公司
地址：北京清华大学 84-48信箱 大众知识服务
出版物经营许可证 新出发京批字第直0595号
订购热线：400-819-82499
服务热线：010--
在线咨询：
传真：010-
京公网安备75号PDDK Guide_甜梦文库
PDDK Guide
Phone Driver Development Kit GuidePalmSource ConfidentialCONTRIBUTORS Written by Olivier Naudan, Brian Maas, and Jenny Green. Technical assistance from Mike Spratt, Hervé Fayolle, and Hatem Oueslati.Copyright ? , PalmSource, Inc. and its affiliates. All rights reserved. This technical documentation contains confidential and proprietary information of PalmSource, Inc. (“PalmSource”), and is provided to the licensee (“you”) under the terms of a Nondisclosure Agreement, Product Development Kit license, Software Development Kit license or similar agreement between you and PalmSource. You must use commercially reasonable efforts to maintain the confidentiality of this technical documentation. You may print and copy this technical documentation solely for the permitted uses specified in your agreement with PalmSource. In addition, you may make up to two (2) copies of this technical documentation for archival and backup purposes. All copies of this technical documentation remain the property of PalmSource, and you agree to return or destroy them at PalmSource’s written request. Except for the foregoing or as authorized in your agreement with PalmSource, you may not copy or distribute any part of this technical documentation in any form or by any means without express written consent from PalmSource, Inc., and you may not modify this technical documentation or make any derivative work of it (such as a translation, localization, transformation or adaptation) without express written consent from PalmSource. PalmSource, Inc. reserves the right to revise this technical documentation from time to time, and is not obligated to notify you of any revisions. THIS TECHNICAL DOCUMENTATION IS PROVIDED ON AN “AS IS” BASIS. NEITHER PALMSOURCE NOR ITS SUPPLIERS MAKES, AND EACH OF THEM EXPRESSLY EXCLUDES AND DISCLAIMS TO THE FULL EXTENT ALLOWED BY APPLICABLE LAW, ANY REPRESENTATIONS OR WARRANTIES REGARDING THIS TECHNICAL DOCUMENTATION, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY WARRANTIES IMPLIED BY ANY COURSE OF DEALING OR COURSE OF PERFORMANCE AND ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, ACCURACY, AND SATISFACTORY QUALITY. PALMSOURCE AND ITS SUPPLIERS MAKE NO REPRESENTATIONS OR WARRANTIES THAT THIS TECHNICAL DOCUMENTATION IS FREE OF ERRORS OR IS SUITABLE FOR YOUR USE. TO THE FULL EXTENT ALLOWED BY APPLICABLE LAW, PALMSOURCE, INC. ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, EXEMPLARY OR PUNITIVE DAMAGES OF ANY KIND ARISING OUT OF OR IN ANY WAY RELATED TO THIS TECHNICAL DOCUMENTATION, INCLUDING WITHOUT LIMITATION DAMAGES FOR LOST REVENUE OR PROFITS, LOST BUSINESS, LOST GOODWILL, LOST INFORMATION OR DATA, BUSINESS INTERRUPTION, SERVICES STOPPAGE, IMPAIRMENT OF OTHER GOODS, COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR OTHER FINANCIAL LOSS, EVEN IF PALMSOURCE, INC. OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR IF SUCH DAMAGES COULD HAVE BEEN REASONABLY FORESEEN. PalmSource, the PalmSource logo, BeOS, Graffiti, HandFAX, HandMAIL, HandPHONE, HandSTAMP, HandWEB, HotSync, the HotSync logo, iMessenger, MultiMail, MyPalm, Palm, the Palm logo, the Palm trade dress, Palm Computing, Palm OS, Palm Powered, PalmConnect, PalmGear, PalmGlove, PalmModem, Palm Pack, PalmPak, PalmPix, PalmPower, PalmPrint, Palm.Net, Palm Reader, Palm Talk, Simply Palm and ThinAir are trademarks of PalmSource, Inc. or its affiliates. All other product and brand names may be trademarks or registered trademarks of their respective owners. IF THIS TECHNICAL DOCUMENTATION IS PROVIDED ON A COMPACT DISC, THE SOFTWARE AND OTHER DOCUMENTATION ON THE COMPACT DISC ARE SUBJECT TO THE LICENSE AGREEMENTS ACCOMPANYING THE SOFTWARE AND OTHER DOCUMENTATION.LPhone Driver Development Kit Guide Document Number
January 23, 2004PalmSource, Inc. 1240 Crossman Avenue Sunnyvale, CA 94089 USA PalmSource ConfidentialTable of Contents1 Phone Driver Development Kit Installation 1Requirements . . . . . . . . . . . . . . . . . . . . . . . 1 Installation Procedures . . . . . . . . . . . . . . . . . . . 22 Telephony ArchitectureTelephony Manager Architecture . . . . . Telephony Components . . . . . . . . Tasks and Libraries . . . . . . . . . . Interaction with Handheld Applications. Interaction with the Telephony Task . . Telephony Task Architecture . . . . . . . Component Layers . . . . . . . . . . Dispatch Layer. . . . . . . . . . . . Base Driver . . . . . . . . . . . . . Serial Layer . . . . . . . . . . . . . PDDK Library . . . . . . . . . . . . Phone Drivers . . . . . . . . . . . . Telephony Task Calling Mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.3 .3 .4 .5 .5 .6 .7 .8 .9 .9 10 10 113 Phone Driver User InterfacePreferences Application . . . . Connection Panel . . . . . . . Available Connections List . Edit Connections Form . . . Connection Details Form . . Phone Panel . . . . . . . . . Phone Panel’s Test Button . . Phone Panel’s Details Button. User Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1313 13 14 14 15 16 16 18 194 Phone Driver Development Process21Connecting Your Mobile Phone . . . . . . . . . . . . . . . 21 Testing with Palm OS Simulator . . . . . . . . . . . . . 21 Evaluating Phone Compliance with the Default Driver . . . . 25Phone Driver Development Kit Guide iii PalmSource ConfidentialTesting with the DriverTester Application . . Testing with ROM Applications . . . . . . Writing a Phone Driver . . . . . . . . . . . Modifying the Driver Stationery . . . . . . Writing a Driver Function . . . . . . . . . Testing a Phone Driver . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . Problems with the Default Initialization String Problems with IrDA . . . . . . . . . . . Problems with Timeouts . . . . . . . . . Problems with RS232 Hardware Flow Control Problems with Phone Limitations . . . . .. . . . . . . . . . . .. . . . . . . . . . . .. . . . . . . . . . . .. . . . . . . . . . . .. . . . . . . . . . . .. . . . . . . . . . . .. . . . . . . . . . . .25 27 28 28 30 30 31 31 31 32 32 335 Phone Driver Entry PointAt Telephony Task Initialization . . . . . . . . . . At Phone Panel Initialization . . . . . . . . . . . . When Displaying Details in the Connection Panel. . . When Displaying Details in the Phone Panel . . . . . Others Considerations. . . . . . . . . . . . . . . Initialization String . . . . . . . . . . . . . . . User Interface Guidelines . . . . . . . . . . . . Localization Concerns . . . . . . . . . . . . . Communication While Displaying the Details Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3535 40 44 46 47 47 48 48 496 Writing a Phone Driver FunctionSpecifying the Function Template . . . . Retrieving the Application Parameters . Understanding Typical Processing . . . Using the Base Driver Source Code . . . Setting the Receive Timeout . . . . . . Managing Buffers. . . . . . . . . . . Using Global Variables . . . . . . . . Understanding the Driver Environment . Returning Error Codes . . . . . . . . Understanding the Phone Answer Format Result Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5151 51 52 53 54 54 55 56 56 63 63iv Phone Driver Development Kit Guide PalmSource ConfidentialUnsolicited Strings . . . . . . . . . . . . . . . . . . . 637 Lexical Analyzer GenerationIntroduction . . . . . . . . . . . . Lexical Unit Input File Format . . . . LUD File Example . . . . . . . . Order of Token Definition . . . . . Using Lexical Analyzer . . . . . . . Integration with CodeWarrior for PC LexGen as a Stand Alone . . . . . Using the yyLex Function . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6565 65 67 68 68 68 69 70 70Index71Phone Driver Development Kit Guide v PalmSource Confidentialvi Phone Driver Development Kit Guide PalmSource ConfidentialAbout This DocumentPhone Driver Development Kit Guide is part of the Palm OS? Phone Driver Development Kit. This introduction discusses what materials are included in this document and what conventions are used. This book is intended to be used with Phone Driver Development Kit Reference.What This Document Contains? Chapter 1, “Phone Driver Development Kit Installation,” on page 1 lists all the elements--programs, documents, and materials--required to use the Phone Driver Development Kit (PDDK). It also describes how to install these elements onto your computer. ? Chapter 2, “Telephony Architecture,” on page 3 describes the components of the Telephony Manager and the Telephony Task, and discusses how they interact with applications and phone drivers. ? Chapter 3, “Phone Driver User Interface,” on page 13 describes the user interface rela that is, it describes the configuration panels that phone drivers use to interact with users. ? Chapter 4, “Phone Driver Development Process,” on page 21 explains step-by-step how to develop a phone driver. It explains how to write a phone driver using the stationery, discusses what must be changed, and explains how to test a phone driver. ? Chapter 5, “Phone Driver Entry Point,” on page 35 describes how the phone driver is initialized, parameterized, and called from the Connection panel and the Phone panel. ? Chapter 6, “Writing a Phone Driver Function,” on page 51 describes how to write a phone driver function which responds to a Telephony Manager call.Phone Driver Development Kit Guide vii PalmSource ConfidentialAbout This Document Conventions Used in This Book? Chapter 7, “Lexical Analyzer Generation,” on page 65 describes how to use the Lexical Analyzer Generator tool for parsing AT commands.Conventions Used in This BookThis document uses the following typographical conventions: This style... fixed width font fixed width underline bold blue and underlined xxx or XXX Is used for... Code elements such as function, structure, field, bitfield. Emphasis (for code elements). Emphasis (for other elements). Hot links. Used as a “wildcard” to indicate missing letters. For example, kTelXXX is considered a match for any constant starting with the characters kTel.Additional Resources? Documentation PalmSource publishes its latest versions of this and other documents for Palm OS developers at /dev/support/docs/ ? Training PalmSource and its partners host training classes for Palm OS developers. For topics and schedules, check /dev/training ? Knowledge Base The Knowledge Base is a fast, web-based database of technical information. Search for frequently asked questionsviii Phone Driver Development Kit Guide PalmSource ConfidentialAbout This Document Additional Resources(FAQs), sample code, white papers, and the development documentation at /dev/support/kb/Phone Driver Development Kit Guide ix PalmSource ConfidentialAbout This Document Additional Resourcesx Phone Driver Development Kit Guide PalmSource Confidential1Phone Driver Development Kit InstallationThe Phone Driver Development Kit (PDDK) is a product for the development of phone drivers to enable communication between Palm OS? 5 and third-party cellular phones. The PDDK product is composed of documentation, libraries, tools, and examples. It is designed to provide application developers with the programming tools necessary to interface Palm Powered? handhelds with mobile phones.RequirementsIn order to develop a phone driver, you need the following items. If you do not have these programs, documents, and materials, you must obtain them from the web sites mentioned.Phone Driver Development Kit Guide 1 PalmSource ConfidentialPhone Driver Developm ent Kit Installation Installation ProceduresTable 1.1 Required Materials Product Code Warrior for Palm Computing? platform Palm OS Simulator Palm OS 5 SDK A Palm terminal program A suitable Palm OS 5 device A data cable for the phone See your phone manufacturer. Web Site /dev/ tools/ /dev/ tools/simulator/ /dev/ tools/ / (for example, OnLine.prc)Installation Procedures? Install the required products listed above. ? Copy the folder Palm OS Phone Device Driver of the PDDK package from Code Warrior Support/(Project Stationery) into the folder Stationery of Code Warrior. ? Copy the folder Palm OS PDDK Support into the Code Warrior folder. ? Copy the files LexGen.exe and LexGen_CW_Plugin.dll from Code Warrior Support/CodeWarrior Plugins/ Compiler into Code Warrior’s Bin/Plugins/Compiler folder.2 Phone Driver Development Kit Guide PalmSource Confidential2Telephony ArchitectureThis chapter describes the various components related to telephony services. The first section provides an overview of the Telephony Manager components, while the second section focuses on the Telephony Task.Telephony Manager ArchitectureThe Telephony Manager is a Palm OS? shared library dedicated to handling telephony services. The Telephony Manager provides access to speech calls, messaging services, and phonebook functions. The Telephony Manager has been designed to provide easy support for telephony services. It is network independent and aims to provide the same level of abstraction on every supported network. As much as possible, it is also phone-independent. The Telephony Manager API aims to have the same basic behavior with every phone. The Telephony Manager relies on a messaging system, associated with a dedicated background task called the Telephony Task. Each time an application calls a Telephony Manager function, function creates a message and sends it to the Telephony Task. The Telephony Task is a server which processes telephony requests and runs transparently in the background. The results of the telephony functions are stored in a message structure which is sent back to the application via the same messaging mechanism.Telephony ComponentsThe following diagram, Figure 2.1, shows a stack view of the telephony components.Phone Driver Development Kit Guide 3 PalmSource ConfidentialTelephony Architecture Telephony Manager ArchitectureFigure 2.1Stack View of Telephony ComponentsEnd user applications, such as Address book, Calendar, and Memo A shared library providing access to phone-related features Messaging system to exchange requests and answers between Telephony Mgr and Telephony Task, based on queues Palm OS task communicating with a phone t an abstract layer of telephony services on top of the low level phone hardware and softwareTasks and LibrariesThe following diagram, Figure 2.2, presents the general Telephony Manager architecture in terms of libraries and tasks. The Telephony Manager is available to every task running under Palm OS. Figure 2.2 Tasks and Library View4 Phone Driver Development Kit Guide PalmSource ConfidentialTelephony Architecture Telephony Manager ArchitectureInteraction with Handheld ApplicationsThe interactions between Telephony Manager and handheld applications rely on standard Palm OS mechanisms--function calls, events, notifications, and sub-launches--as described below. Most Telephony Manager functions are available in both synchronous and asynchronous modes. When an application calls a synchronous function, the application is blocked until the Telephony Task completes the associated request and sends back the result to the Telephony Manager. Synchronous calls from different tasks are multiplexed by the Telephony Manager. When an application calls an asynchronous function, the function call returns immediately, and the application receives an event via TelGetEvent when the result is returned from the Telephony Task. A background task can also use the Telephony Manager in order to access telephony services. But a background task must use TelGetTelephonyEvent, which retrieve only telephony events. This API is specific to background tasks. The Telephony Manager handles events distribution task by task. If an application wants to be warned of unsolicited phone events such as incoming SMS messages or incoming calls, the application must register with the Notify Manager. When an unsolicited event occurs, the Telephony Task, through the Notify Manager, will sublaunch the application. The launch code indicates the type of the telephony event which initiated the sub-launch.Interaction with the Telephony TaskThe following diagram, Figure 2.3, summarizes the interactions between handheld applications, Telephony Manager, and the Telephony Task.Phone Driver Development Kit Guide 5 PalmSource ConfidentialTelephony Architecture Telephony Task ArchitectureFigure 2.3Telephony Manager and Telephony TaskTelephony Task ArchitectureThe Telephony Task is a background task dedicated to communication with a phone. It implements an AT command based communication protocol on a serial port (RS232 or IrComm). It sends standard AT commands, parses the phone's answers and returns results to the application. The Telephony Task is fully compliant with ETSI GSM 07.05 and GSM 07.07 standards. The UCS-2 character set is used by default. GSM is used only if a phone does not support UCS-2. Because very few phones respect the entire standard AT command set, the Telephony Task may not communicate reliably with some phones. In order to avoid providing a different Telephony Task for each specific phone, the Telephony Task has a plug-in structure. The plug-ins are called phone drivers. Phone drivers are PRC files with code resources and user interface resources. Phone drivers are loaded and called by the Telephony Task, the Connection panel and the Phone panel (in the Preferences application). The phone driver must override functions which do not work by default. For instance, the default TelInfGetInformation function sends AT+CGMI. If the phone does not support this6 Phone Driver Development Kit Guide PalmSource ConfidentialTelephony Architecture Telephony Task Architecturecommand, the phone driver may replace the function by one which sends ATI1. As soon as the Telephony Manager function has the same behavior as the original function, the replacement is transparent to the application. The phone driver may disable
for example, if a phone does not support PIN code management, the phone driver can disable PIN code management. In addition, the phone driver may implement new features that are not in the Telephony Task, such as melody selection or SIM Toolkit functions, via an OEM function. The phone driver also supports phone-specific characteristics: the phone’s name, supported communication ports, baud rate, and timeouts.Component LayersAs shown in Figure 2.4, the Telephony Task is composed of three layers: a dispatch layer, a driver layer, and a serial layer. The driver layer contains the Base Driver and the phone driver, which both use the PDDK Library.Phone Driver Development Kit Guide 7 PalmSource ConfidentialTelephony Architecture Telephony Task ArchitectureFigure 2.4Telephony Task’s 3 Layer StructureDispatch LayerThe Dispatch Layer is the Telephony Task's main engine. It is an infinite loop that: ? Waits for: C a Telephony Manager query (through message queues), resulting from a Telephony Manager function call. C an unsolicited string from the phone, such as an incoming call or an incoming SMS message.8 Phone Driver Development Kit Guide PalmSource ConfidentialTelephony Architecture Telephony Task Architecture? Calls an entry point according to the Telephony Manager query, or the received unsolicited string, which points to a Base Driver function or a phone driver function. ? Constructs a reply message and transmits it back to the Telephony Manager. Communication between the Telephony Manager shared library and the Telephony Task is message- that is, it is via message queues.Base DriverThe Base Driver implements most Telephony Manager functions. It is fully compliant with ETSI GSM 07.05 and 07.07. Each function: ? Sends an AT command. ? Waits for the phone's answer. ? Parses the answer line by line. ? Processes phone error codes by converting them into Telephony Manager error codes. ? Fills the Telephony API reply message associated with the function. The Base Driver also process incoming AT strings from SMS messages and incoming calls. Corresponding functions in the Base Driver can be overridden in the phone driver. Base Driver source code is provided in the Examples directory of the package. For a complete description of the Base Driver, see Phone Driver Development Kit Reference.Serial LayerThe Serial Layer manages: ? The opening and closing of a serial port: RS232, IrComm, or others. ? The transmission of data: sending and receiving via the serial port. This layer is AT independent and relies on the Serial Manager.Phone Driver Development Kit Guide 9 PalmSource ConfidentialTelephony Architecture Telephony Task ArchitecturePDDK LibraryThe PDDK Library contains the API for the phone driver. It provides: ? Communication functions wrapped on Telephony Task Serial Layer. ? A lexical analyzer for parsing AT commands. ? A codec for SMS encoding and decoding. ? Character set conversion functions. ? Error code conversion functions. ? Utility functions (such as PdrvWaitForConfirmation or PdrvTrimQuotes) to manipulate AT command strings. This static library is linked with phone drivers. PDDK functions are listed in Phone Driver Development Kit Reference.Phone DriversIf a default function in the Base Driver does not work with a particular phone, it must be replaced by a function in the phone driver which performs the same task. The phone driver may implement the following: ? Functions documented in the Telephony Manager but which are not implemented in the Base Driver (for example, sound or conference call functions). ? Functions using OEM calls, such as SIM Toolkit, melody selection, or logo selection functions. ? A function to process unsolicited phone strings, such as ring or SMS notification functions. ? Functions that are called when the communication port is opened or closed. The default opening function only sends an initialization string, but it can be overridden. The phone driver also sets default parameters for the Base Driver, such as: C The type of SMS encoding C The phonebook's base index10 Phone Driver Development Kit Guide PalmSource ConfidentialTelephony Architecture Telephony Task ArchitectureC Timeout settings A phone driver is required to start the Telephony Task. It is not a stand-alone module. The simplest phone driver is the Standard GSM driver. It is almost empty, and it overrides only one function of the Base Driver (the ATUrqMatchPhoneDriver function). A sample phone driver, SampleDrv, is also included in the PDDK package. It overrides two functions: ? ATInfGetInformation, which retrieves phone information such as brand, model, and revision. ? ATOemCall, which implements additional non-standard phone features. NOTE: The Base Driver is not the same as the Standard GSM phone driver. The Base Driver implements all Telephony Manager functions. On the other hand, the Standard GSM phone driver is the simplest phone driver, and is almost empty.Telephony Task Calling MechanismWhen an application needs telephony service, it has to load the Telephony Manager shared library. The Telephony Manager launches the Telephony Task. The Telephony Task automatically loads the phone driver currently selected in the Phone panel. On initialization, the Telephony Task creates an entry point table that is an array of function pointers, one entry per Telephony Manager function. The Telephony Task first calls the Base Driver, which fills the table and then calls the phone driver, which completes or overrides existing entries. When an application calls a Telephony Manager function, the Telephony Manager constructs a message containing the function's unique ID and enqueues it. When the Telephony Task receives the function's ID, it uses the ID as an index to locate the function's pointer in the entry point table. The function can be located in the Base Driver or the phone driver, as shown in Figure 2.5.Phone Driver Development Kit Guide 11 PalmSource ConfidentialTelephony Architecture Telephony Task ArchitectureFigure 2.5Calling Mechanism12 Phone Driver Development Kit Guide PalmSource Confidential3Phone Driver User InterfaceThis chapter presents the user interface related to phone drivers.Preferences ApplicationPhone drivers interact with two panels in the Preferences application: the Connection panel and the Phone panel. Figure 3.1 Using the Preferences ApplicationConnection PanelThe Connection panel organizes the various device profiles connected to a Palm handheld. Installation of a phone driver is a “plug-and-play” procedure. When a phone driver PRC is installed on a Palm Powered? handheld (either by beaming or by HotSync? operation), a connection profile is created, one for each serial link.Phone Driver Development Kit Guide 13 PalmSource ConfidentialPhone Driver User Interface Connection PanelAvailable Connections ListFigure 3.2 shows the Connection panel’s connection profile list, which is called Available Connections. The Standard GSM phone driver, which is included in the ROM and which is always available, creates two connection profiles: ? Infrared to GSM Phone for the default Infrared connection. ? Serial to GSM Phone for the default RS232 connection. Figure 3.2 Available Connections in the Connection PanelThe Connection panel has three buttons: ? To create a new connection profile, the user taps New. ? To edit a selected connection profile, the user taps Edit. ? To delete a selected connection profile, the user tap Delete.Edit Connections FormWhen the user taps Edit, the Edit Connections form is displayed, as shown in Figure 3.3.14 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Us er Interface Connection PanelFigure 3.3Edit Connection FormTo select a phone driver in the Edit Connection form, the user taps the Model pick list and selects an item: for example, Standard GSM or another specific driver.Connection Details FormTo set connection parameters for a selected phone driver, the user taps Details in the Edit Connection form. If your phone requires additional parameters specific to the phone driver, your phone driver must provide its own connection Details form. The default connection Details form (used by the Standard GSM phone driver) is shown in Figure 3.4. Figure 3.4 Default Connection Details FormThe AT initialization string, Init String, can be modified to accommodate countries and carriers requiring a specific initialization string. In some cases, the baud rate, Speed, may need to be changed also.Phone Driver Development Kit Guide 15 PalmSource ConfidentialPhone Driver User Interface Phone PanelSee Chapter 5, “Phone Driver Entry Point,” on page 35 for more information concerning displaying and hiding the Details button and how to implement a connection Details form.Phone PanelThe Phone panel is for selecting the current connection profile to use for telephony applications. ? The Phone panel always has a Test button, which is described in “Phone Panel’s Test Button.” ? The Phone panel may also have a Details button, which is described in “Phone Panel’s Details Button” on page 18.Phone Panel’s Test ButtonAs shown in Figure 3.5, the Phone panel always has a Test button. To test a selected connection profile, the user taps Test. The test function verifies whether the selected phone driver and the connected phone are compatible. Figure 3.5 Phone Panel’s Test ButtonThe results of the test can be any of the following: ? An error, ? A partial match, or ? A full match. The Phone panel displays a different alert for each of these results.16 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Us er Interface Phone PanelPhone Test Error Message The phone test error message, shown in Figure 3.6, indicates that the handheld is unable to connect to the phone. When the user receives this message, the user needs to check the connection between the handheld and the phone. Figure 3.6 Phone Test Error MessagePhone Test Partial Match Message The phone test partial match message, shown in Figure 3.7, indicates that the connection between the Palm handheld and the phone was a partial success. The two devices are able to communicate with each other, but the phone driver does not recognize the phone. Some telephony services may work, while others may not. Figure 3.7 Phone Test Partial Match MessagePhone Driver Development Kit Guide 17 PalmSource ConfidentialPhone Driver User Interface Phone PanelPhone Test Full Match Message The phone test full match message, show in Figure 3.8, indicates that the current phone driver is an exact match for the connected phone. Figure 3.8 Phone Test Full Match MessagePhone Panel’s Details ButtonIf the phone driver provides a Phone Details form, then the Details button is visible upon driver selection. Figure 3.9 shows a Phone panel with a Details button. Figure 3.9 Phone Panel’s Details ButtonWhen the user taps Details, the Phone Details form is displayed. Figure 3.10 shows an example of a Phone Details form.18 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Us er Interface User ConsiderationsFigure 3.10Example of a Phone Details FormPossible items for the Phone Details form include the following: ? SMS Service Center ? SMS validity period ? PIN code entry ? Melody selection ? Download logo See Chapter 5, “Phone Driver Entry Point,” on page 35 for information on displaying and hiding the Details button, and for instructions on how to implement a Phone Details form. NOTE: Do not confuse the Phone Details form of the Phone panel with the Connection Details form of the Connection panel.User ConsiderationsWith the correct phone driver selected, the user does not need to use the Connection panel or the Phone panel. The user will need to use the Phone panel to complete the following tasks: ? To swap between different phones. ? To set up an RS232 connection. For an RS232 connection, the connection profile Serial to GSM Phone must be selected instead of the default setting Infrared to GSM Phone.Phone Driver Development Kit Guide 19 PalmSource ConfidentialPhone Driver User Interface User ConsiderationsThe user will need to use the Connection panel for the following tasks: ? To change the initialization string. Some carriers require that a specific command be specified in the initialization string. ? To create a new connection profile, if none of the existing profiles work.20 Phone Driver Development Kit Guide PalmSource Confidential4Phone Driver Development ProcessThis chapter describes how to develop a phone driver. It is composed of four parts, which correspond to the four steps of the development process: 1. Connect a mobile phone to a computer running the Palm OS? Simulator. 2. Test the phone with the default phone driver, to evaluate which functions need to be tailored to work with the phone. 3. Write the phone driver code. 4. Test the phone driver code with a Palm Powered? handheld. We recommend that you follow this process. The following description refers to any documentation that you may need.Connecting Your Mobile PhoneHandhelds and mobile phones can be linked via an RS232 connection or via an infrared connection. If your phone supports both connection types, then you should test both connection types. We recommend that you use Palm OS Simulator for early stages of development, but that you use a Palm Powered handheld device for final testing.Testing with Palm OS SimulatorPalm OS Simulator supports both RS232 connections and infrared connections. If your computer has an infrared port that supports IrComm, which is available on some laptop computers, Palm OSPhone Driver Development Kit Guide 21 PalmSource ConfidentialPhone Driver Development Process Connecting Your Mobile PhoneSimulator can use the infrared COM port to communicate with an infrared phone. ? Start Palm OS Simulator and select the PDDKDebug.rom file, or drag and drop the PDDKDebug.rom file on the Palm OS Simulator window. ? Right-click the Simulator window and select Settings & Communication & Communication Ports. Next, select the COM port you are testing and click Edit. For Transport Type select IR through RS-232, and for Bound to select a COM port. You may also use an XTNDAccess device (select IR through JetEye) or TCP/IP (select TCP/IP). ? Go to the Phone panel in the Preferences application and test the phone driver as described in the following sections. Using an Infrared Connection If your phone has an infrared port, activate the port by using the phone's menu. Next, point the phone’s infrared port at the infrared port of the computer running Palm OS Simulator. By default, an infrared connection is selected on the handheld. ? Tap the Preferences application. ? Select Phone and then select the connection profile Infrared to GSM Phone. ? Tap Test to test the connection. The possible responses are shown in “Possible Responses.” Using a Serial Connection Connect the computer running Palm OS Simulator and the phone with the serial cable provided with the phone (or a combination of cables and adapters). ? Tap the Preferences application. ? Select Phone and then select the connection profile Serial to GSM Phone. ? Tap Test to test the connection. The possible responses are shown in “Possible Responses.” Possible Responses The following responses are possible:22 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Connecting Your Mobile Phone? “Connection is OK” on page 23. ? “Unable to Connect” on page 23. ? “Unable to Handle Request” on page 24. Connection is OK This alert, shown in Figure 4.1, is normal and occurs when the phone driver is set on the default Standard GSM phone driver. Figure 4.1 “Connection Is OK” MessageThe Standard GSM phone driver provides a limited compatibility with the connected phone. Unable to Connect This alert, shown in Figure 4.2, appears if the communication could not be established. Figure 4.2 “Unable to Connect” MessageTo resolve the connection problem, try the following: ? For a serial connection, check the cable connecting the phone and the computer. ? For an infrared connection, check the line of sight between the computer and the phone.Phone Driver Development Kit Guide 23 PalmSource ConfidentialPhone Driver Development Process Connecting Your Mobile Phone? In the Preferences application, select Connection. With the phone driver selected in the Available Connections list, tap Edit. Next, tap Details and check that the baud rate and the initialization string are correct. ? Try to establish communication with a Palm terminal program, with a Hilgraeve’s HyperTerminal application, or with any other serial communications program. ? Try changing the baud rate, parity, or any other COM port parameter that may affect the connection. ? Try to send basic AT commands (such as ATZ) in order to get a correct answer from the phone. Unable to Handle Request This alert, shown in Figure 4.3 appears if communication was established, but the phone answered with an error. As a result of the error, some AT commands may not work. Figure 4.3 “Unable to Handle Request” MessageTo resolve the connection problem, try the following: ? In the Preferences application, select Connection. ? With the phone driver selected in the Available Connections list, tap Edit. ? Next, tap Details and check that the initialization string is correct. ? Check that the phone supports the +CGMM and +CGMI commands.24 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Evaluating Phone Compliance with the Default DriverEvaluating Phone Compliance with the Default DriverThe next step in the phone driver development process is to evaluate how well your phone works with the Standard GSM default phone driver. The Standard GSM phone driver is compliant with the ETSI standard (GSM 07.05 and GSM 07.07). For background information, make sure you are familiar with the following: ? The Telephony Manager concepts described in Palm OS Programmer’s Companion, vol. II, Communications ? The Telephony Manager API described in Palm OS Programmer’s API Reference. ? The telephony architecture described in and Chapter 2, “Telephony Architecture,” on page 3. ? The phone driver user interface described in Chapter 3, “Phone Driver User Interface,” on page 13. In your evaluation, test all Telephony Manager functions against your phone. This testing will identify those phone driver functions that already work with your phone versus the functions that you will need to tailor for your phone. Use the dedicated application DriverTester and the ROM application to perform your tests.Testing with the DriverTester ApplicationInstall the test application DriverTester. To install an application, drag and drop it onto the Simulator window, or use a HotSync? operation to install the application on your handheld. DriverTester can be found in the PRC Files folder of the package. DriverTester displays two popup lists on the top. The left one lists the various telephony services (for example, Phonebook or Speech Call). The right one lists the various telephony functions of the selected service. For instance, if Speech is selected in the left popup list, then only Speech functions appear in the right. If CallPhone Driver Development Kit Guide 25 PalmSource ConfidentialPhone Driver Development Process Evaluating Phone Compliance with the Default DriverNumber is selected, it will ask for the phone number to dial and then call TelSpcCallNumber. Guidelines for Testing ? Try every function of every service, at least once. ? Be careful with the Call option of the Emergency service. This option uses TelEmcCall, which may really call emergency services (ATD112). On a handheld and with the release version of PRCs, hang-up immediately to avoid bothering emergency services. If you use Palm OS Simulator or the debug PRC, then the number dialed is replaced by the first entry of the current phonebook (ATD&1) for testing purposes. ? To test incoming calls and incoming SMS notifications, the communication port must already be opened when the incoming call or the SMS message arrives. In Urgent Queries, select Open Connection. This menu calls the function TelUrqOpenPhoneConnection. Then call or send an SMS message to the tested mobile phone using another phone. ? Some functions depend on context and must be tried several times. For instance, the Get State function in the Speech service (TelGetCallState) should be tried while an outgoing call is in progress, during an incoming call, and also during an idle state. However, when switching between two phone calls--an incoming call and an outgoing call--this function may return an invalid result. ? Some functions only work in a particular context. For example: C Voice-related functions fail when no call is in progress. Voice-related functions include TelSpcHoldLine, TelSpcRetrieveHeldLine, TelSpcGetCallerNumber, and TelSndMute. The error code returned at the time of failure is usually telErrCommandFailed or telErrUnavailableValue. C The functions TelSpcConference and TelSpcSelectLine are not implemented. Conference calls are not supported. You can only switch between two calls.26 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Evaluating Phone Compliance with the Default DriverC The functions TelSndPlayKeyTone and TelSndStopKeyTone are not implemented. There are no standard AT commands for these functions. C The function TelNwkSelectNetwork will not work without roaming capability. C The function TelPowSetPowerLevel does not turn on a phone when the phone is switched off. C The function TelSmsSendManualAcknowledge is not supported on GSM networks. C The function TelEmcSelectNumber is not applicable to GSM networks. C The default Standard GSM driver won’t read the SMS Status report from SIM. The command +CNMI=1,1,0,2,1 is not in the driver’s initialization string. Considerations for what to use as an initialization string are discussed in “Initialization String” on page 47. C The Standard GSM driver won’t show the caller’s number with TelGetCallerNumber. The command +CLIP=1 is not in the driver’s initialization string. Considerations for what to use as an initialization string are discussed in “Initialization String” on page 47. AT commands sent from the phone driver and the expected phone answers are described in Phone Driver Development Kit Reference. NOTE: All telephony functions are callable from Driver Tester.Testing with ROM Applications? In the Address book application, create a new entry with a phone number, and then select Dial in the menu. Tap Dial to dial the number. Also try to send a vCard by tapping Record & Send Address. ? In the Date Book application, try to send a vCal by tapping Record & Send Event. ? In the Memo application, try to send a vObject by tapping Record & Send Memo.Phone Driver Development Kit Guide 27 PalmSource ConfidentialPhone Driver Development Process Writing a Phone Driver? In the SMS application, send several SMS messages to yourself, and verify that you receive them properly. Use the various options, such as return receipt, SMS center, and expiration date.Writing a Phone DriverThis section describes how to modify the provided driver stationery and how to write a driver function.Modifying the Driver StationeryBefore writing a phone driver, read through the remaining chapters in this book and browse Phone Driver Development Kit Reference. Also, read through the sample driver SampleDrv and the Base Driver ATPhoneDriver. The Base Driver implements all of the phone driver functions. IMPORTANT: To compile the SampleDrv or the ATPhoneDriver, the LexGen tool must be installed as described in “Phone Driver Development Kit Installation” on page 1. To create a new driver project: ? Launch Code Warrior ? Select File & New. ? In Project, select Palm OS Phone Device Driver. ? Enter the project name and adjust the location if needed, and then click OK. The default names of the files in the project are StationeryDrvXXX. To rename the files, use the Save As menu (Code Warrior will update the project as well). See the Code Warrior documentation for more information. After renaming the files, you must update the project's settings with the correct project name: ? Open the project's settings. ? Select the Linker & PalmRez Post Linker tab.28 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Writing a Phone Driver? Enter the correct values for Mac Resource Files, Output File and Database Name. ? Select the Target & 68K Target tab. ? In the File Name field, enter the same file name as you specified for the Mac Resource Files field. IMPORTANT: You must specify the same value for the field File Name in the tab Target & 68K Target and the field Mac Resource Files in the tab Linker & PalmRez Post Linker. All PRC files are stored as databases, and are identified by a database type and a database creator. The databases type reserved for phone drivers is pdrv. The Phone panel uses this type to recognize phone drivers. The database type must not be changed from pdrv. However, the value specified for database creator must be unique. Each company must register a creator value on the PalmSource web site (/creatorid/). To set the creator value for your phone driver: ? Open the project settings. ? Select the tab Linker & PalmRez Post Linker. ? Change the Creator field. NOTE: Database types and creators are 32-bits values composed of 4 characters. They are not C strings. Resource File Considerations Edit the resource file and change the following: ? Change the PhoneName, which is the string that appears in the Model field of the Connection panel. ? Also change the ProfileName, which is an array of strings, one per connection type (Serial, Infrared). They appear in Available Configuration list of the Connection panel. ? You should also change the Application Icon Name to your phone driver name.Phone Driver Development Kit Guide 29 PalmSource ConfidentialPhone Driver Development Process Testing a Phone DriverSource Code Modifications Edit the StationeryDrv.c file and change the following: ? Change the initialization string according to the phone’s requirements. It is stored in the C global constant named gInitString. See “Initialization String” on page 47 for more details. ? Change the list of phones your driver supports. The list is stored in the global C variable named gSupportedPhone. ? Modify the DrvEntryPoint function. This is detailed in Chapter 5, “Phone Driver Entry Point.” Now, compile and link your phone driver. Preliminary Testing To test your driver, use a HotSync operation to install it on a handheld, or drag-and-drop it on the Palm OS Simulator window. A handheld asks for a reset. In Palm OS Simulator, a manual soft reset is required. Right-click the Simulator window, and select Reset & Soft. If you don’t do a reset, the phone driver won't show up on the lists in the Connection and Phone panels.Writing a Driver FunctionBased upon the test results with the DriverTester application, as described in “Evaluating Phone Compliance with the Default Driver” on page 25, you have identified the functions that need to be rewritten. Start writing these functions, respecting the recommendations in Chapter 6, “Writing a Phone Driver Function,” on page 51. Pay special attention to the recommendations for using the function template, for error handling, and for buffer management.Testing a Phone DriverOnce the phone driver is written and unit-tested, you should do final testing on a handheld with the release version of the PRC file. ? Before you start testing, set the Beam Receive option to on (which is located in Preferences & General).30 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Troubleshooting? With the DriverTester application, verify all functions several times, in both synchronous and asynchronous mode. Try canceling at any time. Also plug and unplug the cable during communication (if you’re using a RS232 connection), or move one of the device away (if you’re using an IrDa connection). The command sent at the time of disconnection must fail gracefully, while next command must succeed. ? Check the option No memory of the DriverTester application and retry every function. With this option set, the application will pass a NULL pointer for buffers, and the phone driver functions should return the error telErrBufferSize, as described in “Managing Buffers” on page 54. ? Try to read from a phonebook with a lot of filled entries (in DriverTester, select Phoneboook & ReadEntries). ? Try to send several SMS messages and multipart SMS messages with the SMS application. If unexpected and intermittent errors such as Unable to connect to phone occur, see “Troubleshooting” on page 31.TroubleshootingThis section describes phone driver problems and discusses how to resolve them.Problems with the Default Initialization StringSymptom: All functions fails. Possible solution: Reduce the initialization string. Some commands may not be supported, or the initialization string may need to be split into smaller strings.Problems with IrDAIn some circumstances, a phone may confuse the Palm IrDA stack.Phone Driver Development Kit Guide 31 PalmSource ConfidentialPhone Driver Development Process TroubleshootingSymptom: The communication is not reliable (that is, sometimes commands fail for unknown reasons). Possible solution: ? Try communicating with the Beam Receive option on and then with the Beam Receive option off on the handheld. ? If the problem disappears with the option off, you should document it. There is no simple way to disable the Beam Receive option in the phone driver. ? Try using an IrDA sniffer to log the communication between the phone and the handheld.Problems with TimeoutsSymptom: Functions timeout before the phone gets a chance to answer. Possible solutions: ? If a few functions timeout, override these functions and use longer timeouts. ? If a lot of functions timeout, increase the default receive timeout value.Problems with RS232 Hardware Flow ControlSome phones do not manage hardware flow control on AT commands. The problem occurs when the phone sends a relatively large amount of data to the handheld. Symptom: When reading several SMS messages, or several phonebook entries, a communication error occurs. Possible solutions: ? Some phones have an AT command which enable hardware flow control. Add this AT command in the initialization string and redo the tests.32 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver D evelopment Process Troubleshooting? If the phone supports more than one baud rate, try to reduce the baud rate. ? As a last resort, increase the receive buffer size with SrmSetReceiveBuffer. See Palm OS Programmer’s API Reference for more information.Problems with Phone LimitationsIn some rare cases the phone itself may have some limitations. Symptom: A particular AT command fails when it should succeed. Possible solutions: ? Try to reproduce the problem with a desktop computer and a terminal application. ? Try to find a work around using other AT commands. ? If there is no work around, disable the function in the driver. Document it as an unsupported function.Phone Driver Development Kit Guide 33 PalmSource ConfidentialPhone Driver Development Process Troubleshooting34 Phone Driver Development Kit Guide PalmSource Confidential5Phone Driver Entry PointThe phone driver has one main entry point which has multiple purposes. It is called by the Telephony Task, by the Connection panel, and by the Phone panel. The prototype for the main entry point is this:typedef Err (*PdrvEntryPointPtr) (ePdrvOpCodeType opCode, void * pdrvParamP);The opCode parameter indicates the sub-function and the pdrvParamP parameter refers to a structure specific to the opCode, as shown in the following table: Table 5.1 opCode and Parameter Type opCode kPdrvInit kPdrvGetSettings kPdrvConnection Detail kPdrvPhoneDetails pdrvParamP type PdrvFuncParamType PdrvGetSettingsParamType PdrvUIEntryPointType Called At Telephony Task initialization At Phone panel initialization When displaying Details in the Connection panel When displaying Details in the Phone panelPdrvUIEntryPointTypeAt Telephony Task InitializationOn initialization, the Telephony Task loads the phone driver, and then calls the entry point with opCode set to kPdrvInit and with pdrvParamP as a pointer to a PdrvFuncParamType structure.Phone Driver Development Kit Guide 35 PalmSource ConfidentialPhone Driver Entry Point At Telephony Task InitializationHere is part of the PdrvFuncParamT it lists the fields that must be set. The fields that are not listed must not be changed.typedef struct _PdrvFuncParamType { /* Driver version */ UInt32 versionDrvS /* TelMgr entry points */ PdrvTelFuncType atDriverEntriesTable[kTelLastMessage + 1]; /* Flags indicating which services are enabled */ PdrvServiceType atDriverS /* Called on unsollicited event (ring, SMS, ...) */ PdrvIncomingFuncType drvIncomingP; /* Reserved for driver globals. Can refer any structure allocated by driver. * Freed by TT */ MemPtr phoneDataP; /* List of supported phone by driver. This is used by the default * TelMatchPhoneDriver. Useless if overriden */ const char * supportedP [...] /* SMS globals */ UInt16 smsFirstE /* Index of first SMS entry */ Boolean embedS /* true to add SMSC at start of PDU */ /* Phonebook globals */ UInt16 phbFirstE /* Index of first phonebook entry */ [...] /* Drivers Comm function entry points */ PdrvDriverOpenFuncPtr driverOpenCommP; PdrvDriverCloseFuncPtr driverCloseCommP; [...] /* Charset supported by phone */ UInt8 charsetSupportedByP /* kPdrvCharsetUCS2 or kPdrvCharsetGSM */ /* SMS globals for UCS2 and GSM SMS processing */ UInt16 oldSmsDataS /* dataSize of the sender's message */ TelSmsSubmitMessageType currentS /* current processing SMS */ } PdrvFuncParamT36 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Entry Point At Telephony Task Initialization? UInt32 versionDrvSpec Phone driver version. Must be set to kTelMgrVersion. The Telephony Task verifies version for compatibility with other components. ? PdrvTelFuncType atDriverEntriesTable [kTelLastMessage + 1] This table contains function pointers for each Telephony Manager function. It is initialized by the Base Driver and the phone driver updates it. For each entry point, options are: C Leave the default function, if the default implementation in the Base Driver works. C Override the function. Example for TelSpcCallNumber: paramP-&atDriverEntriesTable [kTelSpcCallNumberMessage]= MySpcCallN C Dea that is, if the feature is not supported by the phone. For example, to have TelSndMute call returns telErrFeatureNotSupported, you would use the following: atDriverEntriesTable [kTelSndMuteMessage] = NULL; NOTE: If all functions of the service become disabled, set the corresponding bit to 0 in the atDriverService field. In previous example, snd service does not have any more functions, so set paramP-&atDriverService.snd to 0. C Implement the function. Example: To implement the OEM call which was previously NULL, use the following: paramP-&atDriverEntriesTable [kTelOemCallMessage] = ATOemC For more information on OEM calls, see Phone Driver Development Kit Reference.Phone Driver Development Kit Guide 37 PalmSource ConfidentialPhone Driver Entry Point At Telephony Task InitializationNOTE: If all functions of the service were previously disabled, set the corresponding flag to 1 in atDriverService field. For example: paramP-&atDriverService.oem = 1; ? PdrvServiceType atDriverService Telephony Manager functions are grouped in sets called services. For instance, functions that deal with speech calls are in spc service and are prefixed TelSpcXXX. This bit field structure has one bit per service and indicates which services are enabled or disabled. If a phone doesn't support any of the speech call functions, set the spc bit to 0. Then TelIsSpcServiceAvailable will return telErrFeatureNotSupported. If the phone driver supports an OEM call, set the oem bit to 1, and override the kTelOemCallMessage as shown below. Enable a service if at least one function of the service is implemented. NOTE: When disabling a service, set all the corresponding entries in the atDriverEntriesTable to NULL as well. Then the TelIs&Func&Supported of this service will return the error telErrFeatureNotSupported. ? PdrvIncomingFuncType drvIncomingP This function is called when unsolicited strings are received from the phone. This can happen when the communication port is open and no commands are in progress. The Base Driver implements incoming calls and incoming SMS notification processing. This function can also be replaced in the phone driver. See Phone Driver Development Kit Reference for more information. ? MemPtr phoneDataP The phone driver can allocate a structure with MemPtrNew for storing its global variables and store the pointer in this field. This pointer will be passed as a parameter to all phone driver functions. The Telephony Task frees the allocated block of memory upon termination. Because the Telephony Task is not aware of the structure content, these global38 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Entry Point At Telephony Task Initializationvariables must be a “flat” C structure t that is, they must not have pointers to other allocated blocks inside. ? const char * supportedPhone Must contain an array of strings (brands and models) identifying the supported phones. The default ATUrqMatchPhoneDriver function sends +CGMI and +CGMM commands and compares the first n characters of the result strings with the supportedPhone array of strings. The format is: Brand1\0Model1\0Brand2\0Model2\0...\0 Note the double terminating null characters at the end. If ATUrqMatchPhoneDriver is overridden, this field is unused. When the model starts with number, the following syntax may be used: supportedPhone = { 'A', 'B', 'C', '\0', '1', '2', '3', '\0', '\0' } NOTE: Constant strings must be declared in code segment using the __declspec(pcrel) directive, as shown in the sample driver. ? UInt16 smsFirstEntry Set this parameter to the base index of SMS entries. This is usually 1. See Phone Driver Development Kit Reference for more information. ? Boolean embedSmsc Set this parameter to true to add SMSC at the start of the SMS PDUs; otherwise, set this parameter to false. ? UInt16 phbFirstEntry Set this parameter to the base index of the phonebook entries. This is usually 1. See Phone Driver Development Kit Reference for more information. ? PdrvDriverOpenFuncPtr driverOpenCommP This function is called by PdrvOpenComm at the beginning of each driver function. It opens the communication port and sends the initialization string. It can be overridden by thePhone Driver Development Kit Guide 39 PalmSource ConfidentialPhone Driver Entry Point At Phone Panel Initializationphone driver. See Phone Driver Development Kit Reference for more information. ? PdrvDriverCloseFuncPtr driverCloseCommP This function is called by PdrvCloseComm at the end of each driver function. By default, this function is empty, but it can be replaced in the phone driver. See Phone Driver Development Kit Reference for more information. ? UInt8 charsetSupportedByPhone Set this parameter to specify which character set the phone supports. This can be kPdrvCharsetUCS2 (for the UCS-2 character set) or kPdrvCharsetGSM (for the GSM character set). ? UInt16 oldSmsDataSize Set this parameter to the dataSize of the sender’s message. ? TelSmsSubmitMessageType currentSMS Set this parameter to specify the SMS that is currently being processed. IMPORTANT: Other fields of the PdrvFuncParamType structure must remain unchanged.At Phone Panel InitializationThe Phone panel calls the phone driver entry point with the opcode kPdrvGetSettings to create the connection profiles. The phone driver returns its name and its version number. The pdrvParamP is a pointer to a PdrvGetSettingsParamType structure.typedef struct _PdrvGetSettingsParamType { /* Telephony version, must be set to kTelMgrVersion */ UInt32 /* Type and creator of the Telephony Task the driver refers to */ UInt32 ttT /* Must be set to kPdrvTTType */ UInt32 ttC /* Must be set to kPdrvTTCreator */40 Phone Driver Development Kit Guide PalmSource ConfidentialPhone Driver Entry Point At Phone Panel Initialization/* Appears in &Model& combo box */ char phoneName[kPdrvPhoneNameSize]; /* Connection Panel Details: none, default or custom */ ePdrvDetailsPanelType connectionD /* Phone Panel Details: none or custom (no default) */ ePdrvDetailsPanelType phoneD /* Number of profile used in the following array */ UInt16 profN PdrvProfileInfoType profInfo [kPdrvMaxConnectionProfile]; /* See below */ } PdrvGetSettingsParamType, *PdrvGetSettingsParamP typedef struct _PdrvProfileInfoType { /* Name of profile, appears in Connection Panel. ex: &My Phone on serial& */ char profileName[kCncParamNameMaxSize]; /* Communication port. ex: 'ircm', serPortCradleRS232Port UInt32 /* Baud rate */ UInt32 baudR /* Serial communication flags (bits per char, parity, flow control,...) */ UInt32 /* Sending timeout in ms when CTS deasserted and hardware flow control set */ UInt32 ctsTimeoutMs; /* Default time out in ms when waiting for phone answer. Used by functions * that don't need an access to the network (ex: TelNwkGetSelectedNetwork) */ UInt32 receiveTimeoutMs; /* Initialization string */ char initString[kCncParamInitStringMaxSize]; /* Handle on driver specific parameter. Can be any flat structure */ MemHandle driverP /* Size of driver specific parameter */ UInt16 driverParamS } PdrvProfileInfoType, *PdrvProfileInfoP */Phone Driver Development Kit Guide 41 PalmSource ConfidentialPhone Driver Entry Point At Phone Panel Initialization? UInt32 version Must be set to kTelMgrVersion. ? UInt32 ttType Type of the Telephony Task the driver is compatible with. Must be set to kPdrvTTType. ? UInt32 ttCreator Creator of the Telephony Task the driver is compatible with. Must be set to kPdrvTTCreator. ? char phoneName[kPdrvPhoneNameSize] The phone name that appears in the Model pick list of the Connection panel. If the phone driver is localized, you can get the phone name from a string resource via SysCopyStringResource function. ? ePdrvDetailsPanelType connectionDetails This field controls the panel that is opened by the D}