/* * Copyright 1999-2014 University of Chicago * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef GLOBUS_NET_MANAGER_H #define GLOBUS_NET_MANAGER_H 1 #include "globus_common.h" #include "globus_net_manager_attr.h" #ifdef __cplusplus extern "C" { #endif /** * @file globus_net_manager.h * @brief Globus Net Manager Interface */ #ifndef GLOBUS_GLOBAL_DOCUMENT_SET /** * @mainpage Overview * The Globus Net Manager library is a plug-in point for network * management tasks, such as: * - selectively open ports in a firewall and allow these ports to be closed * when transfers are complete * - configure a virtual circuit based on a site policy and route traffic * over this circuit * - route network traffic related to a task over a particular network * * @section globus_net_manager_implementor Implementing a Network Manager * For users interested in implementing such functionality, * the @link globus_net_manager globus_net_manager library @endlink provides a * low-level set of interfaces to implement specific network managers. * * These interfaces provide methods for registering functions to be called * before and after interesting network operations. Those functions may * observe or modify the attributes of the network operations. This information * can be used to modify the port to listen on, or modify the * addresses used to use a particular network interface. * * In addition, the globus_net_manager library includes sample * implementations to provide a starting point for implementing * network managers. *
*
Logging Manager
*
Logs network operations as they occur. This implementation * shows the simplest network manager implementation in C
* *
@ref globus_net_manager_python
*
Loads a python module, and calls python functions when network * operations occur.
*
* * The Logging Manager sample is broken down in detail in the * @ref globus_net_manager_tutorial page. * * @section globus_net_manager_user Using Network Managers * For users interested in using the network manager in their own services, * they can use the @ref globus_net_manager_context APIs to configure and * invoke network manager plug-ins, or the * @link globus_xio_net_manager_driver Globus XIO Net Manager Driver @endlink * to plug the network manager interface directly into the Globus XIO stack. * * To configure a GridFTP server to use the network manager, use the * configuration option '-xnetmgr' ('xnetmgr' in the config file). The * parameters to this option are a list of managers and their configuration * attributes. See the @ref globus_net_manager_python documentation for an * example. */ #endif struct globus_net_manager_s; /** * @defgroup globus_net_manager Net Manager * @brief Net Manager API * * @details * This API defines the plug-in points for network manager functionality, * as well as functions for registering a particular network manager * implementation so that it can be invoked during network events. * * To implement a network manager, define a struct #globus_net_manager_s * with the functions you want called, and register it by calling * globus_net_manager_register(). More details are included in * @ref globus_net_manager_tutorial */ /** * @defgroup globus_net_manager_types Net Manager Data Types * @ingroup globus_net_manager * @brief Net Manager Data Types * * @details * Data types for the Net Manager interface. * @ref globus_net_manager_tutorial */ /** * @defgroup globus_net_manager_signatures Function Signatures * @ingroup globus_net_manager * @brief Net Manager Function Signatures * * Function signatures for the Net Manager interface. * @ref globus_net_manager_tutorial */ /** * @brief Net Manager Pre-Listen Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called before the transport-specific listening port has * been created. * * The network manager is passed the network transport-specific options * for the listener. It may modify these before the * listener is created by the transport. * * The globus_net_manager library aborts the listen operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_pre_listen functions configured for this listener. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_pre_listen)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const globus_net_manager_attr_t *attr_array, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager Post-Listen Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called after the transport-specific listening port has * been created. * * The network manager is passed the network transport-specific options and * contact string for the listener. It may modify either of these before the * transport listener is made available to the service which requested * the listening port. * * The globus_net_manager library aborts the listen operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_post_listen functions configured for this listener. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the listener [in]. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. * @param[out] local_contact_out * A pointer to the local contact which the network manager wants to * return to the service. This may be NULL to indicate no change in * the contact. This value will be freed() by the globus_net_manager * library. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_post_listen)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const globus_net_manager_attr_t *attr_array, char **local_contact_out, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager End-Listen Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called when the transport-specific listening port will * be closed. * * The network manager is passed the network transport-specific options and * contact string for the listener. * * The globus_net_manager library aborts the closing of the listening port * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_end_listen functions configured for this listener. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the listener [in]. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. */ typedef globus_result_t (*globus_net_manager_end_listen)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const globus_net_manager_attr_t *attr_array); /** * @brief Net Manager Pre-Accept Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called before accepting a connection on a * transport-specific listening port. * * The network manager is passed the network transport-specific options and * contact string for the listener. It may modify the options before the * accept operation is complete. * * The globus_net_manager library aborts the accept operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_pre_accept functions configured for this listener. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the listener. * @param[in] attr_array * A NULL-terminated array of transport attributes associated with the * listener. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_pre_accept)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const globus_net_manager_attr_t *attr_array, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager Post-Accept Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called after accepting a connection on a * transport-specific listening port. * * The network manager is passed the network transport-specific options and * contact string for both ends of the connection. It may modify the attributes * of the local side of the connection. * * The globus_net_manager library aborts the accept operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_post_accept functions configured for this connection. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the local side of the * connection. * @param[in] remote_contact * The transport-specific contact string for the remote side of the * connection. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_post_accept)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const char *remote_contact, const globus_net_manager_attr_t *attr_array, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager Pre-Connect Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called after initiating a connection to a * transport-specific listener. * * The network manager is passed the network transport-specific options and * contact string for both ends of the connection. It may modify the attributes * of the local side of the connection. * * The globus_net_manager library aborts the connect operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_pre_connect functions configured for this connection. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] remote_contact * The transport-specific contact string for the remote side of the * connection. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. * @param[out] remote_contact_out * A pointer to the remote contact which the network manager wants to * connect to. This may be NULL to indicate no change in * the contact. This value will be freed() by the globus_net_manager * library. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_pre_connect)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *remote_contact, const globus_net_manager_attr_t *attr_array, char **remote_contact_out, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager Post-Connect Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called after establishing a connection to a * transport-specific listener. * * The network manager is passed the network transport-specific options and * contact string for both ends of the connection. It may modify the attributes * of the local side of the connection. * * The globus_net_manager library aborts the connect operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_post_connect functions configured for this connection. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] remote_contact * The transport-specific contact string for the remote side of the * connection. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. * @param[out] attr_array_out * A pointer to an array of transport options to apply to the * listener prior to returning it to the service. This may be NULL to * indicate no change in the options. If non-NULL, this array must be * terminated with an attribute having a NULL scope. * The array and the members of the * globus_net_manager_attr_t struct will be freed by the * globus_net_manager library by calling * free(). */ typedef globus_result_t (*globus_net_manager_post_connect)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const char *remote_contact, const globus_net_manager_attr_t *attr_array, globus_net_manager_attr_t **attr_array_out); /** * @brief Net Manager Pre-Close Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called prior to closing a connection. * * The network manager is passed the network transport-specific options and * contact string for both ends of the connection. * * The globus_net_manager library aborts the close operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_pre_close functions configured for this connection. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the local side of the * connection. * @param[in] remote_contact * The transport-specific contact string for the remote side of the * connection. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. */ typedef globus_result_t (*globus_net_manager_pre_close)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const char *remote_contact, const globus_net_manager_attr_t *attr_array); /** * @brief Net Manager Post-Close Function Signature * @ingroup globus_net_manager_signatures * @details * A function of this signature, if included in a network manager * implementation, is called after closing a connection. * * The network manager is passed the network transport-specific options and * contact string for both ends of the connection. * * The globus_net_manager library aborts the close operation * if this function returns a value other than GLOBUS_SUCCESS. In this * case, the globus_net_manager will not call any other * globus_net_manager_pre_close functions configured for this connection. * * @param[in] manager * Pointer to the network manager struct that is being invoked. * @param[in] manager_attr_array * An array of attributes associated with the * manager. The end of the array is indicated by * an attribute containing a NULL scope. * @param[in] task_id * An application-specific task ID associated with this network operation. * @param[in] transport * The name of the transport associated with this listener. * @param[in] local_contact * The transport-specific contact string for the local side of the * connection. * @param[in] remote_contact * The transport-specific contact string for the remote side of the * connection. * @param[in] attr_array * An array of transport attributes associated with the * listener. The end of the array is indicated by * an attribute containing a NULL scope. */ typedef globus_result_t (*globus_net_manager_post_close)( struct globus_net_manager_s *manager, const globus_net_manager_attr_t *manager_attr_array, const char *task_id, const char *transport, const char *local_contact, const char *remote_contact, const globus_net_manager_attr_t *attr_array); /** * @brief Net Manager Definition * @ingroup globus_net_manager_types * @details */ typedef struct globus_net_manager_s { /** Name of the network manager */ const char *name; /** Pre-listen function implementation */ globus_net_manager_pre_listen pre_listen; /** Post-listen function implementation */ globus_net_manager_post_listen post_listen; /** End-listen function implementation */ globus_net_manager_end_listen end_listen; /** Pre-accept function implementation */ globus_net_manager_pre_accept pre_accept; /** Post-accept function implementation */ globus_net_manager_post_accept post_accept; /** Pre-connect function implementation */ globus_net_manager_pre_connect pre_connect; /** Post-connect function implementation */ globus_net_manager_post_connect post_connect; /** Pre-close function implementation */ globus_net_manager_pre_close pre_close; /** Post-close function implementation */ globus_net_manager_post_close post_close; } globus_net_manager_t; extern globus_extension_registry_t globus_i_net_manager_registry; #define GLOBUS_NET_MANAGER_REGISTRY &globus_i_net_manager_registry globus_result_t globus_net_manager_register( globus_net_manager_t *manager, globus_module_descriptor_t *module); globus_result_t globus_net_manager_unregister( globus_net_manager_t *manager); extern globus_module_descriptor_t globus_i_net_manager_module; /** * @brief Module descriptor * @ingroup globus_net_manager * @hideinitializer * @details * The Globus Net Manager uses Grid Community Toolkit module activation and * deactivation. Before any Net Manager functions can be called, * the module must be activated, like this: * @code globus_module_activate(GLOBUS_NET_MANAGER_MODULE); @endcode * * This function returns GLOBUS_SUCCESS if the library * is successfully initialized. Otherwise, an error code is returned, * and Net Manager functions should not be subsequently called. * * Activations are reference counted, so it is safe to activate the * module multiple times or in different modules. * * To deactivate Net Manager, call * * @code globus_module_deactivate(GLOBUS_NET_MANAGER_MODULE); @endcode * * This function should be done once for each time the Net Manager * was activated. * */ #define GLOBUS_NET_MANAGER_MODULE (&globus_i_net_manager_module) typedef enum { GLOBUS_NET_MANAGER_ERROR_PARAMETER, GLOBUS_NET_MANAGER_ERROR_MEMORY, GLOBUS_NET_MANAGER_ERROR_INIT, GLOBUS_NET_MANAGER_ERROR_MANAGER, GLOBUS_NET_MANAGER_ERROR_WRAPPED } globus_net_manager_error_type_t; /* all macros in this file require each function to 'declare' their name with * this */ #define GlobusNetManagerName(func) /* #ifdef __GNUC__ #define GlobusNetManagerName(func) static const char * _netmgr_name __attribute__((__unused__)) = #func #else #define GlobusNetManagerName(func) static const char * _netmgr_name = #func #endif */ #define GlobusNetManagerErrorParameter(param_name) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ GLOBUS_NULL, \ GLOBUS_NET_MANAGER_ERROR_PARAMETER, \ __FILE__, \ __func__, \ __LINE__, \ "Bad parameter, %s", \ (param_name))) #define GlobusNetManagerErrorMemory(mem_name) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ GLOBUS_NULL, \ GLOBUS_NET_MANAGER_ERROR_MEMORY, \ __FILE__, \ __func__, \ __LINE__, \ "Memory allocation failed on %s", \ (mem_name))) #define GlobusNetManagerErrorInit(manager, explain) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ NULL, \ GLOBUS_NET_MANAGER_ERROR_INIT, \ __FILE__, \ __func__, \ __LINE__, \ "An error occurred accessing a module. %s: %s", manager, explain)) #define GlobusNetManagerErrorManager(result, manager, explain) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ globus_error_get((result)), \ GLOBUS_NET_MANAGER_ERROR_MANAGER, \ __FILE__, \ __func__, \ __LINE__, \ "A network manager (%s) errored in %s.", manager, explain)) #define GlobusNetManagerErrorWrapFailed(failed_func, result) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ globus_error_get((result)), \ GLOBUS_NET_MANAGER_ERROR_WRAPPED, \ __FILE__, \ __func__, \ __LINE__, \ "%s failed.", \ (failed_func))) #define GlobusNetManagerErrorWrapFailedWithMessage(result, format, arg) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ globus_error_get((result)), \ GLOBUS_NET_MANAGER_ERROR_WRAPPED, \ __FILE__, \ __func__, \ __LINE__, \ (format), \ (arg))) #define GlobusNetManagerErrorWrapFailedWithMessage2(result, format, arg1, arg2) \ globus_error_put( \ globus_error_construct_error( \ GLOBUS_NET_MANAGER_MODULE, \ globus_error_get((result)), \ GLOBUS_NET_MANAGER_ERROR_WRAPPED, \ __FILE__, \ __func__, \ __LINE__, \ (format), \ (arg1), (arg2))) #ifdef __cplusplus } #endif #endif /* GLOBUS_NET_MANAGER_H */