PureBasic Survival Guide XIV - Networking
PureBasic Survival Guide
a tutorial for using purebasic for windows 4.50rc2

Part 0 - TOC
Part I - General
Part II - Converts
Part III - Primer I
Part IV - Primer II
Part V - Advanced
Part VI - 2D Graphics I
Part VII - 2D Graphics II
Part X - Assembly
Part XI - Debugger
Part XII - VirtualBox
Part XIII - Databases
Part XIV - Networking
Part XV - Regular Expressions
Part XVI - Application Data
Part XXVII - Irregular Expressions
Part XXIX - Projects

Part XIV - Networking
v1.03 11.04.2011

14.1 Get connected!
14.2 Setting up shop.
14.3 Build-in commands.
14.4 WinSock.
14.5 All together now...
14.6 FTP
14.7 Port forwarding

This page is under construction.

14.1 Get connected!

Ports?!? IP addresses? TCP/IP or protocols?!?!?

UDP is like the US mail...

Is it? :-) Euh, I just may have to tell you whtt it's all about.

A most simplistic view: every device on the Internet has a number, an IP address. Every device also has a number of ports. A program on your computer can use those ports to talk to other computers... Another way to look at it:

  1. Networks are like streets.
  2. Each computer connected to that network is like a house on that street and has it's own address (an IP address).
  3. Each house has many mailboxes (ports).
  4. Each house may have one or more inhabitants (programs) using those mailboxes (ports).
  5. A firewall is a piece of duct tape, and is used to close some of those mailboxes.
  6. We're going to send letters (packets) from one mailbox to another.
  7. There are two delivery services making their rounds. One simply picks up mail and drops it somewhere else. And if looses a letter, well... too bad (some call it UDP, some call it US mail :-)). UDP doesn't care in what order letters arrive.
  8. The other service picks up the letter (packet) and keeps holding on to it until it is able to deliver it. This one's called TCP, and it also makes sure the oldest letters are delivered first.
  9. Sometimes, the sender, the postman, and the receiver talk to each other using special secret handshakes (a protocol).
To keep things interesting, the delivery services use a list and instruction manual to find the right house.
  1. When the delivery service uses a list and an instruction manual, they can do all sorts of intelligent things, like readressing letters etcetera (routers).
  2. If they loose the instruction manual they just run around and try to find the right house. Then they'll make up their own little list, which they redo whenever someone moves. Without the instruction manual they cannot do smart things (switches).
  3. Some very dumb postmen even lost their little list, and just offer their letters to every door at the same time, hoping someone takes it (hubs). Fortunately, they're less common these days.
I hope this explanation is silly enough :-) So now you now what ports are. So, what are they? (If you answered 'places where ships come and go' it's time to find another hobby.)

PureBasic offers you some build-in commands, and if those do not suffy you can use WinAPI to call WinSock.

Simple network samples

1. A really simple network with two PC's would probably look something like this:

PC1 --- SWITCH --- PC2
2. Typically we simply ignore switches and hubs (they won't do anything smart to our data) and thus we could look at the network like this:
PC1 --- PC2
I do like the simple things in life :-)

3. Let's say you have a single PC and a modem (and huge phonebills :-)) that connects you to the Internet:

4. If you have an ADSL or cable modem things look pretty much the same.
5. Most ADSL modems are no longer simple modems, but are smart devices, messing around with the data we pass through them. In other words... they are routers and modems in one! And most of them are smart enough to protect you somewhat from the dangers of the Internet. Just a little, mind you... To confuse matters, ADSL routers are often called ADSL modems. Anyway...
6. Some routers have only a single network port, so if you run a network you may have to add a switch...
7. Obviously, multiple machines could be connected to that switch...
PC1 ----
PC3 ----
8. Switches are fairly stupid, so there's no reason why you can't stack them. Traffic will find its way...
9. WiFi boxes could be considered another kind of switch (with a little added protection). Think of a WiFi link as just another piece of cable...
10. Just make sure you don't create loops... they just might kill your network!
11. Many modern day routers may have their switch and router 'build in', so you can connect your PC's to them directly, without the use for a seperate box. Though logically it would still be seperate blocks, physically it's all in a single box, which we tend to call a router (though it's actually a router + WiFi + switch + firewall + modem all mixed up):
PC1 ----
PC3 ----
12. A LAN is a local network. It's a bunch of PC's hooked up together through a switch. It's what you find in companies, or in a geek's home ;-) Between the different PC's there's little security, and local network speeds are typically high. Great for games, sharing music, watching movies, or for more serious things like accessing documents on a central office server. Let's repeat example number 7 once more...
PC1 ----
PC3 ----
13. The LAN (Local Area Network) is on the left side...
PC1 ----
PC2 --- SWITCH --- ROUTER ---
PC3 ----
14. And the WAN (Wide Area Network) is on the right side...
       --- ROUTER --- INTERNET 
(I hope the web and your browser won't mess up these little drawings...)

With these basics under your belt go on the Internet and try to understand NAT. It's an essential part (and source of many problems) when it comes to IP network related programming.

14.2 Setting up shop

If you don't have multiple machines at hand, you may opt for using a virtual machine like VirtualBox. (Which is why I did spend so much time on VM's for more pure PureBasic happines...) In fact, it's often a lot more practial to have it all on one system in front of you. Only when dealing with CPU intensive applications (games), or applications that need exclusive access to your hardware (more games) you may need multiple dedicated machines to bring enough horsepower to your desktop.

Some tools / applications you definitely want to take a look at before diving in...

  • dual monitor setups (couldn't live without this)
  • virtual machines (VMware, VirtualBox)
  • a hardware KVM (if everything is nearby and you don't like software solutions)
  • a software package called Synergy (nice for desktop + laptop setups)
  • remote management software such as VNC (especially for far away servers)
Here's my sample setup: a large machine with three virtual machines on-board, a small dedicated server, and a router / firewall to stay connected to the outside world:

Install all machines, and if you know you can trust your router / firewall you may disable any software firewalls on your PC, just for testing. If you're concerned about your safety, disconnect from the Internet before you do so and reconnect afterwards. Software firewalls can seriously cause confusion when you start with network programming.

For the next steps, I used the following setup:

  • one host machine running VirtualBox (dev2 on
  • inside VirtualBox one virtual machine (mysqlserver on
  • both machines (the real and the virtual one) can 'ping' eachother fine (firewall settings on BOTH sides!)
  • I will make no further references to local software firewalls, they are from now on officially your problem, not mine!

14.3 Build-in commands

This section is under construction.

14.4 WinSock

This section is under construction.

14.5 All together now...

This section is under construction.

14.6 FTP

FTP using the Windows client

Not exactly a PureBasic topic in itself, yet it may help you verifying the workings of your own code. The example below is what I use to update CodeCaddy, and is similar to what I use to create the survival guide archive and then upload it onto my homepage.

The first part is a batch file that creates a folder, then copies a selected set of files into it, and then packs it into a zip file. Yeah, I know. No PureBasic at all in this part, except for a folder name :-)

rem *** this batch script creates an archive containing codecaddy

rem p_drive  = projects drive     = d:
rem p_folder = projects folder    = d:\purebasic\_projects
rem t_drive  = temporary drive    = e:
rem t_folder = temporary folder   = e:\codecaddy
rem v_drive  = destination drive  = v:
rem v_folder = destination folder = v:\data\webpages\nightlive\purebasic

set p_drive=d:
set p_folder=%p_drive%\purebasic\_projects
set t_drive=e:
set t_folder=%t_drive%\codecaddy
set v_drive=v:
set v_folder=v:\data\webpages\nightlive\purebasic

rmdir %t_folder% /Q /S

mkdir %t_folder%
mkdir %t_folder%\source
mkdir %t_folder%\source\codecaddy
mkdir %t_folder%\source\codecaddy\icons
mkdir %t_folder%\source\codecaddy\images
mkdir %t_folder%\source\x_lib
mkdir %t_folder%\source\x_lib\icons

cd %t_folder%
copy %p_folder%\codecaddy\readme.txt
copy %p_folder%\codecaddy\quickhelp.txt
copy %p_folder%\codecaddy\license.txt
copy %p_folder%\codecaddy\about.txt
copy %p_folder%\codecaddy\codecaddy.swf

copy %p_drive%\purebasic\codecaddy.exe

cd %t_folder%\source\codecaddy
copy %p_folder%\codecaddy\readme.txt
copy %p_folder%\codecaddy\quickhelp.txt
copy %p_folder%\codecaddy\license.txt
copy %p_folder%\codecaddy\about.txt
copy %p_folder%\codecaddy\codecaddy.pb
copy %p_folder%\codecaddy\tools.prefs
copy %p_folder%\codecaddy\icons\*.ico icons
copy %p_folder%\codecaddy\images\wackoware_respect.bmp images\wackoware.bmp

cd %t_folder%\source\x_lib
copy %p_folder%\x_lib\x_lib*.pb
copy %p_folder%\x_lib\icons\*.ico icons

7z a -tzip -r %v_folder%\codecaddy.zip %t_folder%

ftp -n -s:%v_drive%\batch\up_codecaddy.ftp

set p_drive=
set p_folder=
set t_drive=
set t_folder=
set v_drive=
set v_folder=

First I create a few variables for the batch file, so I can change paths in a single place. Other people may prefer to hardcode all paths and do a search / replace, it's just a matter of taste. My distribution of CodeCaddy is a subset of all files in the CodeCaddy related folders, so I create a dedicated folder and fill it with the files and folders I want to distribute. (That's all those 'copy' lines.)

I then use (the free) 7zip to pack the whole shebang into a zip archive (which I place in my local offline copy of my website). I use the 7zip compatibility mode to make sure older / other (un)packers can handle the final zip file. I've now created a zip file containing the latest public version of CodeCaddy, but I might also have changed the related page 'purebasic 29.htm' on the website and I need to upload them both.

Windows XP comes with its own FTP client, called... wait for it... tada... ftp.exe.You can choose to either use it online / interactive, or to use a script. To find out all about ftp.exe and its command line parameters type:

ftp.exe -?
 I use two ftp.exe options: -s to load and execute a script and -n suppress a password prompt:
ftp.exe -n -s:<scriptfile>
Have a look at the following script. I've stored it on my 'v-drive' which actually is a TrueCrypt encrypted drive. (If someone would nick my PC then he / she would not have my passwords and private documents).
open ftp.xs4all.nl 21
user secretusername secretuserpassword
cd WWW
cd purebasic
put v:\data\webpages\nightlive\purebasic\codecaddy.zip
put "v:\data\webpages\nightlive\purebasic\purebasic 29.htm"
From top to bottom:
  1. 'open' an ftp connection to my internet provider
  2. login using a username and password (sorry, the above ones are obviously fake :-))
  3. change to the proper remote folder
  4. 'hash' turns on progress indicator
  5. 'binary' turns on binary mode
  6. the 'put' command copies a single file (no wildcards allowd, no folders) from the local drive to the ftp server
  7. 'quit' ends the ftp session
You can send multiple filenames using the 'mput' command, like this:
mput v:\data\webpages\nightlive\purebasic\*.jpg
With a bit of creativity and some googling you should now be able to write your own ftp scripts for the Windows ftp client, and you might execute them from within PureBasic using the RunProgram() command. But where's the fun in that... :-)

FTP using PureBasic - advanced functions

Look for the basic topics here.

This section is under construction.

14.7 Port forwarding

PC's on the Internet find each other by using 'public' Internet addresses. Typically a firewall or router seperates the big bad Internet from your home or office network. To the outside world it looks like all PC's in your home network have a single address. Don't worry how the router figures out where to send information to if you requested something from another machine on the Internet. Better question yourself what the router will do with UNREQUESTED information / packets... This is where port forwarding comes in.

Two sides talking

Assume you and someone else are running a game or other application over the Internet. Let's say both sides have a router+PC, like this:

PC1 --- ROUTER1 --- ISP1 --- INTERNET --- ISP2 --- ROUTER2 --- PC2
The IP addresses may be assigned dynamically, or be fixed. (Following addresses are chosen at random and don't mean much.) I assume you both have a fixed IP.

Many people have their machine assigned an address by DHCP on the router, ie. the router defines the address of the PC on the local network.

PC1 (DHCP client) --- ROUTER1 (DHCP server assigning address to client PC)
This, typically, may not be such a good idea. You want to be sure the PC is always on the same address in your local network, so you can forward incoming traffic to it. So disable DHCP on your client and assign it a fixed IP address, OR configure your router in such a way that it will always assign a specific IP address to your PC (this may not always be possible).
PC1 --- ROUTER1 
Now the router itself MAY be assigned a fixed address by your ISP, or it may be assigned a dynamical address by your ISP. If it's a fixed address then life will be easier. If you AND the other party both have a dynamic address you're pretty much out of luck, unless you find a third party so you and the other party can exchance their current adresses. Or you type them in by hand every time, that will work as well :-)

Depending on your configuration and setup, you may have to either specify the router address as your DNS server, or use the DNS server of your ISP. I tend to do the latter, as routers don't always play nice when it comes to DNS. The gateway address is typically the address of the router itself.

I assume the ISP assigns permanent IP address to your router, resulting in something like:

PC1 --- ROUTER1 --- ISP1 --- ...
(Yes, that router has two addresses, one local to your network, and one to the outside world.)

Traffic incoming from the internet has to be redirected to some PC on your network. If that traffic was a reply to something your PC send out (such as a typical HTTP session) it will be routed to that PC. But if it is incoming and NOT a reply to something you send out, it will be stuck at the router. The router doesn't know where to send it to.

Port forwarding

So, what you have to do is a port forward, ie. someone on the internet tries to make a connection to a port on your router, and your router redirects it to your PC. How to set up such a forwarded port depends on your router. The ports don't need to match. You may set up a rule like this:

Router port 6000 should be forwarded to port 7000.
Now everytime something on the big bad Internet tries to contact your PC, it does so by sending packets to port 6000, and the PC receives them on port 7000.

Obviously, the same applies to the other side as well.

Hooking up two machines could look something like this:

PC1 --- ROUTER --- ISP1 --- INTERNET --- ISP2 --- ROUTER --- PC2
Duh. Sounds difficult, but actually it isn't.

Exchanging IP adresses through an intermediate station

Now if BOTH sides have dynamically assigned public addresses, things are a little more complicated. You will need a third party that is contacted by both clients to exchange proper IP adresses. Obviously that third party needs a fixed address otherwise both clients cannot find it...

Dynamic DNS

There's a way around, and that is using dynamic DNS adresses. But if you understand dynamic DNS, then you won't need my advice :-) I just wanted to mention it...

Skype style

For many games / applications both parties have to open up certain ports and add port forwarding rules. There are also those that do not need such rules, either because they always route through a central location, OR because they punch holes in the firewall in Skype style. (Google a little and you will see what I mean.)


Can of worms alert! Do a Google, and find out why many people disable this functionality on their routers. Things have improved, but still...

This section is under construction.