gistfile1.txt

Define a new struct, MumblePlugin2FetchArgs

	struct MumblePlugin2FetchArgs {
		int version;

		// version == 0
		float *avatar_pos;
		float *avatar_front;
		float *avatar_top;
		float *camera_pos;
		float *camera_front;
		float *camera_top;
		std::string *context;
		std::wstring *identity;
		bool *is_spectator;

		// !!! FOR EXAMPLE PURPOSES ONLY !!!

		// version >= 1
		unsigned long *imaginary_future_field;

		// version >= 2
		bool *is_below_20_degrees_celcius;

		// !!! END EXAMPLE !!!
	};

The idea is that new fields can be added by bumping the version
field. The new struct's version starts at 0, and includes a new field compared
to the old fetch() interface: is_spectator.
The struct above also shows how we can extend it in the future: add a new field, and bump
the version. Plugins that know about the new feature can use it. Plugins that don't will
ignore the new feature.

Add new fetch function to MumblePlugin2:

static int fetch2(MumblePlugin2FetchArgs *args) {
	// Plugins

	args->avatar_pos[0] = 1.0f;
	args->avatar_pos[1] = 1.0f;
	args->avatar_pos[2] = 1.0f;

	*(args->is-spectator) = true;

	// To support imaginary_future_field, plugins
	// need to do: the following:

	if (args->version >= 1) { // OK, imaginary_future_field is available...
		*(args->imaginary_future_field) = 0xdeadbeef;
	}

	// To support is_below_20_degrees_celcious

	if (args->version >= 2) { // OK, is_below_20_degrees_celcius is available...
		*(args->is_below_20_degrees_celcius) = false; // NO THANKS!
	}
}

Plugins still need to implement the old fetch interface, which can
be implemented via:

int fetch(float *avatar_pos, float *avatar_front, float *avatar_top,
          float *camera_pos, float *camera_front, float *camera_top,
          std::string &context, std::wstring &identity) {

	bool is_spectator; // fetch2 needs to write to this...

	MumblePlugin2FetchArgs args;
	memset(&args, 0, sizeof(args));
	args.version = 0;
	args.avatar_pos = avatar_pos;
	args.avatar_front = avatar_front;
	args.avatar_top = avatar_top;
	args.camera_pos = camera_pos;
	args.camera_front = camera_front;
	args.camera_top = camera_top;
	args.context = &context;
	args.identity = &identity;
	args.is_spectator = &is_spectator;
	
	return fetch2(&args);
}