VMware Tools Plugins

Defines the API used by the Tools Services for dynamically loading plugins. More...

Data Structures

struct  ToolsAppCtx
struct  ToolsAppCapability
struct  ToolsAppProvider
struct  ToolsAppReg
struct  ToolsServiceProperty
struct  ToolsPluginSignalCb
struct  ToolsPluginData

Defines

#define TOOLS_CORE_SIG_XIOERROR   "tcs_de_xioerror"
#define TOOLS_CORE_SIG_XSM_SAVE_YOURSELF   "tcs_de_xsm_save_yourself"
#define TOOLS_CORE_SIG_XSM_DIE   "tcs_de_xsm_die"
#define TOOLS_CORE_SIG_XSM_SAVE_COMPLETE   "tcs_de_xsm_save_complete"
#define TOOLS_CORE_SIG_XSM_SHUTDOWN_CANCELLED   "tcs_de_xsm_shutdown_cancelled"
#define VMTOOLSAPP_ERROR(ctx, err)
#define VMTOOLSAPP_ATTACH_SOURCE(ctx, src, cb, data, destroy)
#define TOOLS_IS_MAIN_SERVICE(ctx)
#define TOOLS_IS_USER_SERVICE(ctx)
#define TOOLS_STATE_LOG_ROOT   0
#define TOOLS_STATE_LOG_CONTAINER   1
#define TOOLS_STATE_LOG_PLUGIN   2
#define TOOLS_CORE_SIG_CAPABILITIES   "tcs_capabilities"
#define TOOLS_CORE_SIG_CONF_RELOAD   "tcs_conf_reload"
#define TOOLS_CORE_SIG_DUMP_STATE   "tcs_dump_state"
#define TOOLS_CORE_SIG_RESET   "tcs_reset"
#define TOOLS_CORE_SIG_SET_OPTION   "tcs_set_option"
#define TOOLS_CORE_SIG_SHUTDOWN   "tcs_shutdown"
#define TOOLS_CORE_PROP_CTX   "tcs_app_ctx"
 Property where the container's ToolsAppCtx is stored.
#define TOOLS_MODULE_EXPORT   VMTOOLS_EXTERN_C

Typedefs

typedef ToolsPluginData *(* ToolsPluginOnLoad )(ToolsAppCtx *ctx)

Enumerations

enum  ToolsCoreAPI { TOOLS_CORE_API_V1 = 0x1 }
enum  ToolsCapabilityType { TOOLS_CAP_OLD = 0, TOOLS_CAP_OLD_NOVAL = 1, TOOLS_CAP_NEW = 2 }
enum  ToolsAppType { TOOLS_APP_GUESTRPC = 1, TOOLS_APP_SIGNALS = 2, TOOLS_APP_PROVIDER = 3, TOOLS_SVC_PROPERTY = 4 }

Detailed Description

Defines the API used by the Tools Services for dynamically loading plugins.

Plugins are dynamically loaded into the Tools service process, and may provide applications that hook into the functionality provided by the service, such as the glib main loop and the GuestRPC channel.

Plugins that want to remain loaded by the service should always return registration data when their registration function (ToolsPluginOnLoad()) is called. The registration data, defined by the ToolsPluginData data structure, provides information about what events the plugin is interested in (for example, incoming RPCs).


Define Documentation

#define TOOLS_CORE_PROP_CTX   "tcs_app_ctx"

Property where the container's ToolsAppCtx is stored.

This property is useful in cases where the client code has access to the service object instance but not to the container's context object, such as in the callback for the object's "notify" signal.

#define TOOLS_CORE_SIG_CAPABILITIES   "tcs_capabilities"

Signal sent when registering or unregistering capabilities.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context.
[in] set gboolean: TRUE if setting capabilities, FALSE if unsetting them.
[in] data Client data.
Returns:
A GArray instance with the capabilities to be set or unset. The elements should be of type ToolsAppCapability.
#define TOOLS_CORE_SIG_CONF_RELOAD   "tcs_conf_reload"

Signal sent when the config file is reloaded.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: The application context.
[in] data Client data.
#define TOOLS_CORE_SIG_DUMP_STATE   "tcs_dump_state"

Signal sent when the service receives a request to dump its internal state to the log. This is for debugging purposes, and plugins can respond to the signal by dumping their own state also.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: The application context.
[in] data Client data.
#define TOOLS_CORE_SIG_RESET   "tcs_reset"

Signal sent when a successful RpcChannel reset occurs.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: The application context.
[in] data Client data.
#define TOOLS_CORE_SIG_SET_OPTION   "tcs_set_option"

Signal sent when a "set option" RPC message arrives.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: The application context.
[in] option gchar *: Option being set.
[in] value gchar *: Option value.
[in] data Client data.
Returns:
A gboolean saying whether the option was recognized and the value was valid.
#define TOOLS_CORE_SIG_SHUTDOWN   "tcs_shutdown"

Signal sent when shutting down the service.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: The application context.
[in] data Client data.
#define TOOLS_CORE_SIG_XIOERROR   "tcs_de_xioerror"

Signal emitted upon X I/O error callback firing.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context.
[in] data Client data.
#define TOOLS_CORE_SIG_XSM_DIE   "tcs_de_xsm_die"

Signal emitted upon SmcCallbacks::die.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context.
[in] data Client data.
#define TOOLS_CORE_SIG_XSM_SAVE_COMPLETE   "tcs_de_xsm_save_complete"

Signal emitted upon SmcCallbacks::save_complete.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context.
[in] data Client data.
#define TOOLS_CORE_SIG_XSM_SAVE_YOURSELF   "tcs_de_xsm_save_yourself"

Signal emitted upon SmcCallbacks::save_yourself.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context. [in] saveType Refer to SMlib.xml.
[in] shutdown 0 = checkpoint, 1 = shutdown.
[in] interactStyle May interact with user?
[in] fast Shutdown as quickly as possible.
[in] data Client data.
#define TOOLS_CORE_SIG_XSM_SHUTDOWN_CANCELLED   "tcs_de_xsm_shutdown_cancelled"

Signal emitted upon SmcCallbacks::shutdown_cancelled.

Parameters:
[in] src The source object.
[in] ctx ToolsAppCtx *: the application context.
[in] data Client data.
#define TOOLS_IS_MAIN_SERVICE ( ctx   ) 
Value:
(strcmp((ctx)->name, \
                                           VMTOOLS_GUEST_SERVICE) == 0)

Checks if the Tools service is main (system) service or not.

Parameters:
[in] ctx The application context or tools service state.
#define TOOLS_IS_USER_SERVICE ( ctx   ) 
Value:
(strcmp((ctx)->name, \
                                           VMTOOLS_USER_SERVICE) == 0)

Checks if the Tools service is user (logged in user) service or not.

Parameters:
[in] ctx The application context or tools service state.
#define TOOLS_MODULE_EXPORT   VMTOOLS_EXTERN_C

Definition for tagging functions to be exported in the plugin binary. Use this to tag the plugin entry point function, and any other functions that the plugin needs to export.

#define VMTOOLSAPP_ATTACH_SOURCE ( ctx,
src,
cb,
data,
destroy   ) 
Value:
do {      \
   GSource *__src = (src);                                              \
   g_source_set_callback(__src, (GSourceFunc) (cb), (data), (destroy)); \
   g_source_attach(__src, g_main_loop_get_context((ctx)->mainLoop));    \
} while (0)

Attaches the given event source to the app context's main loop.

Parameters:
[in] ctx The application context.
[in] src Source to attach.
[in] cb Callback to call when event is "ready".
[in] data Data to provide to the callback.
[in] destroy Destruction notification callback.
#define VMTOOLSAPP_ERROR ( ctx,
err   ) 
Value:
do {   \
   ASSERT((err) != 0);                    \
   (ctx)->errorCode = (err);              \
   g_main_loop_quit((ctx)->mainLoop);     \
} while (0)

Error reporting macro. Call this if the app encounters an error that requires the service to quit. The service's main loop will stop as soon as it regains control of the application.

Parameters:
[in] ctx The application context.
[in] err Error code. Must not be 0.

Typedef Documentation

Signature for the plugin entry point function. The function should be called ToolsOnLoad, and be exported in the plugin binary (e.g., by tagging it with TOOLS_MODULE_EXPORT).

If the plugin wants to stay loaded, it always should return the registration data, even if all it contains is the (mandatory) plugin name. Plugins which return NULL will be unloaded before the service is started, so they shouldn't modify the service state (for example, by adding callbacks to the service's main loop).


Enumeration Type Documentation

Type of the application feature being registered.

Enumerator:
TOOLS_APP_GUESTRPC 

Denotes a list of GuestRPC registrations (type RpcChannelCallback).

TOOLS_APP_SIGNALS 

Denotes a list of signals the application is interested in (type ToolsPluginSignalCb).

TOOLS_APP_PROVIDER 

Denotes an application provider (type ToolsAppProvider). This allows plugins to extend the functionality of vmtoolsd by adding new application types (that other plugins can hook into).

TOOLS_SVC_PROPERTY 

Denotes a property made available through the service's instance object (ToolsAppCtx::serviceObj).

Identifies the type of a Tools capability.

This enum lists all API versions that different versions of vmtoolsd support. The "ToolsAppCtx" instance provided to plugins contains a "version" field which is a bit-mask of these values, telling plugins what features the container supports.

Refer to a specific feature's documentation for which version of the API is needed for it to be supported.


Generated on 4 Apr 2017 for open-vm-tools 10.1.5 by  doxygen 1.6.1