The simplest plugin, examining EchoServer.dll

WASP plugins are, at present, native DLLs that expose a set of known entry points. The minimal plugin exposes a single entry point, either OnReadCompleted() or OnReadCompletedEx(). The entry points and other details that you need to build a plugin for WASP are detailed in the WASPDLLEntryPoint.h header file that ships in the SDK directory with WASP.

The simplest plugin that you could possibly write is one that uses OnReadCompletedEx() and which simply echoes all inbound data back to the client again. The complete code for such a plugin can be downloaded from here, but the actual code required is just this:

#include "WASPPluginSDK\WASPDLLEntryPoints.h"

#pragma comment(lib, "ws2_32.lib")

WaspDataLength __cdecl  OnReadCompletedEx(
   const WaspConnectionHandle /*connectionHandle*/,
   WaspConnectionUserData /*connectionUserData*/,
   const BYTE * const /*pDataIn*/,
   const WaspDataLength dataLength,
   const BYTE * /*pDataOut*/,
   const WaspDataLength /*outputBufferSize*/)
   return dataLength;

OnReadCompletedEx() is a more advanced version of OnReadCompleted() which allows you to optimise your server by using the input buffer space as your output buffer, for some server designs this can reduce the number of data buffers that the server needs to allocate as long as your output message can fit into the buffer size that you have configured and as long as you can hold off building your response until you’ve completely processed your input message. This design is useful for things like high performance ISO 8583 message processors, and other structured request/response servers.

We’re taking advantage of the fact that the input buffer is used for sending output in this simple echo server.

We’ll ignore the connectionHandle and connectionUserData for now and deal with them in a later tutorial. That leaves us with pDataIn which is a pointer to the bytes that have arrived, dataLength which is the number of bytes that have arrived, pDataOut which is a pointer to a buffer to write your output into and outputBufferSize which is the size of the output buffer. You return the number of bytes that you’ve written, and as explained above, pDataIn and pDataOut point to the same buffer. This means that to simply echo all bytes that arrive you just need to return the dataLength that you are passed in as the number of bytes that you wish to write. You don’t need to copy the bytes from pDataIn to pDataOut.

Since this message handling dll is configured without a framing dll no message framing is done so each time a read completes the number of bytes that have arrived will be passed directly to the echo server plugin and echoed immediately.

To debug a plugin you simply load the plugin’s solution and adjust the debugging properties as follows:

WASP - EchoServer Debug

By setting the “command” to point to your installed instance of WASP you cause WASP to run when you begin debugging. You can now set a break point in your plugin DLL and when data arrives the break point will be hit. To test this plugin simply connect to your WASP instance on the port that you’ve configured using telnet.