API Guide Home (Online version only) |

# HsPhoneGSM.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    HsPhoneGSM.h
    00012  *
    00013  * @brief  Header File for Phone Library API ---- GSM 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 SMS category.  These API calls are used for features that only apply
    00019  *  to GSM networks.
    00020  */
    00021
    00022
    00023 #ifndef HS_PHONEGSM_H
    00024 #define HS_PHONEGSM_H
    00025 #include <PalmOS.h>
    00026 #include <PalmTypes.h>
    00027 #ifndef __CORE_COMPATIBILITY_H__
    00028 #include <PalmCompatibility.h>
    00029     /** workaround for differing header files in sdk-3.5 and sdk-internal */
    00030     #ifndef __CORE_COMPATIBILITY_H__
    00031     #define __CORE_COMPATIBILITY_H__
    00032     #endif
    00033 #endif
    00034 #include <HsPhoneTraps.h>     /** trap table definition for phone library calls */
    00035 #include <HsPhoneErrors.h>    /** error codes returned by phone library functions */
    00036 #include <HsPhoneTypes.h>
    00037
    00038
    00039 /**
    00040  *  @brief Sets the active line number.
    00041  *
    00042  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00043  *  @param line:    IN:  Line number to be set to active.
    00044  *  @retval 0 for success; otherwise failed and returned an error code
    00045  *          as defined in “Phone Library Error Codes.”
    00046  **/
    00047 extern Err PhnLibSetActiveLine(UInt16 refNum, Int16 line)
    00048         PHN_LIB_TRAP(PhnLibTrapSetActiveLine);
    00049
    00050
    00051 /**
    00052  *  @brief Retrieve the Fixed Dialing Numbers from the SIM.
    00053  *
    00054  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00055  *  @param aList:   IN:  Returned with the list of numbers
    00056  *  @param info:    IN:
    00057  *  @retval 0 for success; otherwise failed and returned an error code
    00058  *          as defined in “Phone Library Error Codes.”
    00059  **/
    00060 extern Err PhnLibGetFDNList(UInt16 refNum, PhnAddressList* aList, PhnPhoneBookInfoPtr info)
    00061         PHN_LIB_TRAP(PhnLibTrapGetFDNList);
    00062
    00063 /**
    00064  *  @brief Set entry in the Fix Dialing field on the SIM.
    00065  *
    00066  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00067  *  @param index:   IN:  index into SIM
    00068  *  @param name:    IN:  name value for SIM entry
    00069  *  @param number:  IN:  phone number for SIM entry
    00070  *  @retval 0 for success; otherwise failed and returned an error code
    00071  *          as defined in “Phone Library Error Codes.”
    00072  **/
    00073 extern Err PhnLibSetFDNEntry (UInt16 refnum, UInt16 index, char* name, char * number)
    00074               PHN_LIB_TRAP(PhnLibTrapSetFDNEntry);
    00075
    00076 /**
    00077  *  @brief This routine reads the PhoneBook of phone numbers from your SIM (GSM only).
    00078  *         This command can take several seconds if the PhoneBook is large.
    00079  *
    00080  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00081  *  @param numbers: IN:
    00082  *  @param info:    IN:
    00083  *  @retval 0 for success; otherwise failed and returned an error code
    00084  *          as defined in “Phone Library Error Codes.”
    00085  **/
    00086 extern Err PhnLibGetPhoneBook (UInt16 refNum, PhnAddressList* numbers, PhnPhoneBookInfoPtr info)
    00087               PHN_LIB_TRAP(PhnLibTrapGetPhoneBook);
    00088
    00089 /**
    00090  *  @brief This routine writes the PhoneBook of phone numbers from your SIM (GSM only).
    00091  *         This command can take several seconds if the PhoneBook is large.
    00092  *
    00093  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00094  *  @param numbers: IN:
    00095  *  @retval 0 for success; otherwise failed and returned an error code
    00096  *          as defined in “Phone Library Error Codes.”
    00097  **/
    00098 extern Err PhnLibSetPhoneBook (UInt16 refnum, PhnAddressList numbers)
    00099               PHN_LIB_TRAP(PhnLibTrapSetPhoneBook);
    00100
    00101 /**
    00102  *  @brief Set entry in SIM Phone Book
    00103  *
    00104  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00105  *  @param index:   IN:  index into SIM Phone Book
    00106  *  @param name:    IN:  name value for SIM Phone Book entry
    00107  *  @param number:  IN:  phone number for SIM Phone Book entry
    00108  *  @retval 0 for success; otherwise failed and returned an error code
    00109  *          as defined in “Phone Library Error Codes.”
    00110  **/
    00111 extern Err PhnLibSetPhoneBookEntry (UInt16 refnum, UInt16 index, char* name, char * number)
    00112               PHN_LIB_TRAP(PhnLibTrapSetPhoneBookEntry);
    00113
    00114 /**
    00115  *  @brief This routine gets the index of the given PhoneBook address on your SIM (GSM only).
    00116  *
    00117  *  @param unused:  IN:  for the future, set to 0.
    00118  *  @param address:
    00119  *  @retval Index number.
    00120  **/
    00121 extern UInt32 PhnLibGetPhoneBookIndex(UInt16, PhnAddressHandle address)
    00122                   PHN_LIB_TRAP(PhnLibTrapGetPhoneBookIndex);
    00123
    00124
    00125 /**
    00126  *  @brief
    00127  *
    00128  *  @param refNum:  IN:
    00129  *  @param aList:   IN:
    00130  *  @param info:    IN:
    00131  *  @retval Err Error code.
    00132  **/
    00133 extern Err PhnLibGetSDNList(UInt16 refNum, PhnAddressList* aList, PhnPhoneBookInfoPtr info)
    00134         PHN_LIB_TRAP(PhnLibTrapGetSDNList);
    00135
    00136 /**
    00137  *  @brief Send USSD value to radio
    00138  *
    00139  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00140  *  @param cmd:     IN:  USSD value to be sent
    00141  *  @retval 0 for success; otherwise failed and returned an error code
    00142  *          as defined in “Phone Library Error Codes.”
    00143  **/
    00144 extern Err  PhnLibSendUSSD (UInt16 refNum, CharPtr cmd)
    00145                   PHN_LIB_TRAP(PhnLibTrapSendUSSD);
    00146
    00147 /**
    00148  *  @brief Retrieve SAT main menu.
    00149  *
    00150  *  @param refNum:      IN:  Library reference number obtained from SysLibLoad.
    00151  *  @param menuHandlePtr:   IN:  Pointer to a GSMSATEventMenuPtr.
    00152  *  @retval 0 for success; otherwise failed and returned an error code
    00153  *          as defined in “Phone Library Error Codes.” And the pointer
    00154  *          is filled with a pointer to a main menu or phnErrSATUnavailable
    00155  *          if there is no active session.
    00156  **/
    00157 extern Err PhnLibSATGetMainMenu(UInt16 refNum, MemHandle* menuHandlePtr)
    00158               PHN_LIB_TRAP(PhnLibTrapSATGetMainMenu);
    00159
    00160 /**
    00161  *  @brief Send application’s request to firmware
    00162  *
    00163  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00164  *  @param request: IN:  Request type
    00165  *  @param decision:    IN:  Decision Type
    00166  *  @param data:    IN:  Data to send
    00167  *  @param length:  IN:  Length of data to send (only for Input)
    00168  *  @retval 0 if succeed
    00169  *          phnErrIllegalCondition:unrecognized parameters or an unneeded param is not zero.
    00170  *          phnErrSATUnavailable:SAT is not available
    00171  *          phnErrSATInactive : no active SAT session; must call
    00172  *              PhnLibSATGetMainMenu() before calling this function().
    00173  **/
    00174 extern Err PhnLibSATSendRequest(UInt16 refNum, SATRequestType request, SATDecisionType decision, UInt32 data, UInt32 length)
    00175               PHN_LIB_TRAP(PhnLibTrapSATSendRequest);
    00176
    00177 /**
    00178  *  @brief Terminate an active SAT session.
    00179  *
    00180  *  @param refNum:  IN: Library reference number obtained from SysLibLoad.
    00181  *  @retval 0 if succeeded or an error from PhnLibSATSendRequest() session
    00182  **/
    00183 extern Err PhnLibSATEndSession(UInt16 refNum)
    00184               PHN_LIB_TRAP(PhnLibTrapSATEndSession);
    00185
    00186 /**
    00187  *  @brief This routine reads the IMSI number from the SIM (Subscriber Information
    00188  *         Module) on your GSM device. IMSI stands for International Mobile Subscriber
    00189  *         Identify, and is used to uniquely identify a user to the wireless network.
    00190  *
    00191  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00192  *  @param imsi:    IN:  imsi number is a string pointer.
    00193  *  @retval Boolean
    00194  **/
    00195 extern Boolean PhnLibSIMInfo (UInt16 refNum, CharPtr* imsi)
    00196               PHN_LIB_TRAP(PhnLibTrapSIMInfo);
    00197
    00198 /**
    00199  *  @brief This routine returns status of the SIM (Subscriber Information Module) on your
    00200  *         GSM device. The SIM is managed by the radio module on the handset. The SIM
    00201  *         must be present and active before the radio is allowed to make phone calls (other
    00202  *         than emergency calls). The SIM also stores various user information and settings.
    00203  *
    00204  *  @param refNum:  IN: Library reference number obtained from SysLibLoad.
    00205  *  @retval Sim Status
    00206  **/
    00207 extern GSMSIMStatus PhnLibGetSIMStatus(UInt16 refNum)
    00208               PHN_LIB_TRAP(PhnLibTrapGetSIMStatus);
    00209
    00210 /**
    00211  *  @brief Check if we are currently attached to the GPRS Network.
    00212  *
    00213  *  @param refNum:  IN: Library reference number obtained from SysLibLoad.
    00214  *  @retval True if we are attached
    00215  **/
    00216 extern Boolean PhnLibGPRSAttached (UInt16 refNum)
    00217                   PHN_LIB_TRAP(PhnLibTrapGPRSAttached);
    00218
    00219 /**
    00220  *  @brief This function will store the given settings as a profile in the radios flash
    00221  *         memory. The profile id will be the same as the context id that you pass
    00222  *         with valid values between 1 and 32.
    00223  *
    00224  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00225  *  @param contextId:   IN:
    00226  *  @param pdpType: IN:
    00227  *  @param *apn:    IN:
    00228  *  @param apnLen:  IN:
    00229  *  @param *pdpAddr:    IN:
    00230  *  @param pdpAddrLen:  IN:
    00231  *  @param pdpDataCompression:  IN:
    00232  *  @param pdpHdrCompression:   IN:
    00233  *  @retval 0 for success; otherwise failed and returned an error code
    00234  *          as defined in “Phone Library Error Codes.”
    00235  **/
    00236 extern Err PhnLibGPRSPDPContextDefine(UInt16 refNum,
    00237   UInt16 contextId,
    00238   PhnGPRSPDPType pdpType, const char* apn, UInt16 apnLen,
    00239   const char* pdpAddr, UInt16 pdpAddrLen,
    00240   UInt16 pdpDataCompression, UInt16 pdpHdrCompression)
    00241               PHN_LIB_TRAP(PhnLibTrapGPRSPDPContextDefine);
    00242
    00243 /**
    00244  *  @brief Get a linked list of pdp contexts currently stored on the device. It is
    00245  *         necessary to call the Destruct after use of the list to free the memory.
    00246  *
    00247  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00248  *  @param listHeadPP:  IN:  Pointer to a pointer where the head of the linked list will be stored.
    00249  *  @retval 0 for success; otherwise failed and returned an error code
    00250  *          as defined in “Phone Library Error Codes.”
    00251  **/
    00252 extern Err PhnLibGPRSPDPContextListConstruct(UInt16 refNum, struct PhnGPRSPDPContextListNodeType** listHeadPP)
    00253               PHN_LIB_TRAP(PhnLibTrapGPRSPDPContextListConstruct);
    00254
    00255 /**
    00256  *  @brief Function that cleans up the list of pdp contexts created by the construct functions.
    00257  *
    00258  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00259  *  @param headNodePP:  IN:  Pointer to a pointer to the head of the list.
    00260  *  @retval 0 for success; otherwise failed and returned an error code
    00261  *          as defined in “Phone Library Error Codes.”
    00262  **/
    00263 extern Err PhnLibGPRSPDPContextListDestruct(UInt16 refNum, struct PhnGPRSPDPContextListNodeType** headNodePP)
    00264               PHN_LIB_TRAP(PhnLibTrapGPRSPDPContextListDestruct);
    00265
    00266 /**
    00267  *  @brief Set either the Required or Minimum QOS service parameters. If 0 is passed for the
    00268  *         parameter, the network will decide the settings. Valid settings are listed below
    00269  *
    00270  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00271  *  @param qosType: IN:  Required or Minimum.
    00272  *  @param contextId:   IN:  id of the profile that you are setting with these QOS Values.
    00273  *  @param precedence:  IN:  (1-3) 1 being highest priority
    00274  *  @param delay:   IN:  (1-3) Predictive 4 - Best Effort
    00275  *  @param reliability: IN:  (1-5) - Unknown
    00276  *  @param peakThroughput:  IN:  (1-9) 1 is the lowest and 9 the highest
    00277  *  @param meanThroughput:  IN:  (1-9) 1 is the lowest and 9 the highest
    00278  *  @retval 0 for success; otherwise failed and returned an error code
    00279  *          as defined in “Phone Library Error Codes.”
    00280  **/
    00281 extern Err PhnLibGPRSQualityOfServiceGet(UInt16 refNum, PhnGPRSQOSType qosType, UInt16 contextId,
    00282   UInt16* precedence, UInt16* delay, UInt16* reliability, UInt16* peakThroughput,
    00283   UInt16* meanThroughput)
    00284               PHN_LIB_TRAP(PhnLibTrapGPRSQualityOfServiceGet);
    00285
    00286 /**
    00287  *  @brief Set either the Required or Minimum QOS service parameters. If 0 is passed for the
    00288  *         parameter, the network will decide the settings. Valid settings are listed below.
    00289  *
    00290  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00291  *  @param qosType:     IN:  Required or Minimum.
    00292  *  @param  contextId:  IN:  id of the profile that you are setting with these QOS Values.
    00293  *  @param  precedence: IN:  (1-3) 1 being highest priority
    00294  *  @param  delay:  IN:  (1-3) Predictive 4 - Best Effort
    00295  *  @param  reliability:    IN:  (1-5) - Unknown
    00296  *  @param  peakThroughput: IN:  (1-9) 1 is the lowest and 9 the highest
    00297  *  @param  meanThroughput: IN:  (1-9) 1 is the lowest and 9 the highest
    00298  *  @retval 0 for success; otherwise failed and returned an error code
    00299  *          as defined in “Phone Library Error Codes.”
    00300  **/
    00301 extern Err PhnLibGPRSQualityOfServiceSet(UInt16 refNum, PhnGPRSQOSType qosType, UInt16 contextId,
    00302   UInt16 precedence, UInt16 delay, UInt16 reliability, UInt16 peakThroughput,
    00303   UInt16 meanThroughput)
    00304                 PHN_LIB_TRAP(PhnLibTrapGPRSQualityOfServiceSet);
    00305
    00306 /**
    00307  *  @brief
    00308  *
    00309  *  @param refNum:  IN:
    00310  *  @param digit:   IN:
    00311  *  @param sendMode:    IN:
    00312  *  @param on:      IN:
    00313  *  @retval Err Error code.
    00314  **/
    00315 extern Err PhnLibSendLongDTMF(UInt refNum, Char digit, PhnAudioSendMode sendMode,
    00316     Boolean on)
    00317           PHN_LIB_TRAP(PhnLibTrapSendLongDTMF);
    00318
    00319 /**
    00320  *  @brief
    00321  *
    00322  *  @param refNum:  IN:
    00323  *  @param iccid:   IN:
    00324  *  @retval Err Error code.
    00325  **/
    00326 extern Err PhnLibGetICCID (UInt refNum, CharPtr* iccid)
    00327               PHN_LIB_TRAP(PhnLibTrapGetICCID);
    00328
    00329
    00330
    00331 /**
    00332  *  @brief Retreives currrent/camped Location Area Code (LAC) and Cell ID.
    00333  *
    00334  *  @param refNum:  IN:  Library reference number obtained from SysLibLoad.
    00335  *  @param pLac :   IN:  Pointer to UInt32 thats populated with LAC upon successful return.
    00336  *  @param pCellId :    IN:  Pointer to UInt32 thats populated with Cell ID upon successful return.
    00337  *  @retval Err Error code as defined in HsPhoneErrors.h
    00338  **/
    00339 extern Err PhnLibGetGSMCellInfo (UInt refNum, UInt32 *pLac, UInt32 *pCellId)
    00340               PHN_LIB_TRAP(PhnLibTrapGetGSMCellInfo);
    00341
    00342
    00343
    00344 /**
    00345  *  @brief
    00346  *
    00347  *  @param refNum:  IN: Library reference number obtained from SysLibLoad
    00348  *  @param spn:     IN: Service Provider Name from SIM
    00349  *  @retval Err Error code.
    00350  **/
    00351 extern Err PhnLibGetSpn (UInt refNum, CharPtr* spn)
    00352               PHN_LIB_TRAP(PhnLibTrapGetSpn);
    00353 #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