source3/registry/reg_format.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  Format registration entries (.reg) files.
  22  * A formatter is a talloced incarnation of an opaque struct reg_format.
  23  * It is fed with registry key's and value's and emits output by calling
  24  * writeline from its reg_format_callback.
  25  * @file   reg_format.h
  26  * @author Gregor Beck <gb@sernet.de>
  27  * @date   Sep 2010
  28  */
  29 #ifndef __REG_FORMAT_H
  30 #define __REG_FORMAT_H
  31
  32 #include <stdbool.h>
  33 #include <stdint.h>
  34 #include <stddef.h>
  35
  36 struct registry_key;
  37 struct registry_value;
  38 struct regval_blob;
  39
  40
  41 /**
  42  * A Formatter for registration entries (.reg) files.
  43  *
  44  * It may be used as a reg_parse_callback, so the following is valid:
  45  * @code
  46  * reg_parse* p = reg_parse_new(mem_ctx,
  47  *                             (reg_parse_callback)reg_format_new(mem_ctx, cb, NULL, 0, "\\"),
  48  *                                NULL, 0);
  49  * @endcode
  50  * @see reg_parse
  51  */
  52 typedef struct reg_format reg_format;
  53
  54 /**
  55  * Prototype for function called to output a line.
  56  *
  57  * @param private_data
  58  * @param line line to write in UNIX charset
  59  *
  60  * @return number of characters written, < 0 on error
  61  *
  62  * @see reg_parse
  63  */
  64 typedef int (*reg_format_callback_writeline_t)(void* private_data,
  65                                                const char* line);
  66 /**
  67  * Type handling the output of a reg_format object.
  68  * It contains the functions to call and an opaque data pointer.
  69  */
  70 typedef struct reg_format_callback {
  71         /**< Function called to write a line */
  72         reg_format_callback_writeline_t writeline;
  73         void* data; /**< Private data passed to callback function */
  74 } reg_format_callback;
  75
  76 /**
  77  * Create a new reg_format object.
  78  *
  79  * @param talloc_ctx the talloc parent
  80  * @param cb         the output handler
  81  * @param str_enc    the charset of hex encoded strings (REG_MULTI_SZ, REG_EXAND_SZ) if not UTF-16
  82  * @param flags
  83  * @param sep        the separator for subkeys
  84  *
  85  * @return a talloc'ed reg_format object, NULL on error
  86  */
  87 reg_format* reg_format_new(const void* talloc_ctx,
  88                            reg_format_callback cb,
  89                            const char* str_enc,
  90                            unsigned flags,
  91                            const char* sep);
  92
  93 /**
  94  * Create a new reg_format object, writing to a file.
  95  *
  96  * @param talloc_ctx the talloc parent
  97  * @param filename   the file to write to
  98  * @param options
  99  *
 100  * @return a talloc'ed reg_format object, NULL on error
 101  */
 102 reg_format* reg_format_file(const void* talloc_ctx,
 103                             const char* filename,
 104                             const char* options);
 105
 106 /**
 107  * Format a registry key given as struct registry_key.
 108  * Create/Open or Delete
 109  *
 110  * @param f   the formatter.
 111  * @param key the key to output.
 112  * @param del whether to format the deletion of the key
 113  *
 114  * @retval >= 0 on success.
 115  */
 116 int reg_format_registry_key(reg_format* f,
 117                             struct registry_key* key,
 118                             bool del);
 119
 120 /**
 121  * Format a registry value given as struct registry_value.
 122  *
 123  * @param f    the formatter.
 124  * @param name the values name
 125  * @param val  the values value.
 126  *
 127  * @retval >= 0 on success.
 128  */
 129 int reg_format_registry_value(reg_format* f,
 130                               const char* name,
 131                               struct registry_value* val);
 132
 133 /**
 134  * Format a registry value given as struct regval_blob.
 135  *
 136  * @param f    the formatter.
 137  * @param name the values name, if NULL use val->valname which is limited in size;
 138  * @param val  the values value.
 139  *
 140  * @retval >= 0 on success.
 141  */
 142 int reg_format_regval_blob(reg_format* f,
 143                            const char* name,
 144                            struct regval_blob* val);
 145
 146
 147 /**
 148  * Format deletion of a registry value.
 149  *
 150  * @param f    the formatter.
 151  * @param name the values name
 152  *
 153  * @retval >= 0 on success.
 154  *
 155  * @see reg_parse_callback_val_del_t
 156  */
 157 int reg_format_value_delete(reg_format* f, const char* name);
 158
 159 /**
 160  * Format a comment.
 161  *
 162  * @param f   the formatter.
 163  * @param txt the comment in UNIX charset, may not contain newlines.
 164  *
 165  * @retval >= 0 on success.
 166  *
 167  * @see reg_parse_callback_comment_t
 168  */
 169 int reg_format_comment(reg_format* f, const char* txt);
 170
 171
 172 int reg_format_set_options(reg_format* f, const char* options);
 173
 174
 175 /* reg_format flags */
 176 #define REG_FMT_HEX_SZ  1
 177 #define REG_FMT_HEX_DW  2
 178 #define REG_FMT_HEX_BIN 4
 179 #define REG_FMT_HEX_ALL (REG_FMT_HEX_SZ | REG_FMT_HEX_DW | REG_FMT_HEX_BIN);
 180 #define REG_FMT_LONG_HIVES 16
 181 #define REG_FMT_SHORT_HIVES 32
 182
 183 /* lowlevel */
 184
 185 /**
 186  * Format a registry key.
 187  * Create/Open or Delete
 188  *
 189  * @param f   the formatter
 190  * @param key the key to output
 191  * @param klen number of elements in key
 192  * @param del whether to format the deletion of the key
 193  *
 194  * @retval >= 0 on success.
 195  *
 196  * @see reg_parse_callback_key_t
 197  */
 198 int reg_format_key(reg_format* f,
 199                    const char* key[], size_t klen,
 200                    bool del);
 201
 202 /**
 203  * Format a registry value.
 204  *
 205  * @param f    the formatter
 206  * @param name the values name
 207  * @param type the values type
 208  * @param data the values value
 209  * @param len  the number of bytes of data
 210  *
 211  * @retval >= 0 on success.
 212  *
 213  * @see reg_parse_callback_val_hex_t
 214  */
 215 int reg_format_value(reg_format* f,
 216                      const char* name, uint32_t type,
 217                      const uint8_t* data, size_t len);
 218
 219 #endif /* __REG_FORMAT_H */