open-vm-tools 12.0.5
|
Defines functions and interfaces for debugging Tools plugins. More...
Data Structures | |
struct | RpcDebugRecvMapping |
struct | RpcDebugMsgMapping |
struct | RpcDebugMsgList |
struct | RpcDebugPlugin |
struct | RpcDebugLibData |
Macros | |
#define | RPCDEBUG_ASSERT(test, retval) |
Typedefs | |
typedef gboolean(* | RpcDebugRecvFn) (char *data, size_t dataLen, char **result, size_t *resultLen) |
typedef struct RpcDebugRecvMapping | RpcDebugRecvMapping |
typedef gboolean(* | RpcDebugValidateFn) (RpcInData *data, gboolean ret) |
typedef struct RpcDebugMsgMapping | RpcDebugMsgMapping |
typedef struct RpcDebugMsgList | RpcDebugMsgList |
typedef gboolean(* | RpcDebugSendFn) (RpcDebugMsgMapping *rpcdata) |
typedef void(* | RpcDebugShutdownFn) (ToolsAppCtx *ctx, struct RpcDebugPlugin *plugin) |
typedef struct RpcDebugPlugin | RpcDebugPlugin |
typedef RpcDebugPlugin *(* | RpcDebugOnLoadFn) (ToolsAppCtx *ctx) |
typedef struct RpcDebugLibData | RpcDebugLibData |
typedef RpcDebugLibData *(* | RpcDebugInitializeFn) (ToolsAppCtx *, gchar *) |
Functions | |
G_BEGIN_DECLS void | RpcDebug_DecRef (ToolsAppCtx *ctx) |
void | RpcDebug_IncRef (void) |
RpcDebugLibData * | RpcDebug_Initialize (ToolsAppCtx *ctx, gchar *dbgPlugin) |
gboolean | RpcDebug_SendNext (RpcDebugMsgMapping *rpcdata, RpcDebugMsgList *list) |
void | RpcDebug_SetResult (const char *str, char **res, size_t *len) |
Defines functions and interfaces for debugging Tools plugins.
This module provides functions for writing "debug plugins" - plugins which provide functionality for driving the Tools Services when they're running in "debug mode". Debug plugins are dynamically loaded by providing specific command-line options to the Tools service process.
Currently, there's only support for GuestRPC-based debug plugins.
The debug library implements an RPC channel that can be driven by a debug plugin, according to information provided by the plugin at load time.
The debug plugin can provide two types of information:
For more details, check the RpcDebugPlugin data structure.
Plugins that depend on events that are not only responses to RPC messages (such as timer-based outgoing RPCs) should make sure they tell the library that it should not stop running by incrementing its ref count (see RpcDebug_IncRef()). When the test is complete, the code can then call RpcDebug_DecRef() and, when the ref count reaches zero, the main application loop will be stopped.
#define RPCDEBUG_ASSERT | ( | test, | |
retval | |||
) |
Shorthand macro to both call CU_ASSERT() and return from the function if the assertion fails. Note that this file doesn't include CUnit.h, so you'll need to include that header to use this macro.
typedef RpcDebugLibData*(* RpcDebugInitializeFn) (ToolsAppCtx *, gchar *) |
Signature of the library's initialization function.
typedef struct RpcDebugLibData RpcDebugLibData |
Describes the external interface of the library. An instance of this struct is returned by RpcDebug_Initialize() and can be used by applications using the library to use the debugging functionality.
typedef struct RpcDebugMsgList RpcDebugMsgList |
Defines a (NULL-terminated) list of message / validator mappings.
typedef struct RpcDebugMsgMapping RpcDebugMsgMapping |
Defines a mapping between a message and a "validate" function.
typedef RpcDebugPlugin*(* RpcDebugOnLoadFn) (ToolsAppCtx *ctx) |
Signature for the plugin's entry point. The function works in a similar way to the "ToolsOnLoad" function for regular plugins.
typedef struct RpcDebugPlugin RpcDebugPlugin |
Registration data for debug plugins, should be returned by the plugin's entry point function.
typedef gboolean(* RpcDebugRecvFn) (char *data, size_t dataLen, char **result, size_t *resultLen) |
Signature for the plugin's "receive" function, to validate the data applications send using RpcChannel_Send.
typedef struct RpcDebugRecvMapping RpcDebugRecvMapping |
Defines a mapping between a message and a "receive" function.
typedef gboolean(* RpcDebugSendFn) (RpcDebugMsgMapping *rpcdata) |
Signature for the plugin's "send" function, which provides the data to be sent when the service tries to read from the RPC Channel.
The function should return FALSE if the service should finish the test (any data provided when this function returns FALSE is ignored).
typedef void(* RpcDebugShutdownFn) (ToolsAppCtx *ctx, struct RpcDebugPlugin *plugin) |
Signature for the plugin's "shutdown" function.
typedef gboolean(* RpcDebugValidateFn) (RpcInData *data, gboolean ret) |
Signature for validation functions. Validation functions are called after an application has processed an "incoming" RPC, so that the plugin can validate the response.
G_BEGIN_DECLS void RpcDebug_DecRef | ( | ToolsAppCtx * | ctx | ) |
Decreases the internal ref count of the library. When the ref count reaches zero, this function will ask the application's main loop to stop running.
[in] | ctx | The application contexnt. |
void RpcDebug_IncRef | ( | void | ) |
Increases the internal ref count of the library. Test code that needs the process to stay alive should call this function to ensure that.
RpcDebugLibData* RpcDebug_Initialize | ( | ToolsAppCtx * | ctx, |
gchar * | dbgPlugin | ||
) |
Initializes the debug library and loads the debug plugin at the given path. This function panics if something goes wrong.
[in] | ctx | The application context. |
[in] | dbgPlugin | Path to the debug plugin. |
gboolean RpcDebug_SendNext | ( | RpcDebugMsgMapping * | rpcdata, |
RpcDebugMsgList * | list | ||
) |
Places the next item on the given RPC message list into the given RPC data. Updates the current index of the list.
[in] | rpcdata | The injected RPC data. |
[in] | list | The message list. |
void RpcDebug_SetResult | ( | const char * | str, |
char ** | res, | ||
size_t * | len | ||
) |
Sets res / len when responding to an RPC.
[in] | str | The string to set. |
[out] | res | Where to store the result. |
[out] | len | Where to store the length. |