lookup.subproj/kvbuf.h

   1 /*
   2  * Copyright (c) 2006-2008 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Portions Copyright (c) 2003 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 #ifndef _KVBUF_H_
  26 #define _KVBUF_H_
  27
  28 #include <stdint.h>
  29 #include <sys/cdefs.h>
  30 #include <malloc/malloc.h>
  31
  32 #define KVBUF_START_SIZE 128
  33
  34 /*
  35  * kvbuf_t is used to encode requests and replies.
  36  * It encodes a list of dictionaries.
  37  * First 4 bytes are number of dictionaries.
  38  * All numbers and lengths are uint32_t in network byte order.
  39  * Each dictionary is a list of (key, value list) pairs.
  40  * First 4 bytes in a dictionary are the number of keys.
  41  * Key is 4 bytes (length) followed by nul-terminated string.
  42  * Following the key is a value list.
  43  * First 4 bytes in a value list are the number of values.
  44  * Each value is 4 bytes (length) followed by nul-terminated string.
  45  */
  46 typedef struct
  47 {
  48         uint32_t datalen;
  49         char *databuf;
  50         uint32_t _size;
  51         uint32_t _dict;
  52         uint32_t _key;
  53         uint32_t _vlist;
  54         uint32_t _val;
  55 } kvbuf_t;
  56
  57 typedef struct
  58 {
  59         uint32_t kcount;
  60         const char **key;
  61         uint32_t *vcount;
  62         const char ***val;
  63 } kvdict_t;
  64
  65 typedef struct
  66 {
  67         uint32_t count;
  68         uint32_t curr;
  69         kvdict_t *dict;
  70         kvbuf_t *kv;
  71 } kvarray_t;
  72
  73 __BEGIN_DECLS
  74
  75 /*
  76  * Utilities for creating KV buffers
  77  */
  78 kvbuf_t *kvbuf_new(void);
  79 kvbuf_t *kvbuf_new_zone(malloc_zone_t *zone);
  80 kvbuf_t *kvbuf_init(char *buffer, uint32_t length);
  81 kvbuf_t *kvbuf_init_zone(malloc_zone_t *zone, char *buffer, uint32_t length);
  82
  83 void kvbuf_add_dict(kvbuf_t *kv);
  84 void kvbuf_add_key(kvbuf_t *kv, const char *key);
  85 void kvbuf_add_val(kvbuf_t *kv, const char *val);
  86 void kvbuf_add_val_len(kvbuf_t *kv, const char *val, uint32_t len);
  87 uint32_t kvbuf_get_len(const char *p);
  88
  89 void kvbuf_make_purgeable(kvbuf_t *kv);
  90 int kvbuf_make_nonpurgeable(kvbuf_t *kv);
  91
  92 void kvbuf_free(kvbuf_t *kv);
  93
  94 /*
  95  * Utilities for getting data back from KV buffers
  96  * These are ugly, but reasonably efficient.
  97  * Libinfo routines decode the raw databuf in a single pass
  98  * i.e. not with these routines.
  99  */
 100
 101 kvarray_t *kvbuf_decode(kvbuf_t *kv);
 102 void kvarray_free(kvarray_t *a);
 103
 104 /*
 105  * Utility to append a kvbuf to an existing kvbuf
 106  */
 107 void kvbuf_append_kvbuf( kvbuf_t *kv, const kvbuf_t *kv2 );
 108
 109 /*
 110  * Call this to start walking through the kvbuf.
 111  * Returns the number of dictionaries.
 112  */
 113 uint32_t kvbuf_reset(kvbuf_t *kv);
 114
 115 /*
 116  * Walk through dictionaries.
 117  * Returns the number of keys in the dictionary.
 118  */
 119 uint32_t kvbuf_next_dict(kvbuf_t *kv);
 120
 121 /*
 122  * Walk through keys in a dictionary.
 123  * Returns the key.  Don't free it!
 124  * Sets the number of values for the key in the val_count output parameter.
 125  */
 126 char *kvbuf_next_key(kvbuf_t *kv, uint32_t *val_count);
 127
 128 /*
 129  * Walk through values for a key.
 130  * Returns the value.  Don't free it!
 131  */
 132 char *kvbuf_next_val(kvbuf_t *kv);
 133
 134 /*
 135  * Walk through values for a key, with a length returned
 136  * Returns the value.  Don't free it!
 137  */
 138 char *kvbuf_next_val_len(kvbuf_t *kv, uint32_t *vl );
 139
 140 /*
 141  * kvbuf query support
 142  */
 143 kvbuf_t *kvbuf_query(char *fmt, ...);
 144 kvbuf_t *kvbuf_query_key_int(const char *key, int32_t i);
 145 kvbuf_t *kvbuf_query_key_uint(const char *key, uint32_t u);
 146 kvbuf_t *kvbuf_query_key_val(const char *key, const char *val);
 147
 148 __END_DECLS
 149
 150 #endif /* ! _KVBUF_H_ */