lib/util/data_blob.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    DATA BLOB
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /* This is a public header file that is installed as part of Samba.
  20  * If you remove any functions or change their signature, update
  21  * the so version number. */
  22
  23 #ifndef _SAMBA_DATABLOB_H_
  24 #define _SAMBA_DATABLOB_H_
  25
  26 #ifndef _PUBLIC_
  27 #define _PUBLIC_
  28 #endif
  29
  30 #include <talloc.h>
  31 #include <stdint.h>
  32
  33 /* used to hold an arbitrary blob of data */
  34 typedef struct datablob {
  35         uint8_t *data;
  36         size_t length;
  37 } DATA_BLOB;
  38
  39 struct data_blob_list_item {
  40         struct data_blob_list_item *prev,*next;
  41         DATA_BLOB blob;
  42 };
  43
  44 /* by making struct ldb_val and DATA_BLOB the same, we can simplify
  45    a fair bit of code */
  46 #define ldb_val datablob
  47
  48 #define data_blob(ptr, size) data_blob_named(ptr, size, "DATA_BLOB: "__location__)
  49 #define data_blob_talloc(ctx, ptr, size) data_blob_talloc_named(ctx, ptr, size, "DATA_BLOB: "__location__)
  50 #define data_blob_dup_talloc(ctx, blob) data_blob_talloc_named(ctx, (blob)->data, (blob)->length, "DATA_BLOB: "__location__)
  51
  52 /**
  53  construct a data blob, must be freed with data_blob_free()
  54  you can pass NULL for p and get a blank data blob
  55 **/
  56 _PUBLIC_ DATA_BLOB data_blob_named(const void *p, size_t length, const char *name);
  57
  58 /**
  59  construct a data blob, using supplied TALLOC_CTX
  60 **/
  61 _PUBLIC_ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
  62
  63 /**
  64  reference a data blob, to the supplied TALLOC_CTX.
  65  Returns a NULL DATA_BLOB on failure
  66 **/
  67 _PUBLIC_ DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
  68
  69 /**
  70  construct a zero data blob, using supplied TALLOC_CTX.
  71  use this sparingly as it initialises data - better to initialise
  72  yourself if you want specific data in the blob
  73 **/
  74 _PUBLIC_ DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length);
  75
  76 /**
  77 free a data blob
  78 **/
  79 _PUBLIC_ void data_blob_free(DATA_BLOB *d);
  80
  81 /**
  82 clear a DATA_BLOB's contents
  83 **/
  84 _PUBLIC_ void data_blob_clear(DATA_BLOB *d);
  85
  86 /**
  87 free a data blob and clear its contents
  88 **/
  89 _PUBLIC_ void data_blob_clear_free(DATA_BLOB *d);
  90
  91 /**
  92 check if two data blobs are equal
  93 **/
  94 _PUBLIC_ int data_blob_cmp(const DATA_BLOB *d1, const DATA_BLOB *d2);
  95
  96 /**
  97 print the data_blob as hex string
  98 **/
  99 _PUBLIC_ char *data_blob_hex_string_upper(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
 100
 101 /**
 102 print the data_blob as hex string
 103 **/
 104 _PUBLIC_ char *data_blob_hex_string_lower(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
 105
 106 /**
 107   useful for constructing data blobs in test suites, while
 108   avoiding const warnings
 109 **/
 110 _PUBLIC_ DATA_BLOB data_blob_string_const(const char *str);
 111
 112 /**
 113   useful for constructing data blobs in test suites, while
 114   avoiding const warnings
 115
 116   includes the terminating null character (as opposed to data_blo_string_const)
 117 **/
 118 _PUBLIC_ DATA_BLOB data_blob_string_const_null(const char *str);
 119
 120 /**
 121  * Create a new data blob from const data
 122  */
 123 _PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length);
 124
 125 /**
 126   realloc a data_blob
 127 **/
 128 _PUBLIC_ bool data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
 129
 130 /**
 131   append some data to a data blob
 132 **/
 133 _PUBLIC_ bool data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
 134                                    const void *p, size_t length);
 135
 136 extern const DATA_BLOB data_blob_null;
 137
 138 #endif /* _SAMBA_DATABLOB_H_ */