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

https://github.com/slibre/freepascal · Pascal · 447 lines · 111 code · 37 blank · 299 comment · 0 complexity · cda4bc247df8cd9f37155f59d518d725 MD5 · raw file

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