Introduction:

The Treo and Centro lines of mobile phones combine a full-featured mobile phone with a color Palm OS PDA. The NSBTreoLib shared library provides access to the API for these phones.

Depending on the service, Treo phones come in two varieties: GSM and CDMA. Both provide telephony, SMS messaging, and web browsing capabilities, with optional EMail. GSM phones also provide a phone book, resident on a card or loaded directly from the network.

In order to use the NSBTreoLib shared library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the Startup Code of the program, as in this example:

Sub main()
    LoadLibrary "NSBTreoLib"
End Sub

This document assumes that the shared library has been loaded this way. The LoadLibrary statement also has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions, as in this example:

Sub main()
    LoadLibrary "NSBTreoLib", "Treo"
End Sub

For this example, you can use the functions and subroutines described in this document with a prefix of Treo instead of NSBTreoLib.

In order to use the NSBTreoLib Shared Library, the NSBTreoLib.inf file must be present in your C:\nsbasic\lib directory, and the NSBTreoLib.prc file must be downloaded to your device or included in your NSBasic program. For more information on shared libraries, refer to the NSBasic documentation.

The Treo shared library is fully compatible with the NSBasic TCP/IP library, but you will have to use that shared library for general TCP/IP functions. The Treo library also provides basic HTTP services for retrieving content from web servers. If you need more capabilities, there are commercial shared libraries for this purpose.

Some desirable features, such as interception and construction of SMS messages, have not been implemented yet because they would require modifications to NSBasic outside of the shared library.

Index and Quick Reference:

Full Reference:

Blink

NSBTreoLib.Blink(count)

Blink makes the green LED near the antenna blink at about four blinks per second. Count is the number of times to blink.

Also see:

BookCount

intVar = NSBTreoLib.BookCount

BookCount returns the number of phone entries stored in the phone book. It only works on GSM phones.

BookCount gets the phone book information from the SIM card or from the network itself. Each entry consists of a first name, a last name, and a phone number.

The phone book is part of the mobile phone system and is distinct from the Palm address book.

BookCount should be called before any of the other Book functions or subroutines. If the phone book is large, BookCount may take several seconds to download the phone book. If BookCount returns zero, there are no entries in the phone book, and none of the other Book functions should be used.

BookCount will return 0 if the phone is off or is not a GSM phone, so use PhoneType and PhoneOn first. BookCount may also return zero if the phone book is temporarily unavailable, such as if the phone is in an area that lacks service. To try again later, call the BookReload subroutine and use BookCount again.

Also see:

BookFirstName

stringVar = NSBTreoLib.BookFirstName(which)

BookFirstName returns a particular first name given by which from the address book on the phone. Which must be between 1 and the value returned by BookCount.

Errors:

Also see:

BookLastName

stringVar = NSBTreoLib.BookLastName(which)

BookLastName returns a particular last name given by which from the address book on the phone. Which must be between 1 and the value returned by BookCount.

Errors:

Also see:

BookPhoneNumber

stringVar = NSBTreoLib.BookPhoneNumber(which)

BookPhoneNumber returns a particular phone number given by which from the address book on the phone. Which must be between 1 and the value returned by BookCount.

Errors:

Also see:

BookReload

NSBTreoLib.BookReload

All of the Book functions as well as MainNumber, use the phone book associated with the mobile phone system. On GSM phones, this phone book may be downloaded from the network, which depending on the size, may take several seconds. To improve the speed, the NSBasic Treo library only loads the phone book when needed and keeps it for subsequent use. This also allows the phone book to be used efen after the radio is switched off.

However, if the phone book changes, which may happen during roaming, then the copy in memory will become out-of-date. BookReload forces the phone book to be reloaded the next time it is needed. When the book is reloaded, you must call BookCount again, because the number of entries may have changed.

Also see:

Browse

NSBTreoLib.Browse(URL)

Browse allows the user to browse a particular URL. URL must be a string containing a well formatted URL, such as "http://www.nsbasic.com/".

After calling Browse, your NSBasic application will exit, and the browser will appear. As always, make sure that your application stores any needed state variables in a database before exiting.

CallWaitingSet

NSBTreoLib.SetCallWaiting(value)

CallWaitingSet enables call waiting if value is true (nonzero) and disables it otherwise. This only works on phones that have call waiting as a feature; on other phones it will have no effect.

CarrierID

stringVar = NSBTreoLib.CarrierID

CarrierID returns a string containing the carrier for which the Treo was built.

DialPhone

NSBTreoLib.DialPhone(phoneNumber)

DialPhone brings up the dial dialog with phoneNumber, which must be a string containing the number to dial. The user can change the phone number before dialing.

Unless the user cancels, DialPhone will exit your program. As always, make sure that your application stores any needed state variables in a database before exiting.

Firmware

stringVar = NSBTreoLib.Firmware

Firmware returns a string containing the version of the firmware.

GetLibRefNum

shortVar = NSBTreoLib.GetLibRefNum

GetLibRefNum returns the library reference number of PhnLib. -1 is returned if the call fails.

GetRingProfile

shortVar = GetRingProfile.GetRingProfile(profile, vol, vib)

GetRingProfile returns the volume and vibrate setting for a given profile.

Profile Settings:
0: Ring Tones
2: Calendar
5: Messaging
6: Phone Alerts

vol Ringer volume, 0 through 7 (0 = Off)

vib Vibrate Mode
0: Never
1: When sound off
256: Vibrate then ring
257: Always

shortVar = NSBTreoLib.GetRoamMode

GetRoamMode returns the current roaming mode. CDMA only.

Mode Values:
0: Home Only (ie roaming is disabled)
1: Any (ie roaming is enabled)
2: Roam Only (ie roaming is required) (Not on Treo 650)

Return Values

GetRoamWarnings

shortVar = NSBTreoLib.GetRoamWarnings

GetRoamWarnings returns the roam-specific application preferences.

NSBTreoLib.HTTPClose

HTTPClose closes the HTTP library. It is normally called at the end of a program if HTTPOpen has been called. HTTPClose will automatically terminate any existing connection.

HTTPEnd

NSBTreoLib.HTTPEnd

Call HTTPEnd after receiving all the data from HTTPRead. You can also call HTTPEnd in the middle of a connection to abort it and ignore the rest of the data.

HTTPGetHeader

stringVar = NSBTreoLib.HTTPGetHeader(timeInMs)

HTTPGetHeader returns the header information for a response from a URL. You must call HTTPGetHeader after calling either HTTPSendRequest or HTTPSendPostRequest.

TimeInMs is the timeout in milliseconds. During a transaction, this call will typically take the most time to execute, if the web site is slow. There are two strategies to deal with this. One is to provide a long timeout. The other is to provide a short timeout and keep polling HTTPGetHeader until a value is returned or the application gives up. Which strategy to use is left up to the developer.

It is not possible to tell the difference between a case where the header has not shown up yet and a case where it will not show up at all. Writers of applications should show appropriate judgement about when to give up. Unlike HTTPRead, HTTPGetHeader will always return a complete header or an empty string.

The application is responsible for interpreting the header. Headers generally consist of several lines, separated by chr(10) or chr(13) characters, consisting each of a keyword, a colon (":"), and a value. Headers are not completely standardized. See http://www.w3c.org and the RFC archives for more information, but in many cases it is easier to check some websites.

HTTPOpen

intVar = NSBTreoLib.HTTPOpen

HTTPOpen opens the HTTP library. Call this function before calling any of the other HTTP functions. HTTPOpen will return true (-1) if the library could be opened and false (0) otherwise.

HTTPOpen will make a connection to the network if one is not present. This may take several seconds and require user input. However, it is probably preferable to call PhoneTUrnOn before calling HTTPOpen.

A program may call HTTPOpen upon startup and HTTPClose at termination, or the HTTP services may be available on demand.

Example:

Also see:

HTTPRead

stringVar = NSBTreoLib.HTTPRead(size, timeInMs)

HTTPRead returns a string containing the next block of information returned from the URL. The string will contain no more than size characters, excluding the terminating null character. HTTPRead will return an empty string if no characters were received during the timeout period or if there are no more characters to receive. As with HTTPGetHeader, it is not possible to distinguish between the case where communication is slow and the case where there is no more information.

TimeInMs is the timeout in milliseconds. Once the header has been received, HTTPRead is usually fairly fast. It should be polled repeatedly until it receives no more characters after a time appropriate to the application.

HTTPSendPostRequest

intVar = NSBTreoLib.HTTPSendPostRequest(URL, postData, timeInMs)

HTTPSendPostRequest sends information to a URL using the Post protocol. URL must be a well formed URL, such as "http://www.nsbasic.com/". PostData is a string containing the data to send to the web site. TimeInMs is the timeout in milliseconds. Connections through a cell phone are slow, so values should be in the tens of seconds (e.g. 20000). HTTPSendPostRequest returns true (-1) if successful and false (0) otherwise.

Also see:

HTTPSendRequest

intVar = NSBTreoLib.HTTPSendRequest(URL, timeInMs)

HTTPSendRequest sends a request to a URL. URL must be a well formed URL, such as "http://www.nsbasic.com/". TimeInMs is the timeout in milliseconds. Connections through a cell phone are slow, so values should be in the tens of seconds (e.g. 20000). HTTPSendRequest returns true (-1) if successful and false (0) otherwise.

HTTPSendRequest can also be used to submit information to the web site using the Get protocol, in which the information follows the URL. For more information, see http://www.w3c.org. To send information using the Post protocol, use HTTPSendPostRequest.

Also see:

Hardware

stringVar = NSBTreoLib.Hardware

Hardware returns a string describing the current version of the hardware.

KeyboardLocked

intVar = NSBTreoLib.KeyboardLocked

KeyboardLocked returns true (-1) if keyguard is active and false (0) otherwise.

KeyboardLock

NSBTreoLib.KeyboardLock(whether)

KeyboardLock turns keyguard on if whether is true (nonzero) or off it whether is false (0). The change to keyguard is not immediate but occurs the next time an event is processed.

MainNumber

numberString = NSBTreoLib.MainNumber

MainNumber returns a string containing the main voice telephone number of this phone. It only works when the phone radio is on.

Errors:

NetworkAvailable

intVar = NSBTreoLib.NetworkAvailable

NetworkAvailable returns true (-1) if the phone radio is on and the network is available, false (0) otherwise.

Also see:

OperatorCount

intVar = NSBTreoLib.OperatorCount

OperatorCount returns the number of operators available on the current network. On CDMA phones, OperatorCount always returns zero.

Also see:

OperatorCurID

stringVar = NSBTreoLib.OperatorCurID

OperatorCurID returns a string describing the ID of the current operator of the current network.

OperatorCurID only works on GSM phones.

Errors:

OperatorCurName

stringVar = NSBTreoLib.OperatorCurName

OperatorCurName returns a string describing the current operator of the current network.

Errors:

Also see:

OperatorName

stringVar = NSBTreoLib.OperatorName(which)

OperatorName returns the name of one of the available operators. Which is an index that determines which operator. It must be a number between 1 and the value OperatorCount returns.

Also see:

Operator

NSBTreoLib.Operator(which, mode)

Operator sets the current operator from the list of available operators. Which is the number of the operator and must be between 1 and the value returned by OperatorCount. Mode gives the registration mode according to the following table:

Operator only works on GSM phones.

PhoneOn

intVar = NSBTreoLib.PhoneOn

PhoneOn returns true (-1) if the phone radio is on and false (0) otherwise.

To save power, the phone portion of a Treo can by turned on or off separately from the PDA portion. This allows the Treo to be used as a PDA without consuming battery power running the phone or in places such as hospitals and airplanes where the phone radio must be off.

Most of the features of the Treo are unavailable when the phone is off. It is usually a good idea to enclose portions of a program that access a phone within an If block, as shown in the example.

Example:

Also see:

PhonePower

shortVar = NSBTreoLib.PhonePower(OnOff)

PhonePower turns the radio on or off without a user dialog. The value of OnOff can be "on" or "off".

intVar = NSBTreoLib.PhoneReady

PhoneReady returns true (-1) if the phone is ready to make a normal call and false (0) otherwise. If PhoneReady returns false, it may still be possible to make an emergency call.

Also see:

PhoneTurnOn

NSBTreoLib.PhoneTurnOn

PhoneTurnOn turns the phone radio on if it is not already on.

The user still has the option of preventing the phone from being turned on, so do not assume that the phone is on after a call to PhoneTurnOn. Always use the PhoneOn function to check.

Also see:

PhoneType

stringVar = NSBTreoLib.PhoneType

PhoneType returns "CDMA" if this is a CDMA phone and "GSM" if this is a GSM phone.

ProductName

stringVar = NSBTreoLib.ProductName

ProductName returns a string containing the name of the product, e.g. "Treo 600".

ProductRevision

stringVar = NSBTreoLib.ProductRevision

ProductRevision returns a string containing a code for the product revision.

Provider

stringVar = NSBTreoLib.Provider

Provider returns a string describing the current service provider.

GSM phones make a distinction between a service provider and an operator on that network. On CDMA phones, this function returns the same value as OperatorCurrent.

Errors:

ROM

stringVar = NSBTreoLib.ROM

ROM returns a string containing the version of the ROM.

Roaming

NSBTreoLib.Roaming

Roaming returns true (-1) if the phone is roaming and false (0) if it is at home. Roaming only works when the phone radio is on and connected to a network.

Also see:

SendSMSMessage

NSBTreoLib.SendSMSMessage(phoneNumber, name, message)

SendSMSMessage sends a message using the Short Message System (SMS). The user can change the fields before sending.

PhoneNumber is a string containing the phone number of the recipient. Name is the name of the recipient. Message is the text of the message. Any or all of the parameters can contain a string with no characters (""), in which case, the user is expected to fill in the fields.

SMS messages are normally limited to 160 characters. Characters within a message are automatically translated from the Palm character set into the SMS character set. You can include a paragraph break with chr(10).

You can also use a valid EMail address instead of phoneNumber, in which case the SMS message will be transferred through a gateway and be sent as EMail. There is no way to set the subject of the message, however.

After calling SendSMSMessage, your NSBasic application will exit, and the message application will appear. As always, make sure that your application stores any needed state variables in a database before exiting.

Intercepting incoming messages and sending messages without exiting the application are not practical at this time.

SendEMail

NSBTreoLib.SendEMail(address, CC, subject, message)

Message brings up the SMS messaging dialog with some fields filled in. The user can change the fields before sending.

Address is a string containing the EMail address of the recipient. CC is the EMail address to send a copy. Either can be lists of addresses separated by comments. Message is the text of the message. Any or all of the parameters can contain a string with no characters (""), in which case, the user is expected to fill in the fields.

EMail does not use the standard Palm Mail application, which is not provided on Treo phones. Instead, depending on the service, a third-party application may be used. If the user has not subsribed to this application, a registration form may appear. There is no way to test for this case which works for all Treo phones.

After calling EMail your NSBasic application will exit, and the appropriate application will appear. As always, make sure that your application stores any needed state variables in a database before exiting.

SerialNumber

stringVar = NSBTreoLib.SerialNumber

SerialNumber returns a string containing the serial number of the Treo.

SetRingProfile

shortVar = NSBTreoLib.SetRingProfile(profile, vol, vib)

SetRingProfile sets the volume and vibrate setting for a given profile.

Profile Settings:
0: Ring Tones
2: Calendar
5: Messaging
6: Phone Alerts

vol Ringer volume, 0 through 7 (0 = Off)

vib Vibrate Mode
0: Never
1: When sound off
256: Vibrate then ring
257: Always

shortVar = NSBTreoLib.SetRoamMode(mode

SetRoamMode sets the phone's roam mode. CDMA only.

Mode Values:
0: Home Only (ie roaming is disabled)
1: Any (ie roaming is enabled)
2: Roam Only (ie roaming is required) (Not on Treo 650)

Return Values

SetRoamWarnings

shortVar = NSBTreoLib.SetRoamWarnings(warnings

SetRoamWarnings sets the roam-specific application preferences

warnings Values:
0: Warn before call & Warn before data unchecked
1: Warn before data checked
256: Warn before call checked
257: Warn before call & Warn before data checked

intVar = NSBTreoLib.SignalQuality

SignalQuality returns the strength of the radio connection in dbM as an Integer. If it is not possible to determine the signal strength, SignalQuality returns 99. SignalQuality only works if the phone is on; otherwise it returns 0.

Also see:

Software

stringVar = NSBTreoLib.Software

Software returns a description of the version of the software

TCPIPDropConnection

NSBTreoLib.TCPIPDropConnection

TCPIPDropConnection immediately drops the IP connection, which is used for browsing Web pages and E-mail.

Vibrate

NSBTreoLib.Vibrate(count)

Vibrate makes the phone vibrate. Count is the number of times to vibrate.

Also see: