carbOnPluginStartupEx¶

bool carbOnPluginStartupEx()¶

An optional function that a plugin author can export from their plugin to start their plugin.

The Framework will call this function after carbOnPluginPreStartup when starting the plugin (the first time an interface is acquired from the plugin). This serves as a guide for plugin authors.

Providing this function is completely optional.

Generally, if this function is provided, a carbOnPluginShutdown should also be provided to cleanup any work done by this function.

This function supersedes carbOnPluginStartup. The main difference is that this function allows the plugin to indicate if startup fails (such as if a required subsystem fails to start) and allow the Framework to fail acquiring an interface gracefully. If this function does not exist, carbOnPluginStartup is called if it exists.

Any interfaces declared as a dependency in CARB_PLUGIN_IMPL_DEPS will be available to this plugin by the time this function is called.

This function is allowed to acquire interfaces and interact with the Framework normally (e.g. add hooks, etc.). However, keep in mind that this function is called by the Framework when the Application or another plugin is trying to acquire an interface from this plugin; actions that result in recursively starting the plugin will result in failure to acquire the interface. However, your plugin is allowed to acquire other interfaces from itself in this function.

Once this function returns successfully, the Framework considers your plugin as initialized. If this function reports failure, the plugin will be unloaded but remain registered. Attempting to acquire an interface from this plugin in the future will reload the plugin and attempt to call this function again.

Typical things this function might do:

Allocate memory and data structures for your plugin
Load settings from carb::settings::ISettings (if available)
Start up libraries and subsystems

The type of this function is carb::OnPluginStartupExFn and named kCarbOnPluginStartupExFnName.

Returns: true if the plugin started successfully; false otherwise.