This chapter describes the telephony calls service sets of the telephony API, which include:
For more information about the telephony manager basic services and the different service sets, see Chapter 73, "Telephony Basic Services."
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
This section describes the data structures used with the telephony calls service sets portion of the telephony manager API.
TelDtcCallNumberType Struct
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
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 atelErrBufferSize
error. -
→
timeout
- The number of milliseconds to wait before timing out.
TelDtcSendDataType Struct
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
TelEmcGetNumberType Struct
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 atelErrBufferSize
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
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
index
th entry.
TelSpcGetCallerNumberType Struct
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 atelErrBufferSize
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
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
This section describes the functions used with the telephony calls service sets portion of the telephony API.
TelDtcCallNumber Function
Purpose
Initiate a data telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelDtcCallNumber( UInt16 iRefnum, TelAppID iAppId, 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 theioDataCallParamP
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 Function
Purpose
Declared In
TelephonyMgr.h
Prototype
Err TelDtcCloseLine( UInt16 iRefnum, TelAppID iAppId, UInt8 iLineId, 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
TelDtcReceiveData Function
Purpose
Receive data on an opened data communications line.
Declared In
TelephonyMgr.h
Prototype
Err TelDtcReceiveData( UInt16 iRefnum, TelAppID iAppId, 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:
- Points to the
TelDtcReceiveDataType
structure passed to this function in theioRcvDataP
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 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
Purpose
Send data on an opened data line.
Declared In
TelephonyMgr.h
Prototype
Err TelDtcSendData( UInt16 iRefnum, TelAppID iAppId, 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 theiParamP
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
Purpose
Call the currently selected emergency service.
Declared In
TelephonyMgr.h
Prototype
Err TelEmcCall( 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
-
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.
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 Function
Purpose
Close the line that is currently opened for an emergency telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelEmcCloseLine( 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
-
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
TelEmcGetNumber Function
Purpose
Retrieve an emergency dial telephone number.
Declared In
TelephonyMgr.h
Prototype
Err TelEmcGetNumber( UInt16 iRefnum, TelAppID iAppId, 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 thevalue
buffer. Upon return, thesize
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 theioGetNumberP
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
Purpose
Retrieve the count of emergency dial telephone numbers.
Declared In
TelephonyMgr.h
Prototype
Err TelEmcGetNumberCount( UInt16 iRefnum, TelAppID iAppId, 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
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( UInt16 iRefnum, TelAppID iAppId, UInt8 iIndex, 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
Purpose
Set the telephone number for the specified emergency dial number.
Declared In
TelephonyMgr.h
Prototype
Err TelEmcSetNumber( UInt16 iRefnum, TelAppID iAppId, 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 theiNumberP
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
TelSpcAcceptCall Function
Purpose
Accept an incoming voice telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcAcceptCall( UInt16 iRefnum, TelAppID iAppId, 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
Purpose
Initiate a voice telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcCallNumber( UInt16 iRefnum, TelAppID iAppId, const Char *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.
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 Function
Purpose
Declared In
TelephonyMgr.h
Prototype
Err TelSpcCloseLine( UInt16 iRefnum, TelAppID iAppId, UInt8 iLineId, 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
TelSpcConference Function
Purpose
Initiate a conference telephone call by merging the active line and the held line.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcConference( UInt16 iRefnum, TelAppID iAppId, 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
Purpose
Retrieve the telephone number of the caller on an incoming telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcGetCallerNumber( UInt16 iRefnum, TelAppID iAppId, 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 thevalue
buffer. Upon return, thesize
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 theioParamP
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
TelSpcHoldLine Function
Purpose
Put the currently active voice line on hold.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcHoldLine( 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
-
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
TelSpcPlayDTMF Function
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( UInt16 iRefnum, TelAppID iAppId, 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 theiParamP
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
Purpose
Reject an incoming voice telephone call.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcRejectCall( 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
-
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
Purpose
Reconnect the voice line that is currently on hold, making it the active voice line.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcRetrieveHeldLine( 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
-
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
TelSpcSelectLine Function
Purpose
Select the specified line ID as the newly active voice line.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcSelectLine( UInt16 iRefnum, TelAppID iAppId, UInt8 iLineId, 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
TelSpcSendBurstDTMF Function
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( UInt16 iRefnum, TelAppID iAppId, const Char *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
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( UInt16 iRefnum, TelAppID iAppId, UInt8 iKeyCode, 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
Purpose
Stop the continuous playing of a tone that was started by calling the TelSpcStartContinuousDTMF()
function.
Declared In
TelephonyMgr.h
Prototype
Err TelSpcStopContinuousDTMF( 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
-
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()