dr_cmd_reg.h File Reference

#include <stdarg.h>
#include <stdbool.h>
#include "cmd.h"
#include "dr.h"

Include dependency graph for dr_cmd_reg.h:

Go to the source code of this file.

Macros
#define	DCR_CREATE_COMMON(type, dr_ptr, ...)
#define	DCR_CREATE_I(dr_p, __value, __writable, ...)
#define	DCR_CREATE_I_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(i, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_F(dr_p, __value, __writable, ...)
#define	DCR_CREATE_F_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(f, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_F64(dr_p, __value, __writable, ...)
#define	DCR_CREATE_F64_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(f64, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VI(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VI_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vi, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VF(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VF_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vf, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VF64(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VF64_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vf64, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VI_AUTOSCALAR(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VI_AUTOSCALAR_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vi_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VF_AUTOSCALAR(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VF_AUTOSCALAR_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vf_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_VF64_AUTOSCALAR(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_VF64_AUTOSCALAR_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(vf64_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)
#define	DCR_CREATE_B(dr_p, __value, __n, __writable, ...)
#define	DCR_CREATE_B_CFG(dr_p, __value, __cfg, ...)    DCR_CREATE_COMMON(b, dr_p, __value, __cfg, __VA_ARGS__)

Functions
void	dcr_init (void)
void	dcr_fini (void)
XPLMCommandRef	dcr_find_cmd (const char *fmt, XPLMCommandCallback_f cb, bool before, void *refcon,...)
XPLMCommandRef	dcr_find_cmd_v (const char *fmt, XPLMCommandCallback_f cb, bool before, void *refcon, va_list ap)
XPLMCommandRef	f_dcr_find_cmd (const char *fmt, XPLMCommandCallback_f cb, bool before, void *refcon,...)
XPLMCommandRef	f_dcr_find_cmd_v (const char *fmt, XPLMCommandCallback_f cb, bool before, void *refcon, va_list ap)
XPLMCommandRef	dcr_create_cmd (const char *cmdname, const char *cmddesc, XPLMCommandCallback_f cb, bool before, void *refcon)
void *	dcr_alloc_rdr (void)
dr_t *	dcr_get_dr (void *token)
void	dcr_insert_rdr (void *token)

Detailed Description

This file contains automation machinery to help bulk dataref and command destruction on plugin unload time. This avoids leaving dangling datarefs and commands around and promotes code cleanliness. ("DCR" = Dataref and Command Registration)

The automation works using two functions. On plugin startup, you should first call dcr_init() before attempting to use any other function or macro in this file. Then use any of the DCR_CREATE_* family of macros, or dcr_*_cmd functions to create/register datarefs and commands. The DCR machinery will keep track of any datarefs and commands you've created and/or registered. On plugin shutdown, you must call dcr_fini() after you are done with any dataref manipulations. This will proceed to delete and unregister any previously registered datarefs and commands using any of the DCR family of macros and functions. Thus, you won't need to keep track of making sure to clean up after each dataref. You can simply create datarefs and commands without worrying about immediately writing cleanup routines for all of them.

See also

dcr_init(), dcr_fini()

DCR_CREATE_I(), DCR_CREATE_F(), DCR_CREATE_F64(), etc.

dcr_find_cmd(), dcr_create_cmd(), etc.

Definition in file dr_cmd_reg.h.

Macro Definition Documentation

DCR_CREATE_B

#define DCR_CREATE_B	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(b, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates a byte array dataref using dr_create_b().

Definition at line 194 of file dr_cmd_reg.h.

DCR_CREATE_B_CFG

#define DCR_CREATE_B_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(b, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 197 of file dr_cmd_reg.h.

DCR_CREATE_COMMON

#define DCR_CREATE_COMMON	(		type,
			dr_ptr,
			...
	)

Value:

    do { \
        void *__rdr = dcr_alloc_rdr(); \
        dr_t *__dr = dcr_get_dr(__rdr); \
        dr_create_ ## type ## _cfg(__dr, __VA_ARGS__); \
        dcr_insert_rdr(__rdr); \
        if ((dr_ptr) != NULL) \
            *(dr_t **)(dr_ptr) = __dr; \
    } while (0)

Internal, do not call, use the type-specific DCR_CREATE macros instead, such as DCR_CREATE_I() or DCR_CREATE_F().

Definition at line 90 of file dr_cmd_reg.h.

DCR_CREATE_F

#define DCR_CREATE_F	(		dr_p,
			__value,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(f, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable) }, __VA_ARGS__)

Same as DCR_CREATE_I(), except creates a dataref using dr_create_f().

Definition at line 123 of file dr_cmd_reg.h.

DCR_CREATE_F64

#define DCR_CREATE_F64	(		dr_p,
			__value,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(f64, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable) }, __VA_ARGS__)

Same as DCR_CREATE_I(), except creates a dataref using dr_create_f64().

Definition at line 131 of file dr_cmd_reg.h.

DCR_CREATE_F64_CFG

#define DCR_CREATE_F64_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(f64, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 134 of file dr_cmd_reg.h.

DCR_CREATE_F_CFG

#define DCR_CREATE_F_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(f, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 126 of file dr_cmd_reg.h.

DCR_CREATE_I

#define DCR_CREATE_I	(		dr_p,
			__value,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(i, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable) }, __VA_ARGS__)

Similar to the dr_create_i() function call from dr.h, but the first argument is of type dr_t **, instead of a plain dr_t *.

Parameters

dr_p	Optional pointer of type dr_t **. If not NULL, this pointer is set to point to the dr_t structure that was created as part of this dataref registration. The actual dr_t is held internally by the DCR machinery. If you don't wish to perform any further setup of the dataref, you may safely pass NULL here and more-or-less forget about where the dr_t is kept.
__value	The value pointer passed to dr_create_i().
__writable	The writable flag passed to dr_create_i().

All remaining parameters are passed to the dr_create_i() function as-is to specify the name format and format arguments to the dataref's printf-style name creation.

Definition at line 115 of file dr_cmd_reg.h.

DCR_CREATE_I_CFG

#define DCR_CREATE_I_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(i, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 118 of file dr_cmd_reg.h.

DCR_CREATE_VF

#define DCR_CREATE_VF	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vf, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n)}, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates an array dataref using dr_create_vf().

Definition at line 149 of file dr_cmd_reg.h.

DCR_CREATE_VF64

#define DCR_CREATE_VF64	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vf64, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates an array dataref using dr_create_vf64().

Definition at line 158 of file dr_cmd_reg.h.

DCR_CREATE_VF64_AUTOSCALAR

#define DCR_CREATE_VF64_AUTOSCALAR	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vf64_autoscalar, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates an auto-scalar array dataref using dr_create_vf64_autoscalar().

Definition at line 185 of file dr_cmd_reg.h.

DCR_CREATE_VF64_AUTOSCALAR_CFG

#define DCR_CREATE_VF64_AUTOSCALAR_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vf64_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 188 of file dr_cmd_reg.h.

DCR_CREATE_VF64_CFG

#define DCR_CREATE_VF64_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vf64, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 161 of file dr_cmd_reg.h.

DCR_CREATE_VF_AUTOSCALAR

#define DCR_CREATE_VF_AUTOSCALAR	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vf_autoscalar, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates an auto-scalar array dataref using dr_create_vf_autoscalar().

Definition at line 176 of file dr_cmd_reg.h.

DCR_CREATE_VF_AUTOSCALAR_CFG

#define DCR_CREATE_VF_AUTOSCALAR_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vf_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 179 of file dr_cmd_reg.h.

DCR_CREATE_VF_CFG

#define DCR_CREATE_VF_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vf, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 152 of file dr_cmd_reg.h.

DCR_CREATE_VI

#define DCR_CREATE_VI	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vi, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_I(), except creates an array dataref using dr_create_vi() and takes an additional number-of-elements argument in __n.

Definition at line 140 of file dr_cmd_reg.h.

DCR_CREATE_VI_AUTOSCALAR

#define DCR_CREATE_VI_AUTOSCALAR	(		dr_p,
			__value,
			__n,
			__writable,
			...
	)

Value:

    DCR_CREATE_COMMON(vi_autoscalar, dr_p, __value, \
        (dr_cfg_t){ .writable = (__writable), .count = (__n) }, __VA_ARGS__)

Same as DCR_CREATE_VI(), except creates an auto-scalar array dataref using dr_create_vi_autoscalar().

Definition at line 167 of file dr_cmd_reg.h.

DCR_CREATE_VI_AUTOSCALAR_CFG

#define DCR_CREATE_VI_AUTOSCALAR_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vi_autoscalar, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 170 of file dr_cmd_reg.h.

DCR_CREATE_VI_CFG

#define DCR_CREATE_VI_CFG	(		dr_p,
			__value,
			__cfg,
			...
	)		DCR_CREATE_COMMON(vi, dr_p, __value, __cfg, __VA_ARGS__)

Definition at line 143 of file dr_cmd_reg.h.

Function Documentation

dcr_alloc_rdr()

void * dcr_alloc_rdr

(

void

)

Internal, do not call, use the DCR_CREATE macros instead

Definition at line 124 of file dr_cmd_reg.c.

dcr_create_cmd()

XPLMCommandRef dcr_create_cmd	(	const char *	cmdname,
		const char *	cmddesc,
		XPLMCommandCallback_f	cb,
		bool	before,
		void *	refcon
	)

Creates a new command and registers a command handler for it in a single step. This also registers the command handler with DCR, so the handler is automatically deregistered when you call dcr_fini().

Parameters

cmdname	The name of the command to be registered. This must be unique to prevent unpredictable behavior.
cmddesc	A human-readable description of the command to show in X-Plane's command assignment UI.
cb	Callback function to register for the command handler.
before	Flag describing whether the callback should be called before X-Plane handles the command, or after.
refcon	Reference constant, which will be passed to the callback in the refcon argument.

Returns

Returns the XPLMCommandRef of the newly created command. If the command creation fails, this function causes a hard assertion failure.

Definition at line 289 of file dr_cmd_reg.c.

dcr_find_cmd()

XPLMCommandRef dcr_find_cmd	(	const char *	fmt,
		XPLMCommandCallback_f	cb,
		bool	before,
		void *	refcon,
			...
	)

Finds a command and register a callback to handle it, while registering it with DCR, so the handler is automatically deregistered when you call dcr_fini().

Parameters

fmt	A printf-style format string which will be evaluated to form the name of the command for the lookup. The variadic arguments to this function are used for the format specifiers in this string.
cb	Callback function to register for the command handler.
before	Flag describing whether the callback should be called before X-Plane handles the command, or after.
refcon	Reference constant, which will be passed to the callback in the refcon argument.

Returns

Returns the XPLMCommandRef of the command, if found and the command has been registered successfully. Otherwise returns NULL.

See also

https://www.man7.org/linux/man-pages/man3/printf.3.html

Definition at line 173 of file dr_cmd_reg.c.

dcr_find_cmd_v()

XPLMCommandRef dcr_find_cmd_v	(	const char *	fmt,
		XPLMCommandCallback_f	cb,
		bool	before,
		void *	refcon,
		va_list	ap
	)

Same as dcr_find_cmd(), but takes a va_list argument list for the format arguments, instead of being variadic.

See also

dcr_find_cmd()

Definition at line 192 of file dr_cmd_reg.c.

dcr_fini()

void dcr_fini

(

void

)

Deinitializes the DCR machinery. This should be called on plugin shutdown and after you are done with all dataref manipulations, typically near the bottom of your XPluginEnable or XPluginStart callbacks.

This function will go through all aggregated datarefs and commands that were created using the DCR family of macros and functions and destroy/unregister them all as necessary.

Definition at line 96 of file dr_cmd_reg.c.

dcr_get_dr()

dr_t * dcr_get_dr

(

void *

token

)

Internal, do not call, use the DCR_CREATE macros instead

Definition at line 132 of file dr_cmd_reg.c.

dcr_init()

void dcr_init

(

void

)

Initializes the DCR machinery. This should be called before any of the other DCR macros or functions are called - typically near the top of your XPluginEnable or XPluginStart callbacks.

Definition at line 75 of file dr_cmd_reg.c.

dcr_insert_rdr()

void dcr_insert_rdr

(

void *

token

)

Internal, do not call, use the DCR_CREATE macros instead

Definition at line 141 of file dr_cmd_reg.c.

f_dcr_find_cmd()

XPLMCommandRef f_dcr_find_cmd	(	const char *	fmt,
		XPLMCommandCallback_f	cb,
		bool	before,
		void *	refcon,
			...
	)

Same as dcr_find_cmd(), but will cause a hard assertion failure if the command doesn't exist. This is similar to the fcmd_find() and fdr_find() functions.

See also

dcr_find_cmd()

Definition at line 234 of file dr_cmd_reg.c.

f_dcr_find_cmd_v()

XPLMCommandRef f_dcr_find_cmd_v	(	const char *	fmt,
		XPLMCommandCallback_f	cb,
		bool	before,
		void *	refcon,
		va_list	ap
	)

Same as f_dcr_find_cmd(), but takes a va_list argument list for the format arguments, instead of being variadic.

See also

f_dcr_find_cmd()

dcr_find_cmd()

Definition at line 254 of file dr_cmd_reg.c.