|
libacfutils
A general purpose library of utility functions designed to make it easier to develop addons for the X-Plane flight simulator.
|
#include <dr.h>
Data Fields | |
| bool | writable |
| Defines whether this dataref will be writable or read-only. | |
| size_t | count |
| size_t | stride |
| void(* | read_cb )(dr_t *dr, void *value_out) |
| void(* | write_cb )(dr_t *dr, void *value_in) |
| bool_t(* | read_scalar_cb )(dr_t *dr, void *value_out) |
| bool_t(* | write_scalar_cb )(dr_t *dr, void *value_in) |
| int(* | read_array_cb )(dr_t *dr, void *values_out, int off, int cnt) |
| void(* | write_array_cb )(dr_t *dr, void *values_in, int off, int cnt) |
| void * | cb_userinfo |
Specifies additional configuration parameters for a dataref.
This data structure is used by the dr_create_*_cfg() functions to specify additional configurable features of owned datarefs. See the description of the individual fields for their purpose. The structure is designed in such a way that you can simply ignore the fields you don't need and thus leave them at 0 or NULL (which is valid). Example of using this configuration structure in code:
| void* cb_userinfo |
Optional user info field that you can set to whatever you want. Use it to stash any extra information you need in your callbacks and read it using dr_get_cb_userinfo().
| size_t count |
| int(* read_array_cb) (dr_t *dr, void *values_out, int off, int cnt) |
| void(* read_cb) (dr_t *dr, void *value_out) |
For scalar datarefs we expose, setting this field to a callback will make that callback be called after a read attempt to the dataref is made. The dr machinery first reads the dataref from the memory location in value and then calls read_cb here (if not NULL), with a copy of the dataref value in value_out, allowing your callback to modify it before being returned to the initiator of the dataref read operation. The type of data in value_out will be the same as that which you used to create the dataref (e.g. if you created the dataref using dr_create_i, the value pointed to by the second argument will be an int). Please note that modifying the value* in the callback's second argument won't alter anything at the dataref's value location.
IMPORTANT: you cannot use this function to substitute the preceding dataref value pointer read. You cannot pass NULL in dr_create_* for the memory location and expect to simply synthesize the value in this callback - this will result in a NULL pointer dereference and assertion failure. To synthesize dataref values on the fly, use the read_scalar_cb, and read_array_cb callbacks.
| bool_t(* read_scalar_cb) (dr_t *dr, void *value_out) |
If not NULL, this callback gets called before a scalar read is attempted from the dataref's memory location. The value_out argument will point to a new memory location to which you can write a new value to be returned to the originator of the dataref read. The size of the value must match the size of the type originally used to create the dataref (e.g. int if you created the dataref using dr_create_i).
If you wish to synthesize a new value, return B_TRUE from this callback. This bypasses any attempt to read the dataref's memory location directly and instead just returns the value you've written to value_out. Otherwise, if you return B_FALSE, the dr machinery will read the memory pointed to by the value field in the dataref.
| size_t stride |
Used by array datarefs to define the distance between successive elements of the array in memory. If left at zero, the default is to use the size of the native data type (e.g. sizeof(int) for integer datarefs). You can set this to a non-zero value in case your data is contained in an array of data structures, which themselves contain multiple fields. In that case, the stride is used to skip to the correct offset in the array. For example:
| bool writable |
| void(* write_array_cb) (dr_t *dr, void *values_in, int off, int cnt) |
| void(* write_cb) (dr_t *dr, void *value_in) |
| bool_t(* write_scalar_cb) (dr_t *dr, void *value_in) |
Same as read_scalar_cb, but instead is called before any attempt is made to write to the dataref's value memory location. The value_in argument points to the value being attempted to be written. If you return B_TRUE from this callback, the write is stopped and no actual dereference of the value pointer in this dataref is performed. Otherwise, the value being written is written as normal. You can still use this callback to alter the value being written though.
1.9.8