This chapter describes the telephony network service set of the telephony API.
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 Network Data Structures
This section describes the data structures used with the telephony network service set portion of the telephony API.
TelNwkGetLocationType Struct
Purpose
You use the TelNwkGetLocationType
structure with the TelNwkGetLocation()
function to retrieve information about the location of the phone.
Declared In
TelephonyMgrTypes.h
Prototype
typedef struct _TelNwkGetLocationType { Char *value; UInt16 size; } TelNwkGetLocationType
Fields
-
←
value
- A buffer into which the current location string is stored. The format of this string is network-dependent.
- Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a
telErrBufferSize
error. -
↔
size
- The size of the
value
string. When the structure is used as an input parameter, this is the allocated size, in bytes, of thevalue
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.
TelNwkGetNetworkNameType Struct
Purpose
You use the TelNwkGetNetworkNameType
structure with the TelNwkGetNetworkName()
function to retrieve the name of the specified, registered network.
Declared In
TelephonyMgrTypes.h
Prototype
typedef struct _TelNwkGetNetworkNameType { UInt32 id; Char *value; UInt16 size; } TelNwkGetNetworkNameType
Fields
-
→
id
- The network ID.
-
←
value
- A null-terminated string buffer into which the network name is stored.
- Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a
telErrBufferSize
error. -
↔
size
- The size of the
value
string. When the structure is used as an input parameter, this is the allocated length, in bytes, of thevalue
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
TelNwkGetNetworksType Struct
Purpose
You use the TelNwkGetNetworksType
structure with the TelNwkGetNetworks()
function to retrieve the number of registered networks.
Declared In
TelephonyMgrTypes.h
Prototype
typedef struct _TelNwkGetNetworksType { UInt32 *networkIdP; UInt8 size; } TelNwkGetNetworksType
Fields
-
←
networkIdP
- An array into which the retrieved network IDs are stored.
- Note that if this buffer is too small to contain all of the available IDs, the data is truncated and the function using this structure generates a
telErrBufferSize
error. -
↔
size
- When the structure is use as an input value, this is the allocated size, in elements, of the
networkIdP
array. - When the structure is used as a return value, this is the number of network IDs that are available. If the
networkP
buffer is too small to contain all of the retrieved IDs, this field is assigned the entire number of available IDs, and the function using this structure generates atelErrBufferSize
error
Telephony Network Constants
This section describes the constants used with the telephony network service set of the telephony API, which include the following constant types:
Network Type Constants
Purpose
The network type constants describe the type of network connection.
Declared In
TelephonyMgr.h
Constants
-
#define kTelNwkCDMA 0
- A CDMA network.
-
#define kTelNwkGSM 1
- A GSM network.
-
#define kTelNwkTDMA 2
- A TDMA network.
-
#define kTelNwkPDC 3
- A PDC network.
Network Search Mode Constants
Purpose
The network search mode constants describe the search mode used to find a network.
Declared In
TelephonyMgr.h
Constants
-
#define kTelNwkAutomaticSearch 0
- Automatic network searching.
-
#define kTelNwkManualSearch 1
- Manual network searching.
Telephony Network Functions
This section describes the data structures used with the telephony network service set portion of the telephony API.
TelNwkGetLocation Function
Purpose
Retrieve information about the location of the mobile unit.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetLocation( UInt16 iRefnum, TelAppID iAppId, TelNwkGetLocationType* 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
TelNwkGetLocationType
structure. - 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 location string, 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
TelNwkGetLocationType
passed to this function in theioParamP
parameter. -
functionId
-
kTelNwkGetLocationMessage
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 location information string is stored into the value
field of the TelNwkGetLocationType
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 TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
TelNwkGetNetworkName Function
Purpose
Returns the name of a registered network.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetNetworkName( UInt16 iRefnum, TelAppID iAppId, TelNwkGetNetworkNameType* 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
TelNwkGetNetworkNameType
structure that stores the network name. - 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 name string, 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
TelNwkGetNetworkNameType
passed to this function in theioParamP
parameter. -
functionId
-
kTelNwkGetNetworkNameMessage
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 network name string is stored into the value
field of the structure. If the value
field buffer in the TelNwkGetNetworkNameType
structure 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 is always updated to contain the actual size of the complete string.
The string that is returned in the value
field of the structure referenced by ioParamP
is network dependent.
On a GSM network, the result string is compliant with the AT 07.07 European Telecommunications Standards Institute (ETSI) standard for COPS
and CREG
commands. The result string contains the following elements:
- The network type, as returned by the
TelNwkGetNetworkType()
function, and followed by a semicolon (';'
) character. - The network operator, using the following syntax:
<area code> ';' <network registration>
The
<area code>
value is the value retrieved by issuing theAT+CREG?
command.The
<network registration>
value is the value retrieved by issuing theAT+CREG?
command.
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TelNwkGetNetworks()
, TelNwkGetSelectedNetwork()
TelNwkGetNetworks Function
Purpose
Retrieves information about the registered networks.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetNetworks( UInt16 iRefnum, TelAppID iAppId, TelNwkGetNetworksType* 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
TelNwkGetNetworksType
structure that stores the network IDs. On input, thesize
field of this structure contains the size, in elements, of thenetworkIdP
array field. - Upon return, the
networkIdP
array contains the IDs of the registered networks, and thesize
field contains the number of IDs in the array. -
↔
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
TelNwkGetNetworksType
passed to this function in theioParamP
parameter. -
functionId
-
kTelNwkGetNetworksMessage
WARNING! When using this function asynchronously, you must ensure that the structure referenced by
ioParamP
remains in memory until the asynchronous call completes.
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TelNwkGetNetworkName()
, TelNwkGetNetworks()
TelNwkGetNetworkType Function
Purpose
Retrieve the type of the selected network.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetNetworkType( UInt16 iRefnum, TelAppID iAppId, UInt8* oTypeP, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
←
oTypeP
- A pointer to an unsigned byte value. Upon return, this is the network type. This is one of Network Type 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
oTypeP
parameter. -
functionId
-
kTelNwkGetNetworkTypeMessage
WARNING! When using this function asynchronously, you must ensure that the value you pass for the
oTypeP
parameter remains in memory until the asynchronous call completes.
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
TelNwkGetSearchMode Function
Purpose
Returns the current network search mode.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetSearchMode( UInt16 iRefnum, TelAppID iAppId, UInt8* oModeP, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
←
oModeP
- A pointer to an unsigned byte value. Upon return, this is the type of search mode that is currently being used. This is one of the Network Search Mode 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
oModeP
parameter. -
functionId
-
kTelNwkGetSearchModeMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by
oModeP
remains in memory until the asynchronous call completes.
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TelNwkGetSelectedNetwork Function
Purpose
Retrieve the network identifier of the currently selected network.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetSelectedNetwork( UInt16 iRefnum, TelAppID iAppId, UInt32* oNetworkIdP, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
←
oNetworkIdP
- A pointer to an unsigned integer value. Upon return, this is the identifier of the currently selected network.
-
↔
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
oNetworkIdP
parameter. -
functionId
-
kTelNwkGetSelectedNetworkMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by
oNetworkP
remains in memory until the asynchronous call completes.
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TelNwkGetNetworkName()
, TelNwkGetNetworks()
, TelNwkSelectNetwork()
TelNwkGetSignalLevel Function
Purpose
Retrieve the selected network carrier signal level.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkGetSignalLevel( UInt16 iRefnum, TelAppID iAppId, UInt8* oSignalP, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
←
oSignalP
- A pointer to an unsigned byte value. Upon return, this is an indication of the signal level in decibels per milliwatt (dBm). The values are explained in the Comments section.
-
↔
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
oSignalP
parameter. -
functionId
-
kTelNwkGetSignalLevelMessage
WARNING! When using this function asynchronously, you must ensure that the value referenced by
oSignalP
remains in memory until the asynchronous call completes.
Comments
This function sets the value of the variable referenced by oSignalP
to an integer value that indicates the signal strength in dBm.
The following table describes the signal strength values.
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
TelNwkSelectNetwork Function
Purpose
Select a network to use from among the set of registered networks.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkSelectNetwork( UInt16 iRefnum, TelAppID iAppId, UInt32 iNetworkId, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
→
iNetworkId
- The identifier of the network to select.
-
↔
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 network unsigned integer value passed to this function in the
iNetworkId
parameter. -
functionId
-
kTelNwkSelectNetworkMessage
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
TelNwkGetNetworkName()
, TelNwkGetNetworks()
, TelNwkGetSelectedNetwork()
TelNwkSetSearchMode Function
Purpose
Sets the search mode used to find a network.
Declared In
TelephonyMgr.h
Prototype
Err TelNwkSetSearchMode( UInt16 iRefnum, TelAppID iAppId, UInt8 iMode, UInt16* ioTransIdP )
Parameters
-
→
iRefnum
- The telephony manager library reference number.
-
→
iAppId
- The telephone application attachment identifier for your application.
-
→
iMode
- The search mode to use. This must be one of the Network Search Mode 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
iMode
parameter. -
functionId
-
kTelNwkSetSearchModeMessage
Comments
Before using this function, you should verify that it is available by calling the TelIsNwkServiceAvailable()
macro.
Compatibility
Implemented only if 4.0 New Feature Set is present.