Main Page | Modules

Required Plugin Functions

Functions signatures for plugin functions. More...

Typedefs

Detailed Description

Functions signatures for plugin functions.

Typedef Documentation

typedef int(* nees_ntcp_plugin_propose_t)( void * arg, const nees_ntcp_transaction_handle_t transaction, globus_bool_t * result)
 

The plugin does site-specific validation of a transaction (such as verifying that all the control points that appear in the request actually exist, or that the control point parameters specified in the transaction request do not exceed any site-specific maximum values).

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
transaction A transaction handle containing a transaction name and any control point parameters associated with this proposed transaction.
result A pointer to a boolean return value. If this function doesn't encounter an exception while validating the transaction, it must set the boolean's value to either
GLOBUS_TRUE
All site-specific conditions for accepting the proposed transaction are met.
GLOBUS_FALSE
Any site-specific condition for accepting the proposed transaction was not met.
Returns:
If any error occurs while attempting to validate the proposed transaction, then this function must return a non-zero value. In that case, the NTCP server will ignore the value of the boolean pointed to by the result parameter and an exception will be thrown.

typedef int(* nees_ntcp_plugin_execute_t)( void * arg, nees_ntcp_transaction_handle_t transaction)
 

The plugin begins asynchronously processing the proposed transaction. If this transaction completes successfully, the plugin must call nees_ntcp_transaction_handle_set_resulting_control_points() with the resulting control point status. If this transaction completes unsuccessfully, then the plugin must call nees_ntcp_transaction_handle_mark_terminated().

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
transaction A transaction handle containing a transaction name and any control point parameters associated with this transaction. If the plugin instance is able to begin executing the transaction successfully, then it may retain a reference to this transaction handle until the transaction is completed, either by the plugin calling nees_ntcp_transaction_handle_set_resulting_control_points(), nees_ntcp_transaction_handle_mark_terminated(), or via a successful return from the plugin's cancel function. After any of those conditions are met, the plugin must no longer access its reference to the transaction handle.
Returns:
If any error occurs while attempting to validate or begin executing the proposed transaction, then this function must return a non-zero value.

typedef int(* nees_ntcp_plugin_cancel_t)( void * arg, const nees_ntcp_transaction_handle_t transaction)
 

The plugin attempts to cancel transaction described by the transaction handle. This function blocks until the specified transaction is either completely cancelled or something exceptional prevents the cancellation from being processed.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
transaction A transaction handle containing a transaction name and any control point parameters associated with this transaction.
Returns:
If the plugin is able to cancel the transaction, it must return zero from this function; otherwise, it must return a non-zero value.

typedef int(* nees_ntcp_plugin_get_control_point_t)( void * arg, const char * name, nees_ntcp_control_point_t * result_point)
 

The plugin returns the values of the named control point.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
name The name of the control point whose value is being requested.
result_point A pointer to a control point which the plugin must initialize and set to a valid control point if the named point is known by the plugin; otherwise, this pointer must be set to NULL. The plugin must not access or free the result point after this function returns.
Returns:
If the plugin is able to set the value of the result_point point successfully, it must return zero; otherwise, it must return a non-zero value.

typedef int(* nees_ntcp_plugin_set_parameter_t)( void * arg, const nees_ntcp_parameter_t parameter)
 

The plugin processes a change in the value of a parameter. The plugin does any required site-specific validation and action based on the new value of the parameter.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
parameter The new value of the parameter. The plugin must not access the parameter outside of this function scope. If the plugin wants to retain a copy of this value, it must make its own copy using nees_ntcp_parameter_copy().
Returns:
If the new parameter value is accepted by the plugin, the plugin must return zero; otherwise, it must return a non-zero value.

typedef int(* nees_ntcp_plugin_get_parameter_t)( void * arg, const char * name, nees_ntcp_parameter_t * result_parameter)
 

The plugin processes a request to find the current value of the requested parameter.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
name The name of the parameter whose value is being requested.
result_parameter A pointer to a parameter which the plugin should modify to point to a newly initialized parameter. If the parameter is unknown by the plugin, it should not modify the result_parameter value to indicate that it is unknown.
Returns:
If no the parameter is unknown, or its value is set in result_parameter successfully, then this function must return zero; otherwise otherwise, it must return a non-zero value to indicate an error occurred.

typedef int(* nees_ntcp_plugin_open_session_t)( void * arg, const nees_ntcp_parameter_t * parameter_array, size_t parameter_array_size)
 

The plugin prepares to run an experiment by setting initial state as necessary.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
parameter_array An array of parameters. Which the plugin may use to initialize the experiment. If the plugin wishes to access any of these parameters after this function returns, it must call nees_ntcp_control_plugin_parameter_copy() to create a copy of that parameter. Any copies made by the plugin must be freed by the plugin.
parameter_array_size The number of entries in the parameter array.
Returns:
If the session state is initialized successfully, the plugin must return zero; otherwise, it must return a non-zero value.

typedef int(* nees_ntcp_plugin_close_session_t)( void * arg)
 

The plugin prepares to end an experiment by doing any site-specific shutdown procedure.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called.
Returns:
If the session state is shut down successfully, the plugin must return zero; otherwise, it must return a non-zero value.

typedef int(* nees_ntcp_plugin_error_string_t)( void * arg, int error_code, char ** string)
 

The plugin converts an error code returned from one of its functions to an error string.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called. If the error_code value was generated by the initialize_plugin function, then this parameter will be NULL.
error_code A non-zero value returned previously from one of the plugin functions.
string A pointer to a char * which the plugin will allocate and populate with an error description string. If this is set to a NULL value, a default unhelpful string will be provided by the plugin interface. The string will be freed by the plugin interface.
Returns:
If the plugin generates a string successfully then this function must return zero; otherwise, it must return a non-zero value and the string value will be ignored (and not freed by the plugin interface).

typedef void(* nees_ntcp_plugin_destroy_t)( void * arg)
 

The plugin destroys any state associated with the plugin instance. This will only be called after all transactions executing in the plugin have been successfully terminated or cancelled. The plugin interface will no longer make any calls into the plugin until the initialize_plugin is called again.

Parameters:
arg The plugin instance-specific data value returned when the plugin's initialize_plugin function was called. This value may be freed by the plugin, if appropriate, as the plugin interface will no longer use it.
Returns:
void

typedef int(* nees_ntcp_plugin_init_t)( void ** arg, nees_ntcp_plugin_propose_t * propose, nees_ntcp_plugin_execute_t * execute, nees_ntcp_plugin_cancel_t * cancel, nees_ntcp_plugin_get_control_point_t * get_control_point, nees_ntcp_plugin_set_parameter_t * set_parameter, nees_ntcp_plugin_get_parameter_t * get_parameter, nees_ntcp_plugin_open_session_t * open_session, nees_ntcp_plugin_close_session_t * close_session, nees_ntcp_plugin_error_string_t * error_string, nees_ntcp_plugin_destroy_t * destroy)
 

The plugin implementation initializes a new plugin instance by returning a pointer to a plugin instance-specific value and pointers to function pointers used to implement the plugin.

Parameters:
arg A pointer to a void * value which the plugin may use to point to a plugin instance-specific data structure. This value will be passed to all of the plugin function pointers.
propose A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to propose a new transaction to the plugin.
execute A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin begin executing a transaction.
cancel A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin cancel a transaction.
get_control_point A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin return the current value of a control point.
set_parameter A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin set the value of a named parameter.
get_parameter A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin get the value of a named parameter.
open_session A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin do any necessary local initialization.
close_session A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin do any necessary local deactivation.
error_string A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to have the plugin translate an integer error code to an error string.
destroy A pointer to a function pointer. This value must be modified by the plugin to point to a function which the plugin interface will call to destroy this plugin instance.
Returns:
If the plugin is able to initialize the plugin instance, it must return zero from this function; otherwise, it must return a non-zero value.

about globus | grid research | globus toolkit | software development

Comments? webmaster@globus.org