- 1 Simulator Notifications and Interplugin Messaging and Management
- 1.1 About the Plugin Management APIs
- 1.2 Plugin IDs
- 1.3 Interplugin Messaging
- 1.4 Plugin Management
- 1.5 Using the Plugin Management APIs
- 1.6 Working with Other Plugins
- 1.7 Sending and Receiving Messages
- 1.8 Plugin Messaging Reference
Simulator Notifications and Interplugin Messaging and Management
About the Plugin Management APIs
The plugin management APIs provide a number of services for working with other plugins. We can locate, send messages to, receive messages from, and control other plugins.
To a limited extent, X-Plane also appears as another plugin. The plugin will receive messages from X-Plane as if it was a plugin. The most common usage of the plugin management APIs is to receive notifications from X-Plane.
If we only need to receive notifications of simulator events from X-Plane, simply read the sections on interplugin messaging and receiving messages from X-Plane. Receiving notifications from X-Plane is very easy to do. The rest of the APIs discussed here are for advanced users.
The infrastructure to enable and disable plugins is entirely public and available via plugin management. The standard user interface to manage plugins is actually in itself provided by a plugin, and it is possible to rewrite, remove, or replace this functionality.
Each plugin that successfully loads is assigned a unique ID. This unique ID is not persistent and may be different each time the simulator runs. It is also only unique for a single running of the simulator. This ID is used to identify the plugin for management purposes.
The value XPLM NO PLUGIN ID (-1) is reserved to indicate that the lack of a plug-in or all plug-ins depending on the API. In some APIs this value is not allowed. The value XPLM PLUGIN XPLANE is used to indicate X-Plane in contexts where the simulator may be treated like a plug-in.
There are a number of ways to get a plug-ins ID:
- A plugin may get its own ID simply by calling a function.
- We can use a loop to iterate across all plugins.
- Given a full file system path, if the file system path points to a plug-in's DLL, we can find the plugin ID that the plugin has been assigned.
- Given a plugin's signature, we can find its ID. This is the best way to locate a plugin if we know exactly which one we're looking for.
- X-Plane's ID is constant.
We may also be given a plugin ID from other APIs:
- When we receive a message from a plug-in, we also receive its ID.
- Other APIs (for example, hot keys) will provide the ID of the plugin that owns an object.
For the purpose of receiving messages from the sim, we may not need plugin IDs at all since we can simply check for specific messages.
Plugins may send messages to each other. Plugin messages consist of an integer message code and a pointer that contains information specific to the message.
Messages may either be broadcast to all plugins or to one specific plugin. Plugins may ignore messages they receive. Disabled plugins do not receive messages.
X-Plane will also send messages to plugins. All of X-Plane's messages are broadcast to all plugins. See the separate messaging documentation for information on the messages that X-Plane sends to plugins.
Plugin messages are always sent serially; when we send a message to a plugin, the plugin stops until the receiving plugin fully handles the message. The simulator does not run during any of this time. For this reason, make sure the messaging handling code is efficient.
Plugins can enable and disable other plugins. These capabilities are useful for allowing the user to present plugins. The routines to do this will only be of interested to plugins that manage other plugins.
Using the Plugin Management APIs
Working with Other Plugins
There are a number of ways to find plugins. The listing below finds a plugin by signature and sends a message to it:
< LISTING - Find a plugin by signature and sending a message to it >
We can also locate all plugins. This function dumps information about all plugins to a file:
< LISTING - Iterating across all plugins and dumping their stats >
A plugin can also get information about itself. This listing finds the location of our DLL on disk by getting our ID and getting info about us.
< LISTING - A plugin finding itself and getting its file location >
Getting Information About Plugins
Given a plugin ID, we can get information about a plugin. This routine prints information about a plugin to disk:
< LISTING - routine that prints info to disk from above >
Enabling and Disabling Plugins
Given a plugin ID, we can enable or disable a plugin. This routine disables all other plugins except ourself and one other plugin of a known signature:
< LISTING - disabling all other plugins >
Sending and Receiving Messages
Sending Messages to Plugins
A plugin can send a message to another plugin, to itself, or to all plugins via broadcast. We can pass anything for the message and pointer.
< LISTING - A plugin sendind a msg to itself, one other plugin, and then all plugins>
Receiving Messages from Plugins
A plugin receives messages from other plugins via its XPluginReceiveMessage callback. This callback receives messages from another plugin to add a waypoint to a flight plan.
< LISTING - A plugin that receives waypoint data and adds it to a flight-plan>
Receiving Messages from X-Plane
We receive messages from X-Plane via the XPluginReceiveMessage callback. This callback responds to the user picking a new plane.
< LISTING - A plugin receives a plane load message from X-Plane>
Plugin Messaging Reference
For reference information on plugin messaging, see the following header files:
Also, see chapter 1, Developing Plugins, and the separate comprehensive list of X-Plane messages.