r24780: More work allowing libutil to be used by external users.
[kai/samba.git] / source4 / 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 #ifndef _SAMBA_DATABLOB_H_
20 #define _SAMBA_DATABLOB_H_
21
22 /* used to hold an arbitrary blob of data */
23 typedef struct datablob {
24         uint8_t *data;
25         size_t length;
26 } DATA_BLOB;
27
28 struct data_blob_list_item {
29         struct data_blob_list_item *prev,*next;
30         DATA_BLOB blob;
31 };
32
33 #define data_blob(ptr, size) data_blob_named(ptr, size, "DATA_BLOB: "__location__)
34 #define data_blob_talloc(ctx, ptr, size) data_blob_talloc_named(ctx, ptr, size, "DATA_BLOB: "__location__)
35 #define data_blob_dup_talloc(ctx, blob) data_blob_talloc_named(ctx, (blob)->data, (blob)->length, "DATA_BLOB: "__location__)
36
37 /**
38  construct a data blob, must be freed with data_blob_free()
39  you can pass NULL for p and get a blank data blob
40 **/
41 _PUBLIC_ DATA_BLOB data_blob_named(const void *p, size_t length, const char *name);
42
43 /**
44  construct a data blob, using supplied TALLOC_CTX
45 **/
46 _PUBLIC_ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
47
48 /**
49  reference a data blob, to the supplied TALLOC_CTX.  
50  Returns a NULL DATA_BLOB on failure
51 **/
52 _PUBLIC_ DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
53
54 /**
55  construct a zero data blob, using supplied TALLOC_CTX. 
56  use this sparingly as it initialises data - better to initialise
57  yourself if you want specific data in the blob
58 **/
59 _PUBLIC_ DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length);
60
61 /**
62 free a data blob
63 **/
64 _PUBLIC_ void data_blob_free(DATA_BLOB *d);
65
66 /**
67 clear a DATA_BLOB's contents
68 **/
69 _PUBLIC_ void data_blob_clear(DATA_BLOB *d);
70
71 /**
72 free a data blob and clear its contents
73 **/
74 _PUBLIC_ void data_blob_clear_free(DATA_BLOB *d);
75
76 /**
77 check if two data blobs are equal
78 **/
79 _PUBLIC_ int data_blob_cmp(const DATA_BLOB *d1, const DATA_BLOB *d2);
80
81 /**
82 print the data_blob as hex string
83 **/
84 _PUBLIC_ char *data_blob_hex_string(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
85
86 /**
87   useful for constructing data blobs in test suites, while
88   avoiding const warnings
89 **/
90 _PUBLIC_ DATA_BLOB data_blob_string_const(const char *str);
91
92 /**
93  * Create a new data blob from const data 
94  */
95 _PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length);
96
97 /**
98   realloc a data_blob
99 **/
100 _PUBLIC_ bool data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
101
102 /**
103   append some data to a data blob
104 **/
105 _PUBLIC_ bool data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
106                                    const void *p, size_t length);
107
108 #endif /* _SAMBA_DATABLOB_H_ */