/packages/httpd22/src/apr/apr_tables.inc

  1{ Copyright 2000-2005 The Apache Software Foundation or its licensors, as
  2 * applicable.
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 *     http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 }
 16
 17{
 18 * @file apr_tables.h
 19 * @brief APR Table library
 20 }
 21
 22{
 23 * @defgroup apr_tables Table and Array Functions
 24 * @ingroup APR
 25 * Tables are used to store entirely opaque structures
 26 * for applications, while Arrays are usually used to
 27 * deal with string lists.
 28 }
 29
 30{ the table abstract data type }
 31type
 32  apr_table_t = record end;
 33  Papr_table_t = ^apr_table_t;
 34
 35{ An opaque array type }
 36  apr_array_header_t = record
 37    { The pool the array is allocated out of }
 38    pool: Papr_pool_t;
 39    { The amount of memory allocated for each element of the array }
 40    elt_size: Integer;
 41    { The number of active elements in the array }
 42    nelts: Integer;
 43    { The number of elements allocated in the array }
 44    nalloc: Integer;
 45    { The elements in the array }
 46    elts: PChar;
 47  end;
 48  Papr_array_header_t = ^apr_array_header_t;
 49  PPapr_array_header_t = ^Papr_array_header_t;
 50
 51{
 52 * The (opaque) structure for string-content tables.
 53 }
 54
 55{ The type for each entry in a string-content table }
 56  apr_table_entry_t = record
 57    { The key for the current table entry }
 58    key: PChar;          { maybe NULL in future;
 59                         * check when iterating thru table_elts
 60                         }
 61    { The value for the current table entry }
 62    val: PChar;
 63
 64    { A checksum for the key, for use by the apr_table internals }
 65    key_checksum: apr_uint32_t;
 66  end;
 67
 68{
 69 * Get the elements from a table
 70 * @param t The table
 71 * @return An array containing the contents of the table
 72 }
 73function apr_table_elts(const t: Papr_table_t): Papr_array_header_t;
 74 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
 75 external LibAPR name LibNamePrefix + 'apr_table_elts' + LibSuff4;
 76
 77{
 78 * Determine if the table is empty
 79 * @param t The table to check
 80 * @return True if empty, False otherwise
 81 }
 82function apr_is_empty_table(const t: Papr_table_t): Integer;
 83 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
 84 external LibAPR name LibNamePrefix + 'apr_is_empty_table' + LibSuff4;
 85
 86{
 87 * Determine if the array is empty
 88 * @param a The array to check
 89 * @return True if empty, False otherwise
 90 }
 91function apr_is_empty_array(const a: Papr_array_header_t): Integer;
 92 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
 93 external LibAPR name LibNamePrefix + 'apr_is_empty_array' + LibSuff4;
 94
 95{
 96 * Create an array
 97 * @param p The pool to allocate the memory out of
 98 * @param nelts the number of elements in the initial array
 99 * @param elt_size The size of each element in the array.
100 * @return The new array
101 }
102function apr_array_make(p: Papr_pool_t;
103 nelts, elt_size: Integer): Papr_array_header_t;
104 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
105 external LibAPR name LibNamePrefix + 'apr_array_make' + LibSuff12;
106
107{
108 * Add a new element to an array (as a first-in, last-out stack)
109 * @param arr The array to add an element to.
110 * @return Location for the new element in the array.
111 * @remark If there are no free spots in the array, then this function will
112 *         allocate new space for the new element.
113 }
114function apr_array_push(arr: Papr_array_header_t): Pointer;
115 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
116 external LibAPR name LibNamePrefix + 'apr_array_push' + LibSuff4;
117
118{
119 * Remove an element from an array (as a first-in, last-out stack)
120 * @param arr The array to remove an element from.
121 * @return Location of the element in the array.
122 * @remark If there are no elements in the array, NULL is returned.
123 }
124function apr_array_pop(arr: Papr_array_header_t): Pointer;
125 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
126 external LibAPR name LibNamePrefix + 'apr_array_pop' + LibSuff4;
127
128{
129 * Concatenate two arrays together
130 * @param dst The destination array, and the one to go first in the combined
131 *            array
132 * @param src The source array to add to the destination array
133 }
134procedure apr_array_cat(dst: Papr_array_header_t;
135 const src: Papr_array_header_t);
136 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
137 external LibAPR name LibNamePrefix + 'apr_array_cat' + LibSuff8;
138
139{
140 * Copy the entire array
141 * @param p The pool to allocate the copy of the array out of
142 * @param arr The array to copy
143 * @return An exact copy of the array passed in
144 * @remark The alternate apr_array_copy_hdr copies only the header, and arranges
145 *         for the elements to be copied if (and only if) the code subsequently
146 *         does a push or arraycat.
147 }
148function apr_array_copy(p: Papr_pool_t;
149 const arr: Papr_array_header_t): Papr_array_header_t;
150 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
151 external LibAPR name LibNamePrefix + 'apr_array_copy' + LibSuff8;
152
153{
154 * Copy the headers of the array, and arrange for the elements to be copied if
155 * and only if the code subsequently does a push or arraycat.
156 * @param p The pool to allocate the copy of the array out of
157 * @param arr The array to copy
158 * @return An exact copy of the array passed in
159 * @remark The alternate apr_array_copy copies the *entire* array.
160 }
161function apr_array_copy_hdr(p: Papr_pool_t;
162 const arr: Papr_array_header_t): Papr_array_header_t;
163 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
164 external LibAPR name LibNamePrefix + 'apr_array_copy_hdr' + LibSuff8;
165
166{
167 * Append one array to the end of another, creating a new array in the process.
168 * @param p The pool to allocate the new array out of
169 * @param first The array to put first in the new array.
170 * @param second The array to put second in the new array.
171 * @return A new array containing the data from the two arrays passed in.
172}
173function apr_array_append(p: Papr_pool_t;
174 const first, second: Papr_array_header_t): Papr_array_header_t;
175 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
176 external LibAPR name LibNamePrefix + 'apr_array_append' + LibSuff12;
177
178{
179 * Generates a new string from the apr_pool_t containing the concatenated
180 * sequence of substrings referenced as elements within the array.  The string
181 * will be empty if all substrings are empty or null, or if there are no
182 * elements in the array.  If sep is non-NUL, it will be inserted between
183 * elements as a separator.
184 * @param p The pool to allocate the string out of
185 * @param arr The array to generate the string from
186 * @param sep The separator to use
187 * @return A string containing all of the data in the array.
188 }
189function apr_array_pstrcat(p: Papr_pool_t;
190 const arr: Papr_array_header_t; sep: Char): PChar;
191 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
192 external LibAPR name LibNamePrefix + 'apr_array_pstrcat' + LibSuff12;
193
194{
195 * Make a new table
196 * @param p The pool to allocate the pool out of
197 * @param nelts The number of elements in the initial table.
198 * @return The new table.
199 * @warning This table can only store text data
200 }
201function apr_table_make(p: Papr_pool_t; nelts: Integer): Papr_table_t;
202 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
203 external LibAPR name LibNamePrefix + 'apr_table_make' + LibSuff8;
204
205{
206 * Create a new table and copy another table into it
207 * @param p The pool to allocate the new table out of
208 * @param t The table to copy
209 * @return A copy of the table passed in
210 }
211function apr_table_copy(p: Papr_pool_t; const t: Papr_table_t): Papr_table_t;
212 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
213 external LibAPR name LibNamePrefix + 'apr_table_copy' + LibSuff8;
214
215{
216 * Delete all of the elements from a table
217 * @param t The table to clear
218 }
219procedure apr_table_clear(t: Papr_table_t);
220 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
221 external LibAPR name LibNamePrefix + 'apr_table_clear' + LibSuff4;
222
223{
224 * Get the value associated with a given key from the table.  After this call,
225 * The data is still in the table
226 * @param t The table to search for the key
227 * @param key The key to search for
228 * @return The value associated with the key, or NULL if the key does not exist.
229 }
230function apr_table_get(t: Papr_table_t; key: PChar): PChar;
231 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
232 external LibAPR name LibNamePrefix + 'apr_table_get' + LibSuff8;
233
234{
235 * Add a key/value pair to a table, if another element already exists with the
236 * same key, this will over-write the old data.
237 * @param t The table to add the data to.
238 * @param key The key fo use
239 * @param val The value to add
240 * @remark When adding data, this function makes a copy of both the key and the
241 *         value.
242 }
243procedure apr_table_set(t: Papr_table_t; const key, val: PChar);
244 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
245 external LibAPR name LibNamePrefix + 'apr_table_set' + LibSuff12;
246
247{
248 * Add a key/value pair to a table, if another element already exists with the
249 * same key, this will over-write the old data.
250 * @param t The table to add the data to.
251 * @param key The key to use
252 * @param val The value to add
253 * @warning When adding data, this function does not make a copy of the key or
254 *          the value, so care should be taken to ensure that the values will
255 *          not change after they have been added..
256 }
257procedure apr_table_setn(t: Papr_table_t; const key, val: PChar);
258 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
259 external LibAPR name LibNamePrefix + 'apr_table_setn' + LibSuff12;
260
261{
262 * Remove data from the table
263 * @param t The table to remove data from
264 * @param key The key of the data being removed
265 }
266procedure apr_table_unset(t: Papr_table_t; const key: PChar);
267 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
268 external LibAPR name LibNamePrefix + 'apr_table_unset' + LibSuff8;
269
270{
271 * Add data to a table by merging the value with data that has already been
272 * stored
273 * @param t The table to search for the data
274 * @param key The key to merge data for
275 * @param val The data to add
276 * @remark If the key is not found, then this function acts like apr_table_add
277 }
278procedure apr_table_merge(t: Papr_table_t; const key, val: PChar);
279 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
280 external LibAPR name LibNamePrefix + 'apr_table_merge' + LibSuff12;
281
282{
283 * Add data to a table by merging the value with data that has already been
284 * stored
285 * @param t The table to search for the data
286 * @param key The key to merge data for
287 * @param val The data to add
288 * @remark If the key is not found, then this function acts like apr_table_addn
289 }
290procedure apr_table_mergen(t: Papr_table_t; const key, val: PChar);
291 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
292 external LibAPR name LibNamePrefix + 'apr_table_mergen' + LibSuff12;
293
294{
295 * Add data to a table, regardless of whether there is another element with the
296 * same key.
297 * @param t The table to add to
298 * @param key The key to use
299 * @param val The value to add.
300 * @remark When adding data, this function makes a copy of both the key and the
301 *         value.
302 }
303procedure apr_table_add(t: Papr_table_t; const key, val: PChar);
304 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
305 external LibAPR name LibNamePrefix + 'apr_table_add' + LibSuff12;
306
307{
308 * Add data to a table, regardless of whether there is another element with the
309 * same key.
310 * @param t The table to add to
311 * @param key The key to use
312 * @param val The value to add.
313 * @remark When adding data, this function does not make a copy of the key or the
314 *         value, so care should be taken to ensure that the values will not
315 *         change after they have been added..
316 }
317procedure apr_table_addn(t: Papr_table_t; const key, val: PChar);
318 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
319 external LibAPR name LibNamePrefix + 'apr_table_addn' + LibSuff12;
320
321{
322 * Merge two tables into one new table
323 * @param p The pool to use for the new table
324 * @param overlay The first table to put in the new table
325 * @param base The table to add at the end of the new table
326 * @return A new table containing all of the data from the two passed in
327 }
328function apr_table_overlay(t: Papr_table_t;
329 const overlay, base: Papr_table_t): Papr_table_t;
330 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
331 external LibAPR name LibNamePrefix + 'apr_table_overlay' + LibSuff12;
332
333{
334 * Declaration prototype for the iterator callback function of apr_table_do()
335 * and apr_table_vdo().
336 * @param rec The data passed as the first argument to apr_table_[v]do()
337 * @param key The key from this iteration of the table
338 * @param value The value from this iteration of the table
339 * @remark Iteration continues while this callback function returns non-zero.
340 * To export the callback function for apr_table_[v]do() it must be declared
341 * in the _NONSTD convention.
342 }
343type
344  apr_table_do_callback_fn_t = function (rec: Pointer;
345   const key, value: PChar): Integer;
346   
347  Papr_table_do_callback_fn_t = ^apr_table_do_callback_fn_t;
348
349{
350 * Iterate over a table running the provided function once for every
351 * element in the table.  If there is data passed in as a vararg, then the
352 * function is only run on those elements whose key matches something in
353 * the vararg.  If the vararg is NULL, then every element is run through the
354 * function.  Iteration continues while the function returns non-zero.
355 * @param comp The function to run
356 * @param rec The data to pass as the first argument to the function
357 * @param t The table to iterate over
358 * @param ... The vararg.  If this is NULL, then all elements in the table are
359 *            run through the function, otherwise only those whose key matches
360 *            are run.
361 * @return FALSE if one of the comp() iterations returned zero; TRUE if all
362 *            iterations returned non-zero
363 * @see apr_table_do_callback_fn_t
364 }
365{APR_DECLARE_NONSTD(int) apr_table_do(apr_table_do_callback_fn_t *comp,
366                                     void *rec, const apr_table_t *t, ...);
367}
368{
369 * Iterate over a table running the provided function once for every
370 * element in the table.  If there is data passed in as a vararg, then the
371 * function is only run on those element's whose key matches something in
372 * the vararg.  If the vararg is NULL, then every element is run through the
373 * function.  Iteration continues while the function returns non-zero.
374 * @param comp The function to run
375 * @param rec The data to pass as the first argument to the function
376 * @param t The table to iterate over
377 * @param vp The vararg table.  If this is NULL, then all elements in the
378 *                table are run through the function, otherwise only those
379 *                whose key matches are run.
380 * @return FALSE if one of the comp() iterations returned zero; TRUE if all
381 *            iterations returned non-zero
382 * @see apr_table_do_callback_fn_t
383 }
384function apr_table_vdo(comp: Papr_table_do_callback_fn_t;
385 rec: Pointer; const t: Papr_table_t; vp: va_list): Integer;
386 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
387 external LibAPR name LibNamePrefix + 'apr_table_vdo' + LibSuff16;
388
389const
390  { flag for overlap to use apr_table_setn }
391  APR_OVERLAP_TABLES_SET = 0;
392  { flag for overlap to use apr_table_mergen }
393  APR_OVERLAP_TABLES_MERGE = 1;
394
395{
396 * For each element in table b, either use setn or mergen to add the data
397 * to table a.  Which method is used is determined by the flags passed in.
398 * @param a The table to add the data to.
399 * @param b The table to iterate over, adding its data to table a
400 * @param flags How to add the table to table a.  One of:
401 *          APR_OVERLAP_TABLES_SET        Use apr_table_setn
402 *          APR_OVERLAP_TABLES_MERGE      Use apr_table_mergen
403 * @remark  This function is highly optimized, and uses less memory and CPU cycles
404 *          than a function that just loops through table b calling other functions.
405 }
406{
407 *<PRE>
408 * Conceptually, apr_table_overlap does this:
409 *
410 *  apr_array_header_t *barr = apr_table_elts(b);
411 *  apr_table_entry_t *belt = (apr_table_entry_t *)barr->elts;
412 *  int i;
413 *
414 *  for (i = 0; i < barr->nelts; ++i) (
415 *      if (flags & APR_OVERLAP_TABLES_MERGE) (
416 *          apr_table_mergen(a, belt[i].key, belt[i].val);
417 *      )
418 *      else (
419 *          apr_table_setn(a, belt[i].key, belt[i].val);
420 *      )
421 *  )
422 *
423 *  Except that it is more efficient (less space and cpu-time) especially
424 *  when b has many elements.
425 *
426 *  Notice the assumptions on the keys and values in b -- they must be
427 *  in an ancestor of a's pool.  In practice b and a are usually from
428 *  the same pool.
429 * </PRE>
430 }
431procedure apr_table_overlap(a: Papr_table_t;
432 const b: Papr_table_t; flags: cuint);
433 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
434 external LibAPR name LibNamePrefix + 'apr_table_overlap' + LibSuff12;
435
436{
437 * Eliminate redundant entries in a table by either overwriting
438 * or merging duplicates
439 *
440 * @param t Table.
441 * @param flags APR_OVERLAP_TABLES_MERGE to merge, or
442 *              APR_OVERLAP_TABLES_SET to overwrite
443 }
444procedure apr_table_compress(t: Papr_table_t; flags: cuint);
445 {$IFDEF WINDOWS} stdcall; {$ELSE} cdecl; {$ENDIF}
446 external LibAPR name LibNamePrefix + 'apr_table_compress' + LibSuff8;
447