This wiki is archived and useful information is being migrated to the main bzflag.org website

Difference between revisions of "BZFS API 2.4 Upgrade"

From BZFlagWiki
Jump to: navigation, search
(Initial notes on upgrading plug-ins from 2.0.4 to 2.3.4)
(No difference)

Revision as of 06:17, 18 May 2011

Overview

For version 2.4 the BZFS_API has undergone some restructuring. This document will go over the changes a plug-in developer must make in order to update to this new release.

Compatibility

In order to gain forward compatibility the API had to be changed in a way that broke backwards compatibility. This means that all plug-ins written for 2.0.x will not load in version 2.3.4 or later.

API Version Numbers

In the past the API version number represented the newest version of the API that the plug-in would run under. This caused plug-ins to have to be recompiled every time the API version changed.

In the new API the version number represents the minimum version required. This will ensure that plug-ins can be loaded in future versions. This also prevents plug-ins from running in versions older then they were written for. Due to the uni-directional nature of software upgrades this is a more useful feature.

Entry Points

The main entry points for the API have changed. The following entry points are no longer used.

BZF_PLUGIN_CALL int bz_Load ( const char* command );
BZF_PLUGIN_CALL int bz_Unload ( void );
BZF_PLUGIN_CALL int bz_GetVersion ( void );

The entry points are replaced with the following new items.

BZF_PLUGIN_CALL bz_Plugin*bz_getPlugin ( void );
BZF_PLUGIN_CALL void bz_freePlugin ( bz_Plugin*);
BZF_PLUGIN_CALL int bz_GetMinVersion ( void );

bz_GetMinVersion is called first to get the minimum API version. If the current BZFS supports this verison then the plug-in will be loaded and bz_getPlugin will be called. This function returns the Plug-in Class that BZFS will use to interact with the plug-in. When a plug-in is unloaded the function bz_freePlugin will be called.

A set of macros are provided in the bzAPI.h Header to simplify the calls for a plug-in.

The plugin can simply call the BZ_PLUGIN(n) macro and provide a classname that is derived from bz_Plugin. This will create and free a plug-in class automatically and return the version of the API that the plug-in was compiled with.

Plug-in Class

The plug-in class is defined by the base class bz_Plugin. It contains 2 methods that each plug-in must implement in a derived class,

 virtual const char* Name () = 0;
 virtual void Init(const char* config) = 0;

Name returns the human readable name for the plug-in as a null terminated ASCII string.

Init is called by BZFS after the plug-in is loaded and serves the same function as the bz_Load entry point in previous versions.

The derived class may also optional provide versions of these additional methods

virtual void Cleanup() {Flush();}
virtual void Event(bz_EventData* /*eventData*/) { return; }

Cleanup is called when a plug-in is unloaded and replaces the [bz_Unload]] function in previous versions. By default Cleanup will automatically remove any events that the plug-in has registered.

Event is called whenever BZFS executes an event that the plug-in has requested to be informed of. This function replaces the bz_EventHandler class in older versions.

Events

Every plug-in now has a single callback method for all events that it registers. The functions bz_registerEvent and bz_removeEvent have been removed from the API. In there place the bz_Plugin class now implements it's own Register and Remove methods.

These methods only take an event type and do not need a separate handler class, they will always use the Event method of the calling class.

A new method, Flush is provided to remove all events that the plug-in has registered. This method is automatically called by the default Cleanup method.

Event Data Classes

In addtion to the new Event handler system, all the event data classes have been changed. Each event data class is now versioned with a number in the class name, such as bz_PlayerSpawnEventData_V1. These event classes will never change and new versions will be derived from them with a higher version number. This allows a plug-in to always get the data it knows about, even as the BZAPI is enhanced to include more data for each event.

The base class for the Event Data Classes has also changed. bz_EventData now includes a timestamp for when the event was triggered in the eventTime data member.

Spelling Changes

Spelling errors and grammatical inconsistencies in the API have been fixed.

BZ string and list classes

The bzApiString and other associated basic types have been renamed to bz_ApiString to be more consistent with the rest of the API.

Callbacks

In order to reduce the number of callback classes that had name conflicts, call callback classes that used the handle method have had there methods renamed to be descriptive of the callback type. This is in order to make the use of multiple inheritance for callbacks simpler.

Idle Time

The function bz_setMaxWaitTime has been removed from the API. bz_Plugin contains a MaxWaitTime data member that can be set by each plug-in individually. BZFS will use the smallest time required by any plug-in. Setting the value to a negative number will indicate that the plug-in has no specific idle time needs.

Inter Plug-in Communication

bz_pluginExists and bz_getPlugin are provided to allow plug-ins to transfer data between themselves. the bz_Plugin class contains the GeneralCallback that can be used to call functions from one plug-in to the other.