gfal2/common/gfal_config.h

0001 /*
0002  * Copyright (c) CERN 2013-2017
0003  *
0004  * Copyright (c) Members of the EMI Collaboration. 2010-2013
0005  *  See  http://www.eu-emi.eu/partners for details on the copyright
0006  *  holders.
0007  *
0008  * Licensed under the Apache License, Version 2.0 (the "License");
0009  * you may not use this file except in compliance with the License.
0010  * You may obtain a copy of the License at
0011  *
0012  *    http://www.apache.org/licenses/LICENSE-2.0
0013  *
0014  * Unless required by applicable law or agreed to in writing, software
0015  * distributed under the License is distributed on an "AS IS" BASIS,
0016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0017  * See the License for the specific language governing permissions and
0018  * limitations under the License.
0019  */
0020
0021 #pragma once
0022 #ifndef GFAL_CONFIG_H_
0023 #define GFAL_CONFIG_H_
0024
0025 #if !defined(__GFAL2_H_INSIDE__) && !defined(__GFAL2_BUILD__)
0026 #   warning "Direct inclusion of gfal2 headers is deprecated. Please, include only gfal_api.h or gfal_plugins_api.h"
0027 #endif
0028
0029 #include "gfal_common.h"
0030
0031 #ifdef __cplusplus
0032 extern "C"
0033 {
0034 #endif
0035
0036 #define CORE_CONFIG_GROUP "CORE"
0037 #define CORE_CONFIG_CHECKSUM_TIMEOUT "CHECKSUM_TIMEOUT"
0038 #define CORE_CONFIG_NAMESPACE_TIMEOUT "NAMESPACE_TIMEOUT"
0039
0040
0041 /**
0042  * @file gfal_config.h
0043  * @brief gfal2 configuration API
0044  * set/get option for the running configuration of GFAL 2.0
0045  * @author Adrien Devresse
0046  */
0047
0048 /*!
0049     \defgroup config_group Parameter API
0050
0051
0052     Allows to overwrite or/and define any parameter of gfal2.
0053     A complete list of parameter is accessible in the gfal2 configuration files directory
0054     ( by default : /etc/gfal2.d/  )
0055
0056     Example ( enable IPv6 support for the gridFTP plugin ) :
0057         gfal2_set_opt_boolean("GRIDFTP PLUGIN", "IPV6", true, NULL);
0058
0059 */
0060
0061 /*!
0062     \addtogroup config_group
0063     @{
0064 */
0065
0066
0067 /**
0068  * @brief get a string parameter in the current GFAL 2.0 configuration
0069  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0070  *
0071  * @param context : context of gfal2
0072  * @param group_name : group name of the parameter
0073  * @param key : key of the parameter
0074  * @param error : GError error report system
0075  * @return parameter value. Must be freed using g_free
0076  **/
0077 gchar * gfal2_get_opt_string(gfal2_context_t context, const gchar *group_name,
0078                                     const gchar *key, GError **error);
0079
0080 /**
0081 * @brief similar to \ref gfal2_get_opt_string but return a default value if
0082 * an error occurs
0083  *
0084  * @param handle : context of gfal2
0085  * @param group_name : group name of the parameter
0086  * @param key : key of the parameter
0087  * @param default_value : Default value
0088  * @return parameter value. Must be freed using g_free
0089  **/
0090 gchar * gfal2_get_opt_string_with_default(gfal2_context_t handle, const gchar *group_name,
0091                                     const gchar *key, const gchar* default_value);
0092
0093 /**
0094  * @brief set a string parameter in the current GFAL 2.0 configuration
0095  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0096  *
0097  * @param context : context of gfal2
0098  * @param group_name : group name of the parameter
0099  * @param key : key of the parameter
0100  * @param value : value to set
0101  * @param error : GError error report system
0102  * @return parameter value
0103  **/
0104 gint gfal2_set_opt_string(gfal2_context_t context, const gchar *group_name,
0105                                     const gchar *key, const gchar* value, GError **error);
0106
0107 /**
0108  * @brief get an integer parameter in the current GFAL 2.0 configuration
0109  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0110  *
0111  * @param context : context of gfal2
0112  * @param group_name : group name of the parameter
0113  * @param key : key of the parameter
0114  * @param error : GError error report system
0115  * @return parameter value
0116  **/
0117 gint gfal2_get_opt_integer(gfal2_context_t context, const gchar *group_name,
0118                                  const gchar *key, GError **error);
0119
0120 /**
0121 * @brief similar to \ref gfal2_get_opt_integer but return a default value if
0122 * an error occurs
0123 *
0124 * @param handle : context of gfal2
0125 * @param group_name : group name of the parameter
0126 * @param key : key of the parameter
0127 * @param default_value : default value returned if not present
0128 * @return parameter value
0129 **/
0130 gint gfal2_get_opt_integer_with_default(gfal2_context_t handle, const gchar *group_name,
0131                                         const gchar *key, gint default_value);
0132
0133 /**
0134  * @brief set an integer parameter in the current GFAL 2.0 configuration
0135  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0136  *
0137  * @param context : context of gfal2
0138  * @param group_name : group name of the parameter
0139  * @param key : key of the parameter
0140  * @param value : value to set
0141  * @param error : GError error report system
0142  * @return parameter value
0143  **/
0144 gint gfal2_set_opt_integer(gfal2_context_t context, const gchar *group_name,
0145                                   const gchar *key, gint value,
0146                                   GError** error);
0147 /**
0148  * @brief set a boolean parameter in the current GFAL 2.0 configuration
0149  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0150  *
0151  * @param context : context of gfal2
0152  * @param group_name : group name of the parameter
0153  * @param key : key of the parameter
0154  * @param value : value to set
0155  * @param error : GError error report system
0156  * @return parameter value
0157  **/
0158 gint gfal2_set_opt_boolean(gfal2_context_t context, const gchar *group_name,
0159                                   const gchar *key, gboolean value, GError **error);
0160
0161 /**
0162 * @brief get a boolean parameter in the current GFAL 2.0 configuration
0163 *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0164 *
0165 * @param context : context of gfal2
0166 * @param group_name : group name of the parameter
0167 * @param key : key of the parameter
0168 * @param error : GError error report system
0169 * @return parameter value
0170 **/
0171 gboolean gfal2_get_opt_boolean(gfal2_context_t context, const gchar *group_name,
0172                                         const gchar *key, GError **error);
0173
0174
0175 /**
0176 * @brief similar to \ref gfal2_get_opt_boolean but return a default value if
0177 * an error occures
0178 *
0179 * @param context : context of gfal2
0180 * @param group_name : group name of the parameter
0181 * @param key : key of the parameter
0182 * @param default_value : default value returned if not present
0183 * @return parameter value
0184 **/
0185 gboolean gfal2_get_opt_boolean_with_default(gfal2_context_t context, const gchar *group_name,
0186                                            const gchar *key, gboolean default_value);
0187
0188
0189 /**
0190  * @brief set a list of string parameter in the current GFAL 2.0 configuration
0191  *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0192  *
0193  * @param context : context of gfal2
0194  * @param group_name : group name of the parameter
0195  * @param key : key of the parameter
0196  * @param list : list of strings
0197  * @param length : length of the list
0198  * @param error : GError error report system
0199  * @return parameter value
0200  **/
0201 gint gfal2_set_opt_string_list(gfal2_context_t context, const gchar *group_name,
0202                                      const gchar *key,
0203                                      const gchar * const list[],
0204                                      gsize length,
0205                                      GError ** error);
0206
0207 /**
0208 * @brief get a list of string parameter in the current GFAL 2.0 configuration
0209 *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0210 *
0211 * @param context : context of gfal2
0212 * @param group_name : group name of the parameter
0213 * @param key : key of the parameter
0214 * @param length : the length of the string is stored here
0215 * @param error : GError error report system
0216 * @return parameter value
0217 **/
0218 gchar ** gfal2_get_opt_string_list(gfal2_context_t context, const gchar *group_name,
0219                                           const gchar *key, gsize *length, GError **error);
0220
0221 /**
0222 * @brief get a list of string parameter in the current GFAL 2.0 configuration
0223 *  see gfal2.d configuration files or gfal2 documentation to know group/key/values
0224 *
0225 * @param context : context of gfal2
0226 * @param group_name : group name of the parameter
0227 * @param key : key of the parameter
0228 * @param length : the length of the string is stored here
0229 * @param default_value : Default array of not found
0230 * @return parameter value
0231 **/
0232 gchar ** gfal2_get_opt_string_list_with_default(gfal2_context_t context, const gchar *group_name,
0233                                           const gchar *key, gsize *length, char** default_value);
0234
0235 /**
0236  * @brief load configuration parameters from the file specified by path
0237  */
0238 gint gfal2_load_opts_from_file(gfal2_context_t context, const char* path, GError** error);
0239
0240 /**
0241  * Get all keys defined for the given group_name
0242  * @param context : context of gfal2
0243  * @param group_name : group name of the parameters
0244  * @param length : the number of keys is stored here
0245  * @param error : GError error report system
0246  * @return NULL on error. A NULL-terminated array with the list of keys. Use g_strfreev() to free it.
0247  */
0248 gchar **gfal2_get_opt_keys(gfal2_context_t context, const gchar *group_name, gsize *length, GError **error);
0249
0250
0251 /**
0252  * Removes a key from the settings
0253  * @param context : context of gfal2
0254  * @param group_name : group name of the parameters
0255  * @param key : key of the parameter
0256  * @param error : GError error report system
0257  * @return TRUE if the key was removed, FALSE otherwise
0258  */
0259 gboolean gfal2_remove_opt(gfal2_context_t context, const gchar *group_name,
0260     const gchar *key, GError **error);
0261
0262 /**
0263  * Set the user agent for those protocols that support this
0264  */
0265 gint gfal2_set_user_agent(gfal2_context_t handle, const char* user_agent,
0266         const char* version, GError** error);
0267
0268 /**
0269  * Returns the user agent and version specified before with gfal2_set_user_agent
0270  * Leave user_agent and version to NULL if not found
0271  */
0272 gint gfal2_get_user_agent(gfal2_context_t handle, const char** user_agent,
0273         const char** version);
0274
0275 /**
0276  * Add a new key/value pair with additional information to be passed to the storage
0277  * for protocols that support it.
0278  * For instance, this will be passed via CLIENTINFO for GridFTP, or the ClientInfo header for SRM and HTTP
0279  * Return < 0 on error
0280  */
0281 gint gfal2_add_client_info(gfal2_context_t handle, const char* key, const char* value, GError** error);
0282
0283 /**
0284  * Removes a key/value pair set previously with gfal2_add_client_info
0285  * Return < 0 on error
0286  */
0287 gint gfal2_remove_client_info(gfal2_context_t handle, const char* key, GError** error);
0288
0289 /**
0290  * Clear the client information
0291  * Return < 0 on error
0292  */
0293 gint gfal2_clear_client_info(gfal2_context_t handle, GError** error);
0294
0295 /**
0296  * Return how many custom pairs have been set
0297  * Return < 0 on error
0298  */
0299 gint gfal2_get_client_info_count(gfal2_context_t handle, GError** error);
0300
0301 /**
0302  * Put into key and value the pair at position index, or NULL if it does not exist
0303  * Return < 0 on error
0304  */
0305 gint gfal2_get_client_info_pair(gfal2_context_t handle, int index, const char** key,
0306         const char** value, GError** error);
0307
0308 /**
0309  * Put into value the value associated with the given key
0310  * Return < 0 on error
0311  */
0312 gint gfal2_get_client_info_value(gfal2_context_t handle, const char* key, const char** value, GError** error);
0313
0314 /**
0315  * For convenience, return all the key/value information in the form
0316  * key1=value1;key2=value2
0317  * The return value is NULL if there is no information. Otherwise, use g_free on it when done.
0318  */
0319 char* gfal2_get_client_info_string(gfal2_context_t handle);
0320
0321 /**
0322     @}
0323     End of the FILE group
0324 */
0325
0326 #ifdef __cplusplus
0327 }
0328 #endif
0329
0330
0331 #endif /* GFAL_CONFIG_H_ */
0332