git.sur5r.net Git - openldap/blob - include/rewrite.h

   1 /* $OpenLDAP$
   2  */
   3 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
   4  *
   5  * Copyright 2000-2018 The OpenLDAP Foundation.
   6  * Portions Copyright 2000-2003 Pierangelo Masarati.
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted only as authorized by the OpenLDAP
  11  * Public License.
  12  *
  13  * A copy of this license is available in file LICENSE in the
  14  * top-level directory of the distribution or, alternatively, at
  15  * <http://www.OpenLDAP.org/license.html>.
  16  */
  17 /* ACKNOWLEDGEMENT:
  18  * This work was initially developed by Pierangelo Masarati for
  19  * inclusion in OpenLDAP Software.
  20  */
  21
  22 #ifndef REWRITE_H
  23 #define REWRITE_H
  24
  25 /*
  26  * Default rewrite context
  27  */
  28 #define REWRITE_DEFAULT_CONTEXT         "default"
  29
  30 /*
  31  * Rewrite engine states
  32  */
  33 #define REWRITE_OFF                     0x0000
  34 #define REWRITE_ON                      0x0001
  35 #define REWRITE_DEFAULT                 REWRITE_OFF
  36
  37 /*
  38  * Rewrite internal status returns
  39  */
  40 #define REWRITE_SUCCESS                 LDAP_SUCCESS
  41 #define REWRITE_ERR                     LDAP_OTHER
  42
  43 /*
  44  * Rewrite modes (input values for rewrite_info_init); determine the
  45  * behavior in case a null or non existent context is required:
  46  *
  47  *      REWRITE_MODE_ERR                error
  48  *      REWRITE_MODE_OK                 no error but no rewrite
  49  *      REWRITE_MODE_COPY_INPUT         a copy of the input is returned
  50  *      REWRITE_MODE_USE_DEFAULT        the default context is used.
  51  */
  52 #define REWRITE_MODE_ERR                0x0010
  53 #define REWRITE_MODE_OK                 0x0011
  54 #define REWRITE_MODE_COPY_INPUT         0x0012
  55 #define REWRITE_MODE_USE_DEFAULT        0x0013
  56
  57 /*
  58  * Rewrite status returns
  59  *
  60  *      REWRITE_REGEXEC_OK              success (result may be empty in case
  61  *                                      of no match)
  62  *      REWRITE_REGEXEC_ERR             error (internal error,
  63  *                                      misconfiguration, map not working ...)
  64  *      REWRITE_REGEXEC_STOP            internal use; never returned
  65  *      REWRITE_REGEXEC_UNWILLING       the server should issue an 'unwilling
  66  *                                      to perform' error
  67  */
  68 #define REWRITE_REGEXEC_OK              (0)
  69 #define REWRITE_REGEXEC_ERR             (-1)
  70 #define REWRITE_REGEXEC_STOP            (-2)
  71 #define REWRITE_REGEXEC_UNWILLING       (-3)
  72 #define REWRITE_REGEXEC_USER            (1)     /* and above: LDAP errors */
  73
  74 /*
  75  * Rewrite variable flags
  76  *      REWRITE_VAR_INSERT              insert mode (default) when adding
  77  *                                      a variable; if not set during value
  78  *                                      update, the variable is not inserted
  79  *                                      if not present
  80  *      REWRITE_VAR_UPDATE              update mode (default) when updating
  81  *                                      a variable; if not set during insert,
  82  *                                      the value is not updated if the
  83  *                                      variable already exists
  84  *      REWRITE_VAR_COPY_NAME           copy the variable name; if not set,
  85  *                                      the name is not copied; be sure the
  86  *                                      referenced string is available for
  87  *                                      the entire life scope of the variable.
  88  *      REWRITE_VAR_COPY_VALUE          copy the variable value; if not set,
  89  *                                      the value is not copied; be sure the
  90  *                                      referenced string is available for
  91  *                                      the entire life scope of the variable.
  92  */
  93 #define REWRITE_VAR_NONE                0x0000
  94 #define REWRITE_VAR_INSERT              0x0001
  95 #define REWRITE_VAR_UPDATE              0x0002
  96 #define REWRITE_VAR_COPY_NAME           0x0004
  97 #define REWRITE_VAR_COPY_VALUE          0x0008
  98
  99 /*
 100  * Rewrite info
 101  */
 102 struct rewrite_info;
 103
 104 struct berval; /* avoid include */
 105
 106 LDAP_BEGIN_DECL
 107
 108 /*
 109  * Inits the info
 110  */
 111 LDAP_REWRITE_F (struct rewrite_info *)
 112 rewrite_info_init(
 113                 int mode
 114 );
 115
 116 /*
 117  * Cleans up the info structure
 118  */
 119 LDAP_REWRITE_F (int)
 120 rewrite_info_delete(
 121                 struct rewrite_info **info
 122 );
 123
 124
 125 /*
 126  * Parses a config line and takes actions to fit content in rewrite structure;
 127  * lines handled are of the form:
 128  *
 129  *      rewriteEngine           {on|off}
 130  *      rewriteMaxPasses        numPasses
 131  *      rewriteContext          contextName [alias aliasedRewriteContex]
 132  *      rewriteRule             pattern substPattern [ruleFlags]
 133  *      rewriteMap              mapType mapName [mapArgs]
 134  *      rewriteParam            paramName paramValue
 135  */
 136 LDAP_REWRITE_F (int)
 137 rewrite_parse(
 138                 struct rewrite_info *info,
 139                 const char *fname,
 140                 int lineno,
 141                 int argc,
 142                 char **argv
 143 );
 144
 145 /*
 146  * process a config file that was already opened. Uses rewrite_parse.
 147  */
 148 LDAP_REWRITE_F (int)
 149 rewrite_read(
 150                 FILE *fin,
 151                 struct rewrite_info *info
 152 );
 153
 154 /*
 155  * Rewrites a string according to context.
 156  * If the engine is off, OK is returned, but the return string will be NULL.
 157  * In case of 'unwilling to perform', UNWILLING is returned, and the
 158  * return string will also be null. The same in case of error.
 159  * Otherwise, OK is returned, and result will hold a newly allocated string
 160  * with the rewriting.
 161  *
 162  * What to do in case of non-existing rewrite context is still an issue.
 163  * Four possibilities:
 164  *      - error,
 165  *      - ok with NULL result,
 166  *      - ok with copy of string as result,
 167  *      - use the default rewrite context.
 168  */
 169 LDAP_REWRITE_F (int)
 170 rewrite(
 171                 struct rewrite_info *info,
 172                 const char *rewriteContext,
 173                 const char *string,
 174                 char **result
 175 );
 176
 177 /*
 178  * Same as above; the cookie relates the rewrite to a session
 179  */
 180 LDAP_REWRITE_F (int)
 181 rewrite_session(
 182                 struct rewrite_info *info,
 183                 const char *rewriteContext,
 184                 const char *string,
 185                 const void *cookie,
 186                 char **result
 187 );
 188
 189 /*
 190  * Inits a session
 191  */
 192 LDAP_REWRITE_F (struct rewrite_session *)
 193 rewrite_session_init(
 194                 struct rewrite_info *info,
 195                 const void *cookie
 196 );
 197
 198 /*
 199  * Defines and inits a variable with session scope
 200  */
 201 LDAP_REWRITE_F (int)
 202 rewrite_session_var_set_f(
 203                 struct rewrite_info *info,
 204                 const void *cookie,
 205                 const char *name,
 206                 const char *value,
 207                 int flags
 208 );
 209
 210 #define rewrite_session_var_set(info, cookie, name, value) \
 211         rewrite_session_var_set_f((info), (cookie), (name), (value), \
 212                         REWRITE_VAR_INSERT|REWRITE_VAR_UPDATE|REWRITE_VAR_COPY_NAME|REWRITE_VAR_COPY_VALUE)
 213
 214 /*
 215  * Deletes a session
 216  */
 217 LDAP_REWRITE_F (int)
 218 rewrite_session_delete(
 219                 struct rewrite_info *info,
 220                 const void *cookie
 221 );
 222
 223
 224 /*
 225  * Params
 226  */
 227
 228 /*
 229  * Defines and inits a variable with global scope
 230  */
 231 LDAP_REWRITE_F (int)
 232 rewrite_param_set(
 233                 struct rewrite_info *info,
 234                 const char *name,
 235                 const char *value
 236 );
 237
 238 /*
 239  * Gets a var with global scope
 240  */
 241 LDAP_REWRITE_F (int)
 242 rewrite_param_get(
 243                 struct rewrite_info *info,
 244                 const char *name,
 245                 struct berval *value
 246 );
 247
 248 /*
 249  * Destroys the parameter tree
 250  */
 251 LDAP_REWRITE_F (int)
 252 rewrite_param_destroy(
 253                 struct rewrite_info *info
 254 );
 255
 256 /*
 257  * Mapping implementations
 258  */
 259
 260 struct rewrite_mapper;
 261
 262 typedef void * (rewrite_mapper_config)(
 263         const char *fname,
 264         int lineno,
 265         int argc,
 266         char **argv );
 267
 268 typedef int (rewrite_mapper_apply)(
 269         void *ctx,
 270         const char *arg,
 271         struct berval *retval );
 272
 273 typedef int (rewrite_mapper_destroy)(
 274         void *ctx );
 275
 276 typedef struct rewrite_mapper {
 277         char *rm_name;
 278         rewrite_mapper_config *rm_config;
 279         rewrite_mapper_apply *rm_apply;
 280         rewrite_mapper_destroy *rm_destroy;
 281 } rewrite_mapper;
 282
 283 /* For dynamic loading and unloading of mappers */
 284 LDAP_REWRITE_F (int)
 285 rewrite_mapper_register(
 286         const rewrite_mapper *map );
 287
 288 LDAP_REWRITE_F (int)
 289 rewrite_mapper_unregister(
 290         const rewrite_mapper *map );
 291
 292 LDAP_REWRITE_F (const rewrite_mapper *)
 293 rewrite_mapper_find(
 294         const char *name );
 295
 296 LDAP_END_DECL
 297
 298 #endif /* REWRITE_H */