Home > Palm > Inside a phone driver
Inside a phone driver
For Palm OS developers

Introduction

The Telephony Manager Library introduced in Palm OS 4.0 offers a standard way for applications to communicate with mobile phone. To keep up with new phone models, the Telephony Manager Library is configuratible with phone drivers. These drivers are plug-ins overriding the default behavior of the Telephony Manager Library. Unfortunately, there is no SDK available to general Palm OS developer community to date. This page provides some insight to a phone driver internals.

Note: I don't have access to the SDK, which is believed to be available to Palm OS licensees and selected partners. Names of constants, structures and functions related the the phone driver are made up by me.

Structure

A phone driver has a filetype of sysFileTPhoneDriver and a creator ID of your choice. Instead of being an application, it is a code resource in a sense of a virtual serial driver. The driver itself is stored in 'code' resource ID 1. The application name 'tAIN' and icons 'tAIB' will not be used by Palm OS thus are not needed. The version resource 'tver' is recommended for informing the users.

The phone driver has an entry point that is very similar to a serial driver:

Err DrvEntryPoint(PdrvEntryOpCodeEnum opCode, void *pdrvData);

How it works

The Palm OS calls the phone driver with an opCode. Each opCode is associated with a pointer to a structure. Here are the opCodes:

typedef enum
{
	pdrvEntryPrepConnect,
	pdrvEntrySetProfile,
	pdrvEntryUnknown,
	pdrvEntryDoDetails
} PdrvEntryOpCodeEnum;

Palm OS calls with pdrvEntryPrepConnect right before it talks to the phone, including when the user taps the Test button on the Phones prefs panel. The associated structure is full of default message handlers of various functions of phone services. Function pointers which are initially set NULL are probably functions not supported by the OS. It is left to the readers to find out what they really are.

Phone Panel 
typedef struct
{
	UInt32 version;	// set to kTelMgrVersion
	MemPtr fSendCommandMessageProc;
	MemPtr fNwkGetNetworkNameMessageProc;
	MemPtr fNwkGetNetworkTypeMessageProc;
	MemPtr fNwkGetSignalLevelMessageProc;
	MemPtr fNwkGetSearchModeMessageProc;
	MemPtr fNwkSetSearchModeMessageProc;
	MemPtr fNwkGetNetworksMessageProc;
	MemPtr fNwkSelectNetworkMessageProc;
	MemPtr fNwkGetSelectedNetworkMessageProc;
	MemPtr fNwkGetLocationMessageProc;
	MemPtr fStyGetAuthenticationStateMessageProc;
	MemPtr fStyEnterAuthenticationCodeMessageProc;
	MemPtr fStyChangeAuthenticationCodeMessageProc;
	MemPtr fPowGetPowerLevelMessageProc;
	MemPtr fPowGetBatteryStatusMessageProc;
	MemPtr fPowSetPhonePowerMessageProc;
	MemPtr fCfgSetSmsCenterMessageProc;
	MemPtr fCfgGetSmsCenterMessageProc;
	MemPtr fCfgGetPhoneNumberMessageProc;
	MemPtr fSmsSendMessageMessageProc;
	MemPtr fSmsSendManualAcknowledgeMessageProc;
	MemPtr fSmsGetMessageCountMessageProc;
	MemPtr fSmsReadMessageMessageProc;
	MemPtr fSmsReadMessagesMessageProc;
	MemPtr fSmsReadSubmittedMessageMessageProc;
	MemPtr fSmsReadSubmittedMessagesMessageProc;
	MemPtr fSmsReadReportMessageProc;
	MemPtr fSmsReadReportsMessageProc;
	MemPtr fSmsDeleteMessageMessageProc;
	MemPtr fSmsGetAvailableStorageMessageProc;
	MemPtr fSmsSelectStorageMessageProc;
	MemPtr fSmsGetSelectedStorageMessageProc;
	MemPtr fSmsGetDataMaxSizeMessageProc;
	MemPtr fEmcGetNumberCountMessageProc;
	MemPtr fEmcGetNumberMessageProc;
	MemPtr fEmcSetNumberMessageProc;	// NULL
	MemPtr fEmcSelectNumberMessageProc;
	MemPtr fEmcCallMessageProc;
	MemPtr fEmcCloseLineMessageProc;
	MemPtr fSpcAcceptCallMessageProc;
	MemPtr fSpcRejectCallMessageProc;
	MemPtr fSpcCallNumberMessageProc;
	MemPtr fSpcCloseLineMessageProc;
	MemPtr fSpcHoldLineMessageProc;
	MemPtr fSpcRetrieveHeldLineMessageProc;
	MemPtr fSpcGetCallerNumberMessageProc;
	MemPtr fSpcSendBurstDTMFMessageProc;
	MemPtr fSpcStartContinuousDTMFMessageProc;	// NULL
	MemPtr fSpcStopContinuousDTMFMessageProc;	// NULL
	MemPtr fSpcConferenceMessageProc;	// NULL
	MemPtr fSpcSelectLineMessageProc;	// NULL
	MemPtr fSpcPlayDTMFMessageProc;
	MemPtr fDtcCallNumberMessageProc;	// NULL
	MemPtr fDtcCloseLineMessageProc;	// NULL
	MemPtr fDtcSendDataMessageProc;	// NULL
	MemPtr fDtcReceiveDataMessageProc;	// NULL
	MemPtr fPhbGetEntryCountMessageProc;
	MemPtr fPhbGetEntryMessageProc;
	MemPtr fPhbGetEntriesMessageProc;
	MemPtr fPhbAddEntryMessageProc;
	MemPtr fPhbDeleteEntryMessageProc;
	MemPtr fPhbGetAvailablePhonebooksMessageProc;
	MemPtr fPhbSelectPhonebookMessageProc;
	MemPtr fPhbGetSelectedPhonebookMessageProc;
	MemPtr fPhbEntryMaxSizesMessageProc;
	MemPtr fSndPlayKeyToneMessageProc;	// NULL
	MemPtr fSndStopKeyToneMessageProc;	// NULL
	MemPtr fSndMuteMessageProc;
	MemPtr fUrqSmsGetUinquePartIdMessageProc;
	MemPtr fUrqClosePhoneConnectionMessageProc;
	MemPtr fUrqOpenPhoneConnectionMessageProc;
	MemPtr fUrqIsPhoneConnectedMessageProc;
	MemPtr fUrqMatchPhoneDriverMessageProc;
	MemPtr fUrqCancelMessageProc;
	MemPtr f308;	// NULL
	MemPtr f310;	// NULL
	MemPtr f312;	// NULL
	MemPtr f316;	// NULL
	MemPtr f320;	// NULL
	MemPtr f324;	// NULL
	MemPtr f328;	// NULL
	MemPtr fIngGetInformationMessageProc;
	MemPtr fOemCallFunctionMessageProc;	// NULL
	UInt16 flags;	// service group support; 0 for OS default
	MemPtr f342;
	UInt8 *p346;	// NULL
	UInt8 *p350;	// NULL
	PhoneProfileType config;	// current profile
	UInt32 pdrvCreator;		// creator type of your driver
	UInt32 pdrvFileType;		// file type of your driver
	Char modelName[32];		// your phone model name
	UInt16 i524;	// 0xFFFF
	UInt8 i526;	// 1
	UInt16 i528;	// 1
	UInt32 i530;	// 0
	UInt32 i534;	// 0
	Char number1[32];
	Char number2[32];
	UInt8 i602;	// 0xFF
	UInt8 i603;	// 0xFF
	UInt32 i604;	// 0
	UInt16 i608;	// 0
	UInt32 i610;	// 0
	UInt32 i614;	// kTelMgrVersion
	UInt16 i618;	// 0
	UInt16 i620;	// 0
	UInt16 i622;	// 0
	MemPtr f624;
	MemPtr f628;
	MemPtr f632;
	MemPtr f636;
	MemPtr f640;
	MemPtr f644;
	MemPtr f648;
	MemPtr f652;
	MemPtr f656;
	// more to follow, which might or might not belong to the TelephonyMgr
} PdrvCallbackType;

The Palm OS calls with pdrvEntrySetProfile when the Telephony Manager Library starts up (to produce the PhoneRegistryDB and to install the default profiles) and when the user opens the Connection prefs panel (to restore the profiles). It has the following definition:

Connection Panel 
typedef struct
{
	UInt32 version;		// set to kTelMgrVersion
	UInt32 fileType;	// set to sysFileTTelTaskSerial
	UInt32 creator;		// set to sysFileCTelTaskSerial
	Char modelName[32];	// phone model; for display when editing a profile
	UInt8 editConfig;	// set 1 to show details on the profile editor, 0 to hide
	UInt8 editDriver;	// set 2 to show details on phone panel, 0 to hide
	UInt16 numConfigs;	// 1 to 8
	PhoneProfileType config[8];
} PdrvPhoneProfileType;

If the editDriver attribute of the PdrvPhoneProfileType structure is set to 2, the Phone prefs panel calls with pdrvEntrySetProfile when the user taps the Details button. The associated structure is basically the profile of the chosen configuration with the contents filled in:

Phone Panel 
typedef struct
{
	UInt16 unknown;	// zero
	PhoneProfileType config;
} PdrvDetailsType;

The common structure used by all calls is a phone profile. Please refer to the Serial Manager for many of its parameters.

typedef struct
{
	Char configName[kCncProfileNameSize];
	UInt32 port;	// serPortxxxPort, sysFileCVirtIrComm, sysFileCVirtRfComm
	UInt32 baudRate;
	UInt32 serialPortFlags;
	UInt32 timeOut;
	UInt32 receiveTimeOut;
	Char initStr[mdmCmdBufSize];
	MemHandle unknownHandle;	// zero
	UInt16 unknownSize;		// zero
} PhoneProfileType;

Tools for development

Programming Tips

Valid XHTML 1.1! Copyright © 2000-04 by Alvin Mok. All rights reserved.