Back to index

openldap  2.4.31
rewrite.h
Go to the documentation of this file.
00001 /* $OpenLDAP$
00002  */
00003 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
00004  *
00005  * Copyright 2000-2012 The OpenLDAP Foundation.
00006  * Portions Copyright 2000-2003 Pierangelo Masarati.
00007  * All rights reserved.
00008  *
00009  * Redistribution and use in source and binary forms, with or without
00010  * modification, are permitted only as authorized by the OpenLDAP
00011  * Public License.
00012  *
00013  * A copy of this license is available in file LICENSE in the
00014  * top-level directory of the distribution or, alternatively, at
00015  * <http://www.OpenLDAP.org/license.html>.
00016  */
00017 /* ACKNOWLEDGEMENT:
00018  * This work was initially developed by Pierangelo Masarati for
00019  * inclusion in OpenLDAP Software.
00020  */
00021 
00022 #ifndef REWRITE_H
00023 #define REWRITE_H
00024 
00025 /*
00026  * Default rewrite context
00027  */
00028 #define REWRITE_DEFAULT_CONTEXT           "default"
00029 
00030 /*
00031  * Rewrite engine states
00032  */
00033 #define REWRITE_OFF                0x0000
00034 #define REWRITE_ON                 0x0001
00035 #define REWRITE_DEFAULT                   REWRITE_OFF
00036 
00037 /*
00038  * Rewrite internal status returns
00039  */
00040 #define REWRITE_SUCCESS                   LDAP_SUCCESS
00041 #define REWRITE_ERR                LDAP_OTHER
00042 
00043 /*
00044  * Rewrite modes (input values for rewrite_info_init); determine the
00045  * behavior in case a null or non existent context is required:
00046  *
00047  *     REWRITE_MODE_ERR            error
00048  *     REWRITE_MODE_OK                    no error but no rewrite
00049  *     REWRITE_MODE_COPY_INPUT            a copy of the input is returned
00050  *     REWRITE_MODE_USE_DEFAULT    the default context is used.
00051  */
00052 #define REWRITE_MODE_ERR           0x0010
00053 #define REWRITE_MODE_OK                   0x0011
00054 #define REWRITE_MODE_COPY_INPUT           0x0012
00055 #define REWRITE_MODE_USE_DEFAULT   0x0013
00056 
00057 /*
00058  * Rewrite status returns
00059  *
00060  *     REWRITE_REGEXEC_OK          success (result may be empty in case
00061  *                                 of no match)
00062  *     REWRITE_REGEXEC_ERR         error (internal error,
00063  *                                 misconfiguration, map not working ...)
00064  *     REWRITE_REGEXEC_STOP        internal use; never returned
00065  *     REWRITE_REGEXEC_UNWILLING   the server should issue an 'unwilling
00066  *                                 to perform' error
00067  */
00068 #define REWRITE_REGEXEC_OK              (0)
00069 #define REWRITE_REGEXEC_ERR             (-1)
00070 #define REWRITE_REGEXEC_STOP            (-2)
00071 #define REWRITE_REGEXEC_UNWILLING       (-3)
00072 #define REWRITE_REGEXEC_USER              (1)    /* and above: LDAP errors */
00073 
00074 /*
00075  * Rewrite variable flags
00076  *     REWRITE_VAR_INSERT          insert mode (default) when adding
00077  *                                 a variable; if not set during value
00078  *                                 update, the variable is not inserted
00079  *                                 if not present
00080  *     REWRITE_VAR_UPDATE          update mode (default) when updating
00081  *                                 a variable; if not set during insert,
00082  *                                 the value is not updated if the
00083  *                                 variable already exists
00084  *     REWRITE_VAR_COPY_NAME              copy the variable name; if not set,
00085  *                                 the name is not copied; be sure the
00086  *                                 referenced string is available for
00087  *                                 the entire life scope of the variable.
00088  *     REWRITE_VAR_COPY_VALUE             copy the variable value; if not set,
00089  *                                 the value is not copied; be sure the
00090  *                                 referenced string is available for
00091  *                                 the entire life scope of the variable.
00092  */
00093 #define REWRITE_VAR_NONE           0x0000
00094 #define REWRITE_VAR_INSERT         0x0001
00095 #define REWRITE_VAR_UPDATE         0x0002
00096 #define REWRITE_VAR_COPY_NAME             0x0004
00097 #define REWRITE_VAR_COPY_VALUE            0x0008
00098 
00099 /*
00100  * Rewrite info
00101  */
00102 struct rewrite_info;
00103 
00104 struct berval; /* avoid include */
00105 
00106 LDAP_BEGIN_DECL
00107 
00108 /*
00109  * Inits the info
00110  */
00111 LDAP_REWRITE_F (struct rewrite_info *)
00112 rewrite_info_init(
00113               int mode
00114 );
00115 
00116 /*
00117  * Cleans up the info structure
00118  */
00119 LDAP_REWRITE_F (int)
00120 rewrite_info_delete(
00121                 struct rewrite_info **info
00122 );
00123 
00124 
00125 /*
00126  * Parses a config line and takes actions to fit content in rewrite structure;
00127  * lines handled are of the form:
00128  *
00129  *      rewriteEngine              {on|off}
00130  *      rewriteMaxPasses    numPasses
00131  *      rewriteContext             contextName [alias aliasedRewriteContex]
00132  *      rewriteRule         pattern substPattern [ruleFlags]
00133  *      rewriteMap          mapType mapName [mapArgs]
00134  *      rewriteParam        paramName paramValue
00135  */
00136 LDAP_REWRITE_F (int)
00137 rewrite_parse(
00138               struct rewrite_info *info,
00139                 const char *fname,
00140                 int lineno,
00141                 int argc,
00142                 char **argv
00143 );
00144 
00145 /*
00146  * process a config file that was already opened. Uses rewrite_parse.
00147  */
00148 LDAP_REWRITE_F (int)
00149 rewrite_read(
00150               FILE *fin,
00151               struct rewrite_info *info
00152 );
00153 
00154 /*
00155  * Rewrites a string according to context.
00156  * If the engine is off, OK is returned, but the return string will be NULL.
00157  * In case of 'unwilling to perform', UNWILLING is returned, and the
00158  * return string will also be null. The same in case of error.
00159  * Otherwise, OK is returned, and result will hold a newly allocated string
00160  * with the rewriting.
00161  *
00162  * What to do in case of non-existing rewrite context is still an issue.
00163  * Four possibilities:
00164  *      - error,
00165  *      - ok with NULL result,
00166  *      - ok with copy of string as result,
00167  *      - use the default rewrite context.
00168  */
00169 LDAP_REWRITE_F (int)
00170 rewrite(
00171               struct rewrite_info *info,
00172               const char *rewriteContext,
00173               const char *string,
00174               char **result
00175 );
00176 
00177 /*
00178  * Same as above; the cookie relates the rewrite to a session
00179  */
00180 LDAP_REWRITE_F (int)
00181 rewrite_session(
00182               struct rewrite_info *info,
00183               const char *rewriteContext,
00184               const char *string,
00185               const void *cookie,
00186               char **result
00187 );
00188 
00189 /*
00190  * Inits a session
00191  */
00192 LDAP_REWRITE_F (struct rewrite_session *)
00193 rewrite_session_init(
00194                 struct rewrite_info *info,
00195                 const void *cookie
00196 );
00197 
00198 /*
00199  * Defines and inits a variable with session scope
00200  */
00201 LDAP_REWRITE_F (int)
00202 rewrite_session_var_set_f(
00203               struct rewrite_info *info,
00204               const void *cookie,
00205               const char *name,
00206               const char *value,
00207               int flags
00208 );
00209 
00210 #define rewrite_session_var_set(info, cookie, name, value) \
00211        rewrite_session_var_set_f((info), (cookie), (name), (value), \
00212                      REWRITE_VAR_INSERT|REWRITE_VAR_UPDATE|REWRITE_VAR_COPY_NAME|REWRITE_VAR_COPY_VALUE)
00213 
00214 /*
00215  * Deletes a session
00216  */
00217 LDAP_REWRITE_F (int)
00218 rewrite_session_delete(
00219               struct rewrite_info *info,
00220               const void *cookie
00221 );
00222 
00223 
00224 /*
00225  * Params
00226  */
00227 
00228 /*
00229  * Defines and inits a variable with global scope
00230  */
00231 LDAP_REWRITE_F (int)
00232 rewrite_param_set(
00233                 struct rewrite_info *info,
00234                 const char *name,
00235                 const char *value
00236 );
00237 
00238 /*
00239  * Gets a var with global scope
00240  */
00241 LDAP_REWRITE_F (int)
00242 rewrite_param_get(
00243                 struct rewrite_info *info,
00244                 const char *name,
00245                 struct berval *value
00246 );
00247 
00248 /*
00249  * Destroys the parameter tree
00250  */
00251 LDAP_REWRITE_F (int)
00252 rewrite_param_destroy(
00253                 struct rewrite_info *info
00254 );
00255 
00256 /*
00257  * Mapping implementations
00258  */
00259 
00260 struct rewrite_mapper;
00261 
00262 typedef void * (rewrite_mapper_config)(
00263        const char *fname,
00264        int lineno,
00265        int argc,
00266        char **argv );
00267 
00268 typedef int (rewrite_mapper_apply)(
00269        void *ctx,
00270        const char *arg,
00271        struct berval *retval );
00272 
00273 typedef int (rewrite_mapper_destroy)(
00274        void *ctx );
00275 
00276 typedef struct rewrite_mapper {
00277        char *rm_name;
00278        rewrite_mapper_config *rm_config;
00279        rewrite_mapper_apply *rm_apply;
00280        rewrite_mapper_destroy *rm_destroy;
00281 } rewrite_mapper;
00282 
00283 /* For dynamic loading and unloading of mappers */
00284 LDAP_REWRITE_F (int)
00285 rewrite_mapper_register(
00286        const rewrite_mapper *map );
00287 
00288 LDAP_REWRITE_F (int)
00289 rewrite_mapper_unregister(
00290        const rewrite_mapper *map );
00291 
00292 LDAP_REWRITE_F (const rewrite_mapper *)
00293 rewrite_mapper_find(
00294        const char *name );
00295 
00296 LDAP_END_DECL
00297 
00298 #endif /* REWRITE_H */