Debugging Tools Plugins

Defines functions and interfaces for debugging Tools plugins. More...

Data Structures

struct  RpcDebugRecvMapping
struct  RpcDebugMsgMapping
struct  RpcDebugMsgList
struct  RpcDebugPlugin
struct  RpcDebugLibData

Defines

#define RPCDEBUG_SET_RESULT(resultStr, result, resultLen)

Typedefs

typedef gboolean(* RpcDebugRecvFn )(char *data, size_t dataLen, char **result, size_t *resultLen)
typedef gboolean(* RpcDebugValidateFn )(RpcInData *data, Bool ret)
typedef gboolean(* RpcDebugSendFn )(RpcDebugMsgMapping *rpcdata)
typedef void(* RpcDebugShutdownFn )(ToolsAppCtx *ctx, struct RpcDebugPlugin *plugin)
typedef RpcDebugPlugin *(* RpcDebugOnLoadFn )(ToolsAppCtx *ctx)
typedef RpcDebugLibData *(* RpcDebugInitializeFn )(ToolsAppCtx *, gchar *)

Functions

void RpcDebug_DecRef (ToolsAppCtx *ctx)
void RpcDebug_IncRef (void)
RpcDebugLibDataRpcDebug_Initialize (ToolsAppCtx *ctx, gchar *dbgPlugin)
RpcChannelRpcDebug_NewDebugChannel (ToolsAppCtx *ctx, RpcDebugLibData *data)
gboolean RpcDebug_SendNext (RpcDebugMsgMapping *rpcdata, RpcDebugMsgList *list)
void RpcDebug_Shutdown (ToolsAppCtx *ctx, RpcDebugLibData *data)

Detailed Description

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.

How debug plugins work

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 Documentation

#define RPCDEBUG_SET_RESULT ( resultStr,
result,
resultLen   ) 

Value:

do { \
   char *__resultStr = (resultStr);                            \
   char **__result = (result);                                 \
   size_t *__resultLen = (resultLen);                          \
   if (__result != NULL) {                                     \
      *__result = Util_SafeStrdup(__resultStr);                \
   }                                                           \
   if (__resultLen != NULL) {                                  \
      *__resultLen = strlen(__resultStr);                      \
   }                                                           \
} while (0)
Helper macro to set result / resultLen when responding to an RPC.

Parameters:
[in] resultStr The string to set.
[out] result Where to store the result.
[out] resultLen Where to store the length.


Typedef Documentation

Signature of the library's initialization function.

Signature for the plugin's entry point. The function works in a similar way to the "ToolsOnLoad" function for regular plugins.

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 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, Bool 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.


Generated on Wed Nov 4 15:44:55 2009 for open-vm-tools 2009.10.15 by  doxygen 1.5.5