Testing Your Application

Testing is fairly straightforward. Once your DLL is compiled, you drop it into a new subdirectory beneath the add-ons directory in the Orb installation (usually C:\Program Files\Orb Networks\Orb\bin\AddOns). The new subdirectory should share the same name as your add-on (ExampleAddOn in this case), and beneath that should be any images or other files you'll use.

At this point, if you're running with the basic Orb server, you need to right-click on the Orb icon in the task bar and click "Stop," wait about 20 seconds, then click "Start" and wait another 20 seconds. This gets a little tedious, and that's where the AddOnManager.exe comes in. This app works like a lightweight server; you can run it instead of the Orb server. You don't have access to all the same functions you'd normally get, but you can modify and re-deploy new add-ons much more quickly.

Binary Data

The final piece of the puzzle is handling binary data. If you want your add-on to serve up a dynamic image to the user based on some form-submitted data, you need to implement three further functions: addOnStartData(), addOnGetData(), and addOnStopData(). The first initializes any data to be read, the second actually delivers the data, and the third performs cleanup.

Here's an example of the start, in this case loading up a graphic image:

ADDON_API int AddOnStartData(IAddOn *addOn, 
  const CStringW &dataId, const CStringW &orbLogin,
  const IParameterMap &formData, CStringW &mimeType,
  long& totalSize, LPVOID& userData)
{
     CString name = formData["imagename"];
		
     ifstream file(name, ios::in|ios::binary|ios::ate);
     mimeType = "jfif";

     if (file.is_open())
     {
          g_totalSize = file.tellg();		
          totalSize=g_totalSize;
          g_buffer = new BYTE [g_totalSize];
          file.seekg (0, ios::beg);
          file.read ((char*)g_buffer, sizeof(BYTE) * g_totalSize);
          file.close();
     }
     return S_OK;
}

The code takes the path to the image from the form data and reads it into memory, in preparation of a subsequent call to actually get the contents of the image. Here, the data in the file is stored in a global byte array called g_buffer and its size is stored in g_totalSize. These values are used in the get call:

ADDON_API int AddOnGetData(IAddOn *addOn, LPVOID userData,
  BYTE *buffer, long offset, long& bufferLen,
  GETDATA_STATUS& status)
{
	buffer = g_buffer;
	bufferLen = g_totalSize;
	offset = 0;
	status = GETDATA_DONE;
	return S_OK;
}

Finally, the memory should be freed up:

ADDON_API int AddOnStopData(IAddOn *addOn, LPVOID userData,
   STOPDATA_STATUS status)
{
	delete g_buffer; 
	return S_OK;
}

Then, to actually access the binary data, an image link can be inserted, like the following:

<img src=\"orb://data?orbName=image&imagename=filename.jpg\"/>

Keep in mind the security concerns described above, when accessing data in such a way.

Worth Playing With

Even if you don't wind up writing your own add-on extensions, Orb offers a very worthwhile and useful service. This version of the API sadly doesn't open up the door to any of Orb's decoding and encoding features, and the exclusively C++ interface seems a little out of place given that restriction, but its relative simplicity makes for very easy development for those looking to whip up some quick utilities.