Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / hash.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJ_HASH_H__
21 #define __PJ_HASH_H__
22
23 /**
24  * @file hash.h
25  * @brief Hash Table.
26  */
27
28 #include <pj/types.h>
29
30 PJ_BEGIN_DECL
31
32 /**
33  * @defgroup PJ_HASH Hash Table
34  * @ingroup PJ_DS
35  * @{
36  * A hash table is a dictionary in which keys are mapped to array positions by
37  * hash functions. Having the keys of more than one item map to the same 
38  * position is called a collision. In this library, we will chain the nodes
39  * that have the same key in a list.
40  */
41
42 /**
43  * If this constant is used as keylen, then the key is interpreted as
44  * NULL terminated string.
45  */
46 #define PJ_HASH_KEY_STRING      ((unsigned)-1)
47
48 /**
49  * This indicates the size of of each hash entry.
50  */
51 #define PJ_HASH_ENTRY_BUF_SIZE  (3*sizeof(void*) + 2*sizeof(pj_uint32_t))
52
53 /**
54  * Type declaration for entry buffer, used by #pj_hash_set_np()
55  */
56 typedef void *pj_hash_entry_buf[(PJ_HASH_ENTRY_BUF_SIZE+sizeof(void*)-1)/(sizeof(void*))];
57
58 /**
59  * This is the function that is used by the hash table to calculate hash value
60  * of the specified key.
61  *
62  * @param hval      the initial hash value, or zero.
63  * @param key       the key to calculate.
64  * @param keylen    the length of the key, or PJ_HASH_KEY_STRING to treat 
65  *                  the key as null terminated string.
66  *
67  * @return          the hash value.
68  */
69 PJ_DECL(pj_uint32_t) pj_hash_calc(pj_uint32_t hval, 
70                                   const void *key, unsigned keylen);
71
72
73 /**
74  * Convert the key to lowercase and calculate the hash value. The resulting
75  * string is stored in \c result.
76  *
77  * @param hval      The initial hash value, normally zero.
78  * @param result    Buffer to store the result, which must be enough to hold
79  *                  the string.
80  * @param key       The input key to be converted and calculated.
81  *
82  * @return          The hash value.
83  */
84 PJ_DECL(pj_uint32_t) pj_hash_calc_tolower(pj_uint32_t hval,
85                                           char *result,
86                                           const pj_str_t *key);
87
88 /**
89  * Create a hash table with the specified 'bucket' size.
90  *
91  * @param pool  the pool from which the hash table will be allocated from.
92  * @param size  the bucket size, which will be round-up to the nearest 2^n-1
93  *
94  * @return the hash table.
95  */
96 PJ_DECL(pj_hash_table_t*) pj_hash_create(pj_pool_t *pool, unsigned size);
97
98
99 /**
100  * Get the value associated with the specified key.
101  *
102  * @param ht        the hash table.
103  * @param key       the key to look for.
104  * @param keylen    the length of the key, or PJ_HASH_KEY_STRING to use the
105  *                  string length of the key.
106  * @param hval      if this argument is not NULL and the value is not zero,
107  *                  the value will be used as the computed hash value. If
108  *                  the argument is not NULL and the value is zero, it will
109  *                  be filled with the computed hash upon return.
110  *
111  * @return the value associated with the key, or NULL if the key is not found.
112  */
113 PJ_DECL(void *) pj_hash_get( pj_hash_table_t *ht,
114                              const void *key, unsigned keylen,
115                              pj_uint32_t *hval );
116
117
118 /**
119  * Associate/disassociate a value with the specified key. If value is not
120  * NULL and entry already exists, the entry's value will be overwritten.
121  * If value is not NULL and entry does not exist, a new one will be created
122  * with the specified pool. Otherwise if value is NULL, entry will be
123  * deleted if it exists.
124  *
125  * @param pool      the pool to allocate the new entry if a new entry has to be
126  *                  created.
127  * @param ht        the hash table.
128  * @param key       the key. If pool is not specified, the key MUST point to
129  *                  buffer that remains valid for the duration of the entry.
130  * @param keylen    the length of the key, or PJ_HASH_KEY_STRING to use the 
131  *                  string length of the key.
132  * @param hval      if the value is not zero, then the hash table will use
133  *                  this value to search the entry's index, otherwise it will
134  *                  compute the key. This value can be obtained when calling
135  *                  #pj_hash_get().
136  * @param value     value to be associated, or NULL to delete the entry with
137  *                  the specified key.
138  */
139 PJ_DECL(void) pj_hash_set( pj_pool_t *pool, pj_hash_table_t *ht,
140                            const void *key, unsigned keylen, pj_uint32_t hval,
141                            void *value );
142
143
144 /**
145  * Associate/disassociate a value with the specified key. This function works
146  * like #pj_hash_set(), except that it doesn't use pool (hence the np -- no 
147  * pool suffix). If new entry needs to be allocated, it will use the entry_buf.
148  *
149  * @param ht        the hash table.
150  * @param key       the key.
151  * @param keylen    the length of the key, or PJ_HASH_KEY_STRING to use the 
152  *                  string length of the key.
153  * @param hval      if the value is not zero, then the hash table will use
154  *                  this value to search the entry's index, otherwise it will
155  *                  compute the key. This value can be obtained when calling
156  *                  #pj_hash_get().
157  * @param entry_buf Buffer which will be used for the new entry, when one needs
158  *                  to be created.
159  * @param value     value to be associated, or NULL to delete the entry with
160  *                  the specified key.
161  */
162 PJ_DECL(void) pj_hash_set_np(pj_hash_table_t *ht,
163                              const void *key, unsigned keylen, 
164                              pj_uint32_t hval, pj_hash_entry_buf entry_buf, 
165                              void *value);
166
167 /**
168  * Get the total number of entries in the hash table.
169  *
170  * @param ht    the hash table.
171  *
172  * @return the number of entries in the hash table.
173  */
174 PJ_DECL(unsigned) pj_hash_count( pj_hash_table_t *ht );
175
176
177 /**
178  * Get the iterator to the first element in the hash table. 
179  *
180  * @param ht    the hash table.
181  * @param it    the iterator for iterating hash elements.
182  *
183  * @return the iterator to the hash element, or NULL if no element presents.
184  */
185 PJ_DECL(pj_hash_iterator_t*) pj_hash_first( pj_hash_table_t *ht,
186                                             pj_hash_iterator_t *it );
187
188
189 /**
190  * Get the next element from the iterator.
191  *
192  * @param ht    the hash table.
193  * @param it    the hash iterator.
194  *
195  * @return the next iterator, or NULL if there's no more element.
196  */
197 PJ_DECL(pj_hash_iterator_t*) pj_hash_next( pj_hash_table_t *ht, 
198                                            pj_hash_iterator_t *it );
199
200 /**
201  * Get the value associated with a hash iterator.
202  *
203  * @param ht    the hash table.
204  * @param it    the hash iterator.
205  *
206  * @return the value associated with the current element in iterator.
207  */
208 PJ_DECL(void*) pj_hash_this( pj_hash_table_t *ht,
209                              pj_hash_iterator_t *it );
210
211
212 /**
213  * @}
214  */
215
216 PJ_END_DECL
217
218 #endif
219
220