API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » telephony

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

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