Introduction

It's fairly simple to include networking functionality in your NS Basic application. This tutorial will guide you with a simple example, so even a beginner should have no problem.

How is it done?

Including network support in your application starts as simply as adding a library to your project. TcpIpLib is included with NS BASIC. Add it to your project as a resource using Project...Add Resource and use the LoadLibrary call to initialize it in your program.

Once you do that, you have some extra methods to play with:

• fd = TcpOpen(hostname, port, timeout)
• TcpClose(fd)
• data = TcpRead(fd, count, matchset, timeout)
• written = TcpWrite(fd, data)
• TcpFlush(fd)

(For a complete reference on the methods above, make sure you read the chapter 1 of Tech Note 18)

If you ever worked with TCP or even saving/reading files from the file system the methods above should mean something for you. If you didn't, don't worry, it's not difficult to understand. You talk to other computers in a similar way you deal with files:

• First of all you have to open it,
• then you can read or write things to/from it,
• and finally you close it.

Because you are dealing with a remote system and not a local file, you have a "timeout" feature. It simply means that if your application does not hear from the remote machine for a specified period of time it will give up.

You must also specify to which service you want to connect in that remote machine, and that's the concept behind "port". Different ports provides different services, for instance,

• a webserver usually listens on port 80,
• your mail server accepts messages for delivery on port 25 (SMTP service), and
• your email client connects on the server's port 110 to retrieve your mail using the POP3 protocol.

Let's check our Email server!

In this project will simply connect to a pop3 server, send username and password, and display the result to the STAT command (it should tell how many messages you have). Let's now put a button and a multi-line field on a form, and the code in the button, as the picture below:

Dim server as String Dim username as String Dim password as String Dim data as String Dim crlf as String Dim handle as Integer Dim bytes as Integer ' These are the same settings you would use in your email client server = "mail.xxx.com" username = "xxx© xxx.com" password = "xxx" crlf = chr(13)+chr(10) ' Connect to the server handle = TcpIpLib.TcpOpen(server, 110, 10000) If handle < 0 Then MsgBox "Error " + str(-handle) ' error code End If ' Read result into data data = TcpIpLib.TcpRead(handle, 256, crlf, 10000) Field1005.text = Field1005.text + chr(10) + data ' Send username and get response bytes = TcpIpLib.TcpWrite(handle, "user " + username + crlf) data = TcpIpLib.TcpRead(handle, 256, crlf, 10000) ' Send password and get response bytes = TcpIpLib.TcpWrite(handle, "pass " + password + crlf) data = TcpIpLib.TcpRead(handle, 256, crlf, 10000) ' get STATUS response bytes = TcpIpLib.TcpWrite(handle, "stat" + crlf) data = TcpIpLib.TcpRead(handle, 256, crlf, 10000) Field1005.text = Field1005.text + chr(10) + data TcpIpLib.TcpClose(handle)

Now let's analyze the code, step by step:

• From line 1 to 7 we are simply defining some variables that we wil work with
• From line 10 to 13 we are saying what is our POP3 server, what is our username and password.
• On line 16 we open the connection to "server" on port 110 with a timeout of 10 seconds.
• Line 22: Read up to 256 characters or until we find a line feed into "data"
• On line 26 we are sending the user name to the server and waiting for a response on line 27.
• The same repeats for the lines 30-31 and 34-35.

This is what is called a chat-style connection. You send something and wait for a response. Thats how the POP3 server works:

• you connect and it greets you
• you send your username, and it says either "ok" or that something is wrong
• you send your password and it will say if you are logged in, or if your password is not correct.

You can tell if the reponse is a success or an error on POP3 protocol by looking at the first character of the response line: a plus means it was accepted, a minus means there was a problem.

Of course this is a very simple example to get you started. A real application would have functions to get lines and to send lines, and also check if the password was accepted, parse the STAT result lines to display only the number of messages and not the entire ugly line, and even retrieve the header of each message and display the sender, subject and date of all the emails, and much more. Make sure to check the TcpIpDemo project on the samples folder of your NS BASIC installation, there you will find the functions I am talking about as well as an example to send email, and to retrieve a web page.

Here is how it would look like after you compile and run our sample:

• The first line is the server greeting and
• The second is the response to the STAT command.

References:

• Tech Note 18: Using the TcpIpLib Library
• POP3 Protocol
• SMTP Protocol
• HTTP Protocol