]> git.sur5r.net Git - openldap/blob - include/lber.h
ITS#6215
[openldap] / include / lber.h
1 /* $OpenLDAP$ */
2 /* This work is part of OpenLDAP Software <http://www.openldap.org/>.
3  *
4  * Copyright 1998-2009 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
142 /* Only meaningful ifdef LDAP_PF_LOCAL_SENDMSG */
143 #define LBER_SB_OPT_UNGET_BUF   15
144
145 /* Largest option used by the library */
146 #define LBER_SB_OPT_OPT_MAX             15
147
148 /* LBER IO operations stacking levels */
149 #define LBER_SBIOD_LEVEL_PROVIDER       10
150 #define LBER_SBIOD_LEVEL_TRANSPORT      20
151 #define LBER_SBIOD_LEVEL_APPLICATION    30
152
153 /* get/set options for Sockbuf */
154 #define LBER_OPT_SOCKBUF_DESC           0x1000
155 #define LBER_OPT_SOCKBUF_OPTIONS        0x1001
156 #define LBER_OPT_SOCKBUF_DEBUG          0x1002
157
158 /* on/off values */
159 LBER_V( char ) ber_pvt_opt_on;
160 #define LBER_OPT_ON             ((void *) &ber_pvt_opt_on)
161 #define LBER_OPT_OFF    ((void *) 0)
162
163 #define LBER_OPT_SUCCESS        (0)
164 #define LBER_OPT_ERROR          (-1)
165
166 typedef struct berelement BerElement;
167 typedef struct sockbuf Sockbuf;
168
169 typedef struct sockbuf_io Sockbuf_IO;
170
171 /* Structure for LBER IO operarion descriptor */
172 typedef struct sockbuf_io_desc {
173         int                     sbiod_level;
174         Sockbuf                 *sbiod_sb;
175         Sockbuf_IO              *sbiod_io;
176         void                    *sbiod_pvt;
177         struct sockbuf_io_desc  *sbiod_next;
178 } Sockbuf_IO_Desc;
179
180 /* Structure for LBER IO operation functions */
181 struct sockbuf_io {
182         int (*sbi_setup)( Sockbuf_IO_Desc *sbiod, void *arg );
183         int (*sbi_remove)( Sockbuf_IO_Desc *sbiod );
184         int (*sbi_ctrl)( Sockbuf_IO_Desc *sbiod, int opt, void *arg);
185
186         ber_slen_t (*sbi_read)( Sockbuf_IO_Desc *sbiod, void *buf,
187                 ber_len_t len );
188         ber_slen_t (*sbi_write)( Sockbuf_IO_Desc *sbiod, void *buf,
189                 ber_len_t len );
190
191         int (*sbi_close)( Sockbuf_IO_Desc *sbiod );
192 };
193
194 /* Helper macros for LBER IO functions */
195 #define LBER_SBIOD_READ_NEXT( sbiod, buf, len ) \
196         ( (sbiod)->sbiod_next->sbiod_io->sbi_read( (sbiod)->sbiod_next, \
197                 buf, len ) )
198 #define LBER_SBIOD_WRITE_NEXT( sbiod, buf, len ) \
199         ( (sbiod)->sbiod_next->sbiod_io->sbi_write( (sbiod)->sbiod_next, \
200                 buf, len ) )
201 #define LBER_SBIOD_CTRL_NEXT( sbiod, opt, arg ) \
202         ( (sbiod)->sbiod_next ? \
203                 ( (sbiod)->sbiod_next->sbiod_io->sbi_ctrl( \
204                 (sbiod)->sbiod_next, opt, arg ) ) : 0 )
205
206 /* structure for returning a sequence of octet strings + length */
207 typedef struct berval {
208         ber_len_t       bv_len;
209         char            *bv_val;
210 } BerValue;
211
212 typedef BerValue *BerVarray;    /* To distinguish from a single bv */
213
214 /* this should be moved to lber-int.h */
215
216 /*
217  * in bprint.c:
218  */
219 LBER_F( void )
220 ber_error_print LDAP_P((
221         LDAP_CONST char *data ));
222
223 LBER_F( void )
224 ber_bprint LDAP_P((
225         LDAP_CONST char *data, ber_len_t len ));
226
227 LBER_F( void )
228 ber_dump LDAP_P((
229         BerElement *ber, int inout ));
230
231 /*
232  * in decode.c:
233  */
234 typedef int (*BERDecodeCallback) LDAP_P((
235         BerElement *ber,
236         void *data,
237         int mode ));
238
239 LBER_F( ber_tag_t )
240 ber_get_tag LDAP_P((
241         BerElement *ber ));
242
243 LBER_F( ber_tag_t )
244 ber_skip_tag LDAP_P((
245         BerElement *ber,
246         ber_len_t *len ));
247
248 LBER_F( ber_tag_t )
249 ber_peek_tag LDAP_P((
250         BerElement *ber,
251         ber_len_t *len ));
252
253 LBER_F( ber_tag_t )
254 ber_get_int LDAP_P((
255         BerElement *ber,
256         ber_int_t *num ));
257
258 LBER_F( ber_tag_t )
259 ber_get_enum LDAP_P((
260         BerElement *ber,
261         ber_int_t *num ));
262
263 LBER_F( ber_tag_t )
264 ber_get_stringb LDAP_P((
265         BerElement *ber,
266         char *buf,
267         ber_len_t *len ));
268
269 #define LBER_BV_ALLOC   0x01    /* allocate/copy result, otherwise in-place */
270 #define LBER_BV_NOTERM  0x02    /* omit NUL-terminator if parsing in-place */
271
272 LBER_F( ber_tag_t )
273 ber_get_stringbv LDAP_P((
274         BerElement *ber,
275         struct berval *bv,
276         int options ));
277
278 LBER_F( ber_tag_t )
279 ber_get_stringa LDAP_P((
280         BerElement *ber,
281         char **buf ));
282
283 LBER_F( ber_tag_t )
284 ber_get_stringal LDAP_P((
285         BerElement *ber,
286         struct berval **bv ));
287
288 LBER_F( ber_tag_t )
289 ber_get_bitstringa LDAP_P((
290         BerElement *ber,
291         char **buf,
292         ber_len_t *len ));
293
294 LBER_F( ber_tag_t )
295 ber_get_null LDAP_P((
296         BerElement *ber ));
297
298 LBER_F( ber_tag_t )
299 ber_get_boolean LDAP_P((
300         BerElement *ber,
301         ber_int_t *boolval ));
302
303 LBER_F( ber_tag_t )
304 ber_first_element LDAP_P((
305         BerElement *ber,
306         ber_len_t *len,
307         char **last ));
308
309 LBER_F( ber_tag_t )
310 ber_next_element LDAP_P((
311         BerElement *ber,
312         ber_len_t *len,
313         LDAP_CONST char *last ));
314
315 LBER_F( ber_tag_t )
316 ber_scanf LDAP_P((
317         BerElement *ber,
318         LDAP_CONST char *fmt,
319         ... ));
320
321 LBER_F( int )
322 ber_decode_oid LDAP_P((
323         struct berval *in,
324         struct berval *out ));
325
326 /*
327  * in encode.c
328  */
329 LBER_F( int )
330 ber_encode_oid LDAP_P((
331         struct berval *in,
332         struct berval *out ));
333
334 typedef int (*BEREncodeCallback) LDAP_P((
335         BerElement *ber,
336         void *data ));
337
338 LBER_F( int )
339 ber_put_enum LDAP_P((
340         BerElement *ber,
341         ber_int_t num,
342         ber_tag_t tag ));
343
344 LBER_F( int )
345 ber_put_int LDAP_P((
346         BerElement *ber,
347         ber_int_t num,
348         ber_tag_t tag ));
349
350 LBER_F( int )
351 ber_put_ostring LDAP_P((
352         BerElement *ber,
353         LDAP_CONST char *str,
354         ber_len_t len,
355         ber_tag_t tag ));
356
357 LBER_F( int )
358 ber_put_berval LDAP_P((
359         BerElement *ber,
360         struct berval *bv,
361         ber_tag_t tag ));
362
363 LBER_F( int )
364 ber_put_string LDAP_P((
365         BerElement *ber,
366         LDAP_CONST char *str,
367         ber_tag_t tag ));
368
369 LBER_F( int )
370 ber_put_bitstring LDAP_P((
371         BerElement *ber,
372         LDAP_CONST char *str,
373         ber_len_t bitlen,
374         ber_tag_t tag ));
375
376 LBER_F( int )
377 ber_put_null LDAP_P((
378         BerElement *ber,
379         ber_tag_t tag ));
380
381 LBER_F( int )
382 ber_put_boolean LDAP_P((
383         BerElement *ber,
384         ber_int_t boolval,
385         ber_tag_t tag ));
386
387 LBER_F( int )
388 ber_start_seq LDAP_P((
389         BerElement *ber,
390         ber_tag_t tag ));
391
392 LBER_F( int )
393 ber_start_set LDAP_P((
394         BerElement *ber,
395         ber_tag_t tag ));
396
397 LBER_F( int )
398 ber_put_seq LDAP_P((
399         BerElement *ber ));
400
401 LBER_F( int )
402 ber_put_set LDAP_P((
403         BerElement *ber ));
404
405 LBER_F( int )
406 ber_printf LDAP_P((
407         BerElement *ber,
408         LDAP_CONST char *fmt,
409         ... ));
410
411
412 /*
413  * in io.c:
414  */
415
416 LBER_F( ber_slen_t )
417 ber_skip_data LDAP_P((
418         BerElement *ber,
419         ber_len_t len ));
420
421 LBER_F( ber_slen_t )
422 ber_read LDAP_P((
423         BerElement *ber,
424         char *buf,
425         ber_len_t len ));
426
427 LBER_F( ber_slen_t )
428 ber_write LDAP_P((
429         BerElement *ber,
430         LDAP_CONST char *buf,
431         ber_len_t len,
432         int zero ));    /* nonzero is unsupported from OpenLDAP 2.4.18 */
433
434 LBER_F( void )
435 ber_free LDAP_P((
436         BerElement *ber,
437         int freebuf ));
438
439 LBER_F( void )
440 ber_free_buf LDAP_P(( BerElement *ber ));
441
442 LBER_F( int )
443 ber_flush2 LDAP_P((
444         Sockbuf *sb,
445         BerElement *ber,
446         int freeit ));
447 #define LBER_FLUSH_FREE_NEVER           (0x0)   /* traditional behavior */
448 #define LBER_FLUSH_FREE_ON_SUCCESS      (0x1)   /* traditional behavior */
449 #define LBER_FLUSH_FREE_ON_ERROR        (0x2)
450 #define LBER_FLUSH_FREE_ALWAYS          (LBER_FLUSH_FREE_ON_SUCCESS|LBER_FLUSH_FREE_ON_ERROR)
451
452 LBER_F( int )
453 ber_flush LDAP_P((
454         Sockbuf *sb,
455         BerElement *ber,
456         int freeit )); /* DEPRECATED */
457
458 LBER_F( BerElement * )
459 ber_alloc LDAP_P(( void )); /* DEPRECATED */
460
461 LBER_F( BerElement * )
462 der_alloc LDAP_P(( void )); /* DEPRECATED */
463
464 LBER_F( BerElement * )
465 ber_alloc_t LDAP_P((
466         int beroptions ));
467
468 LBER_F( BerElement * )
469 ber_dup LDAP_P((
470         BerElement *ber ));
471
472 LBER_F( ber_tag_t )
473 ber_get_next LDAP_P((
474         Sockbuf *sb,
475         ber_len_t *len,
476         BerElement *ber ));
477
478 LBER_F( void )
479 ber_init2 LDAP_P((
480         BerElement *ber,
481         struct berval *bv,
482         int options ));
483
484 LBER_F( void )
485 ber_init_w_nullc LDAP_P((       /* DEPRECATED */
486         BerElement *ber,
487         int options ));
488
489 LBER_F( void )
490 ber_reset LDAP_P((
491         BerElement *ber,
492         int was_writing ));
493
494 LBER_F( BerElement * )
495 ber_init LDAP_P((
496         struct berval *bv ));
497
498 LBER_F( int )
499 ber_flatten LDAP_P((
500         BerElement *ber,
501         struct berval **bvPtr ));
502
503 LBER_F( int )
504 ber_flatten2 LDAP_P((
505         BerElement *ber,
506         struct berval *bv,
507         int alloc ));
508
509 LBER_F( int )
510 ber_remaining LDAP_P((
511         BerElement *ber ));
512
513 /*
514  * LBER ber accessor functions
515  */
516
517 LBER_F( int )
518 ber_get_option LDAP_P((
519         void *item,
520         int option,
521         void *outvalue));
522
523 LBER_F( int )
524 ber_set_option LDAP_P((
525         void *item,
526         int option,
527         LDAP_CONST void *invalue));
528
529 /*
530  * LBER sockbuf.c
531  */
532
533 LBER_F( Sockbuf *  )
534 ber_sockbuf_alloc LDAP_P((
535         void ));
536
537 LBER_F( void )
538 ber_sockbuf_free LDAP_P((
539         Sockbuf *sb ));
540
541 LBER_F( int )
542 ber_sockbuf_add_io LDAP_P((
543         Sockbuf *sb,
544         Sockbuf_IO *sbio,
545         int layer,
546         void *arg ));
547
548 LBER_F( int )
549 ber_sockbuf_remove_io LDAP_P((
550         Sockbuf *sb,
551         Sockbuf_IO *sbio,
552         int layer ));
553
554 LBER_F( int )
555 ber_sockbuf_ctrl LDAP_P((
556         Sockbuf *sb,
557         int opt,
558         void *arg ));
559
560 LBER_V( Sockbuf_IO ) ber_sockbuf_io_tcp;
561 LBER_V( Sockbuf_IO ) ber_sockbuf_io_readahead;
562 LBER_V( Sockbuf_IO ) ber_sockbuf_io_fd;
563 LBER_V( Sockbuf_IO ) ber_sockbuf_io_debug;
564 LBER_V( Sockbuf_IO ) ber_sockbuf_io_udp;
565
566 /*
567  * LBER memory.c
568  */
569 LBER_F( void * )
570 ber_memalloc LDAP_P((
571         ber_len_t s ));
572
573 LBER_F( void * )
574 ber_memrealloc LDAP_P((
575         void* p,
576         ber_len_t s ));
577
578 LBER_F( void * )
579 ber_memcalloc LDAP_P((
580         ber_len_t n,
581         ber_len_t s ));
582
583 LBER_F( void )
584 ber_memfree LDAP_P((
585         void* p ));
586
587 LBER_F( void )
588 ber_memvfree LDAP_P((
589         void** vector ));
590
591 LBER_F( void )
592 ber_bvfree LDAP_P((
593         struct berval *bv ));
594
595 LBER_F( void )
596 ber_bvecfree LDAP_P((
597         struct berval **bv ));
598
599 LBER_F( int )
600 ber_bvecadd LDAP_P((
601         struct berval ***bvec,
602         struct berval *bv ));
603
604 LBER_F( struct berval * )
605 ber_dupbv LDAP_P((
606         struct berval *dst, struct berval *src ));
607
608 LBER_F( struct berval * )
609 ber_bvdup LDAP_P((
610         struct berval *src ));
611
612 LBER_F( struct berval * )
613 ber_mem2bv LDAP_P((
614         LDAP_CONST char *, ber_len_t len, int duplicate, struct berval *bv));
615
616 LBER_F( struct berval * )
617 ber_str2bv LDAP_P((
618         LDAP_CONST char *, ber_len_t len, int duplicate, struct berval *bv));
619
620 #define ber_bvstr(a)    ((ber_str2bv)((a), 0, 0, NULL))
621 #define ber_bvstrdup(a) ((ber_str2bv)((a), 0, 1, NULL))
622
623 LBER_F( char * )
624 ber_strdup LDAP_P((
625         LDAP_CONST char * ));
626
627 LBER_F( ber_len_t )
628 ber_strnlen LDAP_P((
629         LDAP_CONST char *s, ber_len_t len ));
630
631 LBER_F( char * )
632 ber_strndup LDAP_P((
633         LDAP_CONST char *s, ber_len_t l ));
634
635 LBER_F( struct berval * )
636 ber_bvreplace LDAP_P((
637         struct berval *dst, LDAP_CONST struct berval *src ));
638
639 LBER_F( void )
640 ber_bvarray_free LDAP_P(( BerVarray p ));
641
642 LBER_F( int )
643 ber_bvarray_add LDAP_P(( BerVarray *p, BerValue *bv ));
644
645 #define ber_bvcmp(v1,v2) \
646         ((v1)->bv_len < (v2)->bv_len \
647                 ? -1 : ((v1)->bv_len > (v2)->bv_len \
648                         ? 1 : memcmp((v1)->bv_val, (v2)->bv_val, (v1)->bv_len) ))
649
650 /*
651  * error.c
652  */
653 LBER_F( int * ) ber_errno_addr LDAP_P((void));
654 #define ber_errno (*(ber_errno_addr)())
655
656 #define LBER_ERROR_NONE         0
657 #define LBER_ERROR_PARAM        0x1
658 #define LBER_ERROR_MEMORY       0x2
659
660 LDAP_END_DECL
661
662 #endif /* _LBER_H */