< Home < Developers < Development Support < Documentation

## 71 Telephony Network

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 71 Telephony Network Telephony Network Data Structures TelNwkGetLocationType TelNwkGetNetworkNameType TelNwkGetNetworksType Telephony Network Constants Network Type Constants Network Search Mode Constants Telephony Network Functions TelNwkGetLocation TelNwkGetNetworkName TelNwkGetNetworks TelNwkGetNetworkType TelNwkGetSearchMode TelNwkGetSelectedNetwork TelNwkGetSignalLevel TelNwkSelectNetwork TelNwkSetSearchMode |  |  |  | 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 69, "Telephony Basic Services." This chapter describes: Telephony Network Data Structures Telephony Network Constants Telephony Network Functions For more information about using the telephony manager, see Chapter 8, "Telephony Manager" in the Palm OS Programmer's Companion. ## Telephony Network Data Structures This section describes the data structures used with the telephony network service set portion of the telephony API. ## New TelNwkGetLocationType You use the TelNwkGetLocationType structure with the TelNwkGetLocation function to retrieve information about the location of the phone.
    typedef struct _TelNwkGetLocationType
    {
      Char*   value;
      UInt16  size;
    } TelNwkGetLocationType;
#### Field Descriptions #####
<- | 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 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.
## New TelNwkGetNetworkNameType You use the TelNwkGetNetworkNameType structure with the TelNwkGetNetworkName function to retrieve the name of the specified, registered network.
    typedef struct _TelNwkGetNetworkNameType
    {
      UInt32   id;
      Char*    value;
      UInt16   size;
    } TelNwkGetNetworkNameType;
#### Field Descriptions #####
-> | 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 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
## New TelNwkGetNetworksType You use the TelNwkGetNetworksType structure with the TelNwkGetNetworks function to retrieve the number of registered networks.
    typedef struct _TelNwkGetNetworksType
    {
      UInt32*  networkIdP;
      UInt8    size;
    } TelNwkGetNetworksType;
#### Field Descriptions #####
<- | 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 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 a telErrBufferSize 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 Network Search Mode Constants ## Network Type Constants The network type constants describe the type of network connection. #####
Constant | Value | Description
--- | --- | ---
kTelNwkCDMA | 0 | A CDMA network.
kTelNwkGSM | 1 | A GSM network.
kTelNwkTDMA | 2 | A TDMA network.
kTelNwkPDC | 3 | A PDC network.
## Network Search Mode Constants The network search mode constants describe the search mode used to find a network. #####
Constant | Value | Description
--- | --- | ---
kTelNwkManualSearch | 0 | Manual network searching.
kTelNwkAutomaticSearch | 1 | Automatic network searching.
## Telephony Network Functions This section describes the data structures used with the telephony network service set portion of the telephony API. ## New TelNwkGetLocation #### Purpose Retrieve information about the location of the mobile unit. #### 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 the value buffer. Upon return, the size 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 the ioParamP 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. ## New TelNwkGetNetworkName #### Purpose Returns the name of a registered network. #### 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 the value buffer. Upon return, the size 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 the ioParamP 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 the AT+CREG? command. The <network registration> value is the value retrieved by issuing the AT+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 ## New TelNwkGetNetworks #### Purpose Retrieves information about the registered networks. #### 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, the size field of this structure contains the size, in elements, of the networkIdP array field.
#####
| Upon return, the networkIdP array contains the IDs of the registered networks, and the size 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 the ioParamP parameter.
functionId | kTelNwkGetNetworkCountMessage
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 ## New TelNwkGetNetworkType #### Purpose Retrieve the type of the selected network. #### 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. ## New TelNwkGetSearchMode #### Purpose Returns the current network search mode. #### 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 TelNwkSetSearchMode ## New TelNwkGetSelectedNetwork #### Purpose Retrieve the network identifier of the currently selected network. #### 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 ## New TelNwkGetSignalLevel #### Purpose Retrieve the selected network carrier signal level. #### 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. #####
Signal level value | dBm value
--- | ---
0 | £ 113 dBm
1 | 111 dBm
2 to 30 | 109 dBm to 53 dBm
31 | 51 dBm
99 | unknown or undetectable
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. ## New TelNwkSelectNetwork #### Purpose Select a network to use from among the set of registered networks. #### 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 ## New TelNwkSetSearchMode #### Purpose Sets the search mode used to find a network. #### 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. #### See Also TelNwkGetSearchMode |