API Guide Home (Online version only) |

# HsPhoneGSM.h File Reference

## Detailed Description

Header File for Phone Library API ---- GSM 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 SMS category. These API calls are used for features that only apply to GSM networks.

Definition in file HsPhoneGSM.h.

Include dependency graph for HsPhoneGSM.h:

Go to the source code of this file.

## Functions

- Err PhnLibSetActiveLine (UInt16 refNum, Int16 line)
    Sets the active line number.
- Err PhnLibGetFDNList (UInt16 refNum, PhnAddressList *aList, PhnPhoneBookInfoPtr info)
    Retrieve the Fixed Dialing Numbers from the SIM.
- Err PhnLibSetFDNEntry (UInt16 refnum, UInt16 index, char *name, char *number)
    Set entry in the Fix Dialing field on the SIM.
- Err PhnLibGetPhoneBook (UInt16 refNum, PhnAddressList *numbers, PhnPhoneBookInfoPtr info)
    This routine reads the PhoneBook of phone numbers from your SIM (GSM only). This command can take several seconds if the PhoneBook is large.
- Err PhnLibSetPhoneBook (UInt16 refnum, PhnAddressList numbers)
    This routine writes the PhoneBook of phone numbers from your SIM (GSM only). This command can take several seconds if the PhoneBook is large.
- Err PhnLibSetPhoneBookEntry (UInt16 refnum, UInt16 index, char *name, char *number)
    Set entry in SIM Phone Book.
- UInt32 PhnLibGetPhoneBookIndex (UInt16, PhnAddressHandle address)
    This routine gets the index of the given PhoneBook address on your SIM (GSM only).
- Err PhnLibGetSDNList (UInt16 refNum, PhnAddressList *aList, PhnPhoneBookInfoPtr info)
    Parameters:

      | refNum,: | IN:

- Err PhnLibSendUSSD (UInt16 refNum, CharPtr cmd)
    Send USSD value to radio.
- Err PhnLibSATGetMainMenu (UInt16 refNum, MemHandle *menuHandlePtr)
    Retrieve SAT main menu.
- Err PhnLibSATSendRequest (UInt16 refNum, SATRequestType request, SATDecisionType decision, UInt32 data, UInt32 length)
    Send application’s request to firmware.
- Err PhnLibSATEndSession (UInt16 refNum)
    Terminate an active SAT session.
- Boolean PhnLibSIMInfo (UInt16 refNum, CharPtr *imsi)
    This routine reads the IMSI number from the SIM (Subscriber Information Module) on your GSM device. IMSI stands for International Mobile Subscriber Identify, and is used to uniquely identify a user to the wireless network.
- GSMSIMStatus PhnLibGetSIMStatus (UInt16 refNum)
    This routine returns status of the SIM (Subscriber Information Module) on your GSM device. The SIM is managed by the radio module on the handset. The SIM must be present and active before the radio is allowed to make phone calls (other than emergency calls). The SIM also stores various user information and settings.
- Boolean PhnLibGPRSAttached (UInt16 refNum)
    Check if we are currently attached to the GPRS Network.
- Err PhnLibGPRSPDPContextDefine (UInt16 refNum, UInt16 contextId, PhnGPRSPDPType pdpType, const char *apn, UInt16 apnLen, const char *pdpAddr, UInt16 pdpAddrLen, UInt16 pdpDataCompression, UInt16 pdpHdrCompression)
    This function will store the given settings as a profile in the radios flash memory. The profile id will be the same as the context id that you pass with valid values between 1 and 32.
- Err PhnLibGPRSPDPContextListConstruct (UInt16 refNum, struct PhnGPRSPDPContextListNodeType **listHeadPP)
    Get a linked list of pdp contexts currently stored on the device. It is necessary to call the Destruct after use of the list to free the memory.
- Err PhnLibGPRSPDPContextListDestruct (UInt16 refNum, struct PhnGPRSPDPContextListNodeType **headNodePP)
    Function that cleans up the list of pdp contexts created by the construct functions.
- Err PhnLibGPRSQualityOfServiceGet (UInt16 refNum, PhnGPRSQOSType qosType, UInt16 contextId, UInt16 *precedence, UInt16 *delay, UInt16 *reliability, UInt16 *peakThroughput, UInt16 *meanThroughput)
    Set either the Required or Minimum QOS service parameters. If 0 is passed for the parameter, the network will decide the settings. Valid settings are listed below.
- Err PhnLibGPRSQualityOfServiceSet (UInt16 refNum, PhnGPRSQOSType qosType, UInt16 contextId, UInt16 precedence, UInt16 delay, UInt16 reliability, UInt16 peakThroughput, UInt16 meanThroughput)
    Set either the Required or Minimum QOS service parameters. If 0 is passed for the parameter, the network will decide the settings. Valid settings are listed below.
- Err PhnLibSendLongDTMF (UInt refNum, Char digit, PhnAudioSendMode sendMode, Boolean on)
    Parameters:

      | refNum,: | IN:

- Err PhnLibGetICCID (UInt refNum, CharPtr *iccid)
    Parameters:

      | refNum,: | IN:

- Err PhnLibGetGSMCellInfo (UInt refNum, UInt32 *pLac, UInt32 *pCellId)
    Retreives currrent/camped Location Area Code (LAC) and Cell ID.
- Err PhnLibGetSpn (UInt refNum, CharPtr *spn)
    Parameters:

      | refNum,: | IN: Library reference number obtained from SysLibLoad

## Function Documentation

Err PhnLibGetFDNList | ( | UInt16 | refNum,
|  | PhnAddressList * | aList,
|  | PhnPhoneBookInfoPtr | info |
| ) |  |  |

Retrieve the Fixed Dialing Numbers from the SIM.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | aList,: | IN: Returned with the list of numbers
  | info,: | IN:

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibGetGSMCellInfo | ( | UInt | refNum,
|  | UInt32 * | pLac,
|  | UInt32 * | pCellId |
| ) |  |  |

Retreives currrent/camped Location Area Code (LAC) and Cell ID.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | pLac | : IN: Pointer to UInt32 thats populated with LAC upon successful return.
  | pCellId | : IN: Pointer to UInt32 thats populated with Cell ID upon successful return.

Return values:

  | Err | Error code as defined in HsPhoneErrors.h

Err PhnLibGetICCID | ( | UInt | refNum,
|  | CharPtr * | iccid |
| ) |  |  |

Parameters:

  | refNum,: | IN:

Parameters:

  | iccid,: | IN:

Return values:

  | Err | Error code.

Err PhnLibGetPhoneBook | ( | UInt16 | refNum,
|  | PhnAddressList * | numbers,
|  | PhnPhoneBookInfoPtr | info |
| ) |  |  |

This routine reads the PhoneBook of phone numbers from your SIM (GSM only). This command can take several seconds if the PhoneBook is large.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | numbers,: | IN:
  | info,: | IN:

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

UInt32 PhnLibGetPhoneBookIndex | ( | UInt16 | ,
|  | PhnAddressHandle | address |
| ) |  |  |

This routine gets the index of the given PhoneBook address on your SIM (GSM only).

Parameters:

  | unused,: | IN: for the future, set to 0.
  | address,: |

Return values:

  | Index | number.

Err PhnLibGetSDNList | ( | UInt16 | refNum,
|  | PhnAddressList * | aList,
|  | PhnPhoneBookInfoPtr | info |
| ) |  |  |

Parameters:

  | refNum,: | IN:

Parameters:

  | aList,: | IN:
  | info,: | IN:

Return values:

  | Err | Error code.

GSMSIMStatus PhnLibGetSIMStatus | ( | UInt16 | refNum | ) |

This routine returns status of the SIM (Subscriber Information Module) on your GSM device. The SIM is managed by the radio module on the handset. The SIM must be present and active before the radio is allowed to make phone calls (other than emergency calls). The SIM also stores various user information and settings.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.

Return values:

  | Sim | Status

Err PhnLibGetSpn | ( | UInt | refNum,
|  | CharPtr * | spn |
| ) |  |  |

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad

Parameters:

  | spn,: | IN: Service Provider Name from SIM

Return values:

  | Err | Error code.

Boolean PhnLibGPRSAttached | ( | UInt16 | refNum | ) |

Check if we are currently attached to the GPRS Network.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.

Return values:

  | True | if we are attached

Err PhnLibGPRSPDPContextDefine | ( | UInt16 | refNum,
|  | UInt16 | contextId,
|  | PhnGPRSPDPType | pdpType,
|  | const char * | apn,
|  | UInt16 | apnLen,
|  | const char * | pdpAddr,
|  | UInt16 | pdpAddrLen,
|  | UInt16 | pdpDataCompression,
|  | UInt16 | pdpHdrCompression |
| ) |  |  |

This function will store the given settings as a profile in the radios flash memory. The profile id will be the same as the context id that you pass with valid values between 1 and 32.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | contextId,: | IN:
  | pdpType,: | IN:
  | *apn,: | IN:
  | apnLen,: | IN:
  | *pdpAddr,: | IN:
  | pdpAddrLen,: | IN:
  | pdpDataCompression,: | IN:
  | pdpHdrCompression,: | IN:

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibGPRSPDPContextListConstruct | ( | UInt16 | refNum,
|  | struct PhnGPRSPDPContextListNodeType ** | listHeadPP |
| ) |  |  |

Get a linked list of pdp contexts currently stored on the device. It is necessary to call the Destruct after use of the list to free the memory.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | listHeadPP,: | IN: Pointer to a pointer where the head of the linked list will be stored.

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibGPRSPDPContextListDestruct | ( | UInt16 | refNum,
|  | struct PhnGPRSPDPContextListNodeType ** | headNodePP |
| ) |  |  |

Function that cleans up the list of pdp contexts created by the construct functions.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | headNodePP,: | IN: Pointer to a pointer to the head of the list.

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibGPRSQualityOfServiceGet | ( | UInt16 | refNum,
|  | PhnGPRSQOSType | qosType,
|  | UInt16 | contextId,
|  | UInt16 * | precedence,
|  | UInt16 * | delay,
|  | UInt16 * | reliability,
|  | UInt16 * | peakThroughput,
|  | UInt16 * | meanThroughput |
| ) |  |  |

Set either the Required or Minimum QOS service parameters. If 0 is passed for the parameter, the network will decide the settings. Valid settings are listed below.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | qosType,: | IN: Required or Minimum.
  | contextId,: | IN: id of the profile that you are setting with these QOS Values.
  | precedence,: | IN: (1-3) 1 being highest priority
  | delay,: | IN: (1-3) Predictive 4 - Best Effort
  | reliability,: | IN: (1-5) - Unknown
  | peakThroughput,: | IN: (1-9) 1 is the lowest and 9 the highest
  | meanThroughput,: | IN: (1-9) 1 is the lowest and 9 the highest

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibGPRSQualityOfServiceSet | ( | UInt16 | refNum,
|  | PhnGPRSQOSType | qosType,
|  | UInt16 | contextId,
|  | UInt16 | precedence,
|  | UInt16 | delay,
|  | UInt16 | reliability,
|  | UInt16 | peakThroughput,
|  | UInt16 | meanThroughput |
| ) |  |  |

Set either the Required or Minimum QOS service parameters. If 0 is passed for the parameter, the network will decide the settings. Valid settings are listed below.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | qosType,: | IN: Required or Minimum.
  | contextId,: | IN: id of the profile that you are setting with these QOS Values.
  | precedence,: | IN: (1-3) 1 being highest priority
  | delay,: | IN: (1-3) Predictive 4 - Best Effort
  | reliability,: | IN: (1-5) - Unknown
  | peakThroughput,: | IN: (1-9) 1 is the lowest and 9 the highest
  | meanThroughput,: | IN: (1-9) 1 is the lowest and 9 the highest

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibSATEndSession | ( | UInt16 | refNum | ) |

Terminate an active SAT session.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.

Return values:

  | 0 | if succeeded or an error from PhnLibSATSendRequest() session

Err PhnLibSATGetMainMenu | ( | UInt16 | refNum,
|  | MemHandle * | menuHandlePtr |
| ) |  |  |

Retrieve SAT main menu.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | menuHandlePtr,: | IN: Pointer to a GSMSATEventMenuPtr.

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.” And the pointer is filled with a pointer to a main menu or phnErrSATUnavailable if there is no active session.

Err PhnLibSATSendRequest | ( | UInt16 | refNum,
|  | SATRequestType | request,
|  | SATDecisionType | decision,
|  | UInt32 | data,
|  | UInt32 | length |
| ) |  |  |

Send application’s request to firmware.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | request,: | IN: Request type
  | decision,: | IN: Decision Type
  | data,: | IN: Data to send
  | length,: | IN: Length of data to send (only for Input)

Return values:

  | 0 | if succeed phnErrIllegalCondition:unrecognized parameters or an unneeded param is not zero. phnErrSATUnavailable:SAT is not available phnErrSATInactive : no active SAT session; must call PhnLibSATGetMainMenu() before calling this function().

Err PhnLibSendLongDTMF | ( | UInt | refNum,
|  | Char | digit,
|  | PhnAudioSendMode | sendMode,
|  | Boolean | on |
| ) |  |  |

Parameters:

  | refNum,: | IN:

Parameters:

  | digit,: | IN:
  | sendMode,: | IN:
  | on,: | IN:

Return values:

  | Err | Error code.

Err PhnLibSendUSSD | ( | UInt16 | refNum,
|  | CharPtr | cmd |
| ) |  |  |

Send USSD value to radio.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | cmd,: | IN: USSD value to be sent

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibSetActiveLine | ( | UInt16 | refNum,
|  | Int16 | line |
| ) |  |  |

Sets the active line number.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | line,: | IN: Line number to be set to active.

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibSetFDNEntry | ( | UInt16 | refnum,
|  | UInt16 | index,
|  | char * | name,
|  | char * | number |
| ) |  |  |

Set entry in the Fix Dialing field on the SIM.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | index,: | IN: index into SIM
  | name,: | IN: name value for SIM entry
  | number,: | IN: phone number for SIM entry

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibSetPhoneBook | ( | UInt16 | refnum,
|  | PhnAddressList | numbers |
| ) |  |  |

This routine writes the PhoneBook of phone numbers from your SIM (GSM only). This command can take several seconds if the PhoneBook is large.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | numbers,: | IN:

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Err PhnLibSetPhoneBookEntry | ( | UInt16 | refnum,
|  | UInt16 | index,
|  | char * | name,
|  | char * | number |
| ) |  |  |

Set entry in SIM Phone Book.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | index,: | IN: index into SIM Phone Book
  | name,: | IN: name value for SIM Phone Book entry
  | number,: | IN: phone number for SIM Phone Book entry

Return values:

  | 0 | for success; otherwise failed and returned an error code as defined in “Phone Library Error Codes.”

Boolean PhnLibSIMInfo | ( | UInt16 | refNum,
|  | CharPtr * | imsi |
| ) |  |  |

This routine reads the IMSI number from the SIM (Subscriber Information Module) on your GSM device. IMSI stands for International Mobile Subscriber Identify, and is used to uniquely identify a user to the wireless network.

Parameters:

  | refNum,: | IN: Library reference number obtained from SysLibLoad.
  | imsi,: | IN: imsi number is a string pointer.

Return values:

  | Boolean |

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