Telephony Basic Services
 

 < Home   < Developers   < Development Support   < Documentation

69 Telephony Basic Services


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part III: Communications

69 Telephony Basic Services

Telephony Service Types

Telephony Data Structures

TelEventType

TelCallStateType

TelInfGetformationType

TelOemCallType

TelSendCommandStringType

TelSndPlayKeyToneType

Telephony Constants

Battery Status Constants

Telephone Call State Constants

Telephone Call Type Constants

Telephone Call Service Type Constants

Error Code Constants

Information Type Constants

Keycode Constants

Key Sound Type Constants

Message Identifier Constants

Service Set Constants

Telephony Functions

TelCancel

TelClose

TelClosePhoneConnection

TelGetCallState

TelGetEvent

TelGetTelephonyEvent

TelInfGetInformation

TelIsCfgServiceAvailable

TelIsDtcServiceAvailable

TelIsEmcServiceAvailable

TelIsInfServiceAvailable

TelIsNwkServiceAvailable

TelIsOemServiceAvailable

TelIsPhbServiceAvailable

TelIsPhoneConnected

TelIsPowServiceAvailable

TelIsSmsServiceAvailable

TelIsSndServiceAvailable

TelIsSpcServiceAvailable

TelIsStyServiceAvailable

TelMatchPhoneDriver

TelOemCall

TelOpen

TelOpenPhoneConnection

TelPowGetBatteryStatus

TelPowGetPowerLevel

TelPowSetPhonePower

TelSendCommandString

TelSndMute

TelSndPlayKeyTone

TelSndStopKeyTone

Feature Support Functions

TelIs<FunctionName>Supported

TelIs<ServiceSet>Available

       

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:

Telephony Data Structures

Telephony Constants

Telephony Functions

Feature Support Functions

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 8, "Telephony Manager" in the Palm OS Programmer's Companion.

Telephony Service Types

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 69.1
Table 69.1 Telephony service types 
Service prefix
Functionality
Chapter
Description
Tel
Basic
Basic functions that are always available.
TelCfg
Configuration
Allows configuration of the phone, including Short Message Services (SMS) configuration.
TelDtc
Data calls
Functions for handling data calls.
TelEmc
Emergency calls
Functions for handling emergency calls.
TelInf
Information
Functions for retrieving information about the phone.
TelNwk
Network
Provides network oriented services, including authorization, signal level, search mode, and related operations.
TelOem
OEM
Provides OEMs with the ability to incorporate custom functionality.
TelPhb
Phone book
Functions for managing the phone book.
TelPow
Power
Provides access to power supply level.
TelSms
Short Message Service
Addresses the SMS, including functions for reading, sending, replying to, and deleting short messages.
TelSnd
Sound
Functions for playing key tones on and muting the phone.
TelSpc
Speech calls
Function for handling voice calls, including dual tone modulated frequency (DTMF) sounds.
TelSty
Security
Supports PIN code management for access to phone and Subscriber Identity Module (SIM) security-related features.

Telephony Data Structures

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

New TelEventType

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.

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

Field Descriptions

eType
One of the eventsEnum constants. Specifies the type of the event.
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. This value is used mainly by text fields. When the user taps in a text field, two taps selects a word, and three taps selects the entire line.

Note that this field is not filled in for telephony events.
screenX
Window-relative position of the pen in pixels (number of pixels 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 pixels (number of pixels from the top left of the window).

Note that this field is not filled in for telephony events.
functionId
The ID of the message associated with the function call, which specifies the telephony manager function that 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.

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 3, "Palm OS Events."

New TelCallStateType

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

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

Field Descriptions

<-
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.

New TelInfGetformationType

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

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

Field Descriptions

->
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.

New TelOemCallType

You use the TelOemCallType to specify a TelOemCall function.

typedef struct _TelOemCallType 
{ 
  UInt32  OemID; 
  UInt8   funcID; 
  void    *paramP; 
} TelOemCallType; 

Field Descriptions

->
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.

New TelSendCommandStringType

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

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

Field Descriptions

->
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.

New TelSndPlayKeyToneType

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

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

Field Descriptions

->
keycode
The keycode of the key tone to play. This must be one of the Keycode Constants.
->
type
The tone type. This must be one of the Key Sound Type Constants.

Telephony Constants

This section describes the data structures used with the basic services portion of the telephony API, which include the following constant types:

Battery Status Constants

Telephone Call State Constants

Telephone Call Type Constants

Telephone Call Service Type Constants

Error Code Constants

Information Type Constants

Keycode Constants

Key Sound Type Constants

Message Identifier Constants

Service Set Constants

Battery Status Constants

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

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

Telephone Call State Constants

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

Constant
Value
Description
kTelCallIdle
0x00
The connection is idle.
kTelCallConnecting
0x01
A telephone call is currently connecting.
kTelCallConnected
0x02
A telephone call is currently connected.
kTelCallRedial
0x03
A telephone call is being re-dialed.
kTelCallIncoming
0x04
A telephone call is currently incoming.
kTelCallIncomingAck
0x05
An incoming telephone call is currently being acknowledged.
kTelCallDisconnecting
0x06
A telephone call is being disconnected.

Telephone Call Type Constants

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

Constant
Value
Description
kTelCallTypeOutgoing
0x00
An outgoing telephone call.
kTelCallTypeIncoming
0x01
An incoming telephone call.

Telephone Call Service Type Constants

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

Constant
Value
Description
kTelCallServiceVoice
0x00
A voice telephone call.
kTelCallServiceData
0x01
A data telephone call.

Error Code Constants

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

Constant
Description
telErrBufferSize
One of the buffers used to retrieve data is too small.
telErrCodingScheme
The coding scheme specified for the short message is not valid.
telErrCommandFailed
The specified command could not be performed by the phone. Check the phone driver.
telErrEntryNotFound
The specified entry was not found.
telErrFeatureNotSupported
The specified feature is not supported by the phone or network.
telErrGenericDrvNotFound
The generic driver could not be found.
telErrInvalidAppId
The specified application ID is not valid.
telErrInvalidDial
The dial string contains an invalid character.
telErrInvalidIndex
The index specified for accessing a value in storage is incorrect.
telErrInvalidParameter
A parameter is not valid.
telErrInvalidString
The text string contains an invalid character.
telErrLibStillInUse
The shared lib is currently being used by another application. Do not unload it!
telErrMemAllocation
A memory allocation error occurred.
telErrMsgAllocation
The telephony messages pool is empty; a message could not be allocated.
telErrNetworkTimeOut
The network did not reply within the standard time delay amount.
telErrNoNetwork
There is no network available.
telErrNoSIMInserted
The SIM card is not inserted.
telErrNoSpecificDrv
A specific driver was not specified.
telErrNotInstalled
The shared library could not be installed.
telErrPassword
The password is not correct.
telErrPhoneCodeRequired
A phone code is required.
telErrPhoneComm
The communication link with the phone is down.
telErrPhoneMemAllocation
The phone's memory is full.
telErrPhoneMemFailure
The phone encountered a memory error.
telErrPhoneNumber
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.
telErrPhoneReply
The phone reply syntax is incorrect. Check the phone driver.
telErrPhoneToSIMPINRequired
A phone 2 SIM PIN code is required
telErrPIN2Required
A PIN2 code is required.
telErrPINRequired
A PIN code is required.
telErrPUK2Required
A PUK2 code is required.
telErrPUKRequired
A PUK code is required.
telErrResultBusyResource
A resource is busy.
telErrResultTimeOut
A time-out was reached.
telErrResultUserCancel
The user cancelled the action.
telErrSecurity
Access to the phone was not granted.
telErrSettings
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.
telErrSIMBusy
The SIM could not reply.
telErrSIMFailure
The SIM is not working properly.
telErrSIMWrong
The SIM is not accepted by the phone.
telErrSpcCallError
The voice telephone call encountered an error.
telErrSpcLineIsBusy
The voice telephone call failed.
telErrSpcLineIsReleased
The voice telephone call has been released.
telErrSpecificDrvNotFound
The specified driver could not be found.
telErrTooManyApps
The applications table is full.
telErrTTaskNotFound
The Telephony Task could not be found.
telErrTTaskNotRunning
The Telephony Task is not running.
telErrUnavailableValue
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.
telErrUnknown
An unknown telephony manager error occurred.
telErrValidityPeriod
The validity period specified for the short message is not valid.
telErrValueStale
The information could not be retrieved; a copy of the most recently retrieved value has been returned instead.
telErrVersion
The shared library version does not match the version associated with the application.

Information Type Constants

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

Constant
Value
Description
kTelInfPhoneBrand
0
The brand name of the phone.
kTelInfPhoneModel
1
The model number of the phone.
kTelInfPhoneRevision
2
The revision number of the phone.

Keycode Constants

The TelSndPlayKeyToneType structure uses the keycode constants to specify the key tone to play.

Constant
Value
Description
kTel0Key
0x00
The 0 key on the phone keypad.
kTel1Key
0x01
The 1 key on the phone keypad.
kTel2Key
0x02
The 2 key on the phone keypad.
kTel3Key
0x03
The 3 key on the phone keypad.
kTel4Key
0x04
The 4 key on the phone keypad.
kTel5Key
0x05
The 5 key on the phone keypad.
kTel6Key
0x06
The 6 key on the phone keypad.
kTel7Key
0x07
The 7 key on the phone keypad.
kTel8Key
0x08
The 8 key on the phone keypad.
kTel9Key
0x09
The 9 key on the phone keypad.
kTelPoundKey
0x23
The POUND(#) key on the phone keypad.
kTelStarKey
0x2A
The STAR(*) key on the phone keypad.
kTelSendKey
0x45
The SEND key on the phone keypad.
kTelEndKey
0x46
The END key on the phone keypad.
kTelClrKey
0x47
The CLEAR key on the phone keypad.
kTelSaveKey
0x48
The SAVE key on the phone keypad.

Key Sound Type Constants

The TelSndPlayKeyToneType structure uses the key sound type constants to specify how the tone is played.

Constant
Value
Description
kTelSndSingleTone
0x00
Play the key sound as a single tone.
kTelSndMultiTones
0x01
Play the key sound as a multiple tones.

Message Identifier Constants

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 TelephonyMgr.h file.

Constant
Function
kTelGetCallStateMessage
kTelNwkSelectNetworkMessage
kTelSmsReadMessageMessage

Service Set Constants

The service set constants specify a set of API services.

Constant
Value
Description
kTelNwkServiceId
0
The network service set.
kTelStyServiceId
1
The security service set.
kTelPowServiceId
2
The power service set.
kTelCfgServiceId
3
The configuration service set.
kTelSmsServiceId
4
The short message service set.
kTelEmcServiceId
5
The emergency telephone call service set.
kTelSpcServiceId
6
The speech telephone call service set.
kTelDtcServiceId
7
The data telephone call service set.
kTelPhbServiceId
8
The phone book service set.
kTelOemServiceId
9
The OEM service set.
kTelSndServiceId
10
The sound service set.
kTelInfServiceId
11
The information service set.

Telephony Functions

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

New TelCancel

Purpose

Cancels an asynchronous function call.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iTransIdThe transaction ID associated with the function that you are cancelling.
<-> ioTransIdPSet 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.

Comments

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.

New TelClose

Purpose

Close the shared library.

Prototype

Err TelClose(UInt16 iRefnum, TelAppID iAppId);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.

Result

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

New TelClosePhoneConnection

Purpose

Closes down communications with the connected phone.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

Comments

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

New TelGetCallState

Purpose

Retrieves the current telephone call state information.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelCallStateType 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.
<-> ioTransIdPSet 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 TelCallStateType 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 TelCallStateType structure.

The current incoming or outgoing telephone call number is stored into the number field of the TelCallStateType 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

New TelGetEvent

Purpose

Retrieves events for applications that use the telephony manager.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oEventPA pointer to a TelEventType structure. Upon return, the structure contains the event information, which you should use as described in the Comments section.
-> iTimeoutMaximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely).

Result

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

New TelGetTelephonyEvent

Purpose

Retrieves telephony events only.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oEventPA pointer to a TelEventType structure. Upon return, the structure contains the event information.
-> iTimeoutMaximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely).

Result

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

New TelInfGetInformation

Purpose

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

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelInfGetformationType 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.
<-> ioTransIdPSet 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 TelInfGetformationType 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 TelInfGetformationType 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.

New TelIsCfgServiceAvailable

Purpose

A macro that determines if the configuration service set is available in the current environment.

Prototype

TelIsCfgServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

Comments

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 73, "Telephony SMS."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsDtcServiceAvailable

Purpose

A macro that determines if the data calls service set is available in the current environment.

Prototype

TelIsDtcServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 72, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsEmcServiceAvailable

Purpose

A macro that determines if the emergency calls service set is available in the current environment.

Prototype

TelIsEmcServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 72, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsInfServiceAvailable

Purpose

A macro that determines if the information service set is available in the current environment.

Prototype

TelIsInfServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

New TelIsNwkServiceAvailable

Purpose

A macro that determines if the network service set is available in the current environment.

Prototype

TelIsNwkServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 71, "Telephony Network."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsOemServiceAvailable

Purpose

A macro that determines if the OEM service set is available in the current environment.

Prototype

TelIsOemServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

New TelIsPhbServiceAvailable

Purpose

A macro that determines if the phone book service set is available in the current environment.

Prototype

TelIsPhbServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 74, "Telephony Phone Book."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsPhoneConnected

Purpose

Determines if a phone is connected.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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.

New TelIsPowServiceAvailable

Purpose

A macro that determines if the power services set is available in the current environment.

Prototype

TelIsPowServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

New TelIsSmsServiceAvailable

Purpose

A macro that determines if the Short Message Service (SMS) service set is available in the current environment.

Prototype

TelIsSmsServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 73, "Telephony SMS."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsSndServiceAvailable

Purpose

A macro that determines if the sound service set is available in the current environment.

Prototype

TelIsSndServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

New TelIsSpcServiceAvailable

Purpose

A macro that determines if the speech telephone call service set is available in the current environment.

Prototype

TelIsSpcServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 72, "Telephony Calls."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelIsStyServiceAvailable

Purpose

A macro that determines if the security service set is available in the current environment.

Prototype

TelIsStyServiceAvailable (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 71, "Telephony Network."

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelIs<FunctionName>Supported

New TelMatchPhoneDriver

Purpose

Determines if the currently selected driver matches the connected phone.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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.

New TelOemCall

Purpose

Pass a call to an OEM function.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a TelOemCallType structure that contains information about the OEM function call.
<-> ioTransIdPSet 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.

New TelOpen

Purpose

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

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iVersnumThe version number of the shared library for which your application was developed.
<- oAppIdPA 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.

Result

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 before calling any other telephony manager functions.

You can specify the current version of the shared library by using the kTelMgrVersion constant as the value of the iVersnum parameter.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelClose

New TelOpenPhoneConnection

Purpose

Open communications with the connected phone.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

New TelPowGetBatteryStatus

Purpose

Retrieves the status of the phone's battery.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oStatusPA pointer to an unsigned byte value. Upon return, this is the battery status value, which is one of the Battery Status Constants.
<-> ioTransIdPSet 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
kTelPowBatteryStatusMessage

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

New TelPowGetPowerLevel

Purpose

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

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oPowerPA pointer to an unsigned byte value. Upon return, this is the battery percentage value.
<-> ioTransIdPSet 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

New TelPowSetPhonePower

Purpose

Turns the phone on or off.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iPowerOnSet to true to turn the phone on, and set to false to turn the phone off.

Result

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.

New TelSendCommandString

Purpose

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

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA pointer to a command string structure of type TelSendCommandStringType.
<-> ioTransIdPSet 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 TelOemCallType 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.

New TelSndMute

Purpose

Mute or un-mute an active telephone call.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iMuteOnSet to true to mute the telephone call, or set to false to unmute the telephone call.
<-> ioTransIdPSet 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

New TelSndPlayKeyTone

Purpose

Play a keytone sound on the phone.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iParamPA pointer to a TelSndPlayKeyToneType structure that describes the tone to play.
<-> ioTransIdPSet 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
kTelSndPlayKeyTone

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

New TelSndStopKeyTone

Purpose

Stop the playing of a keytone sound on the phone.

Prototype

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

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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

Feature Support Functions

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

New TelIs<FunctionName>Supported

Purpose

Determines if the specified function is supported.

Prototype

TelIs<FunctionName>Supported (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 TelIsCgfGetSmsCenterSupported, 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

New TelIs<ServiceSet>Available

Purpose

Determines if the specified service set is available.

Prototype

TelIs<ServiceSet>Available (iRefnum, iAppId, ioTransIdP);

Parameters

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioTransIdPSet 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 IDs are described in Service Set 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:

TelIsCfgServiceAvailable to determine if the configuration service set is available.

TelIsDtcServiceAvailable to determine if the data calls service set is available.

TelIsEmcServiceAvailable to determine if the emergency calls service set is available.

TelIsInfServiceAvailable to determine if the information service set is available.

TelIsNwkServiceAvailable to determine if the network service set is available.

TelIsOemServiceAvailable to determine if the OEM service set is available.

TelIsPhbServiceAvailable to determine if the phone book service set is available.

TelIsPowServiceAvailable to determine if the power service set is available.

TelIsSmsServiceAvailable to determine if the SMS service set is available.

TelIsSndServiceAvailable to determine if the sound service set is available.

TelIsSpcServiceAvailable to determine if the speech calls service set is available.

TelIsStyServiceAvailable to determine if the security 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