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  ToolsPluginSignalCb
struct  ToolsPluginData

Defines

#define VMTOOLSAPP_ERROR(ctx, err)
#define VMTOOLSAPP_ATTACH_SOURCE(ctx, src, cb, data, destroy)
#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_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 }

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_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_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).

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 17 Feb 2010 for open-vm-tools 2010.01.19 by  doxygen 1.6.1