312 lines
10 KiB
C
312 lines
10 KiB
C
#ifndef _XPLMPlugin_h_
|
|
#define _XPLMPlugin_h_
|
|
|
|
/*
|
|
* Copyright 2005-2012 Sandy Barbour and Ben Supnik
|
|
*
|
|
* All rights reserved. See license.txt for usage.
|
|
*
|
|
* X-Plane SDK Version: 2.1.1
|
|
*
|
|
*/
|
|
|
|
/*
|
|
* 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 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. */
|
|
#define XPLM_MSG_PLANE_CRASHED 101
|
|
|
|
/* This message is sent to your plugin whenever a new plane is loaded. The *
|
|
* parameter is the number of the plane being loaded; 0 indicates the user's *
|
|
* plane. */
|
|
#define XPLM_MSG_PLANE_LOADED 102
|
|
|
|
/* This messages is called whenever the user's plane is positioned at a new *
|
|
* airport. */
|
|
#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. */
|
|
#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. */
|
|
#define XPLM_MSG_AIRPLANE_COUNT_CHANGED 105
|
|
|
|
#if defined(XPLM200)
|
|
/* This message is sent to your plugin whenever a plane is unloaded. The *
|
|
* parameter is the 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. */
|
|
#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 is of type int, passed as the value of a *
|
|
* pointer and represents the aicraft plane number - 0 is the user's plane. */
|
|
#define XPLM_MSG_LIVERY_LOADED 108
|
|
#endif /* XPLM210 */
|
|
|
|
/*
|
|
* 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. 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.
|
|
*
|
|
*/
|
|
|
|
|
|
/*
|
|
* 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
|