Getting Started

The API is available for any development platform you like... as long as it's C++. The API does not support development in Java or .NET, so you need to break out your trusty compilers and target a Win32 DLL.

But, before you can compile anything, you need to write the code. The first task is determining what to write. The add-on API supports two types of extensions to the basic Orb functionality: those that generate and deliver XHTML pages to the user (showing a weather report or sports ticker, for example), and those that deliver binary data (rendering custom graphics or generating binary files). Both are accessed through the same basic API.

Add-On Initialization and Destruction

The first function to implement in your add-on is addOnInit(). This is where you do any object initialization, load resources, and take care of anything else that should be initialized before you display anything to the user. If your add-on uses a class to handle internal logic, now would be a good time to get an instance. Here's an example of a simple init call:

ADDON_API int AddOnInit(IAddOn *addOn)
{
     exampleAddOn = new ExampleAddOn(addOn); 
     return S_OK;
} 

The IAddOn class here represents some information about the current running Orb server, such as which local user is logged on to the computer, and also enables you to retrieve some preferences. The class is not necessarily utilized during the init call, however. It's in the call to addOnGetAttributes() where the IAddOn is used much more extensively.

The addOnGetAttributes() function is where your add-on implementation must identify itself and set a few values into the IAddOn, enabling it to be displayed in the list of available add-ons to the user. This means that it may be called before your add-on has been initialized. In the above example, the init function created an instance of ExampleAddOn. It would not be safe to assume that instance has been created before addOnGetAttributes() is called.

This function is required to set a few values and to return a status (like S_OK, above), as well as specify the expected version of the API. Currently, there's only 1.0 to worry about, so that what we return through the apiVersion param:

ADDON_API int AddOnGetAttributes(IAddOn *addOn,
  float &apiVersion)
{
     apiVersion = 1.0f;
     addOn->setName(L"ExampleAddOn");
     addOn->setDescription(L"This is an example Orb add-on");
     addOn->setIcon(L"images/icon.gif");
     addOn->setConfig(true);
     return S_OK;
}

In this case, a relative path is specified, meaning that the code looks in a subdirectory beneath the add-on installation directory. You can use a full path here, but do be careful about where that path ends. The setConfig function indicates whether your add-on has a separate configuration page that gives the user the ability to specify options for this particular add-on. The example we're creating here is very simple so there are no options, but we set it to true to better show how the page flow works in the next section.

Finally, we need to handle destruction. That's provided in the addOnClose() function. The method signature is exactly the same as addOnInit() and this, of course, is where you'd handle any object cleanup and close any active file I/O.

ADDON_API int AddOnClose(IAddOn *addOn) 
{
     If(addOnExample != NULL)
     {
          delete addOnExample;
          addOnExample = NULL;
     }
     return S_OK;
} 

Handling Application Flow

There's just one function for handling the flow of the application between pages, addOnGetPage(). This call provides some information about who the user is, what page he's currently viewing, and any submitted information from an HTML form. This should give you enough information to determine what to show to the user.

ADDON_API int AddOnGetPage(IAddOn *addOn,
  const CStringW &pageName, const CStringW &username,
  const IParameterMap &formData, CStringW &html) 
{	
     if (_wcsicmp( pageName, ADDON_PAGE_ROOT ) == 0)
     {
     html = "<root>This is the root page</root>";
     }
     else if (_wcsicmp( pageName, ADDON_PAGE_CONFIG ) == 0)
     {
     html = "<root>This is the config page.
 <a href=\"orb://page?orbName=special
 &amp;value=special\">Click here to go to the special page</root>";
     }
	 else if  (_wcsicmp( pageName, L"special") == 0)
	 {
	 html = "<root>This is the "
          + formData["value"] + " page</root>";
	 }
     return S_OK;
}

If you indicate that your add-on has a configuration page, you'll need to work with ADDON_PAGE_ROOT and ADDON_PAGE_CONFIG as the two constant page names. However, you aren't restricted to only these two pages. You can create your own pages and link to them, as in the above example, which results in output that looks like Figure 1.

Setting the config value to True in the addOnGetAttributes() results in the config link being added to the upper-right of the add-on box. Clicking on that takes you to the following page: