Publishing Your Plugin's Data

These functions allow you to create data references that other plug-ins and X-Plane can access via the above data access APIs. Data references published by other plugins operate the same as ones published by X-Plane in all manners except that your data reference will not be available to other plugins if/when your plugin is disabled.

You share data by registering data provider callback functions. When a plug-in requests your data, these callbacks are then called. You provide one callback to return the value when a plugin 'reads' it and another to change the value when a plugin 'writes' it.

Important: you must pick a prefix for your datarefs other than "sim/" - this prefix is reserved for X-Plane. The X-Plane SDK website contains a registry where authors can select a unique first word for dataref names, to prevent dataref collisions between plugins.

XPLMGetDatai_f

callback

Data provider function pointers.

These define the function pointers you provide to get or set data. Note that you are passed a generic pointer for each one. This is the same pointer you pass in your register routine; you can use it to locate plugin variables, etc.

The semantics of your callbacks are the same as the dataref accessors above - basically routines like XPLMGetDatai are just pass-throughs from a caller to your plugin. Be particularly mindful in implementing array dataref read-write accessors; you are responsible for avoiding overruns, supporting offset read/writes, and handling a read with a NULL buffer.

typedef int (* XPLMGetDatai_f)(
                         void *               inRefcon
                    );

XPLMSetDatai_f

callback

typedef void (* XPLMSetDatai_f)(
                         void *               inRefcon,
                         int                  inValue
                    );

XPLMGetDataf_f

callback

typedef float (* XPLMGetDataf_f)(
                         void *               inRefcon
                    );

XPLMSetDataf_f

callback

typedef void (* XPLMSetDataf_f)(
                         void *               inRefcon,
                         float                inValue
                    );

XPLMGetDatad_f

callback

typedef double (* XPLMGetDatad_f)(
                         void *               inRefcon
                    );

XPLMSetDatad_f

callback

typedef void (* XPLMSetDatad_f)(
                         void *               inRefcon,
                         double               inValue
                    );

XPLMGetDatavi_f

callback

typedef int (* XPLMGetDatavi_f)(
                         void *               inRefcon,
                         int *                outValues,    /* Can be NULL */
                         ArrayOffset          inOffset,
                         ArraySize            inMax
                    );

XPLMSetDatavi_f

callback

typedef void (* XPLMSetDatavi_f)(
                         void *               inRefcon,
                         int *                inValues,
                         ArrayOffset          inOffset,
                         ArraySize            inCount
                    );

XPLMGetDatavf_f

callback

typedef int (* XPLMGetDatavf_f)(
                         void *               inRefcon,
                         float *              outValues,    /* Can be NULL */
                         ArrayOffset          inOffset,
                         ArraySize            inMax
                    );

XPLMSetDatavf_f

callback

typedef void (* XPLMSetDatavf_f)(
                         void *               inRefcon,
                         float *              inValues,
                         ArrayOffset          inOffset,
                         ArraySize            inCount
                    );

XPLMGetDatab_f

callback

typedef int (* XPLMGetDatab_f)(
                         void *               inRefcon,
                         byte *               outValue,    /* Can be NULL */
                         ArrayOffset          inOffset,
                         ArraySize            inMaxLength
                    );

XPLMSetDatab_f

callback

typedef void (* XPLMSetDatab_f)(
                         void *               inRefcon,
                         byte *               inValue,
                         ArrayOffset          inOffset,
                         ArraySize            inLength
                    );

XPLMRegisterDataAccessor

function

This routine creates a new item of data that can be read and written. Pass in the data's full name for searching, the type(s) of the data for accessing, and whether the data can be written to. For each data type you support, pass in a read accessor function and a write accessor function if necessary. Pass NULL for data types you do not support or write accessors if you are read-only.

You are returned a dataref for the new item of data created. You can use this dataref to unregister your data later or read or write from it.

XPLM_API XPLMDataRefXPLMRegisterDataAccessor(
                         const char *         inDataName,
                         XPLMDataTypeID       inDataType,
                         int                  inIsWritable,
                         XPLMGetDatai_f       inReadInt,    /* Can be NULL */
                         XPLMSetDatai_f       inWriteInt,    /* Can be NULL */
                         XPLMGetDataf_f       inReadFloat,    /* Can be NULL */
                         XPLMSetDataf_f       inWriteFloat,    /* Can be NULL */
                         XPLMGetDatad_f       inReadDouble,    /* Can be NULL */
                         XPLMSetDatad_f       inWriteDouble,    /* Can be NULL */
                         XPLMGetDatavi_f      inReadIntArray,    /* Can be NULL */
                         XPLMSetDatavi_f      inWriteIntArray,    /* Can be NULL */
                         XPLMGetDatavf_f      inReadFloatArray,    /* Can be NULL */
                         XPLMSetDatavf_f      inWriteFloatArray,    /* Can be NULL */
                         XPLMGetDatab_f       inReadData,    /* Can be NULL */
                         XPLMSetDatab_f       inWriteData,    /* Can be NULL */
                         void *               inReadRefcon,
                         void *               inWriteRefcon
                    );

XPLMUnregisterDataAccessor

function

Use this routine to unregister any data accessors you may have registered. You unregister a dataref by the XPLMDataRef you get back from registration. Once you unregister a dataref, your function pointer will not be called anymore.

XPLM_API void       XPLMUnregisterDataAccessor(
                         XPLMDataRef          inDataRef
                    );