open-vm-tools 12.4.5
VMware Tools Plugins

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

Data Structures

struct  ToolsPluginSvcGuestStore
 Type of the public interface of the guestStore plugin. More...
 
struct  ToolsAppCtx
 
struct  ToolsAppCapability
 
struct  ToolsAppProvider
 
struct  ToolsAppReg
 
struct  ToolsServiceProperty
 
struct  ToolsPluginSignalCb
 
struct  ToolsPluginData
 

Macros

#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 TOOLS_CORE_SIG_GUESTSTORE_STATE   "tcs_gueststore_state"
 
#define TOOLS_PLUGIN_SVC_PROP_GUESTSTORE   "tps_prop_gueststore"
 
#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_NO_RPC   "tcs_no_rpc"
 
#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_CORE_EVENTS_TOOLS_NEW_VERSION   "VMToolsNewVersion"
 
#define TOOLS_CORE_EVENTS_TOOLS_NEED_REBOOT   "VMToolsNeedReboot"
 
#define TOOLS_CORE_EVENTS_GLOBAL_SCOPE   "Global"
 
#define TOOLS_MODULE_EXPORT   VMTOOLS_EXTERN_C
 

Typedefs

typedef struct ToolsPluginSvcGuestStore ToolsPluginSvcGuestStore
 Type of the public interface of the guestStore plugin.
 
typedef void(* RegisterServiceProperty) (gpointer obj, struct ToolsServiceProperty *prop)
 
typedef struct ToolsAppCtx ToolsAppCtx
 
typedef struct ToolsAppCapability ToolsAppCapability
 
typedef struct ToolsAppProvider ToolsAppProvider
 
typedef struct ToolsAppReg ToolsAppReg
 
typedef struct ToolsServiceProperty ToolsServiceProperty
 
typedef struct ToolsPluginSignalCb ToolsPluginSignalCb
 
typedef struct ToolsPluginData ToolsPluginData
 
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).

Macro Definition Documentation

◆ TOOLS_CORE_EVENTS_TOOLS_NEED_REBOOT

#define TOOLS_CORE_EVENTS_TOOLS_NEED_REBOOT   "VMToolsNeedReboot"

Event signaled when VMTools requires a system restart to complete an install.

Name of the event that can be set to the notification event to indicate a system restart is required to complete the install or upgrade of tools.

◆ TOOLS_CORE_EVENTS_TOOLS_NEW_VERSION

#define TOOLS_CORE_EVENTS_TOOLS_NEW_VERSION   "VMToolsNewVersion"

Event signaled when VMTools discovers a newer version is available.

Name of the event that can be set to the notification event to indicate a new version of tools is available for install or upgrade.

◆ TOOLS_CORE_PROP_CTX

#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.

◆ TOOLS_CORE_SIG_CAPABILITIES

#define TOOLS_CORE_SIG_CAPABILITIES   "tcs_capabilities"

Signal sent when registering or unregistering capabilities.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context.
[in]setgboolean: TRUE if setting capabilities, FALSE if unsetting them.
[in]dataClient data.
Returns
A GArray instance with the capabilities to be set or unset. The elements should be of type ToolsAppCapability.

◆ TOOLS_CORE_SIG_CONF_RELOAD

#define TOOLS_CORE_SIG_CONF_RELOAD   "tcs_conf_reload"

Signal sent when the config file is reloaded.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_DUMP_STATE

#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]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_GUESTSTORE_STATE

#define TOOLS_CORE_SIG_GUESTSTORE_STATE   "tcs_gueststore_state"

Signal sent when GuestStore is enabled or disabled.

Parameters
[in]srcThe source object.
[in]enabledTRUE if VMX GuestStore access is enabled, FALSE otherwise.
[in]dataClient data.

◆ TOOLS_CORE_SIG_NO_RPC

#define TOOLS_CORE_SIG_NO_RPC   "tcs_no_rpc"

Signal sent when RpcChannel is going to be destroyed.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_RESET

#define TOOLS_CORE_SIG_RESET   "tcs_reset"

Signal sent when a successful RpcChannel reset occurs.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_SET_OPTION

#define TOOLS_CORE_SIG_SET_OPTION   "tcs_set_option"

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

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]optiongchar *: Option being set.
[in]valuegchar *: Option value.
[in]dataClient data.
Returns
A gboolean saying whether the option was recognized and the value was valid.

◆ TOOLS_CORE_SIG_SHUTDOWN

#define TOOLS_CORE_SIG_SHUTDOWN   "tcs_shutdown"

Signal sent when shutting down the service.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: The application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_XIOERROR

#define TOOLS_CORE_SIG_XIOERROR   "tcs_de_xioerror"

Signal emitted upon X I/O error callback firing.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_XSM_DIE

#define TOOLS_CORE_SIG_XSM_DIE   "tcs_de_xsm_die"

Signal emitted upon SmcCallbacks::die.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_XSM_SAVE_COMPLETE

#define TOOLS_CORE_SIG_XSM_SAVE_COMPLETE   "tcs_de_xsm_save_complete"

Signal emitted upon SmcCallbacks::save_complete.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context.
[in]dataClient data.

◆ TOOLS_CORE_SIG_XSM_SAVE_YOURSELF

#define TOOLS_CORE_SIG_XSM_SAVE_YOURSELF   "tcs_de_xsm_save_yourself"

Signal emitted upon SmcCallbacks::save_yourself.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context. @parma[in] saveType Refer to SMlib.xml.
[in]shutdown0 = checkpoint, 1 = shutdown.
[in]interactStyleMay interact with user?
[in]fastShutdown as quickly as possible.
[in]dataClient data.

◆ TOOLS_CORE_SIG_XSM_SHUTDOWN_CANCELLED

#define TOOLS_CORE_SIG_XSM_SHUTDOWN_CANCELLED   "tcs_de_xsm_shutdown_cancelled"

Signal emitted upon SmcCallbacks::shutdown_cancelled.

Parameters
[in]srcThe source object.
[in]ctxToolsAppCtx *: the application context.
[in]dataClient data.

◆ TOOLS_IS_MAIN_SERVICE

#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]ctxThe application context or tools service state.

◆ TOOLS_IS_USER_SERVICE

#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]ctxThe application context or tools service state.

◆ TOOLS_MODULE_EXPORT

#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.

◆ VMTOOLSAPP_ATTACH_SOURCE

#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]ctxThe application context.
[in]srcSource to attach.
[in]cbCallback to call when event is "ready".
[in]dataData to provide to the callback.
[in]destroyDestruction notification callback.

◆ VMTOOLSAPP_ERROR

#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]ctxThe application context.
[in]errError code. Must not be 0.

Typedef Documentation

◆ RegisterServiceProperty

typedef void(* RegisterServiceProperty) (gpointer obj, struct ToolsServiceProperty *prop)

Type of the function that installs a new property in the application context service object.

Parameters
[in]objThe application context service object.
[in]propProperty to install.

◆ ToolsAppCapability

typedef struct ToolsAppCapability ToolsAppCapability

Information about a capability supported by the application. This structure supports both old-style capabilities (which have a separate RPC message for each capability) and new-style capabilities (as defined in guestCaps.h).

The service will register all capabilities with non-zero values when the service is started (or the host asks for the service to register its capabilities).

◆ ToolsAppCtx

typedef struct ToolsAppCtx ToolsAppCtx

Defines the context of a tools application. This data is provided by the core services to applications when they're loaded.

◆ ToolsAppProvider

typedef struct ToolsAppProvider ToolsAppProvider

Defines the registration data for an "application provider". Application providers allow plugins to hook into new application frameworks that will be then managed by vmtoolsd - for example, an HTTP server or a dbus endpoint.

Application providers will be loaded during startup but not activated until at least one plugin provides registration data for that provider.

◆ ToolsAppReg

typedef struct ToolsAppReg ToolsAppReg

Defines a "app-specific" registration. The array contains data specific to an "application provider" implementation.

When the service is shutting down, if the data field is not NULL, the array instance will be freed, including its backing element array. See the documentation for g_array_free(). This will happen only after any plugin's shutdown callback is called, so plugins have a chance of performing custom clean up of this data.

◆ ToolsPluginData

typedef struct ToolsPluginData ToolsPluginData

The registration data for an application. This gives the service information about all functionality exported by the application, and any events that the application may be interested in.

When the plugin is shut down, if the regs field is not NULL, it (and its element array) are freed with g_array_free().

Plugins shouldn't try to free the returned structure, since the container will try to use it even after the shutdown signal is sent to plugins. The pointer should either point to statically allocated memory, or be leaked (which should't be a problem since it will only be really leaked when the process is shutting down).

◆ ToolsPluginOnLoad

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

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

◆ ToolsPluginSignalCb

typedef struct ToolsPluginSignalCb ToolsPluginSignalCb

Defines a struct for mapping callbacks to signals. Normally it would suffice to use g_signal_connect() directly to register interest in signals; but to allow dynamic registration of signals by plugins, using this struct allows registration to be delayed until all plugins have been loaded and have had the chance to register their own signals. The daemon code then can go through the plugins' registration data and connect all desired signals.

◆ ToolsPluginSvcGuestStore

typedef struct ToolsPluginSvcGuestStore ToolsPluginSvcGuestStore

Type of the public interface of the guestStore plugin.

This struct is published in the tools application context service object's TOOLS_PLUGIN_SVC_PROP_GUESTSTORE property.

◆ ToolsServiceProperty

typedef struct ToolsServiceProperty ToolsServiceProperty

Defines a property that is exposed through the containers instance object (ToolsAppCtx::serviceObj). Plugins can expose properties through this mechanism to share state with other plugins. Properties can be accessed using GObject's g_set_property / g_get_property APIs, or monitored by registering for the "notify" signal on the object.

All properties exposed using this mechanism are opaque pointers. It's up for individual plugins to define the actual types of the properties.

Properties are not ref counted, so consumers (code calling "g_get_property") should be aware of the life cycle of the property as defined by the producer.

Enumeration Type Documentation

◆ ToolsAppType

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

◆ ToolsCapabilityType

Identifies the type of a Tools capability.

◆ ToolsCoreAPI

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.