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

76    Telephony Calls

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter describes the telephony calls service sets of the telephony API, which include:

  • The data calls service set
  • The emergency calls service set
  • The speech (voice) calls service set

For more information about the telephony manager basic services and the different service sets, see Chapter 73, "Telephony Basic Services."

This chapter describes:

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

Telephony Calls Data Structures ^TOP^

This section describes the data structures used with the telephony calls service sets portion of the telephony manager API.

TelDtcCallNumberType Struct ^TOP^

Purpose

The TelDtcCallNumber() function uses the TelDataCallNumberType structure to specify information about the telephone number to call.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelDtcCallNumberType {
Char *dialNumberP;
UInt8 lineId;
} TelDtcCallNumberType

Fields

dialNumberP
The telephone number to dial.
lineId
Upon return from the TelDtcCallNumber() function, this is the ID of the data line that was established for the telephone call.

TelDtcReceiveDataType Struct ^TOP^

Purpose

The TelDtcReceiveData() function uses a TelDtcReceiveDataType structure to receive data from an open data line.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelDtcReceiveDataType {
UInt8 *data;
UInt32 size;
UInt32 timeOut;
} TelDtcReceiveDataType

Fields

data
A buffer into which the data is stored.
Note that if this buffer is too small to contain all of the available data, the end of the data is truncated and the function using this structure generates a telErrBufferSize error.
size
When the structure is used as an input parameter, this is the allocated size, in bytes, of the data buffer.
Upon return, this is the actual number of bytes of data that was retrieved. If the data buffer is too small to contain all of the retrieved data, the function using this structure generates a telErrBufferSize error.
timeout
The number of milliseconds to wait before timing out.

TelDtcSendDataType Struct ^TOP^

Purpose

The TelDtcReceiveData() function uses a TelDtcSendDataType structure to send data to an open data line.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelDtcSendDataType {
UInt8 *data;
UInt32 size;
} TelDtcSendDataType

Fields

data
A pointer to the data to send.
size
The number of bytes of data in the data buffer.

TelEmcGetNumberType Struct ^TOP^

Purpose

The TelEmcGetNumber() function uses a TelEmcGetNumberType structure to retrieve an emergency dial telephone number.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelEmcGetNumberType {
UInt8 index;
UInt8 size;
Char *value;
} TelEmcGetNumberType

Fields

index
The index of the telephone number. This is a zero-based index.
size
When the structure is used as an input parameter, this is the allocated size, in bytes, of the value buffer.
Upon return, this is the actual size of the string, including the null terminator character. If the value buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.
value
A null-terminated string buffer into which the emergency dial telephone number is stored.
Note that if this buffer is too small to contain all of the available data, the end of the data is truncated and the function using this structure generates a telErrBufferSize error.

TelEmcSetNumberType Struct ^TOP^

Purpose

The TelEmcSetNumber() function uses a TelEmcNumberType structure to set an emergency dial telephone number.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelEmcSetNumberType {
UInt8 index;
Char *value;
} TelEmcSetNumberType

Fields

index
The index of the telephone number. This is a zero-based index.
value
The string value of the number to store as the indexth entry.

TelSpcGetCallerNumberType Struct ^TOP^

Purpose

The TelSpcGetCallerNumber() function uses a TelSpcGetCallerNumberType structure to retrieve an incoming telephone number.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelSpcGetCallerNumberType {
UInt8 size;
Char *value;
} TelSpcGetCallerNumberType

Fields

size
When the structure is used as an input parameter, this is the allocated size, in bytes, of the value buffer.
Upon return, this is the actual size of the caller dial telephone number, including the null terminator character. If the value buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error.
value
A null-terminated string buffer into which the caller telephone number is stored.
Note that if this buffer is too small to contain all of the available data, the end of the data is truncated and the function using this structure generates a telErrBufferSize error.

TelSpcPlayDTMFType Struct ^TOP^

Purpose

The TelSpcPlayDTMF() function uses a TelSpcPlayDTMFType structure to specify the qualities of the DTMF (dual-tone, multi-frequency) sound sent by the phone to the network or remote, connected equipment.

Declared In

TelephonyMgrTypes.h

Prototype

typedef struct _TelSpcPlayDTMFType {
UInt8 keyTone;
UInt32 duration;
} TelSpcPlayDTMFType

Fields

keyTone
The keycode of the key tone to play. This must be one of the values declared under "Keycode Constants."
duration
The duration of the tone, specified as a multiple of ten milliseconds.

Telephony Calls Functions ^TOP^

This section describes the functions used with the telephony calls service sets portion of the telephony API.

TelDtcCallNumber Function ^TOP^

Purpose

Initiate a data telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelDtcCallNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelDtcCallNumberType*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 TelDtcCallNumberType structure that specifies information about 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 TelDtcCallNumberType structure passed to this function in the ioDataCallParamP parameter.
functionId
kTelDtcCallNumberMessage

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

Comments

Call this function to start a data telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelDtcCloseLine()

TelDtcCloseLine Function ^TOP^

Purpose

Hang up a data line.

Declared In

TelephonyMgr.h

Prototype

Err TelDtcCloseLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8iLineId,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iLineId
The ID of the line to hang up. This is the ID returned by a previous call to the TelDtcCallNumber() function.
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 iLineId parameter.
functionId
kTelDtcCloseLineMessage

Call this function to end a data telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelDtcCallNumber()

TelDtcReceiveData Function ^TOP^

Purpose

Receive data on an opened data communications line.

Declared In

TelephonyMgr.h

Prototype

Err TelDtcReceiveData(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelDtcReceiveDataType*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 TelDtcReceiveDataType structure.
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 TelDtcReceiveDataType structure passed to this function in the ioRcvDataP parameter.

functionId

kTelDtcReceiveDataMessage

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 receive data during an active data telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelDtcCallNumber(), TelDtcCloseLine(), TelDtcSendData()

TelDtcSendData Function ^TOP^

Purpose

Send data on an opened data line.

Declared In

TelephonyMgr.h

Prototype

Err TelDtcSendData(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelDtcSendDataType*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 TelDtcSendDataType structure that specifies the data to send.
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 TelDtcSendDataType structure passed to this function in the iParamP parameter.
functionId
kTelDtcSendDataMessage

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

Comments

Call this function to send data during an active data telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelDtcCallNumber(), TelDtcCloseLine(), TelDtcReceiveData()

TelEmcCall Function ^TOP^

Purpose

Call the currently selected emergency service.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcCall(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelEmcCallMessage

Comments

This function calls the telephone number specified in a previous call to the TelEmcSelectNumber() function. In synchronous mode, this function returns after the dial command has been sent to the phone.

After calling this function, sub-launched applications can receive notifications when the following telephony events occur. Note that these notifications can be raised after both synchronous and asynchronous calls to this function.

Table 76.1  Telephony events sent to sublaunched applications

Event

Description

sysTelSpcLaunchCmdCallReleased

Warns that the telephone call has been released.

sysTelSpcLaunchCmdCallBusy

Warns that the called equipment is busy.

sysTelSpcLaunchCmdCallConnect

Warns that the line is open. The ID of the open line is stored in the UInt32 value of the parameter block passed to the application.

sysTelSpcLaunchCmdCallError

Warns that an error occurred while attempting to complete the telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcCloseLine(),

TelEmcCloseLine Function ^TOP^

Purpose

Close the line that is currently opened for an emergency telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcCloseLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelDtcCloseLineMessage

Comments

Call this function to end an emergency telephone call.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcCall()

TelEmcGetNumber Function ^TOP^

Purpose

Retrieve an emergency dial telephone number.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcGetNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelEmcGetNumberType*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 TelEmcGetNumberType structure in which you assign the index of the telephone number that you want to retrieve.
On input, 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 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 TelEmcGetNumberType structure passed to this function in the ioGetNumberP parameter.
functionId
kTelEmcGetNumberMessage

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

Comments

The emergency call telephone number is stored into the value field of the TelEmcGetNumberType structure referenced by ioGetNumberP. If the value buffer is too small to contain the complete string, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The size field of the structure is always updated to contain the actual size of the complete string.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcGetNumberCount(), TelEmcSetNumber(), TelEmcSelectNumber()

TelEmcGetNumberCount Function ^TOP^

Purpose

Retrieve the count of emergency dial telephone numbers.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcGetNumberCount(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8*oCountP,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
oCountP
Upon return, the total number of emergency call numbers available.
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 unsigned integer passed to this function in the oCountP parameter.
functionId
kTelEmcGetNumberMessage

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

Comments

The emergency telephone call number is stored into the value field of the TelEmcGetNumberType structure referenced by ioGetNumberP. If the value buffer is too small to contain the complete string, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The size field of the structure is always updated to contain the actual size of the complete string.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcGetNumber(), TelEmcSetNumber(), TelEmcSelectNumber()

TelEmcSelectNumber Function ^TOP^

Purpose

Select the current emergency telephone number. This is the telephone number that gets dialed when you call the TelEmcCall() function.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcSelectNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8iIndex,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iIndex
The zero-based index of the emergency telephone number that you want selected.
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 iIndex parameter.
functionId
kTelEmcSelectNumberMessage

Comments

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcCall(), TelEmcGetNumber(), TelEmcGetNumberCount(), TelEmcSetNumber()

TelEmcSetNumber Function ^TOP^

Purpose

Set the telephone number for the specified emergency dial number.

Declared In

TelephonyMgr.h

Prototype

Err TelEmcSetNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelEmcSetNumberType*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 TelEmcSetNumberType structure that specifies the telephone number.
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 TelEmcSetNumberType structure passed to this function in the iNumberP parameter.
functionId
kTelEmcSetNumberMessage

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

Comments

Call this function to associate a new telephone number with the emergency dial number that has the specified iIndex.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelEmcGetNumber(),

TelSpcAcceptCall Function ^TOP^

Purpose

Accept an incoming voice telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcAcceptCall(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8*oLineIdP,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
oLineIdP
A pointer to an unsigned byte value. Upon return, this is the ID of the voice line assigned to 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 unsigned integer passed to this function in the oLineIdP parameter.
functionId
kTelSpcAcceptCallMessage

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

Comments

If another line was active prior to the execution of this function, that line is put on hold. Note that there can only be one line active at any given time, and there can only be one line on hold at any given time.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcGetCallerNumber(), TelSpcRejectCall()

TelSpcCallNumber Function ^TOP^

Purpose

Initiate a voice telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcCallNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   constChar*iDialNumberP,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iDialNumberP
A pointer to the telephone number to 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 string passed to this function in the iDialNumberP parameter.
functionId
kTelSpcCallNumberMessage

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

Comments

A successful return from a synchronous call or receipt of a successful notification from an asynchronous call does not mean that the telephone call has been connected; instead, it indicates that the dial command was sent to the phone. Successful connection of the telephone call is indicated with a sub-launch.

The dial number is formatted according to the following syntax:


DialNumber ::=<Phone_Number> | <Code_String>
| <Phone_Number> <Code_String> 
 
Phone_Number ::=<IntlPrefix><NatlNumber> 
| <NatlNumber> 
 
IntlPrefix ::='+' <country code> 
 
NatlNumber ::={{Pause<Pause>}{<Digit>}} 
 
Code_String ::=<Symbol>{<Symbol>} 
 
Symbol ::=<Digit> | '#' | '*' 
 
Digit ::='0' | '1' | '2' | '3' | '4'
| '5' | '6' | '7' | '8' | '9' 
 
Pause ::=',' 

After calling this function, sub-launched applications can receive notifications when the following telephony events occur. Note that these notifications can be raised after both synchronous and asynchronous calls to this function.

Table 76.2  Telephony events sent to sublaunched applications

Event

Description

sysTelSpcLaunchCmdCallReleased

This is passed to a sub-launched application to warn that the telephone call has been released.

sysTelSpcLaunchCmdCallBusy

This is passed to a sub-launched application to warn that the called equipment is busy.

sysTelSpcLaunchCmdCallConnect

This is passed to a sub-launched application to warn that the line is open. The ID of the open line is stored in the UInt32 value of the parameter block passed to the application.

sysTelSpcLaunchCmdCallError

This is passed to a sub-launched application to warn that the telephone call encountered an error.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcCloseLine()

TelSpcCloseLine Function ^TOP^

Purpose

Ends a voice telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcCloseLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8iLineId,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iLineId
The ID of the voice line that you want to close. This is the ID returned by a previous call to the TelSpcAcceptCall() function.
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 iLineId parameter.
functionId
kTelSpcCloseLineMessage

Comments

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcCallNumber()

TelSpcConference Function ^TOP^

Purpose

Initiate a conference telephone call by merging the active line and the held line.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcConference(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8*oLineIdP,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
oLineIdP
A pointer to an unsigned byte value. Upon return, this is the ID of the voice line assigned to 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 unsigned integer value passed to this function in the oLineIdP parameter.
functionId
kTelSpcConferenceMessage

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

Comments

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcCallNumber(), TelSpcCloseLine(), TelSpcHoldLine(), TelSpcRetrieveHeldLine(), TelSpcSelectLine()

TelSpcGetCallerNumber Function ^TOP^

Purpose

Retrieve the telephone number of the caller on an incoming telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcGetCallerNumber(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelSpcGetCallerNumberType*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 TelSpcGetCallerNumberType structure that is used to retrieve the caller's telephone number.
On input, 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 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. If there is no active incoming telephone call, this function returns the telErrUnavailableValue error.

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 TelSpcGetCallerNumberType structure passed to this function in the ioParamP parameter.
functionId
kTelSpcGetCallerNumberMessage

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

Comments

The emergency telephone call number is stored into the value field of the TelSpcGetCallerNumberType structure referenced by ioParamP. If the value buffer is too small to contain the complete string, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The size field of the structure is always updated to contain the actual size of the complete string.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcAcceptCall()

TelSpcHoldLine Function ^TOP^

Purpose

Put the currently active voice line on hold.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcHoldLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelSpcHoldLineMessage

Comments

Note that there can only be one line active at any given time, and there can only be one line on hold at any given time.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcRetrieveHeldLine()

TelSpcPlayDTMF Function ^TOP^

Purpose

Play a dual-tone multi-frequency sound to the network system for a specified duration. Note that you can only play a DTMF while a voice telephone call is active.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcPlayDTMF(
   UInt16iRefnum,
   TelAppIDiAppId,
   TelSpcPlayDTMFType*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 TelSpcPlayDTMFType structure that specifies the tone to play and its duration.
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 TelSpcPlayDTMFType structure passed to this function in the iParamP parameter
functionId
kTelSpcPlayDTMFMessage

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 TelIsSpcServiceAvailable() macro.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcSendBurstDTMF(), TelSpcStartContinuousDTMF(), TelSpcStopContinuousDTMF()

TelSpcRejectCall Function ^TOP^

Purpose

Reject an incoming voice telephone call.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcRejectCall(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelSpcRejectCallMessage

Comments

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcAcceptCall(), TelSpcGetCallerNumber()

TelSpcRetrieveHeldLine Function ^TOP^

Purpose

Reconnect the voice line that is currently on hold, making it the active voice line.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcRetrieveHeldLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelSpcRetrieveHeldLineMessage

Comments

Note that there can only be one line active at any given time, and there can only be one line on hold at any given time.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcHoldLine()

TelSpcSelectLine Function ^TOP^

Purpose

Select the specified line ID as the newly active voice line.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcSelectLine(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8iLineId,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iLineId
The ID of the voice line that you want to activate. This is the ID returned by a previous call to the TelSpcAcceptCall() function.
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 iLineId parameter.
functionId
kTelSpcSelectLineMessage

Comments

If a line was active previous to completion of this function, that line is put on hold. Note that there can only be one line active at any given time, and there can only be one line on hold at any given time.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcConference()

TelSpcSendBurstDTMF Function ^TOP^

Purpose

Send a string of dual-tone, multi-frequency sounds to the network system. Note that you can only play a DTMF while a voice telephone call is active.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcSendBurstDTMF(
   UInt16iRefnum,
   TelAppIDiAppId,
   constChar*iDTMFStringP,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iDTMFStringP
A null-terminated string of keytone values. Each byte of the string specifies one of the values declared under "Keycode 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 string passed to this function in the iDTMFStringP parameter.
functionId
kTelSpcSendBurstDTMFMessage

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

Comments

This function sends a burst string of keytones to the network. Each key tone is played for the default duration defined by the network.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcPlayDTMF(), TelSpcStartContinuousDTMF(), TelSpcStopContinuousDTMF()

TelSpcStartContinuousDTMF Function ^TOP^

Purpose

Send a continuous dual-tone, multi-frequency sound to the network system. Note that you can only play a DTMF while a voice telephone call is active.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcStartContinuousDTMF(
   UInt16iRefnum,
   TelAppIDiAppId,
   UInt8iKeyCode,
   UInt16*ioTransIdP
)

Parameters

iRefnum
The telephony manager library reference number.
iAppId
The telephone application attachment identifier for your application.
iKeyCode
The keycode to send to the network. This must be one of the values declared under "Keycode 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 iKeyCode parameter.
functionId
kTelSpcStartContinuousDTMFMessage

Comments

This function sends a key tone to the network system that is played continuously until the TelSpcStopContinuousDTMF() function executes.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcPlayDTMF(), TelSpcSendBurstDTMF(), TelSpcStopContinuousDTMF()

TelSpcStopContinuousDTMF Function ^TOP^

Purpose

Stop the continuous playing of a tone that was started by calling the TelSpcStartContinuousDTMF() function.

Declared In

TelephonyMgr.h

Prototype

Err TelSpcStopContinuousDTMF(
   UInt16iRefnum,
   TelAppIDiAppId,
   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
kTelSpcStopContinuousDTMFMessage

Comments

This function stops the continuous playing of the tone that was previously initiated by calling the TelSpcStartContinuousDTMF() function.

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

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TelSpcPlayDTMF(), TelSpcSendBurstDTMF(), TelSpcStartContinuousDTMF()