Tech Note 18: Using the TcpIpLib Shared Library 2.1 April 23, 2002 © NSB Corporation. All rights reserved.

Contents

    Introduction
    1. Shared Library Methods
    2. Using TcpIpLib to communicate with the Desktop
    3. Some Standard Internet Protocols
    3.1 Getting Web Pages: http
    3.2 Reading Newsgroups: nntp
    3.3 Sending Mail: smtp
    3.4 Getting Mail: pop3
    4. Compiling the Source Code
    Appendix A: List of common Port Numbers
    Appendix B: Palm OS Net Error Messages

Introduction

This shared library was orginally written by Floyd Worley. Version 2.1 was written by Matthijs van Duin. Please send your problems and suggestions to support© nsbasic.com

TcpIpLib is a simple to use shared library that lets you communicate from a Palm using Tcp/IP. We include samples of retrieving a web page and communicating with a desktop program written in Visual Basic.

The libraries and samples can be downloaded here. The following files are included:

• TcpIpLib.INF: INF file for NS Basic to use. Install into \nsbasic\lib.
• TcpIpLib.prc: Shared library. Install into \nsbasic\lib and download to your device.
• TcpIpDemo.prj: NS Basic program which demonstrates standard internet services, such as getting web pages, news, and sending and receiving email.
• TCP2VB.prj: NS Basic program which communicates with a desktop VB program.
• VB Server Folder: Server program for desktop, written in Visual Basic.
• src folder: source code. can be compiled with PRC Tools.

You can run the samples on a net enabled Palm OS device. Remember to install the NSBRuntime and the TCPIPLIB before you try to run the program.

We find the easiest way to test TCP/IP programs is on POSE. Under POSE Properties, make sure that "Redirect NetLib calls to host TCP/IP" is set. The calls you issue in your program will then use your desktop computer's TCP/IP connection.

1. Shared Library Methods

Returns the version number.

fd = TcpOpen(hostname, port, timeout)

Opens the specified post on the hostname. Fd will be returned as a negative value if the open fails. See Appendix A for a list of common port numbers. See Appendix B for a list of error codes.

• Hostname = string filled with dotted IP or hostname
• port = integer for IP Port number
• timeout = integer for timeout in mS (use 5000)
• fd = integer; the reference or error code

Example

fd = TcpOpen("www.nsbasic.com", 80, 5000)
If fd < 0 Then
   msgbox "open error " + str(-fd) ' Palm error code
end if

Closes the current connection fd

• fd = integer. Value set in TcpOpen.

Read data from an open connection.

• data = String. the returned data
• fd = integer. Value set in TcpOpen.
• count = integer. maximum number of characters to return
• matchSet = string, up to 2 characters. TcpRead will return when one of these characters are encountered.
• timeout = timeout in milliseconds

Example

'return when 100 chars are received, 
' until a # or > was found in the stream, 
' or 2.5 seconds have passed
' or connection was closed 
timeout = 2500
toread = 100
data = TcpRead(fd, toread, "#>", timeout) 

Write data to an open connection. Returns the number of bytes of data written. If written is negative, there was an error. See Appendix B for a list of error codes.

• fd = integer. Value set in TcpOpen.
• data = string,
• written = integer

Example

bytes=TcpWrite(fd, data)

Flushes the input buffer

• fd = integer. Value set in TcpOpen.

Example

TcpFlush()

2. Using TcpIpLib to communicate with the Desktop

It's easy to send and receive data with a a VB program running on the desktop. The hostname is the IP Address of the desktop machine and the port is a number that both sides have hard coded in their programs. Send and receive commands then communicate data back and forth.

The easiest way to understand how to do this is to run the sample. Here's how:

1. Install the files as above.
2. From NS Basic, compile, download and run TCP2VB. You can run this on a TCP/IP enabled device with a connection to the desktop or directly on POSE. <>I>Run the program.
3. Fill in the IP address of your desktop. If you don't know the address, on the desktop do Start...Run. Enter CMD to bring up a DOS shell, then type ipconfig to see your IP address.
4. On the destop, run vbTcpIp.exe.
5. On the device, tap Connect to establish the connection.
6. Enter some text into the Send field.
7. Tap the Send button.
8. You will see your text appear in the vbTcpIp program running on the desktop.
9. The vbTcpIp program running on the desktop will then send your message back to the device.

3. Some Standard Internet Protocols

This is an over simplified introduction to some of the most common protocol used on the net. In each case, a link has been provided to the relevant RFC that gives more information than you'll ever need. (An RFC is a Request for Comment, the documents that set forth how just about everything on the internet works.)

The master index to all the RFC documents is at http://www.faqs.org/rfcs/.

Please note that the URLs below are not live: you should substitute current URLs if you want to try these.

3.1 Getting Web Pages: http

(For more information, read RFC2616)

To connect with a web server, use address "www.nsbasic.com" and port 80. (The address will be different depending on the web server you wish to access; the port is always 80. See Appendix A for a list of standard ports).

To get a web page,

GET /testdata.txt HTTP:/1.0
Host: www.nsbasic.com:80

The data will come back and the connection will be closed. Note that while News lines end with CR/LF, web information that returns may end in just LF. At the end of receiving a page of data, the server closes the connection, so to see if the page is complete, wait for the connection to be terminated.

Web sites also have local programs that get run, using something called cgi. For example, to check a stock price, connect to location www.dbc.com and do the following command:

GET /cgibin/htx.exe/squote?TICKER=DOCSF

See the sample TcpIpDemo.prj for an example.

3.2 Reading Newsgroups: nntp

(For more information, read RFC977)

To connect with news, use address such as "nntp.netcruiser" and port 119. (The address will be different with your service provider; the port will always be 119. See Appendix A for a complete list of ports).

You'll get an initial welcome message back:

"200 tor-nn1.netcom.ca InterNetNews NNRP server INN 1.4unoff4 05-Mar-96 
ready (posting ok)."

Tell it what newsgroup you want:

group alt.food.wine

You'll get back :

211 206 16868 17075 alt.food.wine

This means there are 206 articles, numbered from 16868 to 17075.

To read the headers of some of the articles, send

xover 17000-17005

You'll get back:

"17070	Re: Old Liebfraumich...	"Roger L. Lustig" 	
Wed, 31 Jul 1996 22:51:21 -0400	<32001BA9.367© ix.netcom.com>	
<4tnroe$m9m© mcmail.CIS.McMaster.CA>	1092	14"
"17071	Re: Wine de Constantia, info needed	"Roger L. Lustig" 
	Wed, 31 Jul 1996 22:54:37 -0400	
<32001C6D.76ED© ix.netcom.com>	
	1590	31"
"17072	Napa Crush Begins	"Brian Boulden" 	1 Aug 
1996 04:50:45 GMT	<01bb7f64$195b6da0$a677ae8c© boulden.community.net>		1523	
22"
"17073	Re: Alsace	zincats© aol.com (ZinCats)	1 Aug 1996 01:00:41 -0400	
<4tpdlp$m8i© newsbf02.news.aol.com>	<31FD65C5.4774© widomaker.com>	992	8"
"17074	Re: Oregon Bound - Need Help	zincats© aol.com (ZinCats)	1 Aug 1996 
01:14:38 -0400	<4tpefu$mog© newsbf02.news.aol.com>	
<31FAFB21.2052© execpc.com>	793	5"
"17075	RE: Old Liebfraumich...	chris.anderson© dinosaur.com	Wed, 31 Jul 96 
23:06:55 -0700	<9607312306.0WH1U00© dinosaur.com>	
<4tnroe$m9m© mcmail.CIS.McMaster.CA>	1317	18"

To read a single article, send

article 17000

Articles may be any number of lines long, terminated by a final line that consists of a period by itself (".").

See the sample TcpIpDemo.prj for an example.

3.3 Sending Mail: smtp

(For more information, read RFC2821)

The most common program used to send mail is SMTP, sometimes called sendmail.

To connect with a SMTP server, use address such as "netcom.ca" and port 25. (The address will be different depending on the web server you wish to access; the port will always be 25. See Appendix A for a complete list of ports).

To show how this works, we'll connect to a smtp server via telnet and enter the commands manually In your NS BASIC program, you'll want to duplicate this dialog. Lines entered by the user start with U:

U: telnet netcom.ca 25
Trying 207.93.1.148...
Connected to netcom.ca.
Escape character is '^]'.
220 tor-srs1.netcom.ca ESMTP Sendmail 8.7.5/SMI-4.1/Netcom ready at Tue, 
27 Aug 1996 15:23:06 -0400 (EDT)
U: HELO io.com
250 tor-srs1.netcom.ca Hello nsbasic© pentagon.io.com [199.170.88.5], 
pleased to meet you
U: MAIL FROM: gh© nsbasic.com
250 gh© nsbasic.com... Sender ok
U: RCPT TO: gh© nsbasic.com
250 Recipient ok
U: DATA
354 Enter mail, end with "." on a line by itself
U: SUBJECT: This is some test data
U: This is line 1 of my message
U: and line 2.
U: .
250 PAA16699 Message accepted for delivery
U: QUIT
221 tor-srs1.netcom.ca closing connection
Connection closed by foreign host.

See the sample TcpIpDemo.prj for an example.

3.4 Getting Mail: pop3

(For more information, read RFC1939)

The program most commonly used to read mail on a server is called POP3.

To connect with a POP3 server, use an address such as "netcom.ca" and port 110. (The address will be different depending on the web server you wish to access; the port will always be 110. See Appendix A for a complete list of ports).

To show how this works, we'll connect to a smtp server via telnet and enter the commands manually In your NS BASIC program, you'll want to duplicate this dialog. Lines entered by the user start with U:

U: telnet netcom.ca 110
Trying 207.93.1.148...
Connected to netcom.ca.
Escape character is '^]'.
+OK NETCOM v0.1 at tor-srs1 starting : built on Aug  2 1996 14:00:08.
U: user ghenne
+OK Password required for ghenne.
U: PASS xxxxxx
+OK ghenne has 0 message(s) (0 octets).
U: STAT
+OK 3 1766
U: DELE 3
+OK Message 3 has been deleted.
U: LIST
+OK 2 messages (1425 octets)
1 801
2 624
.
U: DELE 2
+OK Message 2 has been deleted.
U: RETR 1
+OK 801 octets
Return-Path: 
Received: from deliverator.io.com by tor-srs1.netcom.ca 
(8.7.5/SMI-4.1/Netcom)
        id PAA17679; Tue, 27 Aug 1996 15:28:22 -0400 (EDT)
From: gh© nsbasic.com
Received: from tor-srs1.netcom.ca (tor-srs1.netcom.ca [207.93.1.148]) by 
deliverator.io.com (8.7.5/8.7.3) with ESMTP id OAA16463 for 
; Tue, 27 Aug 1996 14:24:42 -0500 (CDT)
Received: from pentagon.io.com by tor-srs1.netcom.ca (8.7.5/SMI-4.1/Netcom)
        id PAA16699; Tue, 27 Aug 1996 15:23:18 -0400 (EDT)
Date: Tue, 27 Aug 1996 15:23:18 -0400 (EDT)
Message-Id: <199608271923.PAA16699© tor-srs1.netcom.ca>

This is line 1 of my message
and line 2.

.
U: QUIT
+OK Pop server at  signing off.
Connection closed by foreign host.

See the sample TcpIpDemo.prj for an example.

4. Compiling the source code

The source code for TcpIpLib is included in the download. It can be compiled using the Prc-Tools.

PRC-Tools is a complete compiler tool chain for building Palm OS applications in C or C++. The PRC-Tools package includes patched versions of the GNU packages GCC, binutils, GDB, and various post-linker tools. The Palm OS specific parts of PRC-Tools were originally written by D. Jeff Dionne, Kresten Krab Thourp, they are currently maintained by John Marshall, and many other people have made contributions over the years. It is free software. Visit the PRC-Tools page for the latest version of PRC-Tools and for installation instructions for the latest version. PalmSource also has a PRC-Tools page.

TcpIpLib is a shared library. To find out more about shared libraries and NS Basic, see Tech Note 5.

If you modify TcpIpLib for your own use, be sure to change the name and Creator ID, so it doesn't interfere with the official copy of TcpIpLib that is being used by others.

If you have modfications you think should be part of the standard TcpIpLib release, please send them to Fokko van Duin, who will then decide whether to include them.

Appendix A: List of common Port Numbers

tcpmux          1/tcp                           # TCP port multiplexer (RFC1078)
echo            7/tcp
echo            7/udp
discard         9/tcp           sink null
discard         9/udp           sink null
systat          11/tcp          users
daytime         13/tcp
daytime         13/udp
netstat         15/tcp
qotd            17/tcp          quote
chargen         19/tcp          ttytst source
chargen         19/udp          ttytst source
ftp             21/tcp
telnet          23/tcp
smtp            25/tcp          mail
time            37/tcp          timserver
time            37/udp          timserver
rlp             39/udp          resource        # resource location
nameserver      42/tcp          name            # IEN 116
whois           43/tcp          nicname
domain          53/tcp          nameserver      # name-domain server
domain          53/udp          nameserver
mtp             57/tcp                          # deprecated
bootps          67/udp          bootp           # bootp server
bootpc          68/udp                          # bootp client
tftp            69/udp
gopher          70/tcp
rje             77/tcp          netrjs
finger          79/tcp
link            87/tcp          ttylink
http            80/tcp
supdup          95/tcp
hostnames       101/tcp         hostname        # usually from sri-nic
tsap            102/tcp                         # part of ISODE.
pop2            109/tcp                         # old pop port
pop             110/tcp         pop3 postoffice
sunrpc          111/tcp
sunrpc          111/udp
ident           113/tcp         auth tap authentication
sftp            115/tcp
uucp-path       117/tcp
nntp            119/tcp         read news untp   # USENET News Transfer Protocol
ntp             123/udp         ntpd
imap            143/tcp
snmp            161/udp                         # network time protocol
snmp-trap       162/udp
smux            199/tcp
 

Appendix B: Palm OS Net Error Messages