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

75    Telephony Network

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

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."

This chapter describes:

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

Telephony Network Data Structures ^TOP^

This section describes the data structures used with the telephony network service set portion of the telephony API.

TelNwkGetLocationType Struct ^TOP^

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 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.

TelNwkGetNetworkNameType Struct ^TOP^

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 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

TelNwkGetNetworksType Struct ^TOP^

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 a telErrBufferSize error

Telephony Network Constants ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

This section describes the data structures used with the telephony network service set portion of the telephony API.

TelNwkGetLocation Function ^TOP^

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 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.

TelNwkGetNetworkName Function ^TOP^

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 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()

TelNwkGetNetworks Function ^TOP^

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, 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
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 ^TOP^

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 ^TOP^

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

TelNwkSetSearchMode()

TelNwkGetSelectedNetwork Function ^TOP^

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 ^TOP^

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.

Table 75.1  Network carrier singal 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.

TelNwkSelectNetwork Function ^TOP^

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 ^TOP^

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.

See Also

TelNwkGetSearchMode()

 
   

Copyright © 1996-2004, PalmSource, Inc. and its affiliates. All rights reserved.
Write Us | Training | Knowledge Base | Legal


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