Getting started with WASP

The '8020:' that starts each line in the log file above is simply the thread id of the thread that wrote the log message, this can be useful in some situations, it will likely change with each log produced. Next comes the timestamp of the log entry and finally the log detail itself.

WASP first logs details of the version and build that is running. Next it tells you where it's running and where it expects to find its config file. It then attempts to load the config file and fails because it doesn't exist. WASP then shuts down.

WASP is configured using an XML file called WASP.xml that lives in the config directory. In the example above the config directory is the current directory, but that isn't always the case. For now we'll assume that the config directory is the current working directory.

The simplest config file is as follows (you can download it from here):

WASP works in terms of endpoints of which you can have many per instance of WASP. In the config file above we have a single endpoint which provides a server named "Echo Server" which listens on all of the machine's TCP interfaces on port 5050. The server itself is implemented by a DLL called EchoServer.dll which lives in the config directory. 

Since we don't currently have the DLL in the config directory WASP again fails to start with the following log:

This log contains quite a lot more information, much of it we'll explain in later tutorials. Right now the important part of the log for us is the following section:

This shows that we're configuring an endpoint called "Echo Server" which listens on port 5050. Since we didn't specify any other configuration options in the file we default some values, so we're listening on the IPV4 'any' address, Nagle is enabled and we have a listen backlog queue of 150 connections.

The warning tells us that we have not provided details of a DLL that will perform message framing and so every byte that arrives on the connection will be passed through to our handler DLL as it arrives and we'll need to deal with breaking the byte stream into messages ourselves. The handler DLL is EchoServer.dll which is located in our config directory which is the same as where the executable lives, C:\WASP.

Finally we get an error because the DLL cannot be found. WASP then shuts down.

You can download a prebuild EchoServer.dll from here, be sure to use the same build as your build of WASP, either x86 or x64, don't worry, you'll get a helpful log message if you use the wrong type of DLL. Once the handler DLL is in the correct place you can start WASP and it will actually complete its start up sequence and run; well, you will if nothing else is already listening on the same port, if you get errors in the log about not being able to bind then change the value of Port in your config file to something that isn't in use, use netstat -a to tell you the ports that are currently in use on your machine... 

So, hopefully, you now have a WASP powered echo server running and the log file looks something like this: 

Once again, the important section of this log is this bit:

This shows us which DLL entry points the handler DLL exports. This simple handler exports only one function, OnReadCompletedEx(). Either this or OnReadCompleted() MUST be exported for a DLL to be usable as a handler DLL, all of the other entrypoints are optional.

You can test your WASP using telnet, simply open a command prompt and run up telnet to connect to localhost on port 5050 and type stuff. The stuff that you type will be echoed back to you. Note that since telnet might also echo the data you send you'll likely see two copies of each character that you type.

You can ask WASP to stop accepting new connections, but to continue to process the existing ones by running WASP again from the command line and passing the /pause command line switch to it. The log will show that WASP is no longer accepting connections and a new telnet connection will fail. You can ask WASP to begin accepting connections again by calling it with /pause for a second time, again the log will show what's going on.

When you want WASP to shut down you can request a clean shutdown from the command line by running WASP with the /stop command line argument. All existing connections will be terminated and WASP will shut down.

WASP can also run as a Windows Service but we'll deal with that in the next tutorial. When running as a Windows Service the command line controls cannot be used. Instead you can control the service using the Service Control Manager in the usual way.