Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

73    Telephony Basic Services

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides reference material for the Telephony API, which you can use to interface with telephone systems and equipment. This chapter discusses the following topics:

The header file TelephonyMgr.h declares the telephony manager API. The header file TelephonyMgrType.h declares the data structures that you use with the telephony manager API.

For more information about using the telephony manager, see Chapter 10, "Telephony Manager," in Palm OS Programmer's Companion, vol. II, Communications.

Telephony Service Types ^TOP^

The telephony API organizes functions within sets called service sets. Each service set contains a related set of functions that may or may not be available on a particular mobile device or network. You can use the TelIs<ServiceSet>Available() function to determine if a service set is supported in the current environment, and you can use the TelIs<FunctionName>Supported() to determine if a specific function is supported in the current environment.

The telephony API documentation has been split into several chapters. Each chapter covers one or more of the service sets, as shown in Table 73.1

Table 73.1  Telephony service types 

Service prefix

Functionality

Chapter

Description

Tel

Basic

Chapter 73, "Telephony Basic Services."

Basic functions that are always available.

TelCfg

Configuration

Chapter 74, "Telephony Security and Configuration."

Allows configuration of the phone, including Short Message Services (SMS) configuration.

TelDtc

Data calls

Chapter 76, "Telephony Calls."

Functions for handling data calls.

TelEmc

Emergency calls

Chapter 76, "Telephony Calls."

Functions for handling emergency calls.

TelInf

Information

Chapter 73, "Telephony Basic Services."

Functions for retrieving information about the phone.

TelNwk

Network

Chapter 75, "Telephony Network."

Provides network oriented services, including authorization, signal level, search mode, and related operations.

TelOem

OEM

Chapter 73, "Telephony Basic Services."

Provides OEMs with the ability to incorporate custom functionality.

TelPhb

Phone book

Chapter 78, "Telephony Phone Book."

Functions for managing the phone book.

TelPow

Power

Chapter 73, "Telephony Basic Services."

Provides access to power supply level.

TelSms

Short Message Service

Chapter 77, "Telephony SMS."

Addresses the SMS, including functions for reading, sending, replying to, and deleting short messages.

TelSnd

Sound

Chapter 73, "Telephony Basic Services."

Functions for playing key tones on and muting the phone.

TelSpc

Speech calls

Chapter 76, "Telephony Calls."

Function for handling voice calls, including dual tone modulated frequency (DTMF) sounds.

TelSty

Security

Chapter 74, "Telephony Security and Configuration."

Supports PIN code management for access to phone and Subscriber Identity Module (SIM) security-related features.

Telephony Data Structures ^TOP^

This section describes the data structures used with the basic services portion of the telephony API.

TelAppID Typedef ^TOP^

Purpose

The type for a telephone application attachment identifier. The application attachment identifier uniquely identifies your application. You obtain this value from the TelOpen() and pass it to other Telephony Manager calls.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef UInt32 TelAppID

TelEventType Struct ^TOP^

Purpose

The TelGetEvent() and TelGetTelephonyEvent() functions both return a TelEventType structure to provide information about a telephony-related event.

You call the TelGetEvent() function to retrieve telephony and other events.

You call the TelGetTelephonyEvent() function to retrieve only telephony events. This function does not consume non-telephony events.

Note that the first five fields of the TelEventType structure are the same as the first five fields of the EventType structure, which is described in Chapter 2, "Palm OS Events."

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelEventType {
   eventsEnum eType;
   Boolean penDown;
   UInt8 tapCount;
   Int16 screenX;
   Int16 screenY;
   UInt16 functionId;
   UInt16 transId;
   MemPtr *paramP;
   Err returnCode;
} TelEventType

Fields

eType
kTelTelephonyEvent to specify that a telephony event has occurred. nilEvent to specify that no telephy event has occurred.
penDown
true if the pen was down at the time of the event, and false if the pen was up.
Note that this field is not filled in for telephony events.
tapCount
The number of taps received at this location.
Note that this field is not filled in for telephony events.
screenX
Window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
Note that this field is not filled in for telephony events.
screenY
Window-relative position of the pen in standard coordinates (number of coordinates from the top left of the window).
Note that this field is not filled in for telephony events.
functionId
One of the Message Identifier Constants constants, that identifies the asynchronous function whose completion generated this event.
transId
The transaction ID that was associated with this asynchronous function call.
paramP
A pointer to a parameter structure that was passed when an asynchronous call was made.
returnCode
The return code of the asynchronously called function. The value of this field is errNone if the function succeeded, or an error code if the function failed.

TelGetCallStateType Struct ^TOP^

Purpose

The TelGetCallState() function uses the TelGetCallStateType structure to retrieve information about the current state of the connected phone.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelGetCallStateType {
   UInt8 state;
   UInt8 callType;
   UInt8 callServiceType;
   UInt8 numberSize;
   Char *number;
} TelGetCallStateType

Fields

← state
Filled in with one of the Telephone Call State Constants, which indicates the current state of the telephone call.
← callType
Filled in with one of the Telephone Call Type Constants, which indicates the call type of the current telephone call.
← callServiceType
Filled in with one of the Telephone Call Service Type Constants, which indicates the call service type of the current telephone call.

↔ numberSize

The size of the number string buffer. When the structure is used as an input parameter, this is the allocated size, in bytes, of the buffer.
Upon return, this is the actual size of the string, including the null terminator character. If the number buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error.
← number
A buffer into which the telephone number string is stored.
When the structure describes an incoming telephone call, this is the incoming telephone number. When the structure describes an outgoing telephone call, this is the telephone number that has been called.
Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error.

TelInfGetInformationType Struct ^TOP^

Purpose

The TelInfGetInformation() function uses the TelInfGetInformationType structure to retrieve information about the phone with which you are communicating.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelInfGetInformationType {
   UInt8 infoType;
   UInt16 size;
   Char *value;
} TelInfGetInformationType

Fields

→ infoType
The type of information to retrieve. This must be one of the Information Type Constants.
↔ size
The size of the value buffer. When the structure is used as an input parameter, this is the allocated size, in bytes, of the buffer.
Upon return, this is the actual size of the buffer. If the value buffer is too small to contain all of the retrieved information, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error.
← value
A buffer into which the information is stored.

TelNotificationType Struct ^TOP^

Purpose

Holds information for Telephony Manager notifications.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelNotificationType {
   UInt32 notificationData;
   UInt32 notificationData2;
   UInt32 timeStamp;
   UInt16 notificationId;
   UInt8 priority;
} TelNotificationType

Fields

notificationData
Various notification-specific data.
notificationData2
Various notification-specific data.
timeStamp
Time the event occurred, expressed as the number of seconds elapsed since 12:00 A.M. on January 1, 1904.
notificationId
Identifies the type of event that occurred. One of the constants described in "Notification Identifiers."
priority
One of the constants described in "Notification Priorities."

Comments

This structure is passed for the value of the notifyDetailsP field in the notification parameter block of a kTelTelephonyNotification.

TelOemCallType Struct ^TOP^

Purpose

You use the TelOemCallType to specify a TelOemCall() function.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelOemCallType {
   UInt32 OemId;
   UInt8 funcId;
   void *paramP;
} TelOemCallType

Fields

→ OemID
The unique ID of the OEM function set.
→ funcID
The ID of the function within the OEM function set.
↔ paramP
A pointer to a parameter block that is passed to the OEM function. The OEM function might modify some of the fields in the parameter block.

TelSendCommandStringType Struct ^TOP^

Purpose

The TelSendCommandString() function uses the TelSendCommandStringType structure to send a command string.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelSendCommandStringType {
   Char *commandString;
   Char *resultString;
   UInt16 resultSize;
   UInt32 timeOut;
} TelSendCommandStringType

Fields

→ commandString
The command string to send.
← resultString
The result string.
↔ resultSize
The size of the resultString string buffer. When the structure is used as an input parameter, this is the allocated size, in bytes, of the buffer.
Upon return, this is the actual size of the string, including the null terminator character. If the resultString buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error.
→ timeOut
The number of milliseconds before timing out.

TelSndPlayKeyToneType Struct ^TOP^

Purpose

The TelSndPlayKeyTone() function uses the TelSndPlayKeyToneType structure to specify a key tone.

Declared In

TelephonyMgrTypes.h

Prototype 

typedef struct _TelSndPlayKeyToneType {
   UInt8 keycode;
   UInt8 type;
} TelSndPlayKeyToneType

Fields

→ keycode
The keycode of the key tone to play. This should be one of the values declared under "Keycode Constants."
→ type
The tone type. This should be one of the following constants:
0x00
Play the key sound as a single tone.
0x01
Play the key sound as a multiple tones.

Telephony Constants ^TOP^

Battery Status Constants ^TOP^

Purpose

The battery status constants provide information about the phone's battery.

Declared In

TelephonyMgr.h

Constants

#define kTelPowBatteryPowered 0
The phone is powered by a battery.
#define kTelPowBatteryNotPowered 1
The phone has a battery connected to it, but is not using that battery.
#define kTelPowNoBattery 2
The phone does not have a battery connected to it.
#define kTelPowBatteryFault 3
The phone has a recognized power fault; calls are currently inhibited.

Keycode Constants ^TOP^

Purpose

The keycode constants represent the keys on a telephony keypad.

Declared In

The keypad keys are identified by numeric value; there are currently no symbolic constants declared to represent these values.

Constants

0x00 - 0x09
The numeric keys 0 through 9 on the phone keypad.
0x23
The POUND(#) key on the phone keypad.
0x2A
The STAR(*) key on the phone keypad.
0x45
The SEND key on the phone keypad.
0x46
The END key on the phone keypad.
0x47
The CLEAR key on the phone keypad.
0x48
The SAVE key on the phone keypad.

Telephone Call State Constants ^TOP^

Purpose

The TelGetCallStateType structure uses the telephone call state constants to encode the current state of the connected telephone call.

Declared In

TelephonyMgr.h

Constants

#define kTelCallIdle 0
The connection is idle.
#define kTelCallConnecting 1
A telephone call is currently connecting.
#define kTelCallConnected 2
A telephone call is currently connected.
#define kTelCallRedial 3
A telephone call is being re-dialed.
#define kTelCallIncoming 4
A telephone call is currently incoming.
#define kTelCallIncomingAck 5
An incoming telephone call is currently being acknowledged.
#define kTelCallDisconnecting 6
A telephone call is being disconnected.

Telephone Call Type Constants ^TOP^

Purpose

The TelGetCallStateType structure uses the telephone call type constants to encode the type of the current telephone call.

Declared In

TelephonyMgr.h

Constants

#define kTelCallTypeOutgoing 0
An outgoing telephone call.
#define kTelCallTypeIncoming 1
An incoming telephone call.

Telephone Call Service Type Constants ^TOP^

Purpose

The TelGetCallStateType structure uses the telephone call service type constants to encode the service type of the current telephone call.

Declared In

TelephonyMgr.h

Constants

#define kTelCallServiceVoice 0
A voice telephone call.
#define kTelCallServiceData 1
A data telephone call.

Error Code Constants ^TOP^

Purpose

The Telephony Manager functions return the error code constants shown in the following table to indicate their status.

Declared In

TelephonyMgr.h

Constants

#define telErrorClass (appErrorClass + 0x100)
Base value for Telephony Manager errors.
#define telErrBufferSize (telErrorClass | 0x0A)
One of the buffers used to retrieve data is too small.
#define telErrCodingScheme (telErrorClass | 0x24)
The coding scheme specified for the short message is not valid.
#define telErrCommandFailed (telErrorClass | 0x0E)
The specified command could not be performed by the phone. Check the phone driver.
#define telErrEntryNotFound (telErrorClass | 0x1C)
The specified entry was not found.
#define telErrFeatureNotSupported (telErrorClass | 0x0B)
The specified feature is not supported by the phone or network.
#define telErrGenericDrvNotFound (telErrorClass | 0x2A)
The generic driver could not be found.
#define telErrInvalidAppId (telErrorClass | 0x07)
The specified application ID is not valid.
#define telErrInvalidDial (telErrorClass | 0x1F)
The dial string contains an invalid character.
#define telErrInvalidIndex (telErrorClass | 0x1B)
The index specified for accessing a value in storage is incorrect.
#define telErrInvalidParameter (telErrorClass | 0x22)
A parameter is not valid.
#define telErrInvalidString (telErrorClass | 0x1E)
The text string contains an invalid character.
#define telErrLibStillInUse (telErrorClass | 0x34)
The shared lib is currently being used by another application. Do not unload it!
#define telErrLimitedCompatibility (telErrorClass | 0x32)
Current driver is only partially compatible with the connected phone.
#define telErrMemAllocation (telErrorClass | 0x03)
A memory allocation error occurred.
#define telErrMsgAllocation (telErrorClass | 0x01)
The telephony messages pool is empty; a message could not be allocated.
#define telErrNetworkTimeOut (telErrorClass | 0x21)
The network did not reply within the standard time delay amount.
#define telErrNoNetwork (telErrorClass | 0x20)
There is no network available.
#define telErrNoSIMInserted (telErrorClass | 0x11)
The SIM card is not inserted.
#define telErrNoSpecificDrv (telErrorClass | 0x2B)
A specific driver was not specified.
#define telErrNotInstalled (telErrorClass | 0x2E)
The shared library could not be installed.
#define telErrPassword (telErrorClass | 0x17)
The password is not correct.
#define telErrPhoneCodeRequired (telErrorClass | 0x10)
A phone code is required.
#define telErrPhoneComm (telErrorClass | 0x0C)
The communication link with the phone is down.
#define telErrPhoneMemAllocation (telErrorClass | 0x1A)
The phone's memory is full.
#define telErrPhoneMemFailure (telErrorClass | 0x1D)
The phone encountered a memory error.
#define telErrPhoneNumber (telErrorClass | 0x25)
One of the following errors has occurred: the phone number is wrong, the SMS center is not valid, or the receiver phone number is wrong for the SMS.
#define telErrPhoneReply (telErrorClass | 0x0D)
The phone reply syntax is incorrect. Check the phone driver.
#define telErrPhoneToSIMPINRequired (telErrorClass | 0x28)
A phone 2 SIM PIN code is required
#define telErrPIN2Required (telErrorClass | 0x18)
A PIN2 code is required.
#define telErrPINRequired (telErrorClass | 0x12)
A PIN code is required.
#define telErrProfileConflict (telErrorClass | 0x33)
Current profile conflicts with the requested profile.
#define telErrPUK2Required (telErrorClass | 0x19)
A PUK2 code is required.
#define telErrPUKRequired (telErrorClass | 0x13)
A PUK code is required.
#define telErrResultBusyResource (telErrorClass | 0x06)
A resource is busy.
#define telErrResultTimeOut (telErrorClass | 0x04)
A time-out was reached.
#define telErrResultUserCancel (telErrorClass | 0x05)
The user cancelled the action.
#define telErrSecurity (telErrorClass | 0x09)
Access to the phone was not granted.
#define telErrSettings (telErrorClass | 0x30)
The telephony settings are not valid; this is due to 1) the Phone Panel preferences do not exist, or 2) the Telephony Profile is not correctly set.
#define telErrSIMBusy (telErrorClass | 0x15)
The SIM could not reply.
#define telErrSIMFailure (telErrorClass | 0x14)
The SIM is not working properly.
#define telErrSIMWrong (telErrorClass | 0x16)
The SIM is not accepted by the phone.
#define telErrSpcCallError (telErrorClass | 0x2D)
The voice telephone call encountered an error.
#define telErrSpcLineIsBusy (telErrorClass | 0x0F)
The voice telephone call failed.
#define telErrSpcLineIsReleased (telErrorClass | 0x2C)
The voice telephone call has been released.
#define telErrSpecificDrvNotFound (telErrorClass | 0x29)
The specified driver could not be found.
#define telErrTooManyApps (telErrorClass | 0x08)
The applications table is full.
#define telErrTTaskNotFound (telErrorClass | 0x35)
The Telephony Task could not be found.
#define telErrTTaskNotRunning (telErrorClass | 0x27)
The Telephony Task is not running.
#define telErrUnavailableValue (telErrorClass | 0x31)
The requested value can not be retrieved at the specified time. This is usually due to a TelSpcGetCallerNumber request when there is no active line.
#define telErrUnknown (telErrorClass | 0x02)
An unknown telephony manager error occurred.
#define telErrValidityPeriod (telErrorClass | 0x23)
The validity period specified for the short message is not valid.
#define telErrValueStale (telErrorClass | 0x26)
The information could not be retrieved; a copy of the most recently retrieved value has been returned instead.
#define telErrVersion (telErrorClass | 0x2F)
The shared library version does not match the version associated with the application.

Information Type Constants ^TOP^

Purpose

The TelInfGetInformationType structure uses the information type constants to encode the type of information to retrieve about the phone.

Declared In

TelephonyMgr.h

Constants

#define kTelInfPhoneBrand 0
The brand name of the phone.
#define kTelInfPhoneModel 1
The model number of the phone.
#define kTelInfPhoneRevision 2
The revision number of the phone.

Message Identifier Constants ^TOP^

The message identifier constants are used with asynchronous calls to identify which telephony function is being or has been called. The TelMessages enumeration defines a constant for each function name.

Each message identifier constant has the form:

kfunctionNameMessage

where functionName is replaced by a function name.

The following table shows examples of message identifier constants. For a complete list, see the TelephonyMgrTypes.h file.

Constant

Function

kTelGetCallStateMessage

TelGetCallState()

kTelNwkSelectNetworkMessage

TelNwkSelectNetwork()

kTelSmsReadMessageMessage

TelSmsReadMessage()

TelServices Enum ^TOP^

Purpose

The service set constants specify a set of API services.

Declared In

TelephonyMgrTypes.h

Constants

kTelNwkServiceId
The network service set.
kTelStyServiceId
The security service set.
kTelPowServiceId
The power service set.
kTelCfgServiceId
The configuration service set.
kTelSmsServiceId
The short message service set.
kTelEmcServiceId
The emergency telephone call service set.
kTelSpcServiceId
The speech telephone call service set.
kTelDtcServiceId
The data telephone call service set.
kTelPhbServiceId
The phone book service set.
kTelOemServiceId
The OEM service set.
kTelSndServiceId
The sound service set.
kTelInfServiceId
The information service set.

Notification Priorities ^TOP^

Purpose

Notification priorities used in the priority field of the TelNotificationType structure.

Declared In

TelephonyMgr.h

Constants

#define kTelCallNotificationPriority 0
Voice call.
#define kTelSmsNotificationPriority 1
SMS message.

Call Classes ^TOP^

Purpose

Not currently used.

Declared In

TelephonyMgr.h

Constants

#define kTelSpeechCallClass 0
#define kTelDataCallClass 1
#define kTelFaxCallClass 2

Telephony Manager Database ^TOP^

Purpose

Identifiers for the Telephony Manager database file.

Declared In

TelephonyMgr.h

Constants

#define kTelMgrDatabaseCreator sysFileCTelMgrLib
The creator ID used for the Telephony Manager library's database file.
#define kTelMgrDatabaseType sysFileTLibrary
The type used for the Telephony Manager's database file.
#define kTelMgrLibName "Telephony Library"
The name of the Telephony Manager database.

Version Constants ^TOP^

Purpose

Version of the Telephony Manager and SMS API.

Declared In

TelephonyMgr.h

Constants

#define kTelMgrVersion sysMakeROMVersion(kTelMgrVersionMajor, kTelMgrVersionMinor, kTelMgrVersionFix, sysROMStageBeta, kTelMgrVersionBuild)
The Telephony Manager version information.
#define kTelMgrVersionMajor 1
The major version number.
#define kTelMgrVersionMinor 0
The minor version number.
#define kTelMgrVersionFix 3
The fix number.
#define kTelMgrVersionBuild 0
The build number.
#define kTelSmsAPIVersion 0x0001
Version of the SMS API.

Comments

IMPORTANT: The shared library version number differs depending on which version of Palm OS you are targeting. This means that you may need to change how the kTelMgrVersion constant is constructed. If you are targeting Palm OS version 4.2, the minor version is 1 and the fix level is 0. For Palm OS Garnet, the minor version number is 0 and the fix level is 3. In TelMgr.h, make sure that the appropriate values of kTelMgrVersionMinor and kTelMgrVersionFix are un-commented, and that the values that don't apply are commented out.

Events and Notifications ^TOP^

Purpose

Identifiers for the events and notifications broadcast by the Telephony Manager.

Declared In

TelephonyMgr.h

Constants

#define kTelTelephonyEvent 0x1200
An event posted to the event queue when an asynchronously called Telephony Manager function completes. The TelEventType structure contains the information about the event.
#define kTelTelephonyNotification 'tmgr'
Identifies a notification broadcast by the Telephony Manager, which occurs whenever telephony events occur. Applications interested in such events can register to receive this notification.
The notifyDetailsP field of the notification parameter block points to a TelNotificationType structure.

Miscellaneous Constants ^TOP^

Purpose

Other constants defined in TelephonyMgr.h.

Declared In

TelephonyMgr.h

Constants

#define kTelInfiniteDelay 0xFFFFFFFF
Specifies no time out on certain calls. This value is used internally by the Telephony Manager.
#define kTelInvalidAppId ((TelAppID)-1)
You can use this constant to initialize the telDescP parameter to the TelOpen() and TelOpenProfile() functions. Upon return, it contains a valid application identifier.
#define kTelLocationSeparator ';'
Used to separate tokens in a location string.
#define kTelSpcCallingLineId -1
#define kTelMaxPhoneNumberLen 30
The maximum length of a phone number.

Notification Identifiers Enum ^TOP^

Purpose

Identifies the type of telephony notification. These values are used in the id field of the TelNotificationType structure.

Declared In

TelephonyMgr.h

Constants

kTelSmsLaunchCmdIncomingMessage
Incoming SMS message. The actual message can be retrieved with TelSmsReadMessage() or TelSmsReadSubmittedMessages().
kTelSpcLaunchCmdIncomingCall
Incoming voice call. The call can be answered with TelSpcAcceptCall.
kTelSpcLaunchCmdCallerIDAvailable
Caller ID on an incoming call is available. The information can be retrieved with the TelSpcGetCallerNumber() function.
kTelSpcLaunchCmdCallReleased
A voice call has been released.
kTelSpcLaunchCmdCallBusy
Broadcast as a result of a TelSpcCallNumber() function call if the number that the application is attempting to call is busy.
kTelSpcLaunchCmdCallConnect
Broadcast as a result of a TelSpcCallNumber() function when the call is connected.
kTelSpcLaunchCmdCallError
Broadcast as a result of a TelSpcCallNumber() function if an error occurs or the user cancels the operation before the call can be connected.
kTelEmcLaunchCmdCallReleased
An emergency call has been released.
kTelEmcLaunchCmdCallBusy
Broadcast as a result of the TelEmcCall() function if the emergency call gets a busy signal.
kTelEmcLaunchCmdCallConnect
Broadcast as a result of the TelEmcCall() function when the call is connected.
kTelEmcLaunchCmdCallError
Broadcast as a result of the TelEmcCall() function if an error occurs or the user cancels the operation before the call can be connected.
kTelLastLaunchCode
Specifies the last notification constant in the enumeration.

Telephony Functions ^TOP^

This section describes the functions used with the basic services portion of the telephony API.

TelCancel Function ^TOP^

Purpose

Cancels an asynchronous function call.

Declared In

TelephonyMgr.h

Prototype 

Err TelCancel(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 iTransId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iTransId
The transaction ID associated with the function that you are cancelling.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function call was successfully cancelled. Returns the telErrCommandFailed error code if the function call could not be cancelled.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

functionId

kTelUrqCancelMessage

paramId

Points to the unsigned integer value passed to this function in the iTransId parameter.

This function cancels a pending asynchronous function call. You can cancel any asynchronous call except for an asynchronous call to the TelCancel function.

The function call that is cancelled returns the telErrUserCancel error code.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelClose Function ^TOP^

Purpose

Close the shared library.

Declared In

TelephonyMgr.h

Prototype 

Err TelClose(
   UInt16 iRefnum,
   TelAppID iAppId
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.

Returns

Returns an error code, or error none if the library was successfully closed. If the library is currently being used by another application, this function returns the telErrLibStillInUse error code.

Comments

Call this function when you are done with the telephony manager. You can only use this function synchronously.

If no other application is using the telephony manager, this function stops the Telephony task and releases any resources used by the telephony manager.

See Also

TelOpen()

TelClosePhoneConnection Function ^TOP^

Purpose

Closes down communications with the connected phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelClosePhoneConnection(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

A NULL pointer.

functionId

kTelUrqClosePhoneConnectionMessage

Call this function when you have finished communications with the phone and are ready to disconnect from it.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelOpenPhoneConnection()

TelGetCallState Function ^TOP^

Purpose

Retrieves the current telephone call state information.

Declared In

TelephonyMgr.h

Prototype 

Err TelGetCallState(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelGetCallStateType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a TelGetCallStateType structure that describes the state of the current telephone call.
On input, the numberSize field of this structure specifies the allocated size of the number buffer. Upon return, the numberSize field specifies the actual size of the telephone number, even if it was truncated to fit into the buffer.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the TelGetCallStateType structure passed to this function in the ioCallState parameter.

functionId

kTelGetCallStateMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Comments

This function retrieves information about the current telephone call state of the connection with the phone, and stores that information into the supplied TelGetCallStateType structure.

The current incoming or outgoing telephone call number is stored into the number field of the TelGetCallStateType structure referenced by ioCallStateP. If the number field buffer is too small to contain the complete telephone number, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The numberSize field of the structure is always updated to contain the actual size of the complete telephone number.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcAcceptCall(), TelSpcCallNumber()

TelGetEvent Function ^TOP^

Purpose

Retrieves events for applications that use the telephony manager.

Declared In

TelephonyMgr.h

Prototype 

void TelGetEvent(
   UInt16 iRefnum,
   TelAppID iAppId,
   EventPtr oEventP,
   Int32 iTimeOut
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oEventP
A pointer to a TelEventType structure. Upon return, the structure contains the event information, which you should use as described in the Comments section.
→ iTimeout
Maximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely).

Returns

Returns nothing.

Comments

This function retrieves both telephony and standard Palm OS® events. You must call this function to retrieve events in any application that is running in the UI task and using the telephony manager.

Upon return from this function, you need to test the type of the event by examining the oEventP->type field. If the event type is a telephony event, then you need to cast the pointer as follows to access the fields:

TelEventType *telEventP = (TelEventType *)oEventP;

This function calls both the EvtGetEvent() and TelGetTelephonyEvent() functions to retrieve the next event for your application.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

EvtGetEvent(), TelGetTelephonyEvent()

TelGetTelephonyEvent Function ^TOP^

Purpose

Retrieves telephony events only.

Declared In

TelephonyMgr.h

Prototype 

void TelGetTelephonyEvent(
   UInt16 iRefnum,
   TelAppID iAppId,
   EventPtr oEventP,
   Int32 iTimeOut
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oEventP
A pointer to a TelEventType structure. Upon return, the structure contains the event information.
→ iTimeout
Maximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely).

Returns

Returns nothing.

Comments

Use this function instead of the TelGetEvent() function when you only want to process telephony events.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

EvtGetEvent(), TelGetEvent()

TelInfGetInformation Function ^TOP^

Purpose

Retrieve brand, model, and revision information for the phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelInfGetInformation(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelInfGetInformationType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a TelInfGetInformationType structure.
On input, the infoType field of the structure contains the type of information that you want retrieved. The size field of this structure specifies the allocated size of the value buffer. Upon return, the size field specifies the actual size of the information that was retrieved, even if it was truncated to fit into the buffer.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the TelInfGetInformationType structure passed to this function in the ioInfoP parameter.

functionId

kTelInfGetInformationMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Comments

Call this function to retrieve information about the currently connected phone.

The retrieved information is stored into the value field of the TelInfGetInformationType referenced by ioInfoP structure. If the value field buffer is too small to contain the complete information, the value is truncated and this function returns the telErrBufferSize error. The size field of the structure is always updated to contain the actual size of the retrieved information.

Before using this function, you should verify that it is available by calling the TelIsInfServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelIsCfgServiceAvailable Macro ^TOP^

Purpose

Determines if the configuration service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsCfgServiceAvailable (
   iRefnum,
   iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelCfgServiceId

functionId

kTelUrqIsServiceAvailableMessage

You need to call this macro before calling any function in the configuration service set, which is the family of functions that begin with the TelCfg prefix.

The configuration service set functions are documented in Chapter 77, "Telephony SMS."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsDtcServiceAvailable Macro ^TOP^

Purpose

Determines if the data calls service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsDtcServiceAvailable (
   iRefnum,
   iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelDtcServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments l

You need to call this macro before calling any function in the data calls service set, which is the family of functions that begin with the TelDtc prefix.

The data calls service set functions are documented in Chapter 76, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsEmcServiceAvailable Macro ^TOP^

Purpose

Determines if the emergency calls service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsEmcServiceAvailable (
   iRefnum,
   iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelEmcServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the emergency calls service set, which is the family of functions that begin with the TelEmc prefix.

The emergency calls service set functions are documented in Chapter 76, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsInfServiceAvailable Macro ^TOP^

Purpose

Determines if the information service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsInfServiceAvailable (
   iRefnum,
   iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelInfServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the information service set, which is the family of functions that begin with the TelInf prefix.

The information service set functions are documented in this chapter.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsNwkServiceAvailable Macro ^TOP^

Purpose

Determines if the network service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsNwkServiceAvailable (
   iRefnum,
   iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelNwkServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the network service set, which is the family of functions that begin with the TelNwk prefix.

The network service set functions are documented in Chapter 75, "Telephony Network."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsOemServiceAvailable Macro ^TOP^

Purpose

Determines if the OEM service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsOemServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelOemServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the OEM service set, which is the family of functions that begin with the TelOem prefix.

The OEM service set functions are documented in this chapter.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsPhbServiceAvailable Macro ^TOP^

Purpose

Determines if the phone book service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsPhbServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelPhbServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the phone book service set, which is the family of functions that begin with the TelPhb prefix.

The phone book service set functions are documented in Chapter 78, "Telephony Phone Book."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsPhoneConnected Function ^TOP^

Purpose

Determines if a phone is connected.

Declared In

TelephonyMgr.h

Prototype 

Err TelIsPhoneConnected(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

A NULL pointer.

functionId

kTelUrqIsPhoneConnectedMessage

Comments

Call this function to determine if there is currently a phone connected.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelIsPowServiceAvailable Macro ^TOP^

Purpose

Determines if the power services set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsPowServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelPowServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the power service set, which is the family of functions that begin with the TelPow prefix.

The power service set functions are documented in this chapter.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsSmsServiceAvailable Macro ^TOP^

Purpose

Determines if the Short Message Service (SMS) service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsSmsServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelSmsServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the SMS service set, which is the family of functions that begin with the TelSms prefix.

The SMS service set functions are documented in Chapter 77, "Telephony SMS."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsSndServiceAvailable Macro ^TOP^

Purpose

Determines if the sound service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsSndServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelSndServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the sound service set, which is the family of functions that begin with the TelSnd prefix.

The sound service set functions are documented in this chapter.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsSpcServiceAvailable Macro ^TOP^

Purpose

Determines if the speech telephone call service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsSpcServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelSpcServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the speech telephone call service set, which is the family of functions that begin with the TelSpc prefix.

The speech telephone call service set functions are documented in Chapter 76, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelIsStyServiceAvailable Macro ^TOP^

Purpose

Determines if the security service set is available in the current environment.

Declared In

TelephonyMgr.h

Prototype 

#define TelIsStyServiceAvailable (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available, or an error code if not.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

kTelStyServiceId

functionId

kTelUrqIsServiceAvailableMessage

Comments

You need to call this macro before calling any function in the security service set, which is the family of functions that begin with the TelSty prefix.

The security service set functions are documented in Chapter 75, "Telephony Network."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

TelMatchPhoneDriver Function ^TOP^

Purpose

Determines if the currently selected driver matches the connected phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelMatchPhoneDriver(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure

transId

The transaction ID of the operation.

paramP

A NULL pointer.

functionId

kTelUrqMatchPhoneDriverMessage

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelOemCall Function ^TOP^

Purpose

Pass a call to an OEM function.

Declared In

TelephonyMgr.h

Prototype 

Err TelOemCall(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelOemCallType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a TelOemCallType structure that contains information about the OEM function call.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transID

matches the output value of the ioTransIdP parameter

functionId

matches the function ID in the TelOemCallType structure passed to this function in the ioParamP parameter

paramId

points to the TelOemCallType structure passed to this function in the ioParamP parameter
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Comments

Call this function to send a request to an OEM function. The calling function and the OEM function are responsible for coordinating the parameter block that is passed in the TelOemCallType structure.

Before using this function, you should verify that it is available by calling the TelIsOemServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelOpen Function ^TOP^

Purpose

Open the telephony manager API to initialize telephony services and launch the telephony task.

Declared In

TelephonyMgr.h

Prototype 

Err TelOpen(
   UInt16 iRefnum,
   UInt32 iVersnum,
   TelAppID *oAppIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iVersnum
The version number of the shared library for which your application was developed. See "Version Constants."
← oAppIdP
A pointer to an application ID value. Upon return, this is the application ID that you supply as a parameter to the any other telephony functions that you call.

Returns

Returns errNone if the function was successful or returns an error code if not successful. The following errors can occur:

  • the telephony task could not be found (telErrTTaskNotFound)
  • the telephony task could not be launched (telErrTTaskNotRunning)
  • the phone driver could not be found
  • the shared library version is not valid

Comments

You can only call this function synchronously. You must call this function or TelOpenProfile() before calling any other telephony manager functions.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelClose()

TelOpenPhoneConnection Function ^TOP^

Purpose

Open communications with the connected phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelOpenPhoneConnection(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

A NULL pointer.

functionId

kTelUrqOpenPhoneConnectionMessage

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelClosePhoneConnection()

TelOpenProfile Function ^TOP^

Purpose

Open the Telephony Manager API to initialize telephony services using a particular Connection Manager profile and launch the telephony task.

Declared In

TelephonyMgr.h

Prototype 

Err TelOpenProfile (
   UInt16 iRefnum,
   UInt32 iVersnum,
   UInt32 profileId,
   TelAppID *oAppIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iVersnum
The version number of the shared library for which your application was developed. The version number of the shared library for which your application was developed. See "Version Constants."
→ profileId
The Connection Manager profile ID to use to initialize the Telephony Manager. If 0, use the one currently specified in the Phone Preferences panel.
You cannot specify a specific phone profile if the Telephony Manager has already been initialized. If you do, the phone profile you specify must match the one used to initialize the Telephony Manager.
← oAppIdP
A pointer to an application ID value. Upon return, this is the application ID that you supply as a parameter to the any other telephony functions that you call.

Returns

errNone upon successful or one of the following values:

telErrVersion
The iVersnum parameter is invalid.
telErrProfileConflict
The Telephony Manager was already initialized with a phone profile that is different from that specified in profileId.
telErrTooManyApps
The Telephony Manager's application table is full.

Comments

You can only call this function synchronously, and it must be called before you call any other Telephony Manager functions. TelOpen calls this function.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelClose()

TelPowGetBatteryStatus Function ^TOP^

Purpose

Retrieves the status of the phone's battery.

Declared In

TelephonyMgr.h

Prototype 

Err TelPowGetBatteryStatus(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt8 *oStatusP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oStatusP
A pointer to an unsigned byte value. Upon return, this is the battery status value, which is one of the Battery Status Constants.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the unsigned integer value passed to this function in the oStatusP parameter.

functionId

kTelPowGetBatteryStatusMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by oStatusP remains in memory until the asynchronous call completes.

Comments

Before using this function, you should verify that it is available by calling the TelIsPowServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPowGetPowerLevel()

TelPowGetPowerLevel Function ^TOP^

Purpose

Retrieve the current level of the phone battery, as a percentage value.

Declared In

TelephonyMgr.h

Prototype 

Err TelPowGetPowerLevel(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt8 *oPowerP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
← oPowerP
A pointer to an unsigned byte value. Upon return, this is the battery percentage value.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the unsigned integer value passed to this function in the oPowerP parameter.

functionId

kTelPowGetPowerLevelMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by oPowerP remains in memory until the asynchronous call completes.

Comments

The returned percentage value is an integer value between 0 and 100.

Before using this function, you should verify that it is available by calling the TelIsPowServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelPowGetBatteryStatus()

TelPowSetPhonePower Function ^TOP^

Purpose

Turns the phone on or off.

Declared In

TelephonyMgr.h

Prototype 

Err TelPowSetPhonePower(
   UInt16 iRefnum,
   TelAppID iAppId,
   Boolean iPowerOn
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iPowerOn
Set to true to turn the phone on, and set to false to turn the phone off.

Returns

Returns errNone if the function was successful and an error code if not.

Comments

This function can only be called synchronously.

Before using this function, you should verify that it is available by calling the TelIsPowServiceAvailable() macro.

This function corresponds to the kTelPowSetPhonePowerMessage function ID value.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelSendCommandString Function ^TOP^

Purpose

Sends a command string to the phone or to the network.

Declared In

TelephonyMgr.h

Prototype 

Err TelSendCommandString(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelSendCommandStringType *ioParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioParamP
A pointer to a command string structure of type TelSendCommandStringType.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the TelSendCommandStringType structure passed to this function in the ioParam parameter.

functionId

Matches the function ID in the TelSendCommandStringType referenced by the ioParamP structure.
WARNING! When using this function asynchronously, you must ensure that the structure referenced by ioParamP remains in memory until the asynchronous call completes.

Compatibility

Implemented only if 4.0 New Feature Set is present.

TelSndMute Function ^TOP^

Purpose

Mute or un-mute an active telephone call.

Declared In

TelephonyMgr.h

Prototype 

Err TelSndMute(
   UInt16 iRefnum,
   TelAppID iAppId,
   Boolean iMuteOn,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iMuteOn
Set to true to mute the telephone call, or set to false to unmute the telephone call.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the Boolean value passed to this function in the iMuteOn parameter.

functionId

kTelSndMuteMessage

Comments

Before using this function, you should verify that it is available by calling the TelIsSndServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSndPlayKeyTone()

TelSndPlayKeyTone Function ^TOP^

Purpose

Play a keytone sound on the phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelSndPlayKeyTone(
   UInt16 iRefnum,
   TelAppID iAppId,
   TelSndPlayKeyToneType *iParamP,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ iParamP
A pointer to a TelSndPlayKeyToneType structure that describes the tone to play.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

Points to the TelSndPlayKeyToneType structure passed to this function in the iKeyToneP parameter.

functionId

kTelSndPlayKeyToneMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by iParamP remains in memory until the asynchronous call completes.

Comments

Before using this function, you should verify that it is available by calling the TelIsSndServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSndStopKeyTone()

TelSndStopKeyTone Function ^TOP^

Purpose

Stop the playing of a keytone sound on the phone.

Declared In

TelephonyMgr.h

Prototype 

Err TelSndStopKeyTone(
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the function was successful or returns an error code if not successful.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone upon success or an error code upon failure.

transId

The transaction ID of the operation.

paramP

A NULL pointer.

functionId

kTelSndStopKeyToneMessage

Comments

Before using this function, you should verify that it is available by calling the TelIsSndServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSndPlayKeyTone()

TelUnblockNotifications Function ^TOP^

Purpose

Requests that any pending notifications be sent.

Declared In

TelephonyMgr.h

Prototype 

Err TelUnblockNotifications (
   UInt16 iRefnum
)

Parameters

→ iRefnum
The telephony library reference number.

Returns

Always returns errNone.

Comments

You can only call this function synchronously.

As the Telephony Manager receives notifications from the phone driver, it queues them up in priority order and sends them as deferred notifications. Normally, there are no pending notifications in the queue. You should only need to call this function in an error situation if you want to ensure that any pending notification be sent.

See Also

"Notification Identifiers"

Feature Support Functions ^TOP^

This section describes the functions that you can call to determine if a specific feature or function is supported in the current operating environment.

TelIsFunctionSupported Function ^TOP^

Purpose

Checks if a function is supported by the phone, driver, and network.

Declared In

TelephonyMgr.h

Prototype 

Err TelIsFunctionSupported (
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 functionId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ functionId
Identifier of the function to check. Specify one of the Message Identifier Constants.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the specified function is supported.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the specified function is supported, or an error code if not.

transId

The transaction ID of the operation.

paramP

The function ID of the function for which you are testing. For example, if you call TelIsCfgGetSmsCenterSupported, the value of this field is kTelCfgGetSmsCenterMessage.

The function ID value for each function is described in the documentation for the function.

functionId

kTelUrqIsFunctionSupportedMessage

Comments

The TelephonyMgr.h header file also defines a series of macros that call this function, passing in the appropriate function identifier. These macros have the form TelIsFunctionNameSupported(telDesc).

TelIs<FunctionName>Supported Macro ^TOP^

Purpose

Determines if the specified function is supported.

Declared In

TelephonyMgr.h

Prototype 

#define TelIs<FunctionName>Supported (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the specified function is supported.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the specified function is supported, or an error code if not.

transId

The transaction ID of the operation.

paramP

The function ID of the function for which you are testing. For example, if you call TelIsCfgGetSmsCenterSupported, the value of this field is kTelCfgGetSmsCenterMessage.

The function ID value for each function is described in the documentation for the function.

functionId

kTelUrqIsFunctionSupportedMessage

Comments

This is a family of synchronous macros that test if a specific function is available in the current environment.

To use the macro, substitute a function name for the <FunctionName> portion of the macro name. You can substitute any Telephony Manager function name; for a complete list of the Telephony Manager functions, see "Summary of Telephony Manager" in Palm OS Programmer's Companion, vol. II, Communications.

For example, to determine if the TelNwkGetSignalLevel() function is available in the current environment, call the TelIsNwkGetSignalLevelSupported macro.

NOTE: A service set can be available without all of its functions being available. Thus, if the TelIs<ServiceSet>Available() macro returns true for a specific service set, you know that the service set is available, but you need to call TelIs<FunctionName>Supported() to determine if a specific function is available.

This macro corresponds to the kTelUrqIsFunctionSupportedMessage function ID value.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<ServiceSet>Available()

TelIsServiceAvailable Function ^TOP^

Purpose

Checks if a service set (group of related functions) is supported by the phone, driver, and network.

Declared In

TelephonyMgr.h

Prototype 

Err TelIsServiceAvailable (
   UInt16 iRefnum,
   TelAppID iAppId,
   UInt16 serviceId,
   UInt16 *ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
→ serviceId
Identifier of the service set to check. Specify one of the TelServices constants.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

The service ID of the service set for which you are testing. For example, if you call TelIsCfgServiceAvailable, the value of this field is kTelCfgServiceId.

The service ID is one of the TelServices constants.

functionId

kTelUrqIsServiceAvailableMessage

Comments

The TelephonyMgr.h header file also defines a series of macros that call this function, passing in the appropriate service set identifier. These macros have the form TelIsServiceNameServiceAvailable(telDesc).

TelIs<ServiceSet>Available Macro ^TOP^

Purpose

Determines if the specified service set is available.

Declared In

TelephonyMgr.h

Prototype 

#define TelIs<ServiceSet>Available (
   iRefnum,
    iAppId,
   ioTransIdP
)

Parameters

→ iRefnum
The telephony manager library reference number.
→ iAppId
The telephone application attachment identifier for your application.
↔ ioTransIdP
Set the value of this parameter to NULL to cause the function to execute synchronously.
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation.

Synchronous Result

Returns errNone if the service set is available.

Asynchronous Result

The following fields are updated in the TelEventType event that is sent when the operation completes:

returnCode

errNone if the service set is available, or an error code if not.

transId

The transaction ID of the operation.

paramP

The service ID of the service set for which you are testing. For example, if you call TelIsCfgServiceAvailable, the value of this field is kTelCfgServiceId.

The service ID is one of the TelServices constants.

functionId

kTelUrqIsServiceAvailableMessage

Comments

This is a family of synchronous macros that test if a specific service set is available. You must call the appropriate set availability function before calling a function in the set.

NOTE: A service set can be available without all of its functions being available. You can use this macro to determine the availability of a specific service set, which you might use to determine the configuration of your applications' user interface. To test if a specific function is supported, use the TelIs<FunctionName>Supported() macro.

You can call these specific macros to determine if the service set is available:

Each of these macros corresponds to the kTelUrqIsServiceSupportedMessage function ID value.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index