Block plugins callbacks

Detailed Description


Data Structures

struct  _ntar_data_chunk
 Element of a list representing a generic blob (block of bytes) that have to be written to a trace file, or have been read out of it. More...
struct  _ntar_plugin_data
 This structure is used to uniquely identify a given plugin. It contains the unique identifier of a block, as well as all the pointers to the plugin callbacks. More...

Typedefs

typedef _ntar_data_chunk ntar_data_chunk
 Element of a list representing a generic blob (block of bytes) that have to be written to a trace file, or have been read out of it.
typedef int(* plugin_init )(void **plugin_state)
 Initializes a given plugin state.
typedef int(* plugin_destroy )(void *plugin_state)
 Destroys a given plugin state.
typedef int(* plugin_write_data )(void *plugin_state, void *data, void *data_buffer, size_t *pbuffer_size)
 Formats the data of a block in order to be written to some storage.
typedef int(* plugin_write_option )(void *plugin_state, ntar_option *option, void *opt_buffer, size_t *pbuffer_size)
 Formats the option data of a block option in order to be written to some storage.
typedef int(* plugin_validate_option )(void *plugin_state, ntar_option *option)
 Verifies that a given option is compatible with a given block.
typedef int(* plugin_read_data )(void *plugin_state, int byte_order, void *raw_data, size_t raw_data_size, void **data_buffer, size_t *pbuffer_size, size_t *poption_start)
 This function should decode the data of a block to a library provided memory buffer.
typedef int(* plugin_read_option )(void *plugin_state, option_header *opt_header, int byte_order, void *opt_buffer, size_t *pbuffer_size)
 This function should decode the option data of a block to a library provided memory buffer.
typedef _ntar_plugin_data ntar_plugin_data
 This structure is used to uniquely identify a given plugin. It contains the unique identifier of a block, as well as all the pointers to the plugin callbacks.

Functions

ntar_plugin_data * get_plugin_data (u_int32 block_id)
 This function returns a pointer to a ntar_plugin_data structure uniquely identifying the callbacks of a given block.

Variables

ntar_plugin_data ntar_plugins []

Typedef Documentation

typedef struct _ntar_data_chunk ntar_data_chunk
 

Element of a list representing a generic blob (block of bytes) that have to be written to a trace file, or have been read out of it.

A NULL terminated list of such blocks is dumped to disk without any further modification, and no checks are performed on the contents of the internal buffer.

typedef struct _ntar_plugin_data ntar_plugin_data
 

This structure is used to uniquely identify a given plugin. It contains the unique identifier of a block, as well as all the pointers to the plugin callbacks.

typedef int(* plugin_destroy)(void *plugin_state)
 

Destroys a given plugin state.

This callback is called when a block is closed.

Parameters:
plugin_state state of the plugin, as returned by plugin_init.
Returns:
Note:
Each plugin is initialized and destroyed for each read/written block (if the block type matches the plugin type).

typedef int(* plugin_init)(void **plugin_state)
 

Initializes a given plugin state.

This callback is called whenever the data of a block whose type matches with the given plugin is retrieved (i.e. through ntar_get_block_data or ntar_get_block_options) The plugin can initialize its internal structures and return a handle to such data in the parameter plugin_state

Parameters:
plugin_state Address of a library defined void pointer. On return, the plugin can set the value of this pointer to the state of its internal variables.
Returns:
Note:
Each plugin is initialized and destroyed for each read/written block (if the block type matches the plugin type).

typedef int(* plugin_read_data)(void *plugin_state, int byte_order, void *raw_data, size_t raw_data_size, void **data_buffer, size_t *pbuffer_size, size_t *poption_start)
 

This function should decode the data of a block to a library provided memory buffer.

Parameters:
plugin_state State of the plugin, set by plugin_init
byte_order Byte order of the current section. Possible values are HOST_BYTE_ORDER and SWAPPED_HOST_BYTE_ORDER. The callback must always return data in host byte order.
raw_data Raw data of the block, as written to file.
raw_data_size On input, it contains the length of the raw_data buffer, on output the plugin should fill it with the number of bytes actually read from the raw_data buffer.
data_buffer Address of the pointer to a library provided buffer that has to be used to return the decoded block data. This address can contain the same pointer passed on input, a pointer to an address in the raw_data buffer, or a pointer to some memory allocated by the plugin in the plugin_init phase. In this last case, such memory should be considered owned by the library up to the next call of plugin_read_data or plugin_destroy.
pbuffer_size On input, it points to an integer containing the length of parameter data_buffer. On output, it contains the number of bytes actually used in data_buffer (if the buffer was big enough) or the number of needed bytes, if the data_buffer was too small.
Returns:
The callback should return one of the following codes:
Todo:
The note on data_buffer in [out] is again confusing. Is it possible that the library calls this function twice (when the fcn succeeds)? I don't think so.

typedef int(* plugin_read_option)(void *plugin_state, option_header *opt_header, int byte_order, void *opt_buffer, size_t *pbuffer_size)
 

This function should decode the option data of a block to a library provided memory buffer.

Parameters:
plugin_state State of the plugin, set by plugin_init
opt_header Header of the option, already converted in host byte order. The data of the option immediately follow the option header.
byte_order Byte order of the current section. Possible values are HOST_BYTE_ORDER and SWAPPED_HOST_BYTE_ORDER. The callback must always return data in host byte order.
opt_buffer Address of the pointer to a library provided buffer that has to be used to return the decoded option data. This address can contain the same pointer passed on input, a pointer to an address in the opt_header buffer, or a pointer to some memory allocated by the plugin in the plugin_init phase. In this last case, such memory should be considered owned by the library up to the next call of plugin_read_option or plugin_destroy.
pbuffer_size On input, it points to an integer containing the length of parameter opt_buffer. On output, it contains the number of bytes actually used in opt_buffer (if the buffer was big enough) or the number of needed bytes, if the opt_buffer was too small.
Returns:
The callback should return one of the following codes:

Todo:
The note on opt_buffer in [out] is again confusing. Is it possible that the library calls this function twice (when the fcn succeeds)? I don't think so.

typedef int(* plugin_validate_option)(void *plugin_state, ntar_option *option)
 

Verifies that a given option is compatible with a given block.

This plugin callback is called by the library when the user tries to add an option to a block using ntar_add_block_option. It should return success only if the option is actually supported by the block *and* the data associated with the option have a proper format.

Parameters:
plugin_state State of the plugin, set by plugin_init
option Pointer to a ntar_option, as passed to ntar_add_block_option.
Returns:
The callback should return one of the following codes:
Note:
The library does not request the verification for the standard options COMMENT and END_OF_OPTIONS.
  • The plugin should create a NULL terminated linked list of ntar_data_chunk elements, using the memory provided in data_buffer.

typedef int(* plugin_write_data)(void *plugin_state, void *data, void *data_buffer, size_t *pbuffer_size)
 

Formats the data of a block in order to be written to some storage.

This plugin callback is called by the library when a block should be written to some storage. This callback should format the buffer provided by the user through ntar_create_block in the correct format that should be written to some storage.. In particular, this function should write the data of a block to a library provided memory buffer.

Parameters:
plugin_state State of the plugin, set by plugin_init
data Data of the block to be written. This is the data that the user provided with ntar_create_block
data_buffer Library provided buffer that has to be used to create a linked list of ntar_data_chunk elements. The first element in the list should reside at the very beginning of this buffer. The library will write these blocks to the storage.
pbuffer_size On input, it points to an integer containing the length of the data_buffer. On output, it contains the number of bytes actually used in data_buffer (if the buffer was big enough) or the number of needed bytes, if the data_buffer was too small.
Returns:
The callback should return one of the following codes:
Note:
  • The plugin should create a NULL terminated linked list of ntar_data_chunk elements, using the memory provided in data_buffer.
  • The plugin can fill the linked list with chunks of memory taken from the data_buffer, or from the data parameter, or from some memory allocated in the plugin_init phase. In this last case, such memory should be considered owned by the library up to the next call of plugin_write_data or plugin_destroy.
Todo:
The last note is confusing. Is this callback suposed to be called more than once (supposing it succeeds) for one single block. I don't think so. And this should be clearly stated.

typedef int(* plugin_write_option)(void *plugin_state, ntar_option *option, void *opt_buffer, size_t *pbuffer_size)
 

Formats the option data of a block option in order to be written to some storage.

This plugin callback is called by the library when a block option should be written to some storage. This callback should format the buffer provided by the user through ntar_add_block_option in the correct format that should be written to some storage.. In particular, this function should write the data of a block option to a library provided memory buffer.

Note:
  • The library takes care of writing the two standard options (COMMENT and END_OF_OPTIONS) without calling the specific block option writer call.
  • The library provides a set of optimized functions to save the most common option types:
    • write_option_uint32 writes an unsigned 32bit integer to the caller provided buffer.
    • write_option_uint64 writes an unsigned 64bit integer to the caller provided buffer.
    • write_option_string writes a NULL terminated ANSI string to the caller provided buffer.
    • write_option_raw writes a blob (with a provided size) to the caller provided buffer, without any further modification.
Parameters:
plugin_state State of the plugin, set by plugin_init
option Pointer to antar_option, as passed to ntar_add_block_option.
data_buffer Library provided buffer that has to be used to create a linked list of ntar_data_chunk elements. The first element in the list should reside at the very beginning of this buffer. The library will write these blocks to the storage.
pbuffer_size On input, it points to an integer containing the length of the data_buffer. On output, it contains the number of bytes actually used in data_buffer (if the buffer was big enough) or the number of needed bytes, if the data_buffer was too small.
Returns:
The callback should return one of the following codes:
Note:
  • The plugin should create a NULL terminated linked list of ntar_data_chunk elements, using the memory provided in data_buffer.
  • The plugin can fill the linked list with chunks of memory taken from the data_buffer, or from the data parameter, or from some memory allocated in the plugin_init phase. In this last case, such memory should be considered owned by the library up to the next call of plugin_write_option or plugin_destroy.
Todo:
The last note is confusing. Is this callback suposed to be called more than once (supposing it succeeds) for one single block. I don't think so. And this should be clearly stated.

Function Documentation

ntar_plugin_data* get_plugin_data (  u_int32  block_id  ) 
 

This function returns a pointer to a ntar_plugin_data structure uniquely identifying the callbacks of a given block.

Parameters:
block_id Identifier of the block.
Returns:
A pointer to a ntar_plugin_data structure uniquely identified by the block ID, or NULL.

Variable Documentation

ntar_plugin_data ntar_plugins[]
 

Todo:
The definition of this list here is non-sense, as each source including this file will have its own copy of this array. This does not cause any problem, since all the values in the structures are constant, however it's a waste of memory (and it's not elegant!!).

NTAR documentation. Copyright (c) 2004 - 2005 Condor Engineering, Inc. All rights reserved.