API Guide Home (Online version only) |

# HsPhoneNetwork.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /** @ingroup Telephony
    00006  *
    00007  */
    00008
    00009
    00010 /**
    00011  * @file    HsPhoneNetwork.h
    00012  *
    00013  * @brief  Header File for Phone Library API ---- NETWORK CATEGORY
    00014  *
    00015  * Notes:
    00016  *  All implementations of the Handspring Phone Library support a common API.
    00017  *  This API is broken up into various categories for easier management.  This file
    00018  *  defines the Network category.  These API calls are used to interact with the wireless network.
    00019  */
    00020
    00021
    00022 #ifndef HS_PHONENETWORK_H
    00023 #define HS_PHONENETWORK_H
    00024 #include <PalmOS.h>
    00025 #include <PalmTypes.h>
    00026 #ifndef __CORE_COMPATIBILITY_H__
    00027 #include <PalmCompatibility.h>
    00028     /** workaround for differing header files in sdk-3.5 and sdk-internal */
    00029     #ifndef __CORE_COMPATIBILITY_H__
    00030     #define __CORE_COMPATIBILITY_H__
    00031     #endif
    00032 #endif
    00033 #include <HsPhoneTraps.h>     /**< trap table definition for phone library calls */
    00034 #include <HsPhoneErrors.h>    /**< error codes returned by phone library functions */
    00035 #include <HsPhoneTypes.h>
    00036
    00037 /** Phone Library functions */
    00038
    00039
    00040 /**
    00041  *  @brief Gets information on a specific voicemail box as specified in the data argument.
    00042  *
    00043  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00044  *  @param data:    IN:  See “PhnMsgBoxDataType” for details
    00045  *  @retval 0 for success; otherwise failed.
    00046  **/
    00047
    00048 extern Err PhnLibBoxInformation(UInt16 refNum, PhnMsgBoxDataType* data)
    00049            PHN_LIB_TRAP(PhnLibTrapBoxInformation);
    00050
    00051 /**
    00052  *  @brief Gets or Set information on a specific voicemail box as specified in the data argument.
    00053  *
    00054  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00055  *  @param data:    IN:  See “PhnMsgBoxDataType” for details
    00056  *  @param bGetInfo:    IN:  Indicates whether the operation is a get (True) or set (False).
    00057  *  @retval 0 for success; otherwise failed.
    00058  **/
    00059 extern Err PhnLibBoxInformationEx (UInt16 refNum, PhnMsgBoxDataType *data, Boolean bGetInfo)
    00060            PHN_LIB_TRAP (PhnLibTrapBoxInformationEx);
    00061
    00062 /**
    00063  *  @brief Return the number of the voice box of the given type for the given line as
    00064  *         it is stored on the SIM.
    00065  *
    00066  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00067  *  @param type:    IN:  See “PhnMsgBoxType” for details. On Treo™ 600 smartphone by palmOne,
    00068  *                           only the kBoxVoice type is supported
    00069  *  @param line:    IN:  On a GSM/GPRS device, line can be either “1” or “2”. This is dependant on if
    00070  *                           the subscriber account supports 1 or 2 line(s) (on GSM, this is called
    00071  *                           Alternative Line Service).
    00072  *                           On the CDMA device, it is currently not used.
    00073  *  @param number:  IN:  Returns the number as a string.
    00074  *  @retval PhnLibGetBoxNumber returns 0 if the number could be determined without
    00075  *          encountering an error.
    00076  **/
    00077 extern Err PhnLibGetBoxNumber(UInt16 refNum, PhnMsgBoxType type, UInt16 line, CharPtr * number)
    00078            PHN_LIB_TRAP(PhnLibTrapGetBoxNumber);
    00079
    00080 /**
    00081  *  @brief Get value for home network’s operator ID (MCC+MNC) string
    00082  *
    00083  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00084  *  @param *buffer: IN:  Buffer to hold returned string
    00085  *  @param bufferSizeP: IN:
    00086  *  @retval 0 for success; otherwise failed
    00087  **/
    00088 extern Err PhnLibHomeOperatorID (UInt16 refNum, char *buffer, Int16* bufferSizeP)
    00089            PHN_LIB_TRAP(PhnLibTrapHomeOperatorID);
    00090
    00091 /**
    00092  *  @brief Get value for current network’s operator ID (MCC+MNC) string
    00093  *
    00094  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00095  *  @param *buffer: IN:  buffer to hold returned string
    00096  *  @param bufferSizeP: IN:
    00097  *  @retval 0 for success; otherwise failed
    00098  **/
    00099 extern Err PhnLibCurrentOperatorID (UInt16 refNum, char *buffer, Int16* bufferSizeP)
    00100             PHN_LIB_TRAP(PhnLibTrapCurrentOperatorID);
    00101
    00102     // Used only by the phone app, so change CDMA function to match this prototype -- ignore mode parameter
    00103 /**
    00104  *  @brief Get value for current network’s operator string
    00105  *
    00106  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00107  *  @param id:      IN:  returned operator ID value
    00108  *  @param name:    IN:  returned operator name string
    00109  *  @param mode:    IN:  returned registration mode for current operator
    00110  *  @retval 0 for success; otherwise failed
    00111  **/
    00112 extern Err PhnLibCurrentOperator (UInt16 refNum, PhnOperatorID* id, CharPtr* name, GSMRegistrationMode* mode)
    00113            PHN_LIB_TRAP(PhnLibTrapCurrentOperator);
    00114
    00115
    00116   // Use this as base -- CDMA function just returns phnErrNotSupported
    00117 /**
    00118  *  @brief Set value of operator for radio to register to
    00119  *
    00120  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00121  *  @param op:      IN:  operator to register to
    00122  *  @param regMode: IN:  type of registration to make
    00123  *  @retval 0 for success; otherwise failed
    00124  **/
    00125 extern Err PhnLibSetOperator (UInt16 refNum, PhnOperatorType* op, GSMRegistrationMode regMode)
    00126            PHN_LIB_TRAP(PhnLibTrapSetOperator);
    00127
    00128     // Change to return err, and add PhnRoamStatus parameter
    00129 /**
    00130  *  @brief Return the roaming status
    00131  *
    00132  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00133  *  @param roamStatus:  IN:  PhnLibRoaming returns the roaming status.
    00134  *  @retval 0 if no error; error code otherwise
    00135  **/
    00136 extern Err PhnLibRoaming(UInt16 refNum, PhnRoamStatus * roamStatus)
    00137            PHN_LIB_TRAP(PhnLibTrapRoaming);
    00138
    00139 /**
    00140  *  @brief Checks if the phone found any network cellular service.
    00141  *
    00142  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00143  *  @retval true if service is found.
    00144  *          false if no service
    00145  **/
    00146 extern Boolean PhnLibRegistered (UInt16 refNum)
    00147                PHN_LIB_TRAP(PhnLibTrapRegistered);
    00148
    00149 /**
    00150  *  @brief Return the signal strength
    00151  *
    00152  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00153  *  @param quality: IN:  Phone signal strength in dBm
    00154  *  @retval 0 if no error
    00155  **/
    00156 extern Err PhnLibSignalQuality (UInt16 refNum, UInt16 * quality)
    00157            PHN_LIB_TRAP(PhnLibTrapSignalQuality);
    00158
    00159 /**
    00160  *  @brief Get the signal quality and ecio level information.
    00161  *
    00162  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00163  *  @param quality: IN:  Phone signal strength in dBm
    00164  *  @param *bEcio:  IN:
    00165  *  @param *ecioLvl:    IN:
    00166  *  @retval 0 for success; otherwise failed
    00167  **/
    00168 extern Err PhnLibSignalQualityEx (UInt16 refNum, UInt16 * quality, Boolean *bEcio, UInt16 *ecioLvl)
    00169            PHN_LIB_TRAP (PhnLibTrapSignalQualityEx);
    00170
    00171 /**
    00172  *  @brief Get value for current network’s provider
    00173  *
    00174  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00175  *  @param name:    IN:  returned provider name string
    00176  *  @retval 0 for success; otherwise failed
    00177  **/
    00178 extern Err PhnLibCurrentProvider(UInt16 refNum, char** name)
    00179            PHN_LIB_TRAP(PhnLibTrapCurrentProvider);
    00180
    00181 /**
    00182  *  @brief Get list of operators available to radio
    00183  *
    00184  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00185  *  @param list:    IN:  container for returned list of operator values
    00186  *  @retval 0 for success; otherwise failed
    00187  **/
    00188 extern Err PhnLibGetOperatorList (UInt16 refNum, PhnOperatorListPtr * list)
    00189            PHN_LIB_TRAP(PhnLibTrapGetOperatorList);
    00190
    00191 /**
    00192  *  @brief Return a list of phone numbers from the device. These numbers could be
    00193  *         voicemail box, data line or fax line (if supported).
    00194  *
    00195  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00196  *  @param ownNumbers:  IN:  Pointer to the list of phone box number of the device.
    00197  *  @retval 0 for success; otherwise failed
    00198  **/
    00199 extern Err PhnLibGetOwnNumbers (UInt16 refNum, PhnAddressList* ownNumbers)
    00200            PHN_LIB_TRAP(PhnLibTrapGetOwnNumbers);
    00201
    00202 /**
    00203  *  @brief <description to be provided>
    00204  *
    00205  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00206  *  @param ownNumbers:  IN:
    00207  *  @retval 0 for success; otherwise failed
    00208  **/
    00209 extern Err PhnLibSetOwnNumbers (UInt16 refnum, PhnAddressList ownNumbers)
    00210            PHN_LIB_TRAP(PhnLibTrapSetOwnNumbers);
    00211
    00212 /**
    00213  *  @brief Enable/disable call waiting for phone calls on radio
    00214  *
    00215  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00216  *  @param enabled: IN:  flag to enable/disable call waiting
    00217  *  @retval 0 for success; otherwise failed
    00218  **/
    00219 extern Err PhnLibSetCallWaiting (UInt16 refNum, Boolean enabled)
    00220            PHN_LIB_TRAP(PhnLibTrapSetCallWaiting);
    00221
    00222 /**
    00223  *  @brief Get call waiting setting for phone calls on radio
    00224  *
    00225  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00226  *  @param enabled: IN:  return value of call waiting service on radio.
    00227  *                           true if call waiting is enabled
    00228  *                           false if call waiting is disabled
    00229  *                           value is undefined if return value of function is not 0 (ERROR)
    00230  *  @retval 0 for success; otherwise failed
    00231  **/
    00232 extern Err PhnLibGetCallWaiting (UInt16 refNum, BooleanPtr enabled)
    00233            PHN_LIB_TRAP(PhnLibTrapGetCallWaiting);
    00234
    00235 /**
    00236  *  @brief
    00237  *
    00238  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00239  *  @param enable:  IN:  True to enable CLIP.
    00240  *                           False to disable it.
    00241  *  @retval Err Error code.
    00242  **/
    00243 extern Err PhnLibSetCLIP (UInt16 refNum, Boolean enable)
    00244            PHN_LIB_TRAP(PhnLibTrapSetCLIP);
    00245
    00246 /**
    00247  *  @brief (TBC)
    00248  *
    00249  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00250  *  @param enabled: IN:
    00251  *  @retval Err Error code.
    00252  **/
    00253 extern Err PhnLibGetCLIP(UInt16 refNum, Boolean* enabled)
    00254            PHN_LIB_TRAP(PhnLibTrapGetCLIP);
    00255
    00256     // Used only by the phone app, so change CDMA function to match this prototype
    00257 /**
    00258  *  @brief Returns the forwarded number stored in smartphone radio.
    00259  *
    00260  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00261  *  @param condition:   IN:  forwarding condition to get values for. Currently CDMA only supports
    00262  *                           “phnForwardUnconditional” as defined in “PhnForwardType”.
    00263  *  @param destination: IN:  returned forwarding address for given forwarding condition
    00264  *  @retval Err 0 for success; otherwise failed
    00265  **/
    00266 extern Err PhnLibGetForwarding (UInt16 refNum, PhnForwardType condition, PhnAddressHandle * destination)
    00267            PHN_LIB_TRAP(PhnLibTrapGetForwarding);
    00268
    00269 /**
    00270  *  @brief
    00271  *
    00272  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00273  *  @param mode:    IN:  (TBC)
    00274  *  @retval 0 for success; otherwise failed.
    00275  **/
    00276 extern Err PhnLibSetCLIR (UInt16 refNum, GSMDialCLIRMode mode)
    00277            PHN_LIB_TRAP(PhnLibTrapSetCLIR);
    00278
    00279 /**
    00280  *  @brief (TBC)
    00281  *
    00282  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00283  *  @param mode:    IN:
    00284  *  @param status:  IN:
    00285  *  @retval Err Error code.
    00286  **/
    00287 extern Err PhnLibGetCLIR (UInt16 refNum, GSMDialCLIRMode* mode, PhnCLIRStatus* status)
    00288            PHN_LIB_TRAP(PhnLibTrapGetCLIR);
    00289
    00290 /**
    00291  *  @brief Used to Activate a Barring Service
    00292  *
    00293  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00294  *  @param facility:    IN:  Barring condition to be set
    00295  *  @param password:    IN:  Password to set Barring. This will be used when changing barring option.
    00296  *  @retval 0 for success; otherwise failed
    00297  **/
    00298 extern Err PhnLibSetBarring (UInt16 refNum, PhnBarFacilityType facility, CharPtr password)
    00299            PHN_LIB_TRAP(PhnLibTrapSetBarring);
    00300
    00301 /**
    00302  *  @brief Get Barring Service state for given facility
    00303  *
    00304  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00305  *  @param facility:    IN:  barring condition to get state for
    00306  *  @param enabled: IN:  returned state of given barring service; true = activated.
    00307  *  @retval 0 for success; otherwise failed
    00308  **/
    00309 extern Err PhnLibGetBarring (UInt16 refNum, PhnBarFacilityType facility, Boolean* enabled)
    00310            PHN_LIB_TRAP(PhnLibTrapGetBarring);
    00311
    00312 /**
    00313  *  @brief Used to Deactivate a Barring Service
    00314  *
    00315  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00316  *  @param facility:    IN:  barring condition to be deactivated
    00317  *  @param password:    IN:
    00318  *  @retval 0 for success; otherwise failed
    00319  **/
    00320 extern Err PhnLibDeactivateBarring (UInt16 refNum, PhnBarFacilityType facility, CharPtr password)
    00321            PHN_LIB_TRAP(PhnLibTrapDeactivateBarring);
    00322
    00323 /**
    00324  *  @brief Retrieves the roaming indicator text that needs to be displayed if the
    00325  *         phone is in enhanced roaming mode.
    00326  *
    00327  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00328  *  @param roamTxt: IN:  Pointer to a char of “PhnEnhancedRoamIndMaxLength” maximum length.
    00329  *  @param *iconState:  IN:
    00330  *  @retval phnErrNotAllowed if called when the phone is not in enhanced roaming.
    00331  **/
    00332 extern Err PhnLibGetEnhancedRoamIndicator (UInt16 refNum, char * roamTxt, PhnRoamIconState *iconState)
    00333            PHN_LIB_TRAP(PhnLibTrapEnhancedRoamIndicator);
    00334
    00335 /**
    00336  *  @brief (TBD)
    00337  *
    00338  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00339  *  @param Mode:    IN:  see PhnRoamPrefSelectionType
    00340  *  @retval Err Error code.
    00341  **/
    00342 extern Err PhnLibGetRoamPrefMode (UInt16 refNum, PhnRoamPrefSelectionType *roamPrefP)
    00343            PHN_LIB_TRAP (PhnLibTrapGetRoamPrefMode);
    00344
    00345 /**
    00346  *  @brief Set the roaming mode. This API is the same as used when the user
    00347  *         checks or unchecks the “Enable Digital roaming” in the Phone
    00348  *         Preference on Treo 600. If set, then digital roaming will be allowed.
    00349  *
    00350  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00351  *  @param Mode:    IN:  see PhnRoamPrefSelectionType
    00352  *  @retval Error status
    00353  **/
    00354 extern Err PhnLibSetRoamPrefMode (UInt16 refNum, PhnRoamPrefSelectionType roamPref)
    00355            PHN_LIB_TRAP (PhnLibTrapSetRoamPrefMode);
    00356
    00357 /**
    00358  *  @brief
    00359  *
    00360  *  @param refNum:  IN:
    00361  *  @param pInfo:   IN:
    00362  *  @retval Err Error code.
    00363  **/
    00364 extern Err PhnLibSetRoamPrefInfo (UInt16 refNum, PhnRoamPrefInfoPtr pInfo)
    00365            PHN_LIB_TRAP (PhnLibTrapSetRoamPrefInfo);
    00366
    00367 /**
    00368  *  @brief This function indicate if the Operator has locked the phone to its
    00369  *         network (i.e. it can’t be used on other network)
    00370  *
    00371  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00372  *  @param facilityType:    IN:  optional facility type, or 0 (TBC)
    00373  *  @param enabled: IN:  pointer to output value
    00374  *  @retval True if a network was found even if we are unable to register to it.
    00375  *          False if no network can be found.
    00376  **/
    00377 extern Err PhnLibGetOperatorLock(UInt16 refNum, UInt16 facilityType, Boolean* enabled)
    00378            PHN_LIB_TRAP(PhnLibTrapGetOperatorLock);
    00379
    00380 /**
    00381  *  @brief (TBD)
    00382  *
    00383  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00384  *  @retval Err Error code.
    00385  **/
    00386 extern Boolean PhnLibNetworkAvailable (UInt16 refNum)
    00387                PHN_LIB_TRAP(PhnLibTrapNetworkAvailable);
    00388
    00389   // GSM and CDMA differ
    00390   // Used only by the phone app, so change CDMA function to match this prototype
    00391 /**
    00392  *  @brief Set call forwarding settings
    00393  *
    00394  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00395  *  @param condition:   IN:  forwarding condition to be set
    00396  *  @param mode:    IN:  forwarding condition value to be set
    00397  *  @param destination: IN:  forwarding address value
    00398  *  @retval Err 0 for success; otherwise failed
    00399  **/
    00400 extern Err PhnLibSetForwarding (UInt16 refNum, PhnForwardType condition, PhnForwardModeType mode, PhnAddressHandle destination)
    00401            PHN_LIB_TRAP(PhnLibTrapSetForwarding);
    00402
    00403 /**
    00404  *  @brief This function gives the threshold level of signal quality at which
    00405  *         the radio is capable of sending data.
    00406  *
    00407  *  @param refNum:  IN:  Library reference number returned by HsGetPhoneLibrary().
    00408  *  @param threshold:   IN:  (TBC)
    00409  *  @retval 0 for success; otherwise failed
    00410  **/
    00411 extern Err PhnLibUsableSignalStrengthThreshold (UInt16 refNum, WordPtr threshold)
    00412            PHN_LIB_TRAP(PhnLibTrapUsableSignalStrengthThreshold);
    00413
    00414 /**
    00415  *  @brief Returns the current state of the data session as well as the available
    00416  *         data session type currently available on the network.
    00417  *
    00418  *  @param refNum:              IN:  Library reference number returned by HsGetPhoneLibrary().
    00419  *  @param dataSessionStateP:  OUT:  data structure to be filled out. version field must be set
    00420  *  @retval 0 for success; otherwise failed
    00421  **/
    00422 extern Err PhnLibGetDataSessionInfo(UInt16 refNum, PhnDataSessionStateType *dataSessionStateP)
    00423            PHN_LIB_TRAP(PhnLibTrapGetDataSessionInfo);
    00424
    00425 #endif

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