Telephony Network
 

 < 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA 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.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA 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.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<-> ioParamPA 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.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oTypePA pointer to an unsigned byte value. Upon return, this is the network type. This is one of Network Type Constants.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oModePA 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.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oNetworkIdPA pointer to an unsigned integer value. Upon return, this is the identifier of the currently selected network.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
<- oSignalPA 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.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iNetworkIdThe identifier of the network to select.
<-> ioTransIdPSet 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

-> iRefnumThe telephony manager library reference number.
-> iAppIdThe telephone application attachment identifier for your application.
-> iModeThe search mode to use. This must be one of the Network Search Mode Constants.
<-> ioTransIdPSet 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