source3/registry/reg_parse.h

   1 /*
   2  * Samba Unix/Linux SMB client library
   3  *
   4  * Copyright (C) Gregor Beck 2010
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /**
  21  * @brief  Parser for registration entries (.reg) files.
  22  * A parser is a talloced incarnation of an opaque struct reg_parse.
  23  * It is fed with the (.reg) file line by line calling @ref reg_parse_line
  24  * and emits output by calling functions from its reg_parse_callback.
  25  * @file   reg_parse.h
  26  * @author Gregor Beck <gb@sernet.de>
  27  * @date   Jun 2010
  28  */
  29
  30 #ifndef REG_PARSE_H
  31 #define REG_PARSE_H
  32
  33 #include <stdint.h>
  34 #include <stdbool.h>
  35
  36 /**
  37  * Protoype for function called on key found.
  38  * The usual action to take is delete the key if del==true, open it if
  39  * already existing or create a new one.
  40  *
  41  * @param private_data
  42  * @param key
  43  * @param klen number of elements in key
  44  * @param del whether to delete the key
  45  *
  46  * @retval >=0 on success
  47  *
  48  * @see reg_format_key
  49  */
  50 typedef int (*reg_parse_callback_key_t) (void* private_data,
  51                                          const char* key[],
  52                                          size_t klen,
  53                                          bool del);
  54
  55 /**
  56  * Protoype for function called on value found.
  57  * The usual action to take is set the value of the last opened key.
  58  *
  59  * @param private_data
  60  * @param name the values name
  61  * @param type the values type
  62  * @param data the values value
  63  * @param len  the number of bytes of data
  64  *
  65  * @retval >=0 on success
  66  *
  67  * @see reg_format_value
  68  */
  69 typedef int (*reg_parse_callback_val_t) (void*  private_data,
  70                                          const char* name,
  71                                          uint32_t type,
  72                                          const uint8_t* data,
  73                                          uint32_t len);
  74
  75 /**
  76  * Protoype for function called on value delete found.
  77  * Delete value from the last opened key. It is usually no error if
  78  * no such value exist.
  79  *
  80  * @param private_data
  81  * @param name
  82  *
  83  * @retval >=0 on success
  84  *
  85  * @see reg_format_value_delete
  86  */
  87 typedef int (*reg_parse_callback_val_del_t) (void* private_data,
  88                                              const char* name);
  89
  90
  91 /**
  92  * Protoype for function called on comment found.
  93  *
  94  * @param private_data
  95  * @param line comment with marker removed.
  96  *
  97  * @retval  >=0 on success
  98  *
  99  * @see reg_format_comment
 100  */
 101 typedef int (*reg_parse_callback_comment_t) (void* private_data,
 102                                              const char* line);
 103
 104 /**
 105  * Type handling the output of a reg_parse object.
 106  * It containes the functions to call and an opaque data pointer.
 107  */
 108 typedef struct reg_parse_callback {
 109         reg_parse_callback_key_t key; /**< Function called on key found */
 110         reg_parse_callback_val_t val; /**< Function called on value found */
 111         /** Function called on value delete found */
 112         reg_parse_callback_val_del_t val_del;
 113         /** Function called on comment found */
 114         reg_parse_callback_comment_t comment;
 115         void* data; /**< Private data passed to callback function */
 116 } reg_parse_callback;
 117
 118 /**
 119  * A Parser for a registration entries (.reg) file.
 120  *
 121  * It may be used as a reg_format_callback, so the following is valid:
 122  * @code
 123  * reg_format* f = reg_format_new(mem_ctx,
 124  *                                (reg_format_callback)reg_parse_new(mem_ctx, cb, NULL, 0),
 125  *                                NULL, 0, "\\");
 126  * @endcode
 127  * @see reg_format
 128  */
 129 typedef struct reg_parse reg_parse;
 130
 131 /**
 132  * Create a new reg_parse object.
 133  *
 134  * @param talloc_ctx the talloc parent
 135  * @param cb         the output handler
 136  * @param str_enc    the charset of hex encoded strings (REG_MULTI_SZ, REG_EXAND_SZ) if not UTF-16
 137  * @param flags
 138  *
 139  * @return a talloc'ed reg_parse object, NULL on error
 140  */
 141 reg_parse* reg_parse_new(const void* talloc_ctx,
 142                          reg_parse_callback cb,
 143                          const char* str_enc,
 144                          unsigned flags);
 145
 146 /**
 147  * Feed one line to the parser.
 148  *
 149  * @param parser
 150  * @param line one line from a (.reg) file, in UNIX charset
 151  *
 152  * @return 0 on success
 153  *
 154  * @see reg_format_callback_writeline_t
 155  */
 156 int reg_parse_line(struct reg_parse* parser, const char* line);
 157
 158
 159 /**
 160  * Parse a (.reg) file, read from a file descriptor.
 161  *
 162  * @param fd the file descriptor
 163  * @param cb the output handler
 164  * @param opts
 165  *
 166  * @return 0 on success
 167  */
 168 int reg_parse_fd(int fd,
 169                  const reg_parse_callback* cb,
 170                  const char* opts);
 171
 172 /**
 173  * Parse a (.reg) file
 174  *
 175  * @param filename the file to open
 176  * @param cb the output handler
 177  * @param opts
 178  *
 179  * @return 0 on success
 180  */
 181 int reg_parse_file(const char* filename,
 182                    const reg_parse_callback* cb,
 183                    const char* opts);
 184
 185 int reg_parse_set_options(reg_parse* parser, const char* opt);
 186
 187 /******************************************************************************/
 188
 189
 190 #endif /* REG_PARSE_H */