]> git.sur5r.net Git - openldap/blob - include/lber.h
Add options for ber_get_stringbv() to omit NUL-terminator, to allow
[openldap] / include / lber.h
1 /* $OpenLDAP$ */
2 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
3  *
4  * Copyright 1998-2007 The OpenLDAP Foundation.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted only as authorized by the OpenLDAP
9  * Public License.
10  *
11  * A copy of this license is available in file LICENSE in the
12  * top-level directory of the distribution or, alternatively, at
13  * <http://www.OpenLDAP.org/license.html>.
14  */
15 /* Portions Copyright (c) 1990 Regents of the University of Michigan.
16  * All rights reserved.
17  *
18  * Redistribution and use in source and binary forms are permitted
19  * provided that this notice is preserved and that due credit is given
20  * to the University of Michigan at Ann Arbor. The name of the University
21  * may not be used to endorse or promote products derived from this
22  * software without specific prior written permission. This software
23  * is provided ``as is'' without express or implied warranty.
24  */
25
26 #ifndef _LBER_H
27 #define _LBER_H
28
29 #include <lber_types.h>
30 #include <string.h>
31
32 LDAP_BEGIN_DECL
33
34 /* Overview of LBER tag construction
35  *
36  *      Bits
37  *      ______
38  *      8 7 | CLASS
39  *      0 0 = UNIVERSAL
40  *      0 1 = APPLICATION
41  *      1 0 = CONTEXT-SPECIFIC
42  *      1 1 = PRIVATE
43  *              _____
44  *              | 6 | DATA-TYPE
45  *                0 = PRIMITIVE
46  *                1 = CONSTRUCTED
47  *                      ___________
48  *                      | 5 ... 1 | TAG-NUMBER
49  */
50
51 /* BER classes and mask */
52 #define LBER_CLASS_UNIVERSAL    ((ber_tag_t) 0x00U)
53 #define LBER_CLASS_APPLICATION  ((ber_tag_t) 0x40U)
54 #define LBER_CLASS_CONTEXT              ((ber_tag_t) 0x80U)
55 #define LBER_CLASS_PRIVATE              ((ber_tag_t) 0xc0U)
56 #define LBER_CLASS_MASK                 ((ber_tag_t) 0xc0U)
57
58 /* BER encoding type and mask */
59 #define LBER_PRIMITIVE                  ((ber_tag_t) 0x00U)
60 #define LBER_CONSTRUCTED                ((ber_tag_t) 0x20U)
61 #define LBER_ENCODING_MASK              ((ber_tag_t) 0x20U)
62
63 #define LBER_BIG_TAG_MASK               ((ber_tag_t) 0x1fU)
64 #define LBER_MORE_TAG_MASK              ((ber_tag_t) 0x80U)
65
66 /*
67  * Note that LBER_ERROR and LBER_DEFAULT are values that can never appear
68  * as valid BER tags, and so it is safe to use them to report errors.  In
69  * fact, any tag for which the following is true is invalid:
70  */
71 #define LBER_INVALID(t)     (((t) & (ber_tag_t) 0x080UL) \
72         && (((t) & (ber_tag_t) ~ 0x0FF))
73
74 #define LBER_ERROR                      ((ber_tag_t) -1)
75 #define LBER_DEFAULT            ((ber_tag_t) -1)
76
77 /* general BER types we know about */
78 #define LBER_BOOLEAN            ((ber_tag_t) 0x01UL)
79 #define LBER_INTEGER            ((ber_tag_t) 0x02UL)
80 #define LBER_BITSTRING          ((ber_tag_t) 0x03UL)
81 #define LBER_OCTETSTRING        ((ber_tag_t) 0x04UL)
82 #define LBER_NULL                       ((ber_tag_t) 0x05UL)
83 #define LBER_ENUMERATED         ((ber_tag_t) 0x0aUL)
84 #define LBER_SEQUENCE           ((ber_tag_t) 0x30UL)    /* constructed */
85 #define LBER_SET                        ((ber_tag_t) 0x31UL)    /* constructed */
86
87 /* LBER BerElement options */
88 #define LBER_USE_DER            0x01
89
90 /* get/set options for BerElement */
91 #define LBER_OPT_BER_OPTIONS                    0x01
92 #define LBER_OPT_BER_DEBUG                              0x02
93 #define LBER_OPT_BER_REMAINING_BYTES    0x03
94 #define LBER_OPT_BER_TOTAL_BYTES                0x04
95 #define LBER_OPT_BER_BYTES_TO_WRITE             0x05
96 #define LBER_OPT_BER_MEMCTX                             0x06
97
98 #define LBER_OPT_DEBUG_LEVEL    LBER_OPT_BER_DEBUG
99 #define LBER_OPT_REMAINING_BYTES        LBER_OPT_BER_REMAINING_BYTES
100 #define LBER_OPT_TOTAL_BYTES            LBER_OPT_BER_TOTAL_BYTES
101 #define LBER_OPT_BYTES_TO_WRITE         LBER_OPT_BER_BYTES_TO_WRITE
102
103 #define LBER_OPT_LOG_PRINT_FN   0x8001
104 #define LBER_OPT_MEMORY_FNS             0x8002
105 #define LBER_OPT_ERROR_FN               0x8003
106 #define LBER_OPT_LOG_PRINT_FILE         0x8004
107
108 /* get/set Memory Debug options */
109 #define LBER_OPT_MEMORY_INUSE           0x8005  /* for memory debugging */
110 #define LBER_OPT_LOG_PROC           0x8006  /* for external logging function */
111
112 typedef int* (*BER_ERRNO_FN) LDAP_P(( void ));
113
114 typedef void (*BER_LOG_PRINT_FN) LDAP_P(( LDAP_CONST char *buf ));
115
116 typedef void* (BER_MEMALLOC_FN) LDAP_P(( ber_len_t size, void *ctx ));
117 typedef void* (BER_MEMCALLOC_FN)        LDAP_P(( ber_len_t n, ber_len_t size, void *ctx ));
118 typedef void* (BER_MEMREALLOC_FN)       LDAP_P(( void *p, ber_len_t size, void *ctx ));
119 typedef void  (BER_MEMFREE_FN)          LDAP_P(( void *p, void *ctx ));
120
121 typedef struct lber_memory_fns {
122         BER_MEMALLOC_FN *bmf_malloc;
123         BER_MEMCALLOC_FN *bmf_calloc;
124         BER_MEMREALLOC_FN *bmf_realloc;
125         BER_MEMFREE_FN *bmf_free;
126 } BerMemoryFunctions;
127
128 /* LBER Sockbuf_IO options */
129 #define LBER_SB_OPT_GET_FD              1
130 #define LBER_SB_OPT_SET_FD              2
131 #define LBER_SB_OPT_HAS_IO              3
132 #define LBER_SB_OPT_SET_NONBLOCK        4
133 #define LBER_SB_OPT_GET_SSL             7
134 #define LBER_SB_OPT_DATA_READY          8
135 #define LBER_SB_OPT_SET_READAHEAD       9
136 #define LBER_SB_OPT_DRAIN               10
137 #define LBER_SB_OPT_NEEDS_READ          11
138 #define LBER_SB_OPT_NEEDS_WRITE         12
139 #define LBER_SB_OPT_GET_MAX_INCOMING    13
140 #define LBER_SB_OPT_SET_MAX_INCOMING    14
141 /* Largest option used by the library */
142 #define LBER_SB_OPT_OPT_MAX             14
143
144 /* LBER IO operations stacking levels */
145 #define LBER_SBIOD_LEVEL_PROVIDER       10
146 #define LBER_SBIOD_LEVEL_TRANSPORT      20
147 #define LBER_SBIOD_LEVEL_APPLICATION    30
148
149 /* get/set options for Sockbuf */
150 #define LBER_OPT_SOCKBUF_DESC           0x1000
151 #define LBER_OPT_SOCKBUF_OPTIONS        0x1001
152 #define LBER_OPT_SOCKBUF_DEBUG          0x1002
153
154 /* on/off values */
155 LBER_V( char ) ber_pvt_opt_on;
156 #define LBER_OPT_ON             ((void *) &ber_pvt_opt_on)
157 #define LBER_OPT_OFF    ((void *) 0)
158
159 #define LBER_OPT_SUCCESS        (0)
160 #define LBER_OPT_ERROR          (-1)
161
162 typedef struct berelement BerElement;
163 typedef struct sockbuf Sockbuf;
164 typedef struct seqorset Seqorset;
165
166 typedef struct sockbuf_io Sockbuf_IO;
167
168 /* Structure for LBER IO operarion descriptor */
169 typedef struct sockbuf_io_desc {
170         int                     sbiod_level;
171         Sockbuf                 *sbiod_sb;
172         Sockbuf_IO              *sbiod_io;
173         void                    *sbiod_pvt;
174         struct sockbuf_io_desc  *sbiod_next;
175 } Sockbuf_IO_Desc;
176
177 /* Structure for LBER IO operation functions */
178 struct sockbuf_io {
179         int (*sbi_setup)( Sockbuf_IO_Desc *sbiod, void *arg );
180         int (*sbi_remove)( Sockbuf_IO_Desc *sbiod );
181         int (*sbi_ctrl)( Sockbuf_IO_Desc *sbiod, int opt, void *arg);
182
183         ber_slen_t (*sbi_read)( Sockbuf_IO_Desc *sbiod, void *buf,
184                 ber_len_t len );
185         ber_slen_t (*sbi_write)( Sockbuf_IO_Desc *sbiod, void *buf,
186                 ber_len_t len );
187
188         int (*sbi_close)( Sockbuf_IO_Desc *sbiod );
189 };
190
191 /* Helper macros for LBER IO functions */
192 #define LBER_SBIOD_READ_NEXT( sbiod, buf, len ) \
193         ( (sbiod)->sbiod_next->sbiod_io->sbi_read( (sbiod)->sbiod_next, \
194                 buf, len ) )
195 #define LBER_SBIOD_WRITE_NEXT( sbiod, buf, len ) \
196         ( (sbiod)->sbiod_next->sbiod_io->sbi_write( (sbiod)->sbiod_next, \
197                 buf, len ) )
198 #define LBER_SBIOD_CTRL_NEXT( sbiod, opt, arg ) \
199         ( (sbiod)->sbiod_next ? \
200                 ( (sbiod)->sbiod_next->sbiod_io->sbi_ctrl( \
201                 (sbiod)->sbiod_next, opt, arg ) ) : 0 )
202
203 /* structure for returning a sequence of octet strings + length */
204 typedef struct berval {
205         ber_len_t       bv_len;
206         char            *bv_val;
207 } BerValue;
208
209 typedef BerValue *BerVarray;    /* To distinguish from a single bv */
210
211 /* this should be moved to lber-int.h */
212
213 /*
214  * in bprint.c:
215  */
216 LBER_F( void )
217 ber_error_print LDAP_P((
218         LDAP_CONST char *data ));
219
220 LBER_F( void )
221 ber_bprint LDAP_P((
222         LDAP_CONST char *data, ber_len_t len ));
223
224 LBER_F( void )
225 ber_dump LDAP_P((
226         BerElement *ber, int inout ));
227
228 LBER_F( void )
229 ber_sos_dump LDAP_P((
230         Seqorset *sos ));
231
232 /*
233  * in decode.c:
234  */
235 typedef int (*BERDecodeCallback) LDAP_P((
236         BerElement *ber,
237         void *data,
238         int mode ));
239
240 LBER_F( ber_tag_t )
241 ber_get_tag LDAP_P((
242         BerElement *ber ));
243
244 LBER_F( ber_tag_t )
245 ber_skip_tag LDAP_P((
246         BerElement *ber,
247         ber_len_t *len ));
248
249 LBER_F( ber_tag_t )
250 ber_peek_tag LDAP_P((
251         BerElement *ber,
252         ber_len_t *len ));
253
254 LBER_F( ber_tag_t )
255 ber_get_int LDAP_P((
256         BerElement *ber,
257         ber_int_t *num ));
258
259 LBER_F( ber_tag_t )
260 ber_get_enum LDAP_P((
261         BerElement *ber,
262         ber_int_t *num ));
263
264 LBER_F( ber_tag_t )
265 ber_get_stringb LDAP_P((
266         BerElement *ber,
267         char *buf,
268         ber_len_t *len ));
269
270 #define LBER_BV_ALLOC   0x01    /* allocate/copy result, otherwise in-place */
271 #define LBER_BV_NOTERM  0x02    /* omit NUL-terminator if parsing in-place */
272
273 LBER_F( ber_tag_t )
274 ber_get_stringbv LDAP_P((
275         BerElement *ber,
276         struct berval *bv,
277         int options ));
278
279 LBER_F( ber_tag_t )
280 ber_get_stringa LDAP_P((
281         BerElement *ber,
282         char **buf ));
283
284 LBER_F( ber_tag_t )
285 ber_get_stringal LDAP_P((
286         BerElement *ber,
287         struct berval **bv ));
288
289 LBER_F( ber_tag_t )
290 ber_get_bitstringa LDAP_P((
291         BerElement *ber,
292         char **buf,
293         ber_len_t *len ));
294
295 LBER_F( ber_tag_t )
296 ber_get_null LDAP_P((
297         BerElement *ber ));
298
299 LBER_F( ber_tag_t )
300 ber_get_boolean LDAP_P((
301         BerElement *ber,
302         ber_int_t *boolval ));
303
304 LBER_F( ber_tag_t )
305 ber_first_element LDAP_P((
306         BerElement *ber,
307         ber_len_t *len,
308         char **last ));
309
310 LBER_F( ber_tag_t )
311 ber_next_element LDAP_P((
312         BerElement *ber,
313         ber_len_t *len,
314         LDAP_CONST char *last ));
315
316 LBER_F( ber_tag_t )
317 ber_scanf LDAP_P((
318         BerElement *ber,
319         LDAP_CONST char *fmt,
320         ... ));
321
322 LBER_F( int )
323 ber_decode_oid LDAP_P((
324         struct berval *in,
325         struct berval *out ));
326
327 /*
328  * in encode.c
329  */
330 LBER_F( int )
331 ber_encode_oid LDAP_P((
332         struct berval *in,
333         struct berval *out ));
334
335 typedef int (*BEREncodeCallback) LDAP_P((
336         BerElement *ber,
337         void *data ));
338
339 LBER_F( int )
340 ber_put_enum LDAP_P((
341         BerElement *ber,
342         ber_int_t num,
343         ber_tag_t tag ));
344
345 LBER_F( int )
346 ber_put_int LDAP_P((
347         BerElement *ber,
348         ber_int_t num,
349         ber_tag_t tag ));
350
351 LBER_F( int )
352 ber_put_ostring LDAP_P((
353         BerElement *ber,
354         LDAP_CONST char *str,
355         ber_len_t len,
356         ber_tag_t tag ));
357
358 LBER_F( int )
359 ber_put_berval LDAP_P((
360         BerElement *ber,
361         struct berval *bv,
362         ber_tag_t tag ));
363
364 LBER_F( int )
365 ber_put_string LDAP_P((
366         BerElement *ber,
367         LDAP_CONST char *str,
368         ber_tag_t tag ));
369
370 LBER_F( int )
371 ber_put_bitstring LDAP_P((
372         BerElement *ber,
373         LDAP_CONST char *str,
374         ber_len_t bitlen,
375         ber_tag_t tag ));
376
377 LBER_F( int )
378 ber_put_null LDAP_P((
379         BerElement *ber,
380         ber_tag_t tag ));
381
382 LBER_F( int )
383 ber_put_boolean LDAP_P((
384         BerElement *ber,
385         ber_int_t boolval,
386         ber_tag_t tag ));
387
388 LBER_F( int )
389 ber_start_seq LDAP_P((
390         BerElement *ber,
391         ber_tag_t tag ));
392
393 LBER_F( int )
394 ber_start_set LDAP_P((
395         BerElement *ber,
396         ber_tag_t tag ));
397
398 LBER_F( int )
399 ber_put_seq LDAP_P((
400         BerElement *ber ));
401
402 LBER_F( int )
403 ber_put_set LDAP_P((
404         BerElement *ber ));
405
406 LBER_F( int )
407 ber_printf LDAP_P((
408         BerElement *ber,
409         LDAP_CONST char *fmt,
410         ... ));
411
412
413 /*
414  * in io.c:
415  */
416
417 LBER_F( ber_slen_t )
418 ber_skip_data LDAP_P((
419         BerElement *ber,
420         ber_len_t len ));
421
422 LBER_F( ber_slen_t )
423 ber_read LDAP_P((
424         BerElement *ber,
425         char *buf,
426         ber_len_t len ));
427
428 LBER_F( ber_slen_t )
429 ber_write LDAP_P((
430         BerElement *ber,
431         LDAP_CONST char *buf,
432         ber_len_t len,
433         int nosos ));
434
435 LBER_F( void )
436 ber_free LDAP_P((
437         BerElement *ber,
438         int freebuf ));
439
440 LBER_F( void )
441 ber_free_buf LDAP_P(( BerElement *ber ));
442
443 LBER_F( int )
444 ber_flush2 LDAP_P((
445         Sockbuf *sb,
446         BerElement *ber,
447         int freeit ));
448 #define LBER_FLUSH_FREE_NEVER           (0x0)   /* traditional behavior */
449 #define LBER_FLUSH_FREE_ON_SUCCESS      (0x1)   /* traditional behavior */
450 #define LBER_FLUSH_FREE_ON_ERROR        (0x2)
451 #define LBER_FLUSH_FREE_ALWAYS          (LBER_FLUSH_FREE_ON_SUCCESS|LBER_FLUSH_FREE_ON_ERROR)
452
453 LBER_F( int )
454 ber_flush LDAP_P((
455         Sockbuf *sb,
456         BerElement *ber,
457         int freeit )); /* DEPRECATED */
458
459 LBER_F( BerElement * )
460 ber_alloc LDAP_P(( void )); /* DEPRECATED */
461
462 LBER_F( BerElement * )
463 der_alloc LDAP_P(( void )); /* DEPRECATED */
464
465 LBER_F( BerElement * )
466 ber_alloc_t LDAP_P((
467         int beroptions ));
468
469 LBER_F( BerElement * )
470 ber_dup LDAP_P((
471         BerElement *ber ));
472
473 LBER_F( ber_tag_t )
474 ber_get_next LDAP_P((
475         Sockbuf *sb,
476         ber_len_t *len,
477         BerElement *ber ));
478
479 LBER_F( void )
480 ber_init2 LDAP_P((
481         BerElement *ber,
482         struct berval *bv,
483         int options ));
484
485 LBER_F( void )
486 ber_init_w_nullc LDAP_P((       /* DEPRECATED */
487         BerElement *ber,
488         int options ));
489
490 LBER_F( void )
491 ber_reset LDAP_P((
492         BerElement *ber,
493         int was_writing ));
494
495 LBER_F( BerElement * )
496 ber_init LDAP_P((
497         struct berval *bv ));
498
499 LBER_F( int )
500 ber_flatten LDAP_P((
501         BerElement *ber,
502         struct berval **bvPtr ));
503
504 LBER_F( int )
505 ber_flatten2 LDAP_P((
506         BerElement *ber,
507         struct berval *bv,
508         int alloc ));
509
510 LBER_F( int )
511 ber_remaining LDAP_P((
512         BerElement *ber ));
513
514 /*
515  * LBER ber accessor functions
516  */
517
518 LBER_F( int )
519 ber_get_option LDAP_P((
520         void *item,
521         int option,
522         void *outvalue));
523
524 LBER_F( int )
525 ber_set_option LDAP_P((
526         void *item,
527         int option,
528         LDAP_CONST void *invalue));
529
530 /*
531  * LBER sockbuf.c
532  */
533
534 LBER_F( Sockbuf *  )
535 ber_sockbuf_alloc LDAP_P((
536         void ));
537
538 LBER_F( void )
539 ber_sockbuf_free LDAP_P((
540         Sockbuf *sb ));
541
542 LBER_F( int )
543 ber_sockbuf_add_io LDAP_P((
544         Sockbuf *sb,
545         Sockbuf_IO *sbio,
546         int layer,
547         void *arg ));
548
549 LBER_F( int )
550 ber_sockbuf_remove_io LDAP_P((
551         Sockbuf *sb,
552         Sockbuf_IO *sbio,
553         int layer ));
554
555 LBER_F( int )
556 ber_sockbuf_ctrl LDAP_P((
557         Sockbuf *sb,
558         int opt,
559         void *arg ));
560
561 LBER_V( Sockbuf_IO ) ber_sockbuf_io_tcp;
562 LBER_V( Sockbuf_IO ) ber_sockbuf_io_readahead;
563 LBER_V( Sockbuf_IO ) ber_sockbuf_io_fd;
564 LBER_V( Sockbuf_IO ) ber_sockbuf_io_debug;
565 LBER_V( Sockbuf_IO ) ber_sockbuf_io_udp;
566
567 /*
568  * LBER memory.c
569  */
570 LBER_F( void * )
571 ber_memalloc LDAP_P((
572         ber_len_t s ));
573
574 LBER_F( void * )
575 ber_memrealloc LDAP_P((
576         void* p,
577         ber_len_t s ));
578
579 LBER_F( void * )
580 ber_memcalloc LDAP_P((
581         ber_len_t n,
582         ber_len_t s ));
583
584 LBER_F( void )
585 ber_memfree LDAP_P((
586         void* p ));
587
588 LBER_F( void )
589 ber_memvfree LDAP_P((
590         void** vector ));
591
592 LBER_F( void )
593 ber_bvfree LDAP_P((
594         struct berval *bv ));
595
596 LBER_F( void )
597 ber_bvecfree LDAP_P((
598         struct berval **bv ));
599
600 LBER_F( int )
601 ber_bvecadd LDAP_P((
602         struct berval ***bvec,
603         struct berval *bv ));
604
605 LBER_F( struct berval * )
606 ber_dupbv LDAP_P((
607         struct berval *dst, struct berval *src ));
608
609 LBER_F( struct berval * )
610 ber_bvdup LDAP_P((
611         struct berval *src ));
612
613 LBER_F( struct berval * )
614 ber_mem2bv LDAP_P((
615         LDAP_CONST char *, ber_len_t len, int duplicate, struct berval *bv));
616
617 LBER_F( struct berval * )
618 ber_str2bv LDAP_P((
619         LDAP_CONST char *, ber_len_t len, int duplicate, struct berval *bv));
620
621 #define ber_bvstr(a)    ((ber_str2bv)((a), 0, 0, NULL))
622 #define ber_bvstrdup(a) ((ber_str2bv)((a), 0, 1, NULL))
623
624 LBER_F( char * )
625 ber_strdup LDAP_P((
626         LDAP_CONST char * ));
627
628 LBER_F( struct berval * )
629 ber_bvreplace LDAP_P((
630         struct berval *dst, LDAP_CONST struct berval *src ));
631
632 LBER_F( void )
633 ber_bvarray_free LDAP_P(( BerVarray p ));
634
635 LBER_F( int )
636 ber_bvarray_add LDAP_P(( BerVarray *p, BerValue *bv ));
637
638 #define ber_bvcmp(v1,v2) \
639         ((v1)->bv_len < (v2)->bv_len \
640                 ? -1 : ((v1)->bv_len > (v2)->bv_len \
641                         ? 1 : memcmp((v1)->bv_val, (v2)->bv_val, (v1)->bv_len) ))
642
643 /*
644  * error.c
645  */
646 LBER_F( int * ) ber_errno_addr LDAP_P((void));
647 #define ber_errno (*(ber_errno_addr)())
648
649 #define LBER_ERROR_NONE         0
650 #define LBER_ERROR_PARAM        0x1
651 #define LBER_ERROR_MEMORY       0x2
652
653 LDAP_END_DECL
654
655 #endif /* _LBER_H */