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 */
46typedef 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
57typedef struct
58{
59	uint32_t kcount;
60	const char **key;
61	uint32_t *vcount;
62	const char ***val;
63} kvdict_t;
64
65typedef 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 */
78kvbuf_t *kvbuf_new(void);
79kvbuf_t *kvbuf_new_zone(malloc_zone_t *zone);
80kvbuf_t *kvbuf_init(char *buffer, uint32_t length);
81kvbuf_t *kvbuf_init_zone(malloc_zone_t *zone, char *buffer, uint32_t length);
82
83void kvbuf_add_dict(kvbuf_t *kv);
84void kvbuf_add_key(kvbuf_t *kv, const char *key);
85void kvbuf_add_val(kvbuf_t *kv, const char *val);
86void kvbuf_add_val_len(kvbuf_t *kv, const char *val, uint32_t len);
87uint32_t kvbuf_get_len(const char *p);
88
89void kvbuf_make_purgeable(kvbuf_t *kv);
90int kvbuf_make_nonpurgeable(kvbuf_t *kv);
91
92void 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
101kvarray_t *kvbuf_decode(kvbuf_t *kv);
102void kvarray_free(kvarray_t *a);
103
104/*
105 * Utility to append a kvbuf to an existing kvbuf
106 */
107void 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 */
113uint32_t kvbuf_reset(kvbuf_t *kv);
114
115/*
116 * Walk through dictionaries.
117 * Returns the number of keys in the dictionary.
118 */
119uint32_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 */
126char *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 */
132char *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 */
138char *kvbuf_next_val_len(kvbuf_t *kv, uint32_t *vl );
139
140/*
141 * kvbuf query support
142 */
143kvbuf_t *kvbuf_query(char *fmt, ...);
144kvbuf_t *kvbuf_query_key_int(const char *key, int32_t i);
145kvbuf_t *kvbuf_query_key_uint(const char *key, uint32_t u);
146kvbuf_t *kvbuf_query_key_val(const char *key, const char *val);
147
148__END_DECLS
149
150#endif /* ! _KVBUF_H_ */
151