xplane-sys 4.0.109

#ifndef _XPLMPlugin_h_
#define _XPLMPlugin_h_

/***************************************************************************
 * XPLMPlugin
 ***************************************************************************/
/*
 * These APIs provide facilities to find and work with other plugins and
 * manage other plugins.
 *
 */

#include "XPLMDefs.h"

#ifdef __cplusplus
extern "C" {
#endif

/***************************************************************************
 * FINDING PLUGINS
 ***************************************************************************/
/*
 * These APIs allow you to find another plugin or yourself, or iterate across
 * all plugins.  For example, if you wrote an FMS plugin that needed to talk
 * to an autopilot plugin, you could use these APIs to locate the autopilot
 * plugin.
 *
 */


/*
 * XPLMGetMyID
 * 
 * This routine returns the plugin ID of the calling plug-in.  Call this to
 * get your own ID.
 *
 */
XPLM_API XPLMPluginID XPLMGetMyID(void);

/*
 * XPLMCountPlugins
 * 
 * This routine returns the total number of plug-ins that are loaded, both
 * disabled and enabled.
 *
 */
XPLM_API int        XPLMCountPlugins(void);

/*
 * XPLMGetNthPlugin
 * 
 * This routine returns the ID of a plug-in by index.  Index is 0 based from 0
 * to XPLMCountPlugins-1, inclusive. Plugins may be returned in any arbitrary
 * order.
 *
 */
XPLM_API XPLMPluginID XPLMGetNthPlugin(
                         int                  inIndex);

/*
 * XPLMFindPluginByPath
 * 
 * This routine returns the plug-in ID of the plug-in whose file exists at the
 * passed in absolute file system path.  XPLM_NO_PLUGIN_ID is returned if the
 * path does not point to a currently loaded plug-in.
 *
 */
XPLM_API XPLMPluginID XPLMFindPluginByPath(
                         const char *         inPath);

/*
 * XPLMFindPluginBySignature
 * 
 * This routine returns the plug-in ID of the plug-in whose signature matches
 * what is passed in or XPLM_NO_PLUGIN_ID if no running plug-in has this
 * signature.  Signatures are the best way to identify another plug-in as they
 * are independent of the file system path of a plug-in or the human-readable
 * plug-in name, and should be unique for all plug-ins.  Use this routine to
 * locate another plugin that your plugin interoperates with
 *
 */
XPLM_API XPLMPluginID XPLMFindPluginBySignature(
                         const char *         inSignature);

/*
 * XPLMGetPluginInfo
 * 
 * This routine returns information about a plug-in.  Each parameter should be
 * a pointer to a buffer of at least
 * 256 characters, or NULL to not receive the information.
 * 
 * outName - the human-readable name of the plug-in. outFilePath - the
 * absolute file path to the file that contains this plug-in. outSignature - a
 * unique string that identifies this plug-in. outDescription - a
 * human-readable description of this plug-in.
 *
 */
XPLM_API void       XPLMGetPluginInfo(
                         XPLMPluginID         inPlugin,
                         char *               outName,                /* Can be NULL */
                         char *               outFilePath,            /* Can be NULL */
                         char *               outSignature,           /* Can be NULL */
                         char *               outDescription);        /* Can be NULL */

/***************************************************************************
 * ENABLING/DISABLING PLUG-INS
 ***************************************************************************/
/*
 * These routines are used to work with plug-ins and manage them.  Most
 * plugins will not need to use these APIs.
 *
 */


/*
 * XPLMIsPluginEnabled
 * 
 * Returns whether the specified plug-in is enabled for running.
 *
 */
XPLM_API int        XPLMIsPluginEnabled(
                         XPLMPluginID         inPluginID);

/*
 * XPLMEnablePlugin
 * 
 * This routine enables a plug-in if it is not already enabled. It returns 1
 * if the plugin was enabled or successfully enables itself, 0 if it does not.
 * Plugins may fail to enable (for example, if resources cannot be acquired)
 * by returning 0 from their XPluginEnable callback.
 *
 */
XPLM_API int        XPLMEnablePlugin(
                         XPLMPluginID         inPluginID);

/*
 * XPLMDisablePlugin
 * 
 * This routine disableds an enabled plug-in.
 *
 */
XPLM_API void       XPLMDisablePlugin(
                         XPLMPluginID         inPluginID);

/*
 * XPLMReloadPlugins
 * 
 * This routine reloads all plug-ins.  Once this routine is called and you
 * return from the callback you were within (e.g. a menu select callback) you
 * will receive your XPluginDisable and XPluginStop callbacks and your DLL
 * will be unloaded, then the start process happens as if the sim was starting
 * up.
 *
 */
XPLM_API void       XPLMReloadPlugins(void);

/***************************************************************************
 * INTERPLUGIN MESSAGING
 ***************************************************************************/
/*
 * Plugin messages are defined as 32-bit integers.  Messages below 0x00FFFFFF
 * are reserved for X-Plane and the plugin SDK.
 * 
 * Messages come with a pointer parameter; the meaning of this pointer depends
 * on the message itself. In some messages, the pointer parameter  contains an
 * actual typed pointer to data that can be inspected in the plugin; in these
 * cases the documentation will state that the parameter "points to"
 * information.
 * 
 * in other cases, the value of the pointer is actually an integral number
 * stuffed into the pointer's storage. In these second cases, the pointer
 * parameter needs to be cast, not dereferenced. In these caess, the
 * documentation will state that the parameter "contains" a value, which will
 * always be an integral type.
 * 
 * Some messages don't use the pointer parameter - in this case your plugin
 * should ignore it.
 * 
 * Messages have two conceptual uses: notifications and commands.  Commands
 * are sent from one plugin to another to induce behavior; notifications are
 * sent from one plugin to all others for informational purposes.  It is
 * important that commands and notifications not have the same values because
 * this could cause a notification sent by one plugin to accidentally induce a
 * command in another.
 * 
 * By convention, plugin-defined notifications should have the high bit set
 * (e.g. be greater or equal to unsigned 0x8000000) while commands should have
 * this bit be cleared.
 * 
 * The following messages are sent to your plugin by X-Plane.
 *
 */


/* This message is sent to your plugin whenever the user's plane crashes. The *
 * parameter is ignored.                                                      */
#define XPLM_MSG_PLANE_CRASHED 101

/* This message is sent to your plugin whenever a new plane is loaded.  The   *
 * parameter contains the index number of the plane being loaded; 0 indicates *
 * the user's plane.                                                          */
#define XPLM_MSG_PLANE_LOADED 102

/* This messages is sent whenever the user's plane is positioned at a new     *
 * airport. The parameter is ignored.                                         */
#define XPLM_MSG_AIRPORT_LOADED 103

/* This message is sent whenever new scenery is loaded.  Use datarefs to      *
 * determine the new scenery files that were loaded. The parameter is ignored.*/
#define XPLM_MSG_SCENERY_LOADED 104

/* This message is sent whenever the user adjusts the number of X-Plane       *
 * aircraft models.  You must use XPLMCountPlanes to find out how many planes *
 * are now available.  This message will only be sent in XP7 and higher       *
 * because in XP6 the number of aircraft is not user-adjustable. The parameter*
 * is ignored.                                                                */
#define XPLM_MSG_AIRPLANE_COUNT_CHANGED 105

#if defined(XPLM200)
/* This message is sent to your plugin whenever a plane is unloaded.  The     *
 * parameter contains the index number of the plane being unloaded; 0         *
 * indicates the user's plane.  The parameter is of type int, passed as the   *
 * value of the pointer.  (That is: the parameter is an int, not a pointer to *
 * an int.)                                                                   */
#define XPLM_MSG_PLANE_UNLOADED 106
#endif /* XPLM200 */

#if defined(XPLM210)
/* This message is sent to your plugin right before X-Plane writes its        *
 * preferences file.  You can use this for two purposes: to write your own    *
 * preferences, and to modify any datarefs to influence preferences output.   *
 * For example, if your plugin temporarily modifies saved preferences, you can*
 * put them back to their default values here to avoid having the tweaks be   *
 * persisted if your plugin is not loaded on the next invocation of X-Plane.  *
 * The parameter is ignored.                                                  */
#define XPLM_MSG_WILL_WRITE_PREFS 107
#endif /* XPLM210 */

#if defined(XPLM210)
/* This message is sent to your plugin right after a livery is loaded for an  *
 * airplane.  You can use this to check the new livery (via datarefs) and     *
 * react accordingly.  The parameter contains the index number of the aircraft*
 * whose livery is changing.                                                  */
#define XPLM_MSG_LIVERY_LOADED 108
#endif /* XPLM210 */

#if defined(XPLM301)
/* Sent to your plugin right before X-Plane enters virtual reality mode (at   *
 * which time any windows that are not positioned in VR mode will no longer be*
 * visible to the user). The parameter is unused and should be ignored.       */
#define XPLM_MSG_ENTERED_VR  109
#endif /* XPLM301 */

#if defined(XPLM301)
/* Sent to your plugin right before X-Plane leaves virtual reality mode (at   *
 * which time you may want to clean up windows that are positioned in VR      *
 * mode). The parameter is unused and should be ignored.                      */
#define XPLM_MSG_EXITING_VR  110
#endif /* XPLM301 */

#if defined(XPLM303)
/* Sent to your plugin if another plugin wants to take over AI planes. If you *
 * are a synthetic traffic provider,  that probably means a plugin for an     *
 * online network has connected and wants to supply aircraft flown by real    *
 * humans and you should cease to provide synthetic traffic. If however you   *
 * are providing online traffic from real humans,  you probably don't want to *
 * disconnect, in which case you just ignore this message. The sender is the  *
 * plugin ID of the plugin asking for control of the planes now. You can use  *
 * it to find out who is requesting and whether you should yield to them.     *
 * Synthetic traffic providers should always yield to online networks. The    *
 * parameter is unused and should be ignored.                                 */
#define XPLM_MSG_RELEASE_PLANES 111
#endif /* XPLM303 */

#if defined(XPLM400)
/* Sent to your plugin after FMOD sound banks are loaded. The parameter is the*
 * XPLMBankID enum in XPLMSound.h, 0 for the master bank and 1 for the radio  *
 * bank.                                                                      */
#define XPLM_MSG_FMOD_BANK_LOADED 112
#endif /* XPLM400 */

#if defined(XPLM400)
/* Sent to your plugin before FMOD sound banks are unloaded. Any associated   *
 * resources should be cleaned up at this point. The parameter is the         *
 * XPLMBankID enum in XPLMSound.h, 0 for the master bank and 1 for the radio  *
 * bank.                                                                      */
#define XPLM_MSG_FMOD_BANK_UNLOADING 113
#endif /* XPLM400 */

#if defined(XPLM400)
/* Sent to your plugin per-frame (at-most) when/if datarefs are added. It will*
 * include the new data ref total count so that your plugin can keep a local  *
 * cache of the total, see what's changed and know which ones to inquire about*
 * if it cares.                                                               *
 *                                                                            *
 * This message is only sent to plugins that enable the                       *
 * XPLM_WANTS_DATAREF_NOTIFICATIONS feature.                                  */
#define XPLM_MSG_DATAREFS_ADDED 114
#endif /* XPLM400 */

/*
 * XPLMSendMessageToPlugin
 * 
 * This function sends a message to another plug-in or X-Plane.  Pass
 * XPLM_NO_PLUGIN_ID to broadcast to all plug-ins.  Only enabled plug-ins with
 * a message receive function receive the message.
 *
 */
XPLM_API void       XPLMSendMessageToPlugin(
                         XPLMPluginID         inPlugin,
                         int                  inMessage,
                         void *               inParam);

#if defined(XPLM200)
/***************************************************************************
 * Plugin Features API
 ***************************************************************************/
/*
 * The plugin features API allows your plugin to "sign up" for additional
 * capabilities and plugin system features that are normally disabled for
 * backward compatibility or performance.  This allows advanced plugins to
 * "opt-in"  to new behavior.
 * 
 * Each feature is defined by a permanent string name.  The feature string
 * names will vary with the particular installation of X-Plane, so plugins
 * should not expect a feature to be guaranteed present.
 * 
 * XPLM_WANTS_REFLECTIONS
 * ----------------------
 * 
 * Available in the SDK 2.0 and later for X-Plane 9, enabling this capability
 * causes your plugin to receive drawing hook callbacks when X-Plane builds
 * its off-screen reflection and shadow rendering passes. Plugins should
 * enable this and examine the dataref sim/graphics/view/plane_render_type to
 * determine whether the drawing callback is for a reflection, shadow
 * calculation, or the main screen. Rendering can be simlified or omitted for
 * reflections, and non-solid drawing should be skipped for shadow
 * calculations.
 * 
 * **Note**: direct drawing via draw callbacks is not recommended; use the
 *   XPLMInstance API to create object models instead.
 * 
 * XPLM_USE_NATIVE_PATHS
 * ---------------------
 * 
 * available in the SDK 2.1 and later for X-Plane 10, this modifies the plugin
 * system to use Unix-style paths on all operating systems. With this enabled:
 * 
 * * OS X paths will match the native OS X Unix.
 * * Windows will use forward slashes but preserve C:\ or another drive letter
 *   when using complete file paths.
 * * Linux uses its native file system path scheme.
 * 
 * Without this enabled:
 * 
 * * OS X will use CFM file paths separated by a colon.
 * * Windows will use back-slashes and conventional DOS paths.
 * * Linux uses its native file system path scheme.
 * 
 * All plugins should enable this feature on OS X to access the native file
 * system.
 * 
 * XPLM_USE_NATIVE_WIDGET_WINDOWS
 * ------------------------------
 * 
 * Available in the SDK 3.0.2 SDK, this capability tells the widgets library
 * to use new, modern X-Plane backed XPLMDisplay windows to anchor all widget
 * trees.  Without it, widgets will always use legacy windows.
 * 
 * Plugins should enable this to allow their widget hierarchies to respond to
 * the user's UI size settings and to map widget-based windwos to a VR HMD.
 * 
 * Before enabling this, make sure any custom widget code in your plugin is
 * prepared to cope with the UI coordinate system not being th same as the
 * OpenGL window coordinate system.
 * 
 * XPLM_WANTS_DATAREF_NOTIFICATIONS
 * --------------------------------
 * 
 * Available in the SDK 4.0.0, this capability tells X-Plane to to send the
 * enabling plugin the new XPLM_MSG_DATAREFS_ADDED message any time new
 * datarefs are added. The SDK will coalesce consecutive dataref registrations
 * to minimize the number of messages sent.
 *
 */


/*
 * XPLMFeatureEnumerator_f
 * 
 * You pass an XPLMFeatureEnumerator_f to get a list of all features supported
 * by a given version running version of X-Plane.  This routine is called once
 * for each feature.
 *
 */
typedef void (* XPLMFeatureEnumerator_f)(
                         const char *         inFeature,
                         void *               inRef);

/*
 * XPLMHasFeature
 * 
 * This returns 1 if the given installation of X-Plane supports a feature, or
 * 0 if it does not.
 *
 */
XPLM_API int        XPLMHasFeature(
                         const char *         inFeature);

/*
 * XPLMIsFeatureEnabled
 * 
 * This returns 1 if a feature is currently enabled for your plugin, or 0 if
 * it is not enabled.  It is an error to call this routine with an unsupported
 * feature.
 *
 */
XPLM_API int        XPLMIsFeatureEnabled(
                         const char *         inFeature);

/*
 * XPLMEnableFeature
 * 
 * This routine enables or disables a feature for your plugin.  This will
 * change the running behavior of X-Plane and your plugin in some way,
 * depending on the feature.
 *
 */
XPLM_API void       XPLMEnableFeature(
                         const char *         inFeature,
                         int                  inEnable);

/*
 * XPLMEnumerateFeatures
 * 
 * This routine calls your enumerator callback once for each feature that this
 * running version of X-Plane supports. Use this routine to determine all of
 * the features that X-Plane can support.
 *
 */
XPLM_API void       XPLMEnumerateFeatures(
                         XPLMFeatureEnumerator_f inEnumerator,
                         void *               inRef);

#endif /* XPLM200 */
#ifdef __cplusplus
}
#endif

#endif