Introduction:
The Treo line of mobile phones combine a full-featured mobile phone with a color Palm OS
PDA.  The NSBTreoLib shared library provides access to the Treo API.  This is a
special library for the Treo, which does not support the standard Palm telephony
library.

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.

Entry: MainNumber~Function
Syntax:
_numberString_ = NSBTreoLib.MainNumber
Description:
MainNumber returns a string containing the main voice telephone number of this 
phone.  It only works when the phone radio is on.
Errors:

@"ERROR: Phone not on"@	Returned if the phone radio is not on.

@"ERROR: Number not found"@	Returned if there is no entry for the phone number.

Entry: NetworkAvailable~Function
Syntax:
_intVar_ = NSBTreoLib.NetworkAvailable
Description:
NetworkAvailable returns true (-1) if the phone radio is on and the network is available, false (0) otherwise.
See: 
PhoneReady~Function, PhoneOn~Function

Entry: PhoneOn~Function
Syntax:
_intVar_ = NSBTreoLib.PhoneOn
Description:
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:
If (PhoneOn) Then
    Dim s as String
    s = NSBTreoLib.MainNumber 'Will not work if phone is off
    MsgBox(s)
End If

See: 
PhoneReady~Function,PhoneTurnOn~Subroutine

Entry: PhoneTurnOn~Subroutine
Syntax:
NSBTreoLib.PhoneTurnOn
Description:
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.

See: 
PhoneOn~Function

Entry: TCPIPDrop~Subroutine
Syntax:
NSBTreoLib.TCPIPDrop
Description:
TCPIPDrop immediately drops the IP connection, which is used for browsing Web
pages and E-mail.

Entry: SignalQuality~Function
Syntax:
_intVar_ = NSBTreoLib.SignalQuality
Description:
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.
See:
PhoneOn~Function

Entry: PhoneType~Function
Syntax:
_stringVar_ = NSBTreoLib.PhoneType
Description:
PhoneType returns @"CDMA"@ if this is a CDMA phone and @"GSM"@ if this is a GSM phone.

Entry: PhoneReady~Function
Syntax:
_intVar_ = NSBTreoLib.PhoneReady
Description:
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.
See:
PhoneOn~Function

Entry: BookCount~Function
Syntax:
_intVar_ = NSBTreoLib.BookCount
Description:
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.

See:
PhoneType~Function,PhoneOn~Function,BookPhoneNumber~Function,BookFirstName~Function,BookLastName~Function,BookReload~Subroutine

Entry: BookReload~Subroutine
Syntax:
NSBTreoLib.BookReload
Description:
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.
See:
BookCount~Function, BookPhoneNumber~Function, BookFirstName~Function, BookLastName~Function

Entry: BookPhoneNumber~Function
Syntax:
_stringVar_ = NSBTreoLib.BookPhoneNumber(_which_)
Description:
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: 

@"ERROR: Number not found"@	Returned if the number was not found.  This most commonly means the radio is off.

See:
BookCount~Function

Entry: BookLastName~Function
Syntax:
_stringVar_ = NSBTreoLib.BookLastName(_which_)
Description:
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:

@"ERROR: Name not found"@	Returned if the name was not found.  This most commonly means the radio is off.

See:
BookCount~Function

Entry: BookFirstName~Function
Syntax:
_stringVar_ = NSBTreoLib.BookFirstName(_which_)
Description:
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:

@"ERROR: Name not found"@	Returned if the name was not found.  This most commonly means the radio is off.

See:
BookCount~Function

Entry: Provider~Function
Syntax:
_stringVar_ = NSBTreoLib.Provider
Description:
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:

@"ERROR: No current provider"@	Returned if there is no provider.  This most commonly means the radio is off.

Entry: OperatorCurName~Function
Syntax:
_stringVar_ = NSBTreoLib.OperatorCurName
Description:
OperatorCurName returns a string describing the current operator of the current network.

Errors:

@"ERROR: No current operator"@	Returned if there is no operator.  This most commonly means the radio is off.
See:
Provider~Function

Entry: OperatorCurID~Function
Syntax:
_stringVar_ = NSBTreoLib.OperatorCurID
Description:
OperatorCurID returns a string describing the ID of the current operator of the current network.

OperatorCurID only works on GSM phones.

Errors:

@"ERROR: No current operator"@	Returned if there is no operator.  This most commonly means the radio is off.

Entry: OperatorCount~Function
Syntax:
_intVar_ = NSBTreoLib.OperatorCount
Description:
OperatorCount returns the number of operators available on the current network.  On CDMA
phones, OperatorCount always returns zero.
See:
OperatorName~Function,Operator~Subroutine

Entry: OperatorName~Function
Syntax:
_stringVar_ = NSBTreoLib.OperatorName(_which_)
Description:
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.
See:
OperatorCount~Function

Entry: Operator~Subroutine
Syntax:
NSBTreoLib.Operator(_which_, _mode_)
Description:
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:

0	Automatic

1	Manual

3	Deregister

4	Format

5	Manual/Automatic

Operator only works on GSM phones.

Entry: Dial~Subroutine
Syntax:
NSBTreoLib.Dial(_phoneNumber_)
Description:
Dial 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, Dial will exit your program.  As always, make
sure that your application stores any needed state variables in a database
before exiting.

Entry: CallWaitingSet~Subroutine
Syntax:
NSBTreoLib.SetCallWaiting(_value_)
Description:
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.

Entry: SMSMessage~Subroutine
Syntax:
NSBTreoLib.SMSMessage(_phoneNumber_, _name_, _message_)
Description:
SMSMessage 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 SMSMessage, 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.

Entry: EMail~Subroutine
Syntax:
NSBTreoLib.EMail(_address_, _CC_, _message_)
Description:
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.

Entry: Browse~Subroutine
Syntax:
NSBTreoLib.Browse(_URL_)
Description:
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.

Entry: Roaming~Subroutine
Syntax:
NSBTreoLib.Roaming
Description:
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.

See:
PhoneOn~Function

Entry: Software~Function
Syntax:
_stringVar_ = NSBTreoLib.Software
Description:
Software returns a description of the version of the software

Entry: Vibrate~Subroutine
Syntax:
NSBTreoLib.Vibrate(_count_)
Description:
Vibrate makes the phone vibrate.  _Count_ is the number of times to vibrate.
See:
Blink~Subroutine

Entry: Blink~Subroutine
Syntax:
NSBTreoLib.Blink(_count_)
Description:
Blink makes the green LED near the antenna blink at about four blinks per second.  _Count_ is the number of times to blink.
See:
Vibrate~Subroutine

Entry: Hardware~Function
Syntax:
_stringVar_ = NSBTreoLib.Hardware
Description:
Hardware returns a string describing the current version of the hardware.

Entry: ProductName~Function
Syntax:
_stringVar_ = NSBTreoLib.ProductName
Description:
ProductName returns a string containing the name of the product, _e.g._ @"Treo 600"@.

Entry: SerialNumber~Function
Syntax:
_stringVar_ = NSBTreoLib.SerialNumber
Description:
SerialNumber returns a string containing the serial number of the Treo.

Entry: CarrierID~Function
Syntax:
_stringVar_ = NSBTreoLib.CarrierID
Description:
CarrierID returns a string containing the carrier for which the Treo was built.

Entry: ProductRevision~Function
Syntax:
_stringVar_ = NSBTreoLib.ProductRevision
Description:
ProductRevision returns a string containing a code for the product revision.

Entry: ROM~Function
Syntax:
_stringVar_ = NSBTreoLib.ROM
Description:
ROM returns a string containing the version of the ROM.

Entry: Firmware~Function
Syntax:
_stringVar_ = NSBTreoLib.Firmware
Description:
Firmware returns a string containing the version of the firmware.

Entry: HTTPOpen~Function
Syntax:
_intVar_ = NSBTreoLib.HTTPOpen
Description:
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:
' Note: This example is intended for educational purposes only.
' Real applications should probably use a more sophisticated implementation,
' such as a state machine

Sub object1103()
    Dim result as Integer
    Dim header as String
    Dim body as String
    
    result = NSBTreoLib.HTTPOpen
    If result <> 0 Then
        MsgBox("Opened")
        result = NSBTreoLib.HTTPSendRequest("http://www.slashdot.org/", 20000)
        If result <> 0 Then
            MsgBox("Send succeded")
            header = NSBTreoLib.HTTPGetHeader(20000)
            MsgBox("Header: " + header)
            If "ERROR" <> Left(header, 5) Then
                body = "init" 'Set it to something non-null
                Do While "" <> body
                    body = NSBTreoLib.HTTPRead(250, 20000)
                    MsgBox(body)
                Loop
                NSBTreoLib.HTTPEnd
            End If
        Else
            MsgBox("Send failed")
        End If
        NSBTreoLib.HTTPClose
    Else
        MsgBox("Couldn't open")
    End If
End Sub
See:
HTTPClose~Subroutine
Entry: HTTPClose~Subroutine
Syntax:
NSBTreoLib.HTTPClose
Description:
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.
Entry: HTTPSendRequest~Function
Syntax:
_intVar_ = NSBTreoLib.HTTPSendRequest(_URL_, _timeInMs_)
Description:
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.

See:
HTTPOpen~Function, HTTPSendPostRequest~Function

Entry: HTTPSendPostRequest~Function
Syntax:
_intVar_ = NSBTreoLib.HTTPSendPostRequest(_URL_, _postData_, _timeInMs_)
Description:
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.
See:
HTTPOpen~Function, HTTPSendRequest~Function
Entry: KeyboardLocked~Function
Syntax:
_intVar_ = NSBTreoLib.KeyboardLocked
Description:
KeyboardLocked returns true (-1) if keyguard is active and false (0) otherwise.
Entry: KeyboardLock~Subroutine
Syntax:
NSBTreoLib.KeyboardLock(_whether_)
Description:
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.
Entry: HTTPGetHeader~Function
Syntax:
_stringVar_ = NSBTreoLib.HTTPGetHeader(_timeInMs_)
Description:
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.
Entry: HTTPRead~Function
Syntax:
_stringVar_ = NSBTreoLib.HTTPRead(_size_, _timeInMs_)
Description:
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.
Entry: HTTPEnd~Function
Syntax:
NSBTreoLib.HTTPEnd
Description:
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. 












