XPLMDataAccess

XPLM Data Access API - Theory of Operation

The data access API gives you a generic, flexible, high performance way to read and write data to and from X-Plane and other plug-ins. For example, this API allows you to read and set the nav radios, get the plane location, determine the current effective graphics frame rate, etc.

The data access APIs are the way that you read and write data from the sim as well as other plugins.

The API works using opaque data references. A data reference is a source of data; you do not know where it comes from, but once you have it you can read the data quickly and possibly write it. To get a data reference, you look it up.

Data references are identified by verbose string names (sim/cockpit/radios/nav1_freq_hz). The actual numeric value of the data reference is implementation defined and is likely to change each time the simulator is run (or the plugin that provides the datareference is reloaded).

The task of looking up a data reference is relatively expensive; look up your data references once based on verbose strings, and save the opaque data reference value for the duration of your plugin's operation. Reading and writing data references is relatively fast (the cost is equivalent to two function calls through function pointers).

This allows data access to be high performance, while leaving in abstraction; since data references are opaque and are searched for, the underlying data access system can be rebuilt.

A note on typing: you must know the correct data type to read and write. APIs are provided for reading and writing data in a number of ways. You can also double check the data type for a data ref. Note that automatic conversion is not done for you.

A note for plugins sharing data with other plugins: the load order of plugins is not guaranteed. To make sure that every plugin publishing data has published their data references before other plugins try to subscribe, publish your data references in your start routine but resolve them the first time your 'enable' routine is called, or the first time they are needed in code.

X-Plane publishes well over 1000 datarefs; a complete list may be found in the reference section of the SDK online documentation (from the SDK home page, choose Documentation).

READING AND WRITING DATA

These routines allow you to access a wide variety of data from within x-plane and modify some of it.

XPLMDataRef

typedef void * XPLMDataRef;
A data ref is an opaque handle to data provided by the simulator or another plugin. It uniquely identifies one variable (or array of variables) over the lifetime of your plugin. You never hard code these values; you always get them from XPLMFindDataRef.

XPLMDataTypeID

This is an enumeration that defines the type of the data behind a data reference. This allows you to sanity check that the data type matches what you expect. But for the most part, you will know the type of data you are expecting from the online documentation.

Data types each take a bit field, so sets of data types may be formed.

xplmType_Unknown0 Data of a type the current XPLM doesn't do.
xplmType_Int1 A single 4-byte integer, native endian.
xplmType_Float2 A single 4-byte float, native endian.
xplmType_Double4 A single 8-byte double, native endian.
xplmType_FloatArray8 An array of 4-byte floats, native endian.
xplmType_IntArray16 An array of 4-byte integers, native endian.
xplmType_Data32 A variable block of data.

XPLMFindDataRef

XPLM_API XPLMDataRef          XPLMFindDataRef(
                                   const char *         inDataRefName);    
Given a c-style string that names the data ref, this routine looks up the actual opaque XPLMDataRef that you use to read and write the data. The string names for datarefs are published on the x-plane SDK web site.

This function returns NULL if the data ref cannot be found.

NOTE: this function is relatively expensive; save the XPLMDataRef this function returns for future use. Do not look up your data ref by string every time you need to read or write it.

XPLMCanWriteDataRef

XPLM_API int                  XPLMCanWriteDataRef(
                                   XPLMDataRef          inDataRef);    
Given a data ref, this routine returns true if you can successfully set the data, false otherwise. Some datarefs are read-only.

XPLMIsDataRefGood

XPLM_API int                  XPLMIsDataRefGood(
                                   XPLMDataRef          inDataRef);    
WARNING: This function is deprecated and should not be used. Datarefs are valid until plugins are reloaded or the sim quits. Plugins sharing datarefs should support these semantics by not unregistering datarefs during operation.

This function returns whether a data ref is still valid. If it returns false, you should refind the data ref from its original string. Calling an accessor function on a bad data ref will return a default value, typically 0 or 0-length data.

XPLMGetDataRefTypes

XPLM_API XPLMDataTypeID       XPLMGetDataRefTypes(
                                   XPLMDataRef          inDataRef);    
This routine returns the types of the data ref for accessor use. If a data ref is available in multiple data types, they will all be returned.

DATA ACCESSORS

These routines read and write the data references. For each supported data type there is a reader and a writer.

If the data ref is invalid or the plugin that provides it is disabled or there is a type mismatch, the functions that read data will return 0 as a default value or not modify the passed in memory. The plugins that write data will not write under these circumstances or if the data ref is read-only.

For array-style datarefs, you specify the number of items to read/write and the offset into the array; the actual number of items read or written is returned. This may be less to prevent an array-out-of-bounds error.

XPLMGetDatai

XPLM_API int                  XPLMGetDatai(
                                   XPLMDataRef          inDataRef);    
Read a single integer data ref.

XPLMSetDatai

XPLM_API void                 XPLMSetDatai(
                                   XPLMDataRef          inDataRef,    
                                   int                  inValue);    
Write a single integer data ref.

XPLMGetDataf

XPLM_API float                XPLMGetDataf(
                                   XPLMDataRef          inDataRef);    
Read a single precision floating point (float) data ref.

XPLMSetDataf

XPLM_API void                 XPLMSetDataf(
                                   XPLMDataRef          inDataRef,    
                                   float                inValue);    
Write a single precision floating point (float) data ref.

XPLMGetDatad

XPLM_API double               XPLMGetDatad(
                                   XPLMDataRef          inDataRef);    
Read a double precision floating point data ref.

XPLMSetDatad

XPLM_API void                 XPLMSetDatad(
                                   XPLMDataRef          inDataRef,    
                                   double               inValue);    
Write a double precision floating point data ref.

XPLMGetDatavi

XPLM_API long                 XPLMGetDatavi(
                                   XPLMDataRef          inDataRef,    
                                   int *                outValues,    /* Can be NULL */
                                   int                  inOffset,    
                                   int                  inMax);    
Read a part of an array of integers. Returns number of ints returned. You may pass NULL to just measure the number of values available. You may pass a non-negative offset to read only part of the array.

XPLMSetDatavi

XPLM_API void                 XPLMSetDatavi(
                                   XPLMDataRef          inDataRef,    
                                   int *                inValues,    
                                   int                  inoffset,    
                                   int                  inCount);    
Write part or all of an array of integers.

XPLMGetDatavf

XPLM_API long                 XPLMGetDatavf(
                                   XPLMDataRef          inDataRef,    
                                   float *              outValues,    /* Can be NULL */
                                   int                  inOffset,    
                                   int                  inMax);    
Reads part or all of an array of floats. Returns number of floats read. You may pass NULL to just measure the number of values available. You may pass a positive offset to read only part of the array.

XPLMSetDatavf

XPLM_API void                 XPLMSetDatavf(
                                   XPLMDataRef          inDataRef,    
                                   float *              inValues,    
                                   int                  inoffset,    
                                   int                  inCount);    
Writes part or all of an array of floats.

XPLMGetDatab

XPLM_API long                 XPLMGetDatab(
                                   XPLMDataRef          inDataRef,    
                                   void *               outValue,    /* Can be NULL */
                                   long                 inOffset,    
                                   long                 inMaxBytes);    
Reads part or all of an array of bytes. Returns length of data actually retreived. You may pass NULL to measure the amount of data available.

XPLMSetDatab

XPLM_API void                 XPLMSetDatab(
                                   XPLMDataRef          inDataRef,    
                                   void *               inValue,    
                                   long                 inOffset,    
                                   long                 inLength);    
Writes part or all of an array of bytes.

PUBLISHING YOUR PLUGINS DATA

These functions allow you to create data references that other plug-ins 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. NEWINE 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.

XPLMGetDatai_f

typedef int (* XPLMGetDatai_f)(
                                   void *               inRefcon);    
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 find global variables, etc.

Functions work the same as the accessors above. WARNING: when asked to get an array of floats or raw data, the buffer may be NULL. In this case, just return the actual size of the data or number of floats available. Also, if the buffer size is NULL, you should ignore the 'max size' param and return a count of all of your items or data size.

XPLMSetDatai_f

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

XPLMGetDataf_f

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

XPLMSetDataf_f

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

XPLMGetDatad_f

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

XPLMSetDatad_f

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

XPLMGetDatavi_f

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

XPLMSetDatavi_f

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

XPLMGetDatavf_f

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

XPLMSetDatavf_f

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

XPLMGetDatab_f

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

XPLMSetDatab_f

typedef void (* XPLMSetDatab_f)(
                                   void *               inRefcon,    
                                   void *               inValue,    
                                   int                  inOffset,    
                                   long                 inLength);    

XPLMRegisterDataAccessor

XPLM_API XPLMDataRef          XPLMRegisterDataAccessor(
                                   const char *         inDataName,    
                                   XPLMDataTypeID       inDataType,    
                                   int                  inIsWritable,    
                                   XPLMGetDatai_f       inReadInt,    
                                   XPLMSetDatai_f       inWriteInt,    
                                   XPLMGetDataf_f       inReadFloat,    
                                   XPLMSetDataf_f       inWriteFloat,    
                                   XPLMGetDatad_f       inReadDouble,    
                                   XPLMSetDatad_f       inWriteDouble,    
                                   XPLMGetDatavi_f      inReadIntArray,    
                                   XPLMSetDatavi_f      inWriteIntArray,    
                                   XPLMGetDatavf_f      inReadFloatArray,    
                                   XPLMSetDatavf_f      inWriteFloatArray,    
                                   XPLMGetDatab_f       inReadData,    
                                   XPLMSetDatab_f       inWriteData,    
                                   void *               inReadRefcon,    
                                   void *               inWriteRefcon);    
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 data ref for the new item of data created. You can use this data ref to unregister your data later or read or write from it.

XPLMUnregisterDataAccessor

XPLM_API void                 XPLMUnregisterDataAccessor(
                                   XPLMDataRef          inDataRef);    
Use this routine to unregister any data accessors you may have registered. You unregister a data ref by the XPLMDataRef you get back from registration. Once you unregister a data ref, your function pointer will not be called anymore.

For maximum compatibility, do not unregister your data accessors until final shutdown (when your XPluginStop routine is called). This allows other plugins to find your data reference once and use it for their entire time of operation.

SHARING DATA BETWEEN MULTIPLE PLUGINS

The data reference registration APIs from the previous section allow a plugin to publish data in a one-owner manner; the plugin that publishes the data reference owns the real memory that the data ref uses. This is satisfactory for most cases, but there are also cases where plugnis need to share actual data.

With a shared data reference, no one plugin owns the actual memory for the data reference; the plugin SDK allocates that for you. When the first plugin asks to 'share' the data, the memory is allocated. When the data is changed, every plugin that is sharing the data is notified.

Shared data references differ from the 'owned' data references from the previous section in a few ways:

- With shared data references, any plugin can create the data reference; with owned plugins one plugin must create the data reference and others subscribe. (This can be a problem if you don't know which set of plugins will be present).

- With shared data references, every plugin that is sharing the data is notified when the data is changed. With owned data references, only the one owner is notified when the data is changed.

- With shared data references, you cannot access the physical memory of the data reference; you must use the XPLMGet... and XPLMSet... APIs. With an owned data reference, the one owning data reference can manipulate the data reference's memory in any way it sees fit.

Shared data references solve two problems: if you need to have a data reference used by several plugins but do not know which plugins will be installed, or if all plugins sharing data need to be notified when that data is changed, use shared data references.

XPLMDataChanged_f

typedef void (* XPLMDataChanged_f)(
                                   void *               inRefcon);    
An XPLMDataChanged_f is a callback that the XPLM calls whenever any other plug-in modifies shared data. A refcon you provide is passed back to help identify which data is being changed. In response, you may want to call one of the XPLMGetDataxxx routines to find the new value of the data.

XPLMShareData

XPLM_API int                  XPLMShareData(
                                   const char *         inDataName,    
                                   XPLMDataTypeID       inDataType,    
                                   XPLMDataChanged_f    inNotificationFunc,    
                                   void *               inNotificationRefcon);    
This routine connects a plug-in to shared data, creating the shared data if necessary. inDataName is a standard path for the data ref, and inDataType specifies the type. This function will create the data if it does not exist. If the data already exists but the type does not match, an error is returned, so it is important that plug-in authors collaborate to establish public standards for shared data.

If a notificationFunc is passed in and is not NULL, that notification function will be called whenever the data is modified. The notification refcon will be passed to it. This allows your plug-in to know which shared data was changed if multiple shared data are handled by one callback, or if the plug-in does not use global variables.

A one is returned for successfully creating or finding the shared data; a zero if the data already exists but is of the wrong type.

XPLMUnshareData

XPLM_API int                  XPLMUnshareData(
                                   const char *         inDataName,    
                                   XPLMDataTypeID       inDataType,    
                                   XPLMDataChanged_f    inNotificationFunc,    
                                   void *               inNotificationRefcon);    
This routine removes your notification function for shared data. Call it when done with the data to stop receiving change notifications. Arguments must match XPLMShareData. The actual memory will not necessarily be freed, since other plug-ins could be using it.

Copyright 2005 Sandy Barbour and Ben Supnik

All rights reserved. See license.txt for usage.

X-Plane SDK Version: 1.0.2