API Guide Home (Online version only) |

# HsPhoneNetwork.h File Reference

## Detailed Description

Header File for Phone Library API ---- NETWORK CATEGORY.

Notes: All implementations of the Handspring Phone Library support a common API. This API is broken up into various categories for easier management. This file defines the Network category. These API calls are used to interact with the wireless network.

Definition in file HsPhoneNetwork.h.

Include dependency graph for HsPhoneNetwork.h:

Go to the source code of this file.

## Functions

- Err PhnLibBoxInformation (UInt16 refNum, PhnMsgBoxDataType *data)
    Gets information on a specific voicemail box as specified in the data argument.
- Err PhnLibBoxInformationEx (UInt16 refNum, PhnMsgBoxDataType *data, Boolean bGetInfo)
    Gets or Set information on a specific voicemail box as specified in the data argument.
- Err PhnLibGetBoxNumber (UInt16 refNum, PhnMsgBoxType type, UInt16 line, CharPtr *number)
    Return the number of the voice box of the given type for the given line as it is stored on the SIM.
- Err PhnLibHomeOperatorID (UInt16 refNum, char *buffer, Int16 *bufferSizeP)
    Get value for home network’s operator ID (MCC+MNC) string.
- Err PhnLibCurrentOperatorID (UInt16 refNum, char *buffer, Int16 *bufferSizeP)
    Get value for current network’s operator ID (MCC+MNC) string.
- Err PhnLibCurrentOperator (UInt16 refNum, PhnOperatorID *id, CharPtr *name, GSMRegistrationMode *mode)
    Get value for current network’s operator string.
- Err PhnLibSetOperator (UInt16 refNum, PhnOperatorType *op, GSMRegistrationMode regMode)
    Set value of operator for radio to register to.
- Err PhnLibRoaming (UInt16 refNum, PhnRoamStatus *roamStatus)
    Return the roaming status.
- Boolean PhnLibRegistered (UInt16 refNum)
    Checks if the phone found any network cellular service.
- Err PhnLibSignalQuality (UInt16 refNum, UInt16 *quality)
    Return the signal strength.
- Err PhnLibSignalQualityEx (UInt16 refNum, UInt16 *quality, Boolean *bEcio, UInt16 *ecioLvl)
    Get the signal quality and ecio level information.
- Err PhnLibCurrentProvider (UInt16 refNum, char **name)
    Get value for current network’s provider.
- Err PhnLibGetOperatorList (UInt16 refNum, PhnOperatorListPtr *list)
    Get list of operators available to radio.
- Err PhnLibGetOwnNumbers (UInt16 refNum, PhnAddressList *ownNumbers)
    Return a list of phone numbers from the device. These numbers could be voicemail box, data line or fax line (if supported).
- Err PhnLibSetOwnNumbers (UInt16 refnum, PhnAddressList ownNumbers)
- Err PhnLibSetCallWaiting (UInt16 refNum, Boolean enabled)
    Enable/disable call waiting for phone calls on radio.
- Err PhnLibGetCallWaiting (UInt16 refNum, BooleanPtr enabled)
    Get call waiting setting for phone calls on radio.
- Err PhnLibSetCLIP (UInt16 refNum, Boolean enable)
    Parameters:

      | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

- Err PhnLibGetCLIP (UInt16 refNum, Boolean *enabled)
    (TBC)
- Err PhnLibGetForwarding (UInt16 refNum, PhnForwardType condition, PhnAddressHandle *destination)
    Returns the forwarded number stored in smartphone radio.
- Err PhnLibSetCLIR (UInt16 refNum, GSMDialCLIRMode mode)
    Parameters:

      | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

- Err PhnLibGetCLIR (UInt16 refNum, GSMDialCLIRMode *mode, PhnCLIRStatus *status)
    (TBC)
- Err PhnLibSetBarring (UInt16 refNum, PhnBarFacilityType facility, CharPtr password)
    Used to Activate a Barring Service.
- Err PhnLibGetBarring (UInt16 refNum, PhnBarFacilityType facility, Boolean *enabled)
    Get Barring Service state for given facility.
- Err PhnLibDeactivateBarring (UInt16 refNum, PhnBarFacilityType facility, CharPtr password)
    Used to Deactivate a Barring Service.
- Err PhnLibGetEnhancedRoamIndicator (UInt16 refNum, char *roamTxt, PhnRoamIconState *iconState)
    Retrieves the roaming indicator text that needs to be displayed if the phone is in enhanced roaming mode.
- Err PhnLibGetRoamPrefMode (UInt16 refNum, PhnRoamPrefSelectionType *roamPrefP)
    (TBD)
- Err PhnLibSetRoamPrefMode (UInt16 refNum, PhnRoamPrefSelectionType roamPref)
    Set the roaming mode. This API is the same as used when the user checks or unchecks the “Enable Digital roaming” in the Phone Preference on Treo 600. If set, then digital roaming will be allowed.
- Err PhnLibSetRoamPrefInfo (UInt16 refNum, PhnRoamPrefInfoPtr pInfo)
    Parameters:

      | refNum,: | IN:

- Err PhnLibGetOperatorLock (UInt16 refNum, UInt16 facilityType, Boolean *enabled)
    This function indicate if the Operator has locked the phone to its network (i.e. it can’t be used on other network).
- Boolean PhnLibNetworkAvailable (UInt16 refNum)
    (TBD)
- Err PhnLibSetForwarding (UInt16 refNum, PhnForwardType condition, PhnForwardModeType mode, PhnAddressHandle destination)
    Set call forwarding settings.
- Err PhnLibUsableSignalStrengthThreshold (UInt16 refNum, WordPtr threshold)
    This function gives the threshold level of signal quality at which the radio is capable of sending data.
- Err PhnLibGetDataSessionInfo (UInt16 refNum, PhnDataSessionStateType *dataSessionStateP)
    Returns the current state of the data session as well as the available data session type currently available on the network.

## Function Documentation

Err PhnLibBoxInformation | ( | UInt16 | refNum,
|  | PhnMsgBoxDataType * | data |
| ) |  |  |

Gets information on a specific voicemail box as specified in the data argument.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | data,: | IN: See “PhnMsgBoxDataType” for details

Return values:

  | 0 | for success; otherwise failed.

Err PhnLibBoxInformationEx | ( | UInt16 | refNum,
|  | PhnMsgBoxDataType * | data,
|  | Boolean | bGetInfo |
| ) |  |  |

Gets or Set information on a specific voicemail box as specified in the data argument.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | data,: | IN: See “PhnMsgBoxDataType” for details
  | bGetInfo,: | IN: Indicates whether the operation is a get (True) or set (False).

Return values:

  | 0 | for success; otherwise failed.

Err PhnLibCurrentOperator | ( | UInt16 | refNum,
|  | PhnOperatorID * | id,
|  | CharPtr * | name,
|  | GSMRegistrationMode * | mode |
| ) |  |  |

Get value for current network’s operator string.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | id,: | IN: returned operator ID value
  | name,: | IN: returned operator name string
  | mode,: | IN: returned registration mode for current operator

Return values:

  | 0 | for success; otherwise failed

Err PhnLibCurrentOperatorID | ( | UInt16 | refNum,
|  | char * | buffer,
|  | Int16 * | bufferSizeP |
| ) |  |  |

Get value for current network’s operator ID (MCC+MNC) string.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | *buffer,: | IN: buffer to hold returned string
  | bufferSizeP,: | IN:

Return values:

  | 0 | for success; otherwise failed

Err PhnLibCurrentProvider | ( | UInt16 | refNum,
|  | char ** | name |
| ) |  |  |

Get value for current network’s provider.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | name,: | IN: returned provider name string

Return values:

  | 0 | for success; otherwise failed

Err PhnLibDeactivateBarring | ( | UInt16 | refNum,
|  | PhnBarFacilityType | facility,
|  | CharPtr | password |
| ) |  |  |

Used to Deactivate a Barring Service.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | facility,: | IN: barring condition to be deactivated
  | password,: | IN:

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetBarring | ( | UInt16 | refNum,
|  | PhnBarFacilityType | facility,
|  | Boolean * | enabled |
| ) |  |  |

Get Barring Service state for given facility.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | facility,: | IN: barring condition to get state for
  | enabled,: | IN: returned state of given barring service; true = activated.

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetBoxNumber | ( | UInt16 | refNum,
|  | PhnMsgBoxType | type,
|  | UInt16 | line,
|  | CharPtr * | number |
| ) |  |  |

Return the number of the voice box of the given type for the given line as it is stored on the SIM.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | type,: | IN: See “PhnMsgBoxType” for details. On Treo™ 600 smartphone by palmOne, only the kBoxVoice type is supported
  | line,: | IN: On a GSM/GPRS device, line can be either “1” or “2”. This is dependant on if the subscriber account supports 1 or 2 line(s) (on GSM, this is called Alternative Line Service). On the CDMA device, it is currently not used.
  | number,: | IN: Returns the number as a string.

Return values:

  | PhnLibGetBoxNumber | returns 0 if the number could be determined without encountering an error.

Err PhnLibGetCallWaiting | ( | UInt16 | refNum,
|  | BooleanPtr | enabled |
| ) |  |  |

Get call waiting setting for phone calls on radio.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | enabled,: | IN: return value of call waiting service on radio. true if call waiting is enabled false if call waiting is disabled value is undefined if return value of function is not 0 (ERROR)

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetCLIP | ( | UInt16 | refNum,
|  | Boolean * | enabled |
| ) |  |  |

(TBC)

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | enabled,: | IN:

Return values:

  | Err | Error code.

Err PhnLibGetCLIR | ( | UInt16 | refNum,
|  | GSMDialCLIRMode * | mode,
|  | PhnCLIRStatus * | status |
| ) |  |  |

(TBC)

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | mode,: | IN:
  | status,: | IN:

Return values:

  | Err | Error code.

Err PhnLibGetDataSessionInfo | ( | UInt16 | refNum,
|  | PhnDataSessionStateType * | dataSessionStateP |
| ) |  |  |

Returns the current state of the data session as well as the available data session type currently available on the network.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | dataSessionStateP,: | OUT: data structure to be filled out. version field must be set

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetEnhancedRoamIndicator | ( | UInt16 | refNum,
|  | char * | roamTxt,
|  | PhnRoamIconState * | iconState |
| ) |  |  |

Retrieves the roaming indicator text that needs to be displayed if the phone is in enhanced roaming mode.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | roamTxt,: | IN: Pointer to a char of “PhnEnhancedRoamIndMaxLength” maximum length.
  | *iconState,: | IN:

Return values:

  | phnErrNotAllowed | if called when the phone is not in enhanced roaming.

Err PhnLibGetForwarding | ( | UInt16 | refNum,
|  | PhnForwardType | condition,
|  | PhnAddressHandle * | destination |
| ) |  |  |

Returns the forwarded number stored in smartphone radio.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | condition,: | IN: forwarding condition to get values for. Currently CDMA only supports “phnForwardUnconditional” as defined in “PhnForwardType”.
  | destination,: | IN: returned forwarding address for given forwarding condition

Return values:

  | Err | 0 for success; otherwise failed

Err PhnLibGetOperatorList | ( | UInt16 | refNum,
|  | PhnOperatorListPtr * | list |
| ) |  |  |

Get list of operators available to radio.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | list,: | IN: container for returned list of operator values

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetOperatorLock | ( | UInt16 | refNum,
|  | UInt16 | facilityType,
|  | Boolean * | enabled |
| ) |  |  |

This function indicate if the Operator has locked the phone to its network (i.e. it can’t be used on other network).

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | facilityType,: | IN: optional facility type, or 0 (TBC)
  | enabled,: | IN: pointer to output value

Return values:

  | True | if a network was found even if we are unable to register to it. False if no network can be found.

Err PhnLibGetOwnNumbers | ( | UInt16 | refNum,
|  | PhnAddressList * | ownNumbers |
| ) |  |  |

Return a list of phone numbers from the device. These numbers could be voicemail box, data line or fax line (if supported).

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | ownNumbers,: | IN: Pointer to the list of phone box number of the device.

Return values:

  | 0 | for success; otherwise failed

Err PhnLibGetRoamPrefMode | ( | UInt16 | refNum,
|  | PhnRoamPrefSelectionType * | roamPrefP |
| ) |  |  |

(TBD)

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | Mode,: | IN: see PhnRoamPrefSelectionType

Return values:

  | Err | Error code.

Err PhnLibHomeOperatorID | ( | UInt16 | refNum,
|  | char * | buffer,
|  | Int16 * | bufferSizeP |
| ) |  |  |

Get value for home network’s operator ID (MCC+MNC) string.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | *buffer,: | IN: Buffer to hold returned string
  | bufferSizeP,: | IN:

Return values:

  | 0 | for success; otherwise failed

Boolean PhnLibNetworkAvailable | ( | UInt16 | refNum | ) |

(TBD)

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

Return values:

  | Err | Error code.

Boolean PhnLibRegistered | ( | UInt16 | refNum | ) |

Checks if the phone found any network cellular service.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

Return values:

  | true | if service is found. false if no service

Err PhnLibRoaming | ( | UInt16 | refNum,
|  | PhnRoamStatus * | roamStatus |
| ) |  |  |

Return the roaming status.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | roamStatus,: | IN: PhnLibRoaming returns the roaming status.

Return values:

  | 0 | if no error; error code otherwise

Err PhnLibSetBarring | ( | UInt16 | refNum,
|  | PhnBarFacilityType | facility,
|  | CharPtr | password |
| ) |  |  |

Used to Activate a Barring Service.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | facility,: | IN: Barring condition to be set
  | password,: | IN: Password to set Barring. This will be used when changing barring option.

Return values:

  | 0 | for success; otherwise failed

Err PhnLibSetCallWaiting | ( | UInt16 | refNum,
|  | Boolean | enabled |
| ) |  |  |

Enable/disable call waiting for phone calls on radio.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | enabled,: | IN: flag to enable/disable call waiting

Return values:

  | 0 | for success; otherwise failed

Err PhnLibSetCLIP | ( | UInt16 | refNum,
|  | Boolean | enable |
| ) |  |  |

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

Parameters:

  | enable,: | IN: True to enable CLIP. False to disable it.

Return values:

  | Err | Error code.

Err PhnLibSetCLIR | ( | UInt16 | refNum,
|  | GSMDialCLIRMode | mode |
| ) |  |  |

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().

Parameters:

  | mode,: | IN: (TBC)

Return values:

  | 0 | for success; otherwise failed.

Err PhnLibSetForwarding | ( | UInt16 | refNum,
|  | PhnForwardType | condition,
|  | PhnForwardModeType | mode,
|  | PhnAddressHandle | destination |
| ) |  |  |

Set call forwarding settings.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | condition,: | IN: forwarding condition to be set
  | mode,: | IN: forwarding condition value to be set
  | destination,: | IN: forwarding address value

Return values:

  | Err | 0 for success; otherwise failed

Err PhnLibSetOperator | ( | UInt16 | refNum,
|  | PhnOperatorType * | op,
|  | GSMRegistrationMode | regMode |
| ) |  |  |

Set value of operator for radio to register to.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | op,: | IN: operator to register to
  | regMode,: | IN: type of registration to make

Return values:

  | 0 | for success; otherwise failed

Err PhnLibSetOwnNumbers | ( | UInt16 | refnum,
|  | PhnAddressList | ownNumbers |
| ) |  |  |

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | ownNumbers,: | IN:

Return values:

  | 0 | for success; otherwise failed

Err PhnLibSetRoamPrefInfo | ( | UInt16 | refNum,
|  | PhnRoamPrefInfoPtr | pInfo |
| ) |  |  |

Parameters:

  | refNum,: | IN:

Parameters:

  | pInfo,: | IN:

Return values:

  | Err | Error code.

Err PhnLibSetRoamPrefMode | ( | UInt16 | refNum,
|  | PhnRoamPrefSelectionType | roamPref |
| ) |  |  |

Set the roaming mode. This API is the same as used when the user checks or unchecks the “Enable Digital roaming” in the Phone Preference on Treo 600. If set, then digital roaming will be allowed.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | Mode,: | IN: see PhnRoamPrefSelectionType

Return values:

  | Error | status

Err PhnLibSignalQuality | ( | UInt16 | refNum,
|  | UInt16 * | quality |
| ) |  |  |

Return the signal strength.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | quality,: | IN: Phone signal strength in dBm

Return values:

  | 0 | if no error

Err PhnLibSignalQualityEx | ( | UInt16 | refNum,
|  | UInt16 * | quality,
|  | Boolean * | bEcio,
|  | UInt16 * | ecioLvl |
| ) |  |  |

Get the signal quality and ecio level information.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | quality,: | IN: Phone signal strength in dBm
  | *bEcio,: | IN:
  | *ecioLvl,: | IN:

Return values:

  | 0 | for success; otherwise failed

Err PhnLibUsableSignalStrengthThreshold | ( | UInt16 | refNum,
|  | WordPtr | threshold |
| ) |  |  |

This function gives the threshold level of signal quality at which the radio is capable of sending data.

Parameters:

  | refNum,: | IN: Library reference number returned by HsGetPhoneLibrary().
  | threshold,: | IN: (TBC)

Return values:

  | 0 | for success; otherwise failed

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:22 2008 for Palm API Guide