XPLMDataAccess
Read and write X-Plane datarefs — the primary way to exchange data with the simulator. Supports integers, floats, doubles, and arrays of each.
Enumerations
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; it is legal to have a single dataref be more than one type of data. Whe this happens, you can pick any matching get/set API.
| Constant | Value | Description |
|---|---|---|
xplmType_Unknown |
0 |
Data of a type the current XPLM doesn't do. |
xplmType_Int |
1 |
A single 4-byte integer, native endian. |
xplmType_Float |
2 |
A single 4-byte float, native endian. |
xplmType_Double |
4 |
A single 8-byte double, native endian. |
xplmType_FloatArray |
8 |
An array of 4-byte floats, native endian. |
xplmType_IntArray |
16 |
An array of 4-byte integers, native endian. |
xplmType_Data |
32 |
A variable block of data. |
Functions
XLuaCountDataRefs()
Returns: integer
Returns the total number of datarefs that have been registered in X-Plane.
XLuaGetDataRefsByIndex(offset, count)
Returns: {k} with keys: dataRefs
Given an offset and count, this function will return an array of XPLMDataRefs in that range. The offset/count idiom is useful for things like pagination.
| Argument | Type | Notes |
|---|---|---|
offset |
integer |
|
count |
integer |
Output table keys:
| Key | Type |
|---|---|
dataRefs |
{ i } |
XLuaGetDataRefInfo(dataRef)
Returns: {k} with keys: info
Give a data ref, this routine returns a populated struct containing the available information about the dataref.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
Output table keys:
| Key | Type |
|---|---|
info |
{k} |
XLuaFindDataRef(dataRefName)
Returns: XPLMDataRef
Given a C-style string that names the dataref, 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 dataref cannot be found. NOTE: this function is relatively expensive; save the XPLMDataRef this function returns for future use. Do not look up your dataref by string every time you need to read or write it.
| Argument | Type | Notes |
|---|---|---|
dataRefName |
string |
XLuaCanWriteDataRef(dataRef)
Returns: boolean
Given a dataref, this routine returns true if you can successfully set the data, false otherwise. Some datarefs are read-only. NOTE: even if a dataref is marked writable, it may not act writable. This can happen for datarefs that X-Plane writes to on every frame of simulation. In some cases, the dataref is writable but you have to set a separate "override" dataref to 1 to stop X-Plane from writing it.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaIsDataRefGood(dataRef)
Returns: boolean
This function returns true if the passed in handle is a valid dataref that is not orphaned. Note: there is normally no need to call this function; datarefs returned by XPLMFindDataRef remain valid (but possibly orphaned) unless there is a complete plugin reload (in which case your plugin is reloaded anyway). Orphaned datarefs can be safely read and return 0. Therefore you never need to call XPLMIsDataRefGood to 'check' the safety of a dataref. (XPLMIsDataRefGood performs some slow checking of the handle validity, so it has a performance cost.)
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaGetDataRefTypes(dataRef)
Returns: integer
This routine returns the types of the dataref for accessor use. If a dataref is available in multiple data types, the bit-wise OR of these types will be returned.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaGetDatai(dataRef)
Returns: integer
Read an integer dataref and return its value. The return value is the dataref value or 0 if the dataref is NULL or the plugin is disabled.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaSetDatai(dataRef, value)
Returns: (returns nothing)
Write a new value to an integer dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
value |
integer |
XLuaGetDataf(dataRef)
Returns: number
Read a single precision floating point dataref and return its value. The return value is the dataref value or 0.0 if the dataref is NULL or the plugin is disabled.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaSetDataf(dataRef, value)
Returns: (returns nothing)
Write a new value to a single precision floating point dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
value |
number |
XLuaGetDatad(dataRef)
Returns: number
Read a double precision floating point dataref and return its value. The return value is the dataref value or 0.0 if the dataref is NULL or the plugin is disabled.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
XLuaSetDatad(dataRef, value)
Returns: (returns nothing)
Write a new value to a double precision floating point dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
value |
number |
XLuaGetDatavi(dataRef, offset, max)
Returns: integer, {k} with keys: values
Read a part of an integer array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax. If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
offset |
integer |
|
max |
integer |
Output table keys:
| Key | Type |
|---|---|
values |
{ i } |
XLuaSetDatavi(dataRef, { i }, inoffset, count)
Returns: (returns nothing)
Write part or all of an integer array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write past the end of the dataref array, then fewer values are written. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
values |
{ i } |
Array table — { val1, val2, ... } |
inoffset |
integer |
|
count |
integer |
XLuaGetDatavf(dataRef, offset, max)
Returns: integer, {k} with keys: values
Read a part of a single precision floating point array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax. If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
offset |
integer |
|
max |
integer |
Output table keys:
| Key | Type |
|---|---|
values |
{ i } |
XLuaSetDatavf(dataRef, { i }, inoffset, count)
Returns: (returns nothing)
Write part or all of a single precision floating point array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write past the end of the dataref array, then fewer values are written. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
values |
{ i } |
Array table — { val1, val2, ... } |
inoffset |
integer |
|
count |
integer |
XLuaGetDatab(dataRef, offset, maxBytes)
Returns: integer, {k} with keys: value
Read a part of a byte array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax. If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
offset |
integer |
|
maxBytes |
integer |
Output table keys:
| Key | Type |
|---|---|
value |
{ i } |
XLuaSetDatab(dataRef, { i }, offset, length)
Returns: (returns nothing)
Write part or all of a byte array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write "off the end" of the dataref array, then fewer values are written. Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
value |
{ i } |
Array table — { val1, val2, ... } |
offset |
integer |
|
length |
integer |
XLuaRegisterDataAccessor(dataName, dataType, isWritable, callback, callback, callback, callback, callback, callback, callback, callback, callback, callback, callback, callback, refcon, refcon)
Returns: XPLMDataRef
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.
| Argument | Type | Notes |
|---|---|---|
dataName |
string |
|
dataType |
XPLMDataTypeID |
Enum — use a constant from XPLMDataTypeID |
isWritable |
boolean |
|
readInt |
function |
Callback — a Lua function you define |
writeInt |
function |
Callback — a Lua function you define |
readFloat |
function |
Callback — a Lua function you define |
writeFloat |
function |
Callback — a Lua function you define |
readDouble |
function |
Callback — a Lua function you define |
writeDouble |
function |
Callback — a Lua function you define |
readIntArray |
function |
Callback — a Lua function you define |
writeIntArray |
function |
Callback — a Lua function you define |
readFloatArray |
function |
Callback — a Lua function you define |
writeFloatArray |
function |
Callback — a Lua function you define |
readData |
function |
Callback — a Lua function you define |
writeData |
function |
Callback — a Lua function you define |
readRefcon |
any |
Any Lua value; passed through to your callback unchanged |
writeRefcon |
any |
Any Lua value; passed through to your callback unchanged |
XLuaUnregisterDataAccessor(dataRef)
Returns: (returns nothing)
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.
| Argument | Type | Notes |
|---|---|---|
dataRef |
XPLMDataRef |
Enum — use a constant from XPLMDataRef |
Examples
Examples coming soon.