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:

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

Version()

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.

Example

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


TcpClose(fd)

Closes the current connection fd



data = TcpRead(fd, count, matchset, timeout)

Read data from an open connection.

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) 


written = TcpWrite(fd, data)

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.

Example

bytes=TcpWrite(fd, data)


TcpFlush(fd)

Flushes the input buffer

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.
Your message will appear in the Received Data field on the device, completing the round trip.

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

To get the commands supported by each post, consult the relevant RFC documentation. A complete list of RFC documents is at http://www.faqs.org/rfcs/.

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

Some of the function in the TcpIpLib will return a number. If it is negative, the call failed. The table below lists the meanings of the error numbers (as positive numbers).
4609 netErrAlreadyOpen
4610 netErrNotOpen
4611 netErrStillOpen
4612 netErrParamErr
4613 netErrNoMoreSockets
4614 netErrOutOfResources
4615 netErrOutOfMemory
4616 netErrSocketNotOpen
4617 netErrSocketBusy
4618 netErrMessageTooBig
4619 netErrSocketNotConnected
4620 netErrNoInterfaces
4621 netErrBufTooSmall
4622 netErrUnimplemented
4623 netErrPortInUse
4624 netErrQuietTimeNotElapsed
4625 netErrInternal
4626 netErrTimeout
4627 netErrSocketAlreadyConnected
4628 netErrSocketClosedByRemote
4629 netErrOutOfCmdBlocks
4630 netErrWrongSocketType
4631 netErrSocketNotListening
4632 netErrUnknownSetting
4633 netErrInvalidSettingSize
4634 netErrPrefNotFound
4635 netErrInvalidInterface
4636 netErrInterfaceNotFound
4637 netErrTooManyInterfaces
4638 netErrBufWrongSize
4639 netErrUserCancel
4640 netErrBadScript
4641 netErrNoSocket
4642 netErrSocketRcvBufFull
4643 netErrNoPendingConnect
4644 netErrUnexpectedCmd
4645 netErrNoTCB
4646 netErrNilRemoteWindowSize
4647 netErrNoTimerProc
4648 netErrSocketInputShutdown
4649 netErrCmdBlockNotCheckedOut
4650 netErrCmdNotDone
4651 netErrUnknownProtocol
4652 netErrUnknownService
4653 netErrUnreachableDest
4654 netErrReadOnlySetting
4655 netErrWouldBlock
4656 netErrAlreadyInProgress
4657 netErrPPPTimeout
4658 netErrPPPBroughtDown
4659 netErrAuthFailure
4660 netErrPPPAddressRefused
4661 netErrDNSNameTooLong
4662 netErrDNSBadName
4663 netErrDNSBadArgs
4664 netErrDNSLabelTooLong
4665 netErrDNSAllocationFailure
4666 netErrDNSTimeout
4667 netErrDNSUnreachable
4668 netErrDNSFormat
4669 netErrDNSServerFailure
4670 netErrDNSNonexistantName
4671 netErrDNSNIY
4672 netErrDNSRefused
4673 netErrDNSImpossible
4674 netErrDNSNoRRS
4675 netErrDNSAborted
4676 netErrDNSBadProtocol
4677 netErrDNSTruncated
4678 netErrDNSNoRecursion
4679 netErrDNSIrrelevant
4680 netErrDNSNotInLocalCache
4681 netErrDNSNoPort
4682 netErrIPCantFragment
4683 netErrIPNoRoute
4684 netErrIPNoSrc
4685 netErrIPNoDst
4686 netErrIPktOverflow
4687 netErrTooManyTCPConnections
4688 netErrNoDNSServers
4689 netErrInterfaceDown
4690 netErrNoChannel
4691 netErrDieState
4692 netErrReturnedInMail
4693 netErrReturnedNoTransfer
4694 netErrReturnedIllegal
4695 netErrReturnedCongest
4696 netErrReturnedError
4697 netErrReturnedBusy
4698 netErrGMANState
4699 netErrQuitOnTxFail
4700 netErrFlexListFull
4701 netErrSenderMAN
4702 netErrIllegalType
4703 netErrIllegalState
4704 netErrIllegalFlags
4705 netErrIllegalSendlist
4706 netErrIllegalMPAKLength
4707 netErrIllegalAddressee
4708 netErrIllegalPacketClass
4709 netErrBufferLength
4710 netErrNiCdLowBattery
4711 netErrRFinterfaceFatal
4712 netErrIllegalLogout
4713 netErrAAARadioLoad
4714 netErrAntennaDown
4715 netErrNiCdCharging
4716 netErrAntennaWentDown
4717 netErrNotActivated
4718 netErrRadioTemp
4719 netErrNiCdChargeError
4720 netErrNiCdSag
4721 netErrNiCdChargeSuspend
4722 not used
4723 netErrConfigNotFound
4724 netErrConfigCantDelete
4725 netErrConfigTooMany
4726 netErrConfigBadName
4727 netErrConfigNotAlias
4728 netErrConfigCantPointToAlias
4729 netErrConfigEmpty
4730 netErrAlreadyOpenWithOtherConfig
4731 netErrConfigAliasErr
4732 netErrNoMultiPktAddr
4733 netErrOutOfPackets
4734 netErrMultiPktAddrReset
4735 netErrStaleMultiPktAddr
4736 netErrScptPluginMissing
4737 netErrScptPluginLaunchFail
4738 netErrScptPluginCmdFail
4739 netErrScptPluginInvalidCmd
4740 netErrTelMissingComponent
4741 netErrTelErrorNotHandled