< 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 | Chapter 69, "Telephony Basic Services." | Basic functions that are always available.
TelCfg | Configuration | Chapter 70, "Telephony Security and Configuration." | Allows configuration of the phone, including Short Message Services (SMS) configuration.
TelDtc | Data calls | Chapter 72, "Telephony Calls." | Functions for handling data calls.
TelEmc | Emergency calls | Chapter 72, "Telephony Calls." | Functions for handling emergency calls.
TelInf | Information | Chapter 69, "Telephony Basic Services." | Functions for retrieving information about the phone.
TelNwk | Network | Chapter 71, "Telephony Network." | Provides network oriented services, including authorization, signal level, search mode, and related operations.
TelOem | OEM | Chapter 69, "Telephony Basic Services." | Provides OEMs with the ability to incorporate custom functionality.
TelPhb | Phone book | Chapter 74, "Telephony Phone Book." | Functions for managing the phone book.
TelPow | Power | Chapter 69, "Telephony Basic Services." | Provides access to power supply level.
TelSms | Short Message Service | Chapter 73, "Telephony SMS." | Addresses the SMS, including functions for reading, sending, replying to, and deleting short messages.
TelSnd | Sound | Chapter 69, "Telephony Basic Services." | Functions for playing key tones on and muting the phone.
TelSpc | Speech calls | Chapter 72, "Telephony Calls." | Function for handling voice calls, including dual tone modulated frequency (DTMF) sounds.
TelSty | Security | Chapter 70, "Telephony Security and Configuration." | 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 | TelGetCallState
kTelNwkSelectNetworkMessage | TelNwkSelectNetwork
kTelSmsReadMessageMessage | TelSmsReadMessage
## 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 #####
-> 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.
#### 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The 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 #####
-> 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
#### 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A 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.
#####
<-> 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 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 #####
-> 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).
#### 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 #####
-> 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).
#### 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iAppId | The telephone application attachment identifier for your application.
#####
<-> ioParamP | A 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.
#####
<-> 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 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 #####
-> 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
#### 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 #####
-> 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 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 #####
-> 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 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 #####
-> 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 ## New TelIsNwkServiceAvailable #### Purpose A macro that determines if the network service set is available in the current environment. #### Prototype 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 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 #####
-> 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 ## 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 #####
-> 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 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 #####
-> 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. ## New TelIsPowServiceAvailable #### Purpose A macro that determines if the power services set is available in the current environment. #### Prototype 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 ## 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 #####
-> 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 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 #####
-> 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 ## 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 #####
-> 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 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 #####
-> 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 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 #####
-> 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. ## New TelOemCall #### Purpose Pass a call to an OEM function. #### 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. ## 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 #####
-> iRefnum | The telephony manager library reference number.
#####
-> iVersnum | The version number of the shared library for which your application was developed.
#####
<- 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.
#### 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 #####
-> 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 ## New TelPowGetBatteryStatus #### Purpose Retrieves the status of the phone's battery. #### 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 | 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 #####
-> 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 ## New TelPowSetPhonePower #### Purpose Turns the phone on or off. #### 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.
#### 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 #####
-> 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 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 #####
-> 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 ## New TelSndPlayKeyTone #### Purpose Play a keytone sound on the phone. #### 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 | 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 #####
-> 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 ## 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 #####
-> 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 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 #####
-> 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 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 |