#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include <XPLMDataAccess.h>
#include "helpers.h"
#include "log.h"
#include "types.h"

Include dependency graph for dr.h:

Data Structures
struct	dr_t

struct	dr_cfg_t

Macros
#define	DR_MAX_NAME_LEN 128

#define	DR_EXT_DEPRECATED DEPRECATED_ATTR

#define	fdr_find(dr, ...)

#define	DR_DEBUG(__varstr) log_basename(__FILE__), __LINE__, __varstr

#define	DR_DEBUG_VARS const char filename, int line, const char varname

#define	dr_geti(__dr) dr_geti_impl((__dr), DR_DEBUG(#__dr))

#define	dr_seti(__dr, __i) dr_seti_impl((__dr), DR_DEBUG(#__dr), (__i))

#define	dr_getf(__dr) dr_getf_impl((__dr), DR_DEBUG(#__dr))

#define	dr_setf(__dr, __f) dr_setf_impl((__dr), DR_DEBUG(#__dr), (__f))

#define	dr_getf_prot(__dr) dr_getf_prot_impl((__dr), DR_DEBUG(#__dr))

#define	dr_getvi(__dr, __i, __off, __num) dr_getvi_impl((__dr), DR_DEBUG(#__dr), (__i), (__off), (__num))

#define	dr_setvi(__dr, __i, __off, __num) dr_setvi_impl((__dr), DR_DEBUG(#__dr), (__i), (__off), (__num))

#define	dr_getvf(__dr, __df, __off, __num) dr_getvf_impl((__dr), DR_DEBUG(#__dr), (__df), (__off), (__num))

#define	dr_setvf(__dr, __df, __off, __num) dr_setvf_impl((__dr), DR_DEBUG(#__dr), (__df), (__off), (__num))

#define	dr_getvf32(__dr, __ff, __off, __num) dr_getvf32_impl((__dr), DR_DEBUG(#__dr), (__ff), (__off), (__num))

#define	dr_setvf32(__dr, __ff, __off, __num) dr_setvf32_impl((__dr), DR_DEBUG(#__dr), (__ff), (__off), (__num))

#define	dr_gets(__dr, __str, __cap) dr_gets_impl((__dr), DR_DEBUG(#__dr), (__str), (__cap))

#define	dr_sets(__dr, __str) dr_sets_impl((__dr), DR_DEBUG(#__dr), (__str))

#define	dr_getbytes(__dr, __data, __off, __num) dr_getbytes_impl((__dr), DR_DEBUG(#__dr), (__data), (__off), (__num))

#define	dr_setbytes(__dr, __data, __off, __num) dr_setbytes_impl((__dr), DR_DEBUG(#__dr), (__data), (__off), (__num))

Functions
bool_t	dr_find (dr_t dr, const char fmt,...)

bool_t	dr_writable (dr_t *dr)

int	dr_geti_impl (const dr_t dr, const char filename, int line, const char *varname)

void	dr_seti_impl (const dr_t dr, const char filename, int line, const char *varname, int i)

double	dr_getf_impl (const dr_t dr, const char filename, int line, const char *varname)

void	dr_setf_impl (const dr_t dr, const char filename, int line, const char *varname, double f)

static double	dr_getf_prot_impl (const dr_t dr, const char filename, int line, const char *varname)

int	dr_getvi_impl (const dr_t dr, const char filename, int line, const char varname, int i, unsigned off, unsigned num)

void	dr_setvi_impl (const dr_t dr, const char filename, int line, const char varname, int i, unsigned off, unsigned num)

int	dr_getvf_impl (const dr_t dr, const char filename, int line, const char varname, double df, unsigned off, unsigned num)

void	dr_setvf_impl (const dr_t dr, const char filename, int line, const char varname, double df, unsigned off, unsigned num)

int	dr_getvf32_impl (const dr_t dr, const char filename, int line, const char varname, float ff, unsigned off, unsigned num)

void	dr_setvf32_impl (const dr_t dr, const char filename, int line, const char varname, float ff, unsigned off, unsigned num)

int	dr_gets_impl (const dr_t dr, const char filename, int line, const char varname, char str, size_t cap)

void	dr_sets_impl (const dr_t dr, const char filename, int line, const char varname, char str)

int	dr_getbytes_impl (const dr_t dr, const char filename, int line, const char varname, void data, unsigned off, unsigned num)

void	dr_setbytes_impl (const dr_t dr, const char filename, int line, const char varname, void data, unsigned off, unsigned num)

void	dr_create_i (dr_t dr, int value, bool_t writable, const char *fmt,...)

void	dr_create_i_cfg (dr_t dr, int value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_f (dr_t dr, float value, bool_t writable, const char *fmt,...)

void	dr_create_f_cfg (dr_t dr, float value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_f64 (dr_t dr, double value, bool_t writable, const char *fmt,...)

void	dr_create_f64_cfg (dr_t dr, double value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vi (dr_t dr, int value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vi_cfg (dr_t dr, int value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vf (dr_t dr, float value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vf_cfg (dr_t dr, float value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vf64 (dr_t dr, double value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vf64_cfg (dr_t dr, double value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vi_autoscalar (dr_t dr, int value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vi_autoscalar_cfg (dr_t dr, int value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vf_autoscalar (dr_t dr, float value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vf_autoscalar_cfg (dr_t dr, float value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_vf64_autoscalar (dr_t dr, double value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_vf64_autoscalar_cfg (dr_t dr, double value, dr_cfg_t cfg, const char *fmt,...)

void	dr_create_b (dr_t dr, void value, size_t n, bool_t writable, const char *fmt,...)

void	dr_create_b_cfg (dr_t dr, void value, dr_cfg_t cfg, const char *fmt,...)

void	dr_array_set_stride (dr_t *dr, size_t stride)

void	dr_delete (dr_t *dr)

void *	dr_get_cb_userinfo (const dr_t *dr)

Detailed Description

This file provides a facility for more conveniently interacting with X-Plane's dataref system. Rather than having to write accessors for every piece of data you wish to expose, this subsystem takes care of most of the heavy lifting, while providing a much neater and easier-to-use interface.

If you want to expose your internal data as datarefs, you will register the datarefs using the dr_create_* family of functions. Please note that the returned dr_t object doesn't actually contain the data. Instead, you pass the dr_create_* functions a pointer to your data, and they simply reference it.

To access foreign datarefs, use either dr_find() or fdr_find(). The returned dr_t object can then be passed to the various dr_get* and dr_set* family of macros to access the data exposed through those datarefs. The macros take care of automatically converting types as appropriate, so you don't have to worry about always matching the data type of the dataref. The only exception to these are the dr_gets(), dr_sets(), dr_getbytes() and dr_setbytes() macros, which must only ever be used with datarefs of type xplmType_Data.

Definition in file dr.h.

Macro Definition Documentation

◆ DR_DEBUG

#define DR_DEBUG ( __varstr ) log_basename(__FILE__), __LINE__, __varstr

Definition at line 332 of file dr.h.

◆ DR_DEBUG_VARS

#define DR_DEBUG_VARS const char *filename, int line, const char *varname

Definition at line 333 of file dr.h.

◆ DR_EXT_DEPRECATED

#define DR_EXT_DEPRECATED DEPRECATED_ATTR

Definition at line 66 of file dr.h.

◆ dr_getbytes

#define dr_getbytes	(	__dr,
		__data,
		__off,
		__num
	)	dr_getbytes_impl((__dr), DR_DEBUG(#__dr), (__data), (__off), (__num))

Reads a byte array dataref. This function cannot be invoked on anything other than a dataref that is of type xplmType_Data. This function doesn't support automatic type conversion from different dataref types.

Parameters

__dr	The dataref to be read. Must be a `dr_t *` obtained using dr_find() and be of type `xplmType_Data`.
__data	A `void *` buffer to hold the data to be read. This must be allocated by the caller to have sufficient capacity to hold at least `__num` bytes.
__off	Byte offset in the dataref (NOT the `__data` buffer) from where the read should be performed.
__num	Number of bytes to read in the dataref at offset `__off`.

Returns: The number of bytes actually read (which may be less than __num). By convention in the X-Plane SDK, if you pass NULL for the __data pointer and 0 for both __off and __num, this will make the dr_getbytes() macro return the actual number of bytes available to be read in the dataref.

Example of how to read the entire contents of a dataref of unknown length:

int len = dr_getbytes(dataref, NULL, 0, 0);
uint8_t *buf = safe_malloc(len);
dr_getbytes(dataref, buf, 0, len);

Definition at line 562 of file dr.h.

◆ dr_getf

#define dr_getf ( __dr ) dr_getf_impl((__dr), DR_DEBUG(#__dr))

Same as dr_geti(), but for double floating point data.

Please note that if the dataref contains a NAN value, this macro will return it unaltered.

Definition at line 378 of file dr.h.

◆ dr_getf_prot

#define dr_getf_prot ( __dr ) dr_getf_prot_impl((__dr), DR_DEBUG(#__dr))

Extra error-checking version of dr_getf(). If the read value is a NAN, this trips an assertion failure. This helps protect critical sections of code from being fed unexpected garbage.

Definition at line 396 of file dr.h.

◆ dr_geti

#define dr_geti ( __dr ) dr_geti_impl((__dr), DR_DEBUG(#__dr))

Reads an integer dataref. If the dataref is not an integer, this function automatically converts the types as necessary, so you can read a float dataref as an int without having to worry about type conversions.

This function can also work with array datarefs. If the dataref is an array, this function simply reads the array's first element.

Parameters

__dr	The dataref to be read. Must be a `dr_t *` obtained using dr_find().

Returns: The integer value of the dataref, converting between types as necessary.

Definition at line 348 of file dr.h.

◆ dr_gets

#define dr_gets	(	__dr,
		__str,
		__cap
	)	dr_gets_impl((__dr), DR_DEBUG(#__dr), (__str), (__cap))

Reads a string dataref. String datarefs are byte arrays that contain a NUL-terminated value. This function cannot be invoked on anything other than a dataref that is of type xplmType_Data. This function doesn't support automatic type conversion from different dataref types.

Parameters

__dr	The dataref to be read. Must be a `dr_t *` obtained using dr_find() and be of type `xplmType_Data`.
__str	A `char *` buffer to hold the string to be read. This must be allocated by the caller to have sufficient capacity to hold the returned string. If the buffer doesn't have sufficient capacity, the string is truncated and is guaranteed to always be NUL terminated.
__cap	The capacity of the buffer in `__str` in bytes. The function will never write more than `__cap` bytes, including the terminating NUL character.

Returns: The number of bytes required to hold the returned string, including the terminating NUL byte.

Example of how to read a string of unknown length:

int len = dr_gets(dataref, NULL, 0);
char *str = safe_malloc(len);
dr_gets(dataref, str, len);

Definition at line 511 of file dr.h.

◆ dr_getvf

#define dr_getvf	(	__dr,
		__df,
		__off,
		__num
	)	dr_getvf_impl((__dr), DR_DEBUG(#__dr), (__df), (__off), (__num))

Same as dr_getvi(), but expects a double-precision floating point array in __df instead.

Definition at line 455 of file dr.h.

◆ dr_getvf32

#define dr_getvf32	(	__dr,
		__ff,
		__off,
		__num
	)	dr_getvf32_impl((__dr), DR_DEBUG(#__dr), (__ff), (__off), (__num))

Same as dr_getvi(), but expects a single-precision floating point array in __ff instead.

Definition at line 473 of file dr.h.

◆ dr_getvi

#define dr_getvi	(	__dr,
		__i,
		__off,
		__num
	)	dr_getvi_impl((__dr), DR_DEBUG(#__dr), (__i), (__off), (__num))

Reads a 32-bit integer array dataref. If the dataref is an array of floats, this function automatically converts the float data to ints by truncation.

Parameters

__dr	The dataref to be read. Must be a `dr_t *` obtained using dr_find().
__i	Pointer to an array of `int`s that's supposed to be filled with the read integer data. Must be large enough to hold all the data that was requested to be read.
__off	Offset in the dataref to start the read at. (Caution: NOT an offset into the `__i` array above!)
__num	Number of items in the dataref to read, starting at offset `__off`.

Returns: The number of elements actually read from the dataref. This can be less than __num, if the dataref was shorter than anticipated.; By convention in the X-Plane SDK, you can pass NULL for the __i pointer and 0 for both __off and __num to obtain the actual length of the array.

Definition at line 426 of file dr.h.

◆ DR_MAX_NAME_LEN

#define DR_MAX_NAME_LEN 128

Definition at line 59 of file dr.h.

◆ dr_setbytes

#define dr_setbytes	(	__dr,
		__data,
		__off,
		__num
	)	dr_setbytes_impl((__dr), DR_DEBUG(#__dr), (__data), (__off), (__num))

Writes a byte array dataref. This function cannot be invoked on anything other than a dataref that is of type xplmType_Data. This function doesn't support automatic type conversion from different dataref types.

Parameters

__dr	The dataref to be written. Must be a `dr_t *` obtained using dr_find(), be of type `xplmType_Data` and be writable (see dr_writable()).
__data	A byte buffer containing the data to be written and must contain at least `__num` bytes.
__off	The byte offset into the dataref (NOT the `__data` buffer) where the data buffer should start to be written.
__num	Number of bytes to be written in `__data`.

Definition at line 580 of file dr.h.

◆ dr_setf

#define dr_setf	(	__dr,
		__f
	)	dr_setf_impl((__dr), DR_DEBUG(#__dr), (__f))

Same as dr_seti(), but for double floating point data.

Please note that attempting to write a NAN value using dr_setf() will result in an assertion failure. This is a deliberate check to avoid polluting X-Plane's dataref system with bad data.

Definition at line 388 of file dr.h.

◆ dr_seti

#define dr_seti	(	__dr,
		__i
	)	dr_seti_impl((__dr), DR_DEBUG(#__dr), (__i))

Writes an integer dataref. If the dataref is not an integer, this function automatically converts the types as necessary, so you can write to a float dataref as an int without having to worry about type conversions.

This function can also work with array datarefs. If the dataref is an array, theis function simply writes the array's first element.

CAUTION: do NOT write to a read-only dataref. Attempting to do so will trip an assertion failure.

Parameters

__dr	The dataref to be written. Must be a `dr_t *` obtained using dr_find() and be writable (see dr_writable()).
__i	The integer value to be written to the dataref.

See also: dr_writable()

Definition at line 369 of file dr.h.

◆ dr_sets

#define dr_sets	(	__dr,
		__str
	)	dr_sets_impl((__dr), DR_DEBUG(#__dr), (__str))

Writes a string dataref. String datarefs are byte arrays that contain a NUL-terminated value. This function cannot be invoked on anything other than a dataref that is of type xplmType_Data. This function doesn't support automatic type conversion from different dataref types.

Parameters

__dr	The dataref to be written. Must be a `dr_t *` obtained using dr_find(), be of type `xplmType_Data` and be writable (see dr_writable()).
__str	A NUL-terminated `char *` string to be written. The length of the string is automatically obtained using strlen().

Definition at line 527 of file dr.h.

◆ dr_setvf

#define dr_setvf	(	__dr,
		__df,
		__off,
		__num
	)	dr_setvf_impl((__dr), DR_DEBUG(#__dr), (__df), (__off), (__num))

Same as dr_setvi(), but expects a double-precision floating point array in __df instead.

Definition at line 464 of file dr.h.

◆ dr_setvf32

#define dr_setvf32	(	__dr,
		__ff,
		__off,
		__num
	)	dr_setvf32_impl((__dr), DR_DEBUG(#__dr), (__ff), (__off), (__num))

Same as dr_setvi(), but expects a single-precision floating point array in __ff instead.

Definition at line 482 of file dr.h.

◆ dr_setvi

#define dr_setvi	(	__dr,
		__i,
		__off,
		__num
	)	dr_setvi_impl((__dr), DR_DEBUG(#__dr), (__i), (__off), (__num))

Writes a 32-bit integer array dataref. If the dataref is an array of floats, this function automatically converts the integer data to floats by casting.

Parameters

__dr	The dataref to be written. Must be a `dr_t *` obtained using dr_find() and be writable (see dr_writable()).
__i	Pointer to an array of `int`s that's supposed to be written to the dataref. Must contain `__num` integers.
__off	Offset in the dataref to start the write at. (Caution: NOT an offset into the `__i` array above!)
__num	Number of items in `__i` to be written to the dataref at offset `__off`.

Returns: The number of elements actually written to the dataref. This can be less than __num, if the dataref was shorter than anticipated.

Definition at line 446 of file dr.h.

◆ fdr_find

#define fdr_find	(	dr,
		...
	)

Value:

    do { \
        if (!dr_find(dr, __VA_ARGS__)) { \
            char drname[DR_MAX_NAME_LEN]; \
            snprintf(drname, sizeof (drname), __VA_ARGS__); \
            VERIFY_MSG(0, "dataref \"%s\" not found", drname); \
        } \
    } while (0)

Same as dr_find(), but does a "forcible" lookup. That means, if the dataref doesn't exist, instead of returning B_FALSE, this macro causes a hard assertion failure. Use this to look up datarefs that you absolutely require to exist (such as those that are part of X-Plane itself).

Definition at line 318 of file dr.h.

Function Documentation

◆ dr_array_set_stride()

void dr_array_set_stride	(	dr_t *	dr,
		size_t	stride
	)

Deprecated:

This function is deprecated. Use dr_create_*_cfg() functions which specify the stride in the configuration structure argument.

See also: dr_cfg_t

For array datarefs you create, you can specify a data access stride value. if set to non-zero after creation, the built-in array read functions of the dr.h machinery will use the stride calculate the actual offset in the dataref's data buffer for elements past the [0] index. If set to 0 (the default), the stride is automatically determined from the type of the dataref. You can use this to expose array data that is strided in a bigger struct, for example as follows:

struct my_struct {
    int   foo;
    float bar;
};
struct my_struct baz[8];
 
dr_t baz_dr;
dr_create_vi(&baz_dr, &baz[0].foo, ARRAY_NUM_ELEM(baz),
    B_FALSE, "my/dataref/name");
dr_array_set_stride(&baz_dr, sizeof (struct my_struct));

Definition at line 626 of file dr.c.

◆ dr_create_b()

void dr_create_b	(	dr_t *	dr,
		void *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_vi(), but creates an arbitrary byte array dataref and takes an anonymous void * buffer pointer argument.

Definition at line 919 of file dr.c.

◆ dr_create_b_cfg()

void dr_create_b_cfg	(	dr_t *	dr,
		void *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_b(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 932 of file dr.c.

◆ dr_create_f()

void dr_create_f	(	dr_t *	dr,
		float *	value,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_i(), but creates a single-precision floating point dataref and takes a float * data pointer argument.

Definition at line 718 of file dr.c.

◆ dr_create_f64()

void dr_create_f64	(	dr_t *	dr,
		double *	value,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_i(), but creates a double-precision floating point dataref and takes a double * data pointer argument.

Definition at line 745 of file dr.c.

◆ dr_create_f64_cfg()

void dr_create_f64_cfg	(	dr_t *	dr,
		double *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_f64(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 757 of file dr.c.

◆ dr_create_f_cfg()

void dr_create_f_cfg	(	dr_t *	dr,
		float *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_f(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 730 of file dr.c.

◆ dr_create_i()

void dr_create_i	(	dr_t *	dr,
		int *	value,
		bool_t	writable,
		const char *	fmt,
			...
	)

Creates an integer dataref. The data is held by the caller, and the dataref simply receives a reference to the data to be exposed. The dr.h machinery takes care of registering all the appropriate data accessors, as well as handling type conversions as appropriate. After initialization, may want to further customize the dr_t reference by installing a read or write callback. See dr_t.

This function automatically registers the created dataref with DataRefEditor (and DataRefTool, or any 3rd party dataref monitoring plugin, which responds to dataref registration interplugin messages). Thus you do not need to perform the registration yourself.

Parameters

dr	A pointer to an unused dr_t structure, which will be initialized to contain the information of the dataref.
value	A pointer to the integer value to be read (and possibly written). If you plan on installing your own `read_scalar_cb` and/or `write_scalar_cb` callbacks, you may pass `NULL` here and manipulate the data entirely dynamically. However, for the vast majority of datarefs, a valid pointer here must be provided and the memory this points to must remain allocated and available throghout the entire existence of the dataref.
writable	Flag designating the dataref registration as being either writable or read-only.
fmt	A printf-style format string, from which the name of the dataref will be constructed. The remaining extra variadic arguments are used for this printf-style string construction.

Definition at line 691 of file dr.c.

◆ dr_create_i_cfg()

void dr_create_i_cfg	(	dr_t *	dr,
		int *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_i(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 703 of file dr.c.

◆ dr_create_vf()

void dr_create_vf	(	dr_t *	dr,
		float *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_vi(), but creates a single-precision floating point array dataref and takes a float * array pointer argument.

Definition at line 793 of file dr.c.

◆ dr_create_vf64()

void dr_create_vf64	(	dr_t *	dr,
		double *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_vi(), but creates a double-precision floating point array dataref and takes a double * array pointer argument.

Please note that X-Plane's SDK doesn't natively support a double-precision floating point array dataref. Instead, the dataref will be registered as a single-precision floating point array and type conversions will be performed automatically on read and write. The read_array_cb and write_array_cb will still be treated as dealing with double-precision floating point values, but the values will be type-cast right at the "edge" of the interface to X-Plane.

Definition at line 817 of file dr.c.

◆ dr_create_vf64_autoscalar()

void dr_create_vf64_autoscalar	(	dr_t *	dr,
		double *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_vi_autoscalar(), but creates a double-precision floating point combo scalar/array dataref and takes a double * array pointer argument. Same type conversion caveats apply as in the case of dr_create_vf64(), when the dataref is being accessed as an array.

Definition at line 893 of file dr.c.

◆ dr_create_vf64_autoscalar_cfg()

void dr_create_vf64_autoscalar_cfg	(	dr_t *	dr,
		double *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vf64_autoscalar(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 906 of file dr.c.

◆ dr_create_vf64_cfg()

void dr_create_vf64_cfg	(	dr_t *	dr,
		double *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vf64(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 830 of file dr.c.

◆ dr_create_vf_autoscalar()

void dr_create_vf_autoscalar	(	dr_t *	dr,
		float *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Same as dr_create_vi_autoscalar(), but creates a single-precision floating point combo scalar/array dataref and takes a float * array pointer argument.

Definition at line 867 of file dr.c.

◆ dr_create_vf_autoscalar_cfg()

void dr_create_vf_autoscalar_cfg	(	dr_t *	dr,
		float *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vf_autoscalar(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 880 of file dr.c.

◆ dr_create_vf_cfg()

void dr_create_vf_cfg	(	dr_t *	dr,
		float *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vf(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 806 of file dr.c.

◆ dr_create_vi()

void dr_create_vi	(	dr_t *	dr,
		int *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Creates an integer array ("vi" = vector of int's) dataref. In general this behaves the same as dr_create_i(), except if you wanted to dynamically override the data being read/written through this dataref, you would set the read_array_cb and write_array_cb callback fields.

Parameters

dr	A pointer to an unused dr_t structure, which will be initialized to contain the information of the dataref.
value	A pointer to the array of integer values to be read (and possibly written). If you plan on installing your own `read_array_cb` and/or `write_array_cb` callbacks, you may pass `NULL` here and manipulate the data entirely dynamically. However, for the vast majority of datarefs, a valid pointer here must be provided and the memory this points to must remain allocated and available throghout the entire existence of the dataref.
n	The number of elements in the `value` array above.
writable	Flag designating the dataref registration as being either writable or read-only.
fmt	A printf-style format string, from which the name of the dataref will be constructed. The remaining extra variadic arguments are used for this printf-style string construction.

Definition at line 768 of file dr.c.

◆ dr_create_vi_autoscalar()

void dr_create_vi_autoscalar	(	dr_t *	dr,
		int *	value,
		size_t	n,
		bool_t	writable,
		const char *	fmt,
			...
	)

Similar to dr_create_vi(), but creates a combo dataref that holds both a single scalar integer value, as well as an array of integers. Internally the dataref is registered as a bitwise-OR of both xplmType_Int and xplmType_IntArray, The dataref has read (and write, if writable is set to B_TRUE) handlers implemented for both scalar and array data manipulation. You may also install your own custom callback handlers for read_scalar_cb, write_scalar_cb, read_array_cb and write_array_cb.

This type of dataref is useful for cases where you want to provide both the ability to treat the data as an array, while still providing meaningful results when the dataref is accessed as a scalar (certain lighting control data accesses in X-Plane require this).

Definition at line 841 of file dr.c.

◆ dr_create_vi_autoscalar_cfg()

void dr_create_vi_autoscalar_cfg	(	dr_t *	dr,
		int *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vi_autoscalar(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 854 of file dr.c.

◆ dr_create_vi_cfg()

void dr_create_vi_cfg	(	dr_t *	dr,
		int *	value,
		dr_cfg_t	cfg,
		const char *	fmt,
			...
	)

Same as dr_create_vi(), but provides a configuration structure to specify additional parameters and custom callbacks.

See also: dr_cfg_t

Definition at line 781 of file dr.c.

◆ dr_delete()

void dr_delete ( dr_t * dr )

Destroys a dataref previously created using one of the dr_create_* functions. You MUST destroy every dataref you create prior to your plugin being unloaded.

libacfutils ships with automated macros that help automate the dataref destruction process on plugin unload. See dr_cmd_reg.h for more information.

Definition at line 946 of file dr.c.

◆ dr_find()

bool_t dr_find	(	dr_t *	dr,
		const char *	fmt,
			...
	)

Attempts to find a dataref in the X-Plane dataref system and store a handle to it in ‘dr’. The dataref must exist (have been created) at the time of this call. There is no support for late (lazy) resolving of datarefs.

Parameters

dr	Mandatory return-parameter, which will be filled with an initialized dr_t object that can be used to read the dataref (and write to it, if the dataref is writable).
fmt	A printf-style format string that will be used to construct the name of the dataref to looked up. The remainder of the variadic arguments must match the format string's format specifiers.

Returns: B_TRUE if the dataref was found, B_FALSE otherwise. If you want to hard-assert that the dataref must always exist, use the fdr_find() wrapper macro instead.

Definition at line 44 of file dr.c.

◆ dr_get_cb_userinfo()

void * dr_get_cb_userinfo ( const dr_t * dr )

Returns the cb_userinfo pointer initially set in the configuration structure to the dr_create_*_cfg() functions used to create the dataref.

See also: dr_cfg_t

Definition at line 955 of file dr.c.

◆ dr_getbytes_impl()

int dr_getbytes_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		void *	data,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_getbytes() macro. Use dr_getbytes() instead.

Definition at line 388 of file dr.c.

◆ dr_getf_impl()

double dr_getf_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname
	)

Implementation of the dr_getf() macro. Use dr_getf() instead.

Definition at line 113 of file dr.c.

◆ dr_getf_prot_impl()

static double dr_getf_prot_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname
	)

static

Implementation of the dr_getf_prot() macro. Use dr_getf_prot() instead.

Definition at line 399 of file dr.h.

◆ dr_geti_impl()

int dr_geti_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname
	)

Implementation of the dr_geti() macro. Use dr_geti() instead.

Definition at line 74 of file dr.c.

◆ dr_gets_impl()

int dr_gets_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		char *	str,
		size_t	cap
	)

Implementation of the dr_gets() macro. Use dr_gets() instead.

Definition at line 367 of file dr.c.

◆ dr_getvf32_impl()

int dr_getvf32_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		float *	ff,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_getvf32() macro. Use dr_getvf32() instead.

Definition at line 261 of file dr.c.

◆ dr_getvf_impl()

int dr_getvf_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		double *	df,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_getvf() macro. Use dr_getvf() instead.

Definition at line 217 of file dr.c.

◆ dr_getvi_impl()

int dr_getvi_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		int *	i,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_getvi() macro. Use dr_getvi() instead.

Definition at line 155 of file dr.c.

◆ dr_setbytes_impl()

void dr_setbytes_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		void *	data,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_setbytes() macro. Use dr_setbytes() instead.

Definition at line 396 of file dr.c.

◆ dr_setf_impl()

void dr_setf_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		double	f
	)

Implementation of the dr_setf() macro. Use dr_setf() instead.

Definition at line 133 of file dr.c.

◆ dr_seti_impl()

void dr_seti_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		int	i
	)

Implementation of the dr_seti() macro. Use dr_seti() instead.

Definition at line 94 of file dr.c.

◆ dr_sets_impl()

void dr_sets_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		char *	str
	)

Implementation of the dr_sets() macro. Use dr_sets() instead.

Definition at line 380 of file dr.c.

◆ dr_setvf32_impl()

void dr_setvf32_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		float *	ff,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_setvf32() macro. Use dr_setvf32() instead.

Definition at line 335 of file dr.c.

◆ dr_setvf_impl()

void dr_setvf_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		double *	df,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_setvf() macro. Use dr_setvf() instead.

Definition at line 299 of file dr.c.

◆ dr_setvi_impl()

void dr_setvi_impl	(	const dr_t *	dr,
		const char *	filename,
		int	line,
		const char *	varname,
		int *	i,
		unsigned	off,
		unsigned	num
	)

Implementation of the dr_setvi() macro. Use dr_setvi() instead.

Definition at line 190 of file dr.c.

◆ dr_writable()

bool_t dr_writable ( dr_t * dr )

Returns: B_TRUE if the dataref is writable, B_FALSE if it is read-only.

Definition at line 68 of file dr.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ DR_DEBUG

◆ DR_DEBUG_VARS

◆ DR_EXT_DEPRECATED

◆ dr_getbytes

◆ dr_getf

◆ dr_getf_prot

◆ dr_geti

◆ dr_gets

◆ dr_getvf

◆ dr_getvf32

◆ dr_getvi

◆ DR_MAX_NAME_LEN

◆ dr_setbytes

◆ dr_setf

◆ dr_seti

◆ dr_sets

◆ dr_setvf

◆ dr_setvf32

◆ dr_setvi

◆ fdr_find

Function Documentation

◆ dr_array_set_stride()

◆ dr_create_b()

◆ dr_create_b_cfg()

◆ dr_create_f()

◆ dr_create_f64()

◆ dr_create_f64_cfg()

◆ dr_create_f_cfg()

◆ dr_create_i()

◆ dr_create_i_cfg()

◆ dr_create_vf()

◆ dr_create_vf64()

◆ dr_create_vf64_autoscalar()

◆ dr_create_vf64_autoscalar_cfg()

◆ dr_create_vf64_cfg()

◆ dr_create_vf_autoscalar()

◆ dr_create_vf_autoscalar_cfg()

◆ dr_create_vf_cfg()

◆ dr_create_vi()

◆ dr_create_vi_autoscalar()

◆ dr_create_vi_autoscalar_cfg()

◆ dr_create_vi_cfg()

◆ dr_delete()

◆ dr_find()

◆ dr_get_cb_userinfo()

◆ dr_getbytes_impl()

◆ dr_getf_impl()

◆ dr_getf_prot_impl()

◆ dr_geti_impl()

◆ dr_gets_impl()

◆ dr_getvf32_impl()

◆ dr_getvf_impl()

◆ dr_getvi_impl()

◆ dr_setbytes_impl()

◆ dr_setf_impl()

◆ dr_seti_impl()

◆ dr_sets_impl()

◆ dr_setvf32_impl()

◆ dr_setvf_impl()

◆ dr_setvi_impl()

◆ dr_writable()