lookup.subproj/kvbuf.h

   1 /*
   2  * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Portions Copyright (c) 1999 Apple Computer, Inc.  All Rights
   7  * Reserved.  This file contains Original Code and/or Modifications of
   8  * Original Code as defined in and that are subject to the Apple Public
   9  * Source License Version 1.1 (the "License").  You may not use this file
  10  * except in compliance with the License.  Please obtain a copy of the
  11  * License at http://www.apple.com/publicsource and read it before using
  12  * this file.
  13  *
  14  * The Original Code and all software distributed under the License are
  15  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  16  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  17  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE OR NON- INFRINGEMENT.  Please see the
  19  * License for the specific language governing rights and limitations
  20  * under the License.
  21  *
  22  * @APPLE_LICENSE_HEADER_END@
  23  */
  24 /*
  25  * Useful macros and other stuff for generic lookups
  26  * Copyright (C) 1989 by NeXT, Inc.
  27  */
  28
  29 #ifndef _KVBUF_H_
  30 #define _KVBUF_H_
  31
  32 #include <stdint.h>
  33 #include <sys/cdefs.h>
  34
  35 /*
  36  * kvbuf_t is used to encode requests and replies.
  37  * It encodes a list of dictionaries.
  38  * First 4 bytes are number of dictionaries.
  39  * All numbers and lengths are uint32_t in network byte order.
  40  * Each dictionary is a list of (key, value list) pairs.
  41  * First 4 bytes in a dictionary are the number of keys.
  42  * Key is 4 bytes (length) followed by nul-terminated string.
  43  * Following the key is a value list.
  44  * First 4 bytes in a value list are the number of values.
  45  * Each value is 4 bytes (length) followed by nul-terminated string.
  46  */
  47 typedef struct
  48 {
  49         uint32_t datalen;
  50         char *databuf;
  51         uint32_t _size;
  52         uint32_t _dict;
  53         uint32_t _key;
  54         uint32_t _vlist;
  55         uint32_t _val;
  56 } kvbuf_t;
  57
  58 typedef struct
  59 {
  60         uint32_t kcount;
  61         const char **key;
  62         uint32_t *vcount;
  63         const char ***val;
  64 } kvdict_t;
  65
  66 typedef struct
  67 {
  68         uint32_t count;
  69         uint32_t curr;
  70         kvdict_t *dict;
  71         kvbuf_t *kv;
  72 } kvarray_t;
  73
  74 __BEGIN_DECLS
  75
  76 /*
  77  * Utilities for creating KV buffers
  78  */
  79 kvbuf_t *kvbuf_new(void);
  80 kvbuf_t *kvbuf_init(char *buffer, uint32_t length);
  81
  82 void kvbuf_add_dict(kvbuf_t *kv);
  83 void kvbuf_add_key(kvbuf_t *kv, const char *key);
  84 void kvbuf_add_val(kvbuf_t *kv, const char *val);
  85 void kvbuf_add_val_len(kvbuf_t *kv, const char *val, uint32_t len);
  86 uint32_t kvbuf_get_len(const char *p);
  87 void kvbuf_free(kvbuf_t *kv);
  88
  89 /*
  90  * Utilities for getting data back from KV buffers
  91  * These are ugly, but reasonably efficient.
  92  * Libinfo routines decode the raw databuf in a single pass
  93  * i.e. not with these routines.
  94  */
  95
  96 kvarray_t *kvbuf_decode(kvbuf_t *kv);
  97 void kvarray_free(kvarray_t *a);
  98
  99 /*
 100  * Utility to append a kvbuf to an existing kvbuf
 101  */
 102 void kvbuf_append_kvbuf( kvbuf_t *kv, const kvbuf_t *kv2 );
 103
 104 /*
 105  * Call this to start walking through the kvbuf.
 106  * Returns the number of dictionaries.
 107  */
 108 uint32_t kvbuf_reset(kvbuf_t *kv);
 109
 110 /*
 111  * Walk through dictionaries.
 112  * Returns the number of keys in the dictionary.
 113  */
 114 uint32_t kvbuf_next_dict(kvbuf_t *kv);
 115
 116 /*
 117  * Walk through keys in a dictionary.
 118  * Returns the key.  Don't free it!
 119  * Sets the number of values for the key in the val_count output parameter.
 120  */
 121 char *kvbuf_next_key(kvbuf_t *kv, uint32_t *val_count);
 122
 123 /*
 124  * Walk through values for a key.
 125  * Returns the value.  Don't free it!
 126  */
 127 char *kvbuf_next_val(kvbuf_t *kv);
 128
 129 /*
 130  * Walk through values for a key, with a length returned
 131  * Returns the value.  Don't free it!
 132  */
 133 char *kvbuf_next_val_len(kvbuf_t *kv, uint32_t *vl );
 134
 135 __END_DECLS
 136
 137 #endif /* ! _KVBUF_H_ */