/security/nss/lib/libpkix/include/pkix_util.h

http://github.com/zpao/v8monkey · C Header · 974 lines · 160 code · 40 blank · 774 comment · 0 complexity · e478f9474ddc537598b80afc3fd27720 MD5 · raw file

  1. /* ***** BEGIN LICENSE BLOCK *****
  2. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3. *
  4. * The contents of this file are subject to the Mozilla Public License Version
  5. * 1.1 (the "License"); you may not use this file except in compliance with
  6. * the License. You may obtain a copy of the License at
  7. * http://www.mozilla.org/MPL/
  8. *
  9. * Software distributed under the License is distributed on an "AS IS" basis,
  10. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11. * for the specific language governing rights and limitations under the
  12. * License.
  13. *
  14. * The Original Code is the PKIX-C library.
  15. *
  16. * The Initial Developer of the Original Code is
  17. * Sun Microsystems, Inc.
  18. * Portions created by the Initial Developer are
  19. * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
  20. *
  21. * Contributor(s):
  22. * Sun Microsystems, Inc.
  23. *
  24. * Alternatively, the contents of this file may be used under the terms of
  25. * either the GNU General Public License Version 2 or later (the "GPL"), or
  26. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27. * in which case the provisions of the GPL or the LGPL are applicable instead
  28. * of those above. If you wish to allow use of your version of this file only
  29. * under the terms of either the GPL or the LGPL, and not to allow others to
  30. * use your version of this file under the terms of the MPL, indicate your
  31. * decision by deleting the provisions above and replace them with the notice
  32. * and other provisions required by the GPL or the LGPL. If you do not delete
  33. * the provisions above, a recipient may use your version of this file under
  34. * the terms of any one of the MPL, the GPL or the LGPL.
  35. *
  36. * ***** END LICENSE BLOCK ***** */
  37. /*
  38. * These functions provide support for a number of other functions
  39. * by creating and manipulating data structures used by those functions.
  40. *
  41. */
  42. #ifndef _PKIX_UTIL_H
  43. #define _PKIX_UTIL_H
  44. #include "pkixt.h"
  45. #ifdef __cplusplus
  46. extern "C" {
  47. #endif
  48. /* General
  49. *
  50. * Please refer to the libpkix Programmer's Guide for detailed information
  51. * about how to use the libpkix library. Certain key warnings and notices from
  52. * that document are repeated here for emphasis.
  53. *
  54. * All identifiers in this file (and all public identifiers defined in
  55. * libpkix) begin with "PKIX_". Private identifiers only intended for use
  56. * within the library begin with "pkix_".
  57. *
  58. * A function returns NULL upon success, and a PKIX_Error pointer upon failure.
  59. *
  60. * Unless otherwise noted, for all accessor (gettor) functions that return a
  61. * PKIX_PL_Object pointer, callers should assume that this pointer refers to a
  62. * shared object. Therefore, the caller should treat this shared object as
  63. * read-only and should not modify this shared object. When done using the
  64. * shared object, the caller should release the reference to the object by
  65. * using the PKIX_PL_Object_DecRef function.
  66. *
  67. * While a function is executing, if its arguments (or anything referred to by
  68. * its arguments) are modified, free'd, or destroyed, the function's behavior
  69. * is undefined.
  70. *
  71. */
  72. /* PKIX_Logger
  73. *
  74. * PKIX_Loggers provide a standard way for the caller to insert custom logging
  75. * facilities. These are used by libpkix to log errors, debug information,
  76. * status, etc. The LogCallback allows custom logging to take place.
  77. * Additionally, a Logger can be initialized with a loggerContext, which is
  78. * where the caller can specify configuration data such as the name of a
  79. * logfile or database. Note that this loggerContext must be a PKIX_PL_Object,
  80. * allowing it to be reference-counted and allowing it to provide the standard
  81. * PKIX_PL_Object functions (Equals, Hashcode, ToString, Compare, Duplicate).
  82. *
  83. * Once the caller has created the Logger object(s) (and set the loggerContext
  84. * (if any) and the Log callback), the caller then registers these Loggers
  85. * with the system by calling PKIX_SetLoggers or PKIX_AddLogger. All log
  86. * entries will then be logged using the specified Loggers. If multiple
  87. * Loggers are specified, every log entry will be logged with each of them.
  88. *
  89. * XXX Maybe give some guidance somewhere on how much detail each logging
  90. * level should have and where component boundaries should be. Maybe in
  91. * Implementor's Guide or Programmer's Guide.
  92. */
  93. #define PKIX_LOGGER_LEVEL_TRACE 5
  94. #define PKIX_LOGGER_LEVEL_DEBUG 4
  95. #define PKIX_LOGGER_LEVEL_WARNING 3
  96. #define PKIX_LOGGER_LEVEL_ERROR 2
  97. #define PKIX_LOGGER_LEVEL_FATALERROR 1
  98. #define PKIX_LOGGER_LEVEL_MAX 5
  99. /*
  100. * FUNCTION: PKIX_Logger_LogCallback
  101. * DESCRIPTION:
  102. *
  103. * This callback function logs a log entry containing the String pointed to
  104. * by "message", the integer value of logLevel, and the String pointed to by
  105. * "logComponent". A log entry can be associated with a particular log
  106. * level (i.e. level 3) and a particular log component (i.e. "CertStore").
  107. * For example, someone reading the log may only be interested in very general
  108. * log entries so they look only for log level 1. Similarly, they may only be
  109. * interested in log entries pertaining to the CertStore component so they
  110. * look only for that log component. This function can be used before calling
  111. * PKIX_Initialize.
  112. *
  113. * PARAMETERS:
  114. * "logger"
  115. * Address of logger whose LogCallback is to be used. Must be non-NULL.
  116. * "message"
  117. * Address of String that is to be logged used "logger". Must be non-NULL.
  118. * "logLevel"
  119. * Integer value representing the log level for this entry. The higher the
  120. * level, the more detail. Must be non-NULL.
  121. * "logComponent"
  122. * PKIXERRORNUM value (defined in pkixt.h) designating the log component
  123. * for this entry.
  124. * "plContext"
  125. * Platform-specific context pointer.
  126. * THREAD SAFETY:
  127. * Thread Safe
  128. *
  129. * Multiple threads must be able to safely call this function without
  130. * worrying about conflicts, even if they're operating on the same objects.
  131. * RETURNS:
  132. * Returns NULL if the function succeeds.
  133. * Returns a Logger Error if the function fails in a non-fatal way.
  134. * Returns a Fatal Error if the function fails in an unrecoverable way.
  135. */
  136. typedef PKIX_Error *
  137. (*PKIX_Logger_LogCallback)(
  138. PKIX_Logger *logger,
  139. PKIX_PL_String *message,
  140. PKIX_UInt32 logLevel,
  141. PKIX_ERRORCLASS logComponent,
  142. void *plContext);
  143. /*
  144. * FUNCTION: PKIX_Logger_Create
  145. * DESCRIPTION:
  146. *
  147. * Creates a new Logger using the Object pointed to by "loggerContext"
  148. * (if any) and stores it at "pLogger". The new Logger uses the LogCallback
  149. * pointed to by "callback". The Logger's maximum logging level is initially
  150. * set to a very high level and its logging component is set to NULL (all
  151. * components).
  152. *
  153. * PARAMETERS:
  154. * "callback"
  155. * The LogCallback function to be used. Must be non-NULL.
  156. * "loggerContext"
  157. * Address of Object representing the Logger's context (if any).
  158. * "pLogger"
  159. * Address where object pointer will be stored. Must be non-NULL.
  160. * "plContext"
  161. * Platform-specific context pointer.
  162. * THREAD SAFETY:
  163. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  164. * RETURNS:
  165. * Returns NULL if the function succeeds.
  166. * Returns a Logger Error if the function fails in a non-fatal way.
  167. * Returns a Fatal Error if the function fails in an unrecoverable way.
  168. */
  169. PKIX_Error *
  170. PKIX_Logger_Create(
  171. PKIX_Logger_LogCallback callback,
  172. PKIX_PL_Object *loggerContext,
  173. PKIX_Logger **pLogger,
  174. void *plContext);
  175. /*
  176. * FUNCTION: PKIX_Logger_GetLogCallback
  177. * DESCRIPTION:
  178. *
  179. * Retrieves a pointer to "logger's" Log callback function and puts it in
  180. * "pCallback".
  181. *
  182. * PARAMETERS:
  183. * "logger"
  184. * Address of Logger whose Log callback is desired. Must be non-NULL.
  185. * "pCallback"
  186. * Address where Log callback function pointer will be stored.
  187. * Must be non-NULL.
  188. * "plContext"
  189. * Platform-specific context pointer.
  190. * THREAD SAFETY:
  191. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  192. * RETURNS:
  193. * Returns NULL if the function succeeds.
  194. * Returns a Logger Error if the function fails in a non-fatal way.
  195. * Returns a Fatal Error if the function fails in an unrecoverable way.
  196. */
  197. PKIX_Error *
  198. PKIX_Logger_GetLogCallback(
  199. PKIX_Logger *logger,
  200. PKIX_Logger_LogCallback *pCallback,
  201. void *plContext);
  202. /*
  203. * FUNCTION: PKIX_Logger_GetLoggerContext
  204. * DESCRIPTION:
  205. *
  206. * Retrieves a pointer to a PKIX_PL_Object representing the context (if any)
  207. * of the Logger pointed to by "logger" and stores it at "pLoggerContext".
  208. *
  209. * PARAMETERS:
  210. * "logger"
  211. * Address of Logger whose context is to be stored. Must be non-NULL.
  212. * "pLoggerContext"
  213. * Address where object pointer will be stored. Must be non-NULL.
  214. * "plContext"
  215. * Platform-specific context pointer.
  216. * THREAD SAFETY:
  217. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  218. * RETURNS:
  219. * Returns NULL if the function succeeds.
  220. * Returns a Logger Error if the function fails in a non-fatal way.
  221. * Returns a Fatal Error if the function fails in an unrecoverable way.
  222. */
  223. PKIX_Error *
  224. PKIX_Logger_GetLoggerContext(
  225. PKIX_Logger *logger,
  226. PKIX_PL_Object **pLoggerContext,
  227. void *plContext);
  228. /*
  229. * FUNCTION: PKIX_Logger_GetMaxLoggingLevel
  230. * DESCRIPTION:
  231. *
  232. * Retrieves a pointer to a PKIX_UInt32 representing the maximum logging
  233. * level of the Logger pointed to by "logger" and stores it at "pLevel". Only
  234. * log entries whose log level is less than or equal to this maximum logging
  235. * level will be logged.
  236. *
  237. * PARAMETERS:
  238. * "logger"
  239. * Address of Logger whose maximum logging level is to be stored.
  240. * Must be non-NULL.
  241. * "pLevel"
  242. * Address where PKIX_UInt32 will be stored. Must be non-NULL.
  243. * "plContext"
  244. * Platform-specific context pointer.
  245. * THREAD SAFETY:
  246. * Conditionally Thread Safe
  247. * (see Thread Safety Definitions in Programmer's Guide)
  248. * RETURNS:
  249. * Returns NULL if the function succeeds.
  250. * Returns a Logger Error if the function fails in a non-fatal way.
  251. * Returns a Fatal Error if the function fails in an unrecoverable way.
  252. */
  253. PKIX_Error *
  254. PKIX_Logger_GetMaxLoggingLevel(
  255. PKIX_Logger *logger,
  256. PKIX_UInt32 *pLevel,
  257. void *plContext);
  258. /*
  259. * FUNCTION: PKIX_Logger_SetMaxLoggingLevel
  260. * DESCRIPTION:
  261. *
  262. * Sets the maximum logging level of the Logger pointed to by "logger" with
  263. * the integer value of "level".
  264. *
  265. * PARAMETERS:
  266. * "logger"
  267. * Address of Logger whose maximum logging level is to be set.
  268. * Must be non-NULL.
  269. * "level"
  270. * Maximum logging level to be set
  271. * "plContext"
  272. * Platform-specific context pointer.
  273. * THREAD SAFETY:
  274. * Not Thread Safe - assumes exclusive access to "logger"
  275. * (see Thread Safety Definitions in Programmer's Guide)
  276. * RETURNS:
  277. * Returns NULL if the function succeeds.
  278. * Returns a Logger Error if the function fails in a non-fatal way.
  279. * Returns a Fatal Error if the function fails in an unrecoverable way.
  280. */
  281. PKIX_Error *
  282. PKIX_Logger_SetMaxLoggingLevel(
  283. PKIX_Logger *logger,
  284. PKIX_UInt32 level,
  285. void *plContext);
  286. /*
  287. * FUNCTION: PKIX_Logger_GetLoggingComponent
  288. * DESCRIPTION:
  289. *
  290. * Retrieves a pointer to a String representing the logging component of the
  291. * Logger pointed to by "logger" and stores it at "pComponent". Only log
  292. * entries whose log component matches the specified logging component will
  293. * be logged.
  294. *
  295. * PARAMETERS:
  296. * "logger"
  297. * Address of Logger whose logging component is to be stored.
  298. * Must be non-NULL.
  299. * "pComponent"
  300. * Address where PKIXERRORNUM will be stored. Must be non-NULL.
  301. * "plContext"
  302. * Platform-specific context pointer.
  303. * THREAD SAFETY:
  304. * Conditionally Thread Safe
  305. * (see Thread Safety Definitions in Programmer's Guide)
  306. * RETURNS:
  307. * Returns NULL if the function succeeds.
  308. * Returns a Logger Error if the function fails in a non-fatal way.
  309. * Returns a Fatal Error if the function fails in an unrecoverable way.
  310. */
  311. PKIX_Error *
  312. PKIX_Logger_GetLoggingComponent(
  313. PKIX_Logger *logger,
  314. PKIX_ERRORCLASS *pComponent,
  315. void *plContext);
  316. /*
  317. * FUNCTION: PKIX_Logger_SetLoggingComponent
  318. * DESCRIPTION:
  319. *
  320. * Sets the logging component of the Logger pointed to by "logger" with the
  321. * PKIXERRORNUM pointed to by "component". To match a small set of components,
  322. * create a Logger for each.
  323. *
  324. * PARAMETERS:
  325. * "logger"
  326. * Address of Logger whose logging component is to be set.
  327. * Must be non-NULL.
  328. * "component"
  329. * PKIXERRORNUM value representing logging component to be set.
  330. * "plContext"
  331. * Platform-specific context pointer.
  332. * THREAD SAFETY:
  333. * Not Thread Safe - assumes exclusive access to "logger"
  334. * (see Thread Safety Definitions in Programmer's Guide)
  335. * RETURNS:
  336. * Returns NULL if the function succeeds.
  337. * Returns a Logger Error if the function fails in a non-fatal way.
  338. * Returns a Fatal Error if the function fails in an unrecoverable way.
  339. */
  340. PKIX_Error *
  341. PKIX_Logger_SetLoggingComponent(
  342. PKIX_Logger *logger,
  343. PKIX_ERRORCLASS component,
  344. void *plContext);
  345. /*
  346. * FUNCTION: PKIX_GetLoggers
  347. * DESCRIPTION:
  348. *
  349. * Retrieves a pointer to the List of Loggers (if any) being used for logging
  350. * by libpkix and stores it at "pLoggers". If no loggers are being used, this
  351. * function stores an empty List at "pLoggers".
  352. *
  353. * Note that the List returned by this function is immutable.
  354. *
  355. * PARAMETERS:
  356. * "pLoggers"
  357. * Address where object pointer will be stored. Must be non-NULL.
  358. * "plContext"
  359. * Platform-specific context pointer.
  360. * THREAD SAFETY:
  361. * Conditionally Thread Safe
  362. * (see Thread Safety Definitions in Programmer's Guide)
  363. * RETURNS:
  364. * Returns NULL if the function succeeds.
  365. * Returns a Logger Error if the function fails in a non-fatal way.
  366. * Returns a Fatal Error if the function fails in an unrecoverable way.
  367. */
  368. PKIX_Error *
  369. PKIX_GetLoggers(
  370. PKIX_List **pLoggers, /* list of PKIX_Logger */
  371. void *plContext);
  372. /*
  373. * FUNCTION: PKIX_SetLoggers
  374. * DESCRIPTION:
  375. *
  376. * Sets the Loggers to be used by libpkix to the List of Loggers pointed to
  377. * by "loggers". If "loggers" is NULL, no Loggers will be used.
  378. *
  379. * PARAMETERS:
  380. * "loggers"
  381. * Address of List of Loggers to be set. NULL for no Loggers.
  382. * "plContext"
  383. * Platform-specific context pointer.
  384. * THREAD SAFETY:
  385. * Not Thread Safe
  386. * (see Thread Safety Definitions in Programmer's Guide)
  387. * RETURNS:
  388. * Returns NULL if the function succeeds.
  389. * Returns a Logger Error if the function fails in a non-fatal way.
  390. * Returns a Fatal Error if the function fails in an unrecoverable way.
  391. */
  392. PKIX_Error *
  393. PKIX_SetLoggers(
  394. PKIX_List *loggers, /* list of PKIX_Logger */
  395. void *plContext);
  396. /*
  397. * FUNCTION: PKIX_AddLogger
  398. * DESCRIPTION:
  399. *
  400. * Adds the Logger pointed to by "logger" to the List of Loggers used by
  401. * libpkix.
  402. *
  403. * PARAMETERS:
  404. * "logger"
  405. * Address of Logger to be added. Must be non-NULL.
  406. * "plContext"
  407. * Platform-specific context pointer.
  408. * THREAD SAFETY:
  409. * Not Thread Safe
  410. * (see Thread Safety Definitions in Programmer's Guide)
  411. * RETURNS:
  412. * Returns NULL if the function succeeds.
  413. * Returns a Logger Error if the function fails in a non-fatal way.
  414. * Returns a Fatal Error if the function fails in an unrecoverable way.
  415. */
  416. PKIX_Error *
  417. PKIX_AddLogger(
  418. PKIX_Logger *logger,
  419. void *plContext);
  420. /* Functions pertaining to the PKIX_Error type */
  421. /* Error
  422. *
  423. * An Error object is returned by a function upon encountering some error
  424. * condition. Each Error is associated with an errorCode specified in pkixt.h.
  425. * The remaining components of an Error are optional. An Error's description
  426. * specifies a text message describing the Error. An Error's supplementary info
  427. * specifies additional information that might be useful. Finally, an Error's
  428. * cause specifies the underlying Error (if any) that resulted in this Error
  429. * being returned, thereby allowing Errors to be chained so that an entire
  430. * "error stack trace" can be represented. Once created, an Error is immutable.
  431. *
  432. * Note that the Error's supplementary info must be an Object (although any
  433. * object type), allowing it to be reference-counted and allowing it to
  434. * provide the standard Object functions (Equals, Hashcode, ToString, Compare,
  435. * Duplicate).
  436. *
  437. * Errors are classified as either being fatal or non-fatal. If a function
  438. * fails in an unrecoverable way, it returns an Error whose errorCode is
  439. * PKIX_FATAL_ERROR. If such an error is encountered, the caller should
  440. * not attempt to recover since something seriously wrong has happened
  441. * (e.g. corrupted memory, memory finished, etc.). All other errorCodes
  442. * are considered non-fatal errors and can be handled by the caller as they
  443. * see fit.
  444. */
  445. /*
  446. * FUNCTION: PKIX_Error_Create
  447. * DESCRIPTION:
  448. *
  449. * Creates a new Error using the value of "errorCode", the Error pointed to by
  450. * "cause" (if any), the Object pointed to by "info" (if any), and the String
  451. * pointed to by "desc" and stores it at "pError". If any error occurs during
  452. * error allocation, it will be returned without chaining, since new errors
  453. * cannot be created. Once created, an Error is immutable.
  454. *
  455. * PARAMETERS:
  456. * "errorCode"
  457. * Value of error code.
  458. * "cause"
  459. * Address of Error representing error's cause.
  460. * NULL if none or unspecified.
  461. * "info"
  462. * Address of Object representing error's supplementary information.
  463. * NULL if none.
  464. * "desc"
  465. * Address of String representing error's description. NULL if none.
  466. * "pError"
  467. * Address where object pointer will be stored. Must be non-NULL.
  468. * "plContext"
  469. * Platform-specific context pointer.
  470. * THREAD SAFETY:
  471. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  472. * RETURNS:
  473. * Returns NULL if the function succeeds.
  474. * Returns an Error Error if the function fails in a non-fatal way.
  475. * Returns a Fatal Error if the function fails in an unrecoverable way.
  476. */
  477. PKIX_Error *
  478. PKIX_Error_Create(
  479. PKIX_ERRORCLASS errClass,
  480. PKIX_Error *cause,
  481. PKIX_PL_Object *info,
  482. PKIX_ERRORCODE errCode,
  483. PKIX_Error **pError,
  484. void *plContext);
  485. /*
  486. * FUNCTION: PKIX_Error_GetErrorClass
  487. * DESCRIPTION:
  488. *
  489. * Retrieves the error class of the Error pointed to by "error" and
  490. * stores it at "pClass". Supported error codes are defined in pkixt.h.
  491. *
  492. * PARAMETERS:
  493. * "error"
  494. * Address of Error whose error code is desired. Must be non-NULL.
  495. * "pClass"
  496. * Address where PKIX_UInt32 will be stored. Must be non-NULL.
  497. * "plContext"
  498. * Platform-specific context pointer.
  499. * THREAD SAFETY:
  500. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  501. * RETURNS:
  502. * Returns NULL if the function succeeds.
  503. * Returns an Error Error if the function fails in a non-fatal way.
  504. * Returns a Fatal Error if the function fails in an unrecoverable way.
  505. */
  506. PKIX_Error *
  507. PKIX_Error_GetErrorClass(
  508. PKIX_Error *error,
  509. PKIX_ERRORCLASS *pClass,
  510. void *plContext);
  511. /*
  512. * FUNCTION: PKIX_Error_GetErrorCode
  513. * DESCRIPTION:
  514. *
  515. * Retrieves the error code of the Error pointed to by "error" and
  516. * stores it at "pCode". Supported error codes are defined in pkixt.h.
  517. *
  518. * PARAMETERS:
  519. * "error"
  520. * Address of Error whose error code is desired. Must be non-NULL.
  521. * "pCode"
  522. * Address where PKIX_UInt32 will be stored. Must be non-NULL.
  523. * "plContext"
  524. * Platform-specific context pointer.
  525. * THREAD SAFETY:
  526. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  527. * RETURNS:
  528. * Returns NULL if the function succeeds.
  529. * Returns an Error Error if the function fails in a non-fatal way.
  530. * Returns a Fatal Error if the function fails in an unrecoverable way.
  531. */
  532. PKIX_Error *
  533. PKIX_Error_GetErrorCode(
  534. PKIX_Error *error,
  535. PKIX_ERRORCODE *pCode,
  536. void *plContext);
  537. /*
  538. * FUNCTION: PKIX_Error_GetCause
  539. * DESCRIPTION:
  540. *
  541. * Retrieves the cause of the Error pointed to by "error" and stores it at
  542. * "pCause". If no cause was specified, NULL will be stored at "pCause".
  543. *
  544. * PARAMETERS:
  545. * "error"
  546. * Address of Error whose cause is desired. Must be non-NULL.
  547. * "pCause"
  548. * Address where object pointer will be stored. Must be non-NULL.
  549. * "plContext"
  550. * Platform-specific context pointer.
  551. * THREAD SAFETY:
  552. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  553. * RETURNS:
  554. * Returns NULL if the function succeeds.
  555. * Returns an Error Error if the function fails in a non-fatal way.
  556. * Returns a Fatal Error if the function fails in an unrecoverable way.
  557. */
  558. PKIX_Error *
  559. PKIX_Error_GetCause(
  560. PKIX_Error *error,
  561. PKIX_Error **pCause,
  562. void *plContext);
  563. /*
  564. * FUNCTION: PKIX_Error_GetSupplementaryInfo
  565. * DESCRIPTION:
  566. *
  567. * Retrieves the supplementary info of the Error pointed to by "error" and
  568. * stores it at "pInfo".
  569. *
  570. * PARAMETERS:
  571. * "error"
  572. * Address of Error whose info is desired. Must be non-NULL.
  573. * "pInfo"
  574. * Address where info pointer will be stored. Must be non-NULL.
  575. * "plContext"
  576. * Platform-specific context pointer.
  577. * THREAD SAFETY:
  578. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  579. * RETURNS:
  580. * Returns NULL if the function succeeds.
  581. * Returns an Error Error if the function fails in a non-fatal way.
  582. * Returns a Fatal Error if the function fails in an unrecoverable way.
  583. */
  584. PKIX_Error *
  585. PKIX_Error_GetSupplementaryInfo(
  586. PKIX_Error *error,
  587. PKIX_PL_Object **pInfo,
  588. void *plContext);
  589. /*
  590. * FUNCTION: PKIX_Error_GetDescription
  591. * DESCRIPTION:
  592. *
  593. * Retrieves the description of the Error pointed to by "error" and stores it
  594. * at "pDesc". If no description was specified, NULL will be stored at
  595. * "pDesc".
  596. *
  597. * PARAMETERS:
  598. * "error"
  599. * Address of Error whose description is desired. Must be non-NULL.
  600. * "pDesc"
  601. * Address where object pointer will be stored. Must be non-NULL.
  602. * "plContext"
  603. * Platform-specific context pointer.
  604. * THREAD SAFETY:
  605. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  606. * RETURNS:
  607. * Returns NULL if the function succeeds.
  608. * Returns an Error Error if the function fails in a non-fatal way.
  609. * Returns a Fatal Error if the function fails in an unrecoverable way.
  610. */
  611. PKIX_Error *
  612. PKIX_Error_GetDescription(
  613. PKIX_Error *error,
  614. PKIX_PL_String **pDesc,
  615. void *plContext);
  616. /* PKIX_List
  617. *
  618. * Represents a collection of items. NULL is considered a valid item.
  619. */
  620. /*
  621. * FUNCTION: PKIX_List_Create
  622. * DESCRIPTION:
  623. *
  624. * Creates a new List and stores it at "pList". The List is initially empty
  625. * and holds no items. To initially add items to the List, use
  626. * PKIX_List_AppendItem
  627. *
  628. * PARAMETERS:
  629. * "pList"
  630. * Address where object pointer will be stored. Must be non-NULL.
  631. * "plContext"
  632. * Platform-specific context pointer.
  633. * THREAD SAFETY:
  634. * Thread Safe (see Thread Safety Definitions in Programmer's Guide)
  635. * RETURNS:
  636. * Returns NULL if the function succeeds.
  637. * Returns a Fatal Error if the function fails in an unrecoverable way.
  638. */
  639. PKIX_Error *
  640. PKIX_List_Create(
  641. PKIX_List **pList,
  642. void *plContext);
  643. /*
  644. * FUNCTION: PKIX_List_SetImmutable
  645. * DESCRIPTION:
  646. *
  647. * Sets the List pointed to by "list" to be immutable. If a caller tries to
  648. * change a List after it has been marked immutable (i.e. by calling
  649. * PKIX_List_AppendItem, PKIX_List_InsertItem, PKIX_List_SetItem, or
  650. * PKIX_List_DeleteItem), an Error is returned.
  651. *
  652. * PARAMETERS:
  653. * "list"
  654. * Address of List to be marked immutable. Must be non-NULL.
  655. * "plContext"
  656. * Platform-specific context pointer.
  657. * THREAD SAFETY:
  658. * Not Thread Safe - assumes exclusive access to "list"
  659. * (see Thread Safety Definitions in Programmer's Guide)
  660. * RETURNS:
  661. * Returns NULL if the function succeeds.
  662. * Returns a Fatal Error if the function fails in an unrecoverable way.
  663. */
  664. PKIX_Error *
  665. PKIX_List_SetImmutable(
  666. PKIX_List *list,
  667. void *plContext);
  668. /*
  669. * FUNCTION: PKIX_List_IsImmutable
  670. * DESCRIPTION:
  671. *
  672. * Checks whether the List pointed to by "list" is immutable and stores
  673. * the Boolean result at "pImmutable". If a caller tries to change a List
  674. * after it has been marked immutable (i.e. by calling PKIX_List_AppendItem,
  675. * PKIX_List_InsertItem, PKIX_List_SetItem, or PKIX_List_DeleteItem), an
  676. * Error is returned.
  677. *
  678. * PARAMETERS:
  679. * "list"
  680. * Address of List whose immutability is to be determined.
  681. * Must be non-NULL.
  682. * "pImmutable"
  683. * Address where PKIX_Boolean will be stored. Must be non-NULL.
  684. * "plContext"
  685. * Platform-specific context pointer.
  686. * THREAD SAFETY:
  687. * Conditionally Thread Safe
  688. * (see Thread Safety Definitions in Programmer's Guide)
  689. * RETURNS:
  690. * Returns NULL if the function succeeds.
  691. * Returns a Fatal Error if the function fails in an unrecoverable way.
  692. */
  693. PKIX_Error *
  694. PKIX_List_IsImmutable(
  695. PKIX_List *list,
  696. PKIX_Boolean *pImmutable,
  697. void *plContext);
  698. /*
  699. * FUNCTION: PKIX_List_GetLength
  700. * DESCRIPTION:
  701. *
  702. * Retrieves the length of the List pointed to by "list" and stores it at
  703. * "pLength".
  704. *
  705. * PARAMETERS:
  706. * "list"
  707. * Address of List whose length is desired. Must be non-NULL.
  708. * "pLength"
  709. * Address where PKIX_UInt32 will be stored. Must be non-NULL.
  710. * "plContext"
  711. * Platform-specific context pointer.
  712. * THREAD SAFETY:
  713. * Conditionally Thread Safe
  714. * (see Thread Safety Definitions in Programmer's Guide)
  715. * RETURNS:
  716. * Returns NULL if the function succeeds.
  717. * Returns a Fatal Error if the function fails in an unrecoverable way.
  718. */
  719. PKIX_Error *
  720. PKIX_List_GetLength(
  721. PKIX_List *list,
  722. PKIX_UInt32 *pLength,
  723. void *plContext);
  724. /*
  725. * FUNCTION: PKIX_List_IsEmpty
  726. * DESCRIPTION:
  727. *
  728. * Checks whether the List pointed to by "list" is empty and stores
  729. * the Boolean result at "pEmpty".
  730. *
  731. * PARAMETERS:
  732. * "list"
  733. * Address of List whose emptiness is to be determined. Must be non-NULL.
  734. * "pEmpty"
  735. * Address where PKIX_Boolean will be stored. Must be non-NULL.
  736. * "plContext"
  737. * Platform-specific context pointer.
  738. * THREAD SAFETY:
  739. * Conditionally Thread Safe
  740. * (see Thread Safety Definitions in Programmer's Guide)
  741. * RETURNS:
  742. * Returns NULL if the function succeeds.
  743. * Returns a Fatal Error if the function fails in an unrecoverable way.
  744. */
  745. PKIX_Error *
  746. PKIX_List_IsEmpty(
  747. PKIX_List *list,
  748. PKIX_Boolean *pEmpty,
  749. void *plContext);
  750. /*
  751. * FUNCTION: PKIX_List_AppendItem
  752. * DESCRIPTION:
  753. *
  754. * Appends the Object pointed to by "item" after the last non-NULL item in
  755. * List pointed to by "list", if any. Note that a List may validly contain
  756. * NULL items. Appending "c" into the List ("a", NULL, "b", NULL) will result
  757. * in ("a", NULL, "b", "c").
  758. *
  759. * PARAMETERS:
  760. * "list"
  761. * Address of List to append to. Must be non-NULL.
  762. * "item"
  763. * Address of new item to append.
  764. * "plContext"
  765. * Platform-specific context pointer.
  766. * THREAD SAFETY:
  767. * Not Thread Safe - assumes exclusive access to "list"
  768. * (see Thread Safety Definitions in Programmer's Guide)
  769. * RETURNS:
  770. * Returns NULL if the function succeeds.
  771. * Returns a Fatal Error if the function fails in an unrecoverable way.
  772. */
  773. PKIX_Error *
  774. PKIX_List_AppendItem(
  775. PKIX_List *list,
  776. PKIX_PL_Object *item,
  777. void *plContext);
  778. /*
  779. * FUNCTION: PKIX_List_InsertItem
  780. * DESCRIPTION:
  781. *
  782. * Inserts the Object pointed to by "item" into the List pointed to by "list"
  783. * at the given "index". The index counts from zero and must be less than the
  784. * List's length. Existing list entries at or after this index will be moved
  785. * to the next highest index.
  786. *
  787. * XXX why not allow equal to length which would be equivalent to AppendItem?
  788. *
  789. * PARAMETERS:
  790. * "list"
  791. * Address of List to insert into. Must be non-NULL.
  792. * "index"
  793. * Position to insert into. Must be less than List's length.
  794. * "item"
  795. * Address of new item to append.
  796. * "plContext"
  797. * Platform-specific context pointer.
  798. * THREAD SAFETY:
  799. * Not Thread Safe - assumes exclusive access to "list"
  800. * (see Thread Safety Definitions in Programmer's Guide)
  801. * RETURNS:
  802. * Returns NULL if the function succeeds.
  803. * Returns a Fatal Error if the function fails in an unrecoverable way.
  804. */
  805. PKIX_Error *
  806. PKIX_List_InsertItem(
  807. PKIX_List *list,
  808. PKIX_UInt32 index,
  809. PKIX_PL_Object *item,
  810. void *plContext);
  811. /*
  812. * FUNCTION: PKIX_List_GetItem
  813. * DESCRIPTION:
  814. *
  815. * Copies the "list"'s item at "index" into "pItem". The index counts from
  816. * zero and must be less than the list's length. Increments the reference
  817. * count on the returned object, if non-NULL.
  818. *
  819. * PARAMETERS:
  820. * "list"
  821. * Address of List to get item from. Must be non-NULL.
  822. * "index"
  823. * Index of list to get item from. Must be less than List's length.
  824. * "pItem"
  825. * Address where object pointer will be stored. Must be non-NULL.
  826. * "plContext"
  827. * Platform-specific context pointer.
  828. * THREAD SAFETY:
  829. * Conditionally Thread Safe
  830. * (see Thread Safety Definitions in Programmer's Guide)
  831. * RETURNS:
  832. * Returns NULL if the function succeeds.
  833. * Returns a Fatal Error if the function fails in an unrecoverable way.
  834. */
  835. PKIX_Error *
  836. PKIX_List_GetItem(
  837. PKIX_List *list,
  838. PKIX_UInt32 index,
  839. PKIX_PL_Object **pItem,
  840. void *plContext);
  841. /*
  842. * FUNCTION: PKIX_List_SetItem
  843. * DESCRIPTION:
  844. *
  845. * Sets the item at "index" of the List pointed to by "list" with the Object
  846. * pointed to by "item". The index counts from zero and must be less than the
  847. * List's length. The previous entry at this index will have its reference
  848. * count decremented and the new entry will have its reference count
  849. * incremented.
  850. *
  851. * PARAMETERS:
  852. * "list"
  853. * Address of List to modify. Must be non-NULL.
  854. * "index"
  855. * Position in List to set. Must be less than List's length.
  856. * "item"
  857. * Address of Object to set at "index".
  858. * "plContext"
  859. * Platform-specific context pointer.
  860. * THREAD SAFETY:
  861. * Not Thread Safe - assumes exclusive access to "list"
  862. * (see Thread Safety Definitions in Programmer's Guide)
  863. * RETURNS:
  864. * Returns NULL if the function succeeds.
  865. * Returns a Fatal Error if the function fails in an unrecoverable way.
  866. */
  867. PKIX_Error *
  868. PKIX_List_SetItem(
  869. PKIX_List *list,
  870. PKIX_UInt32 index,
  871. PKIX_PL_Object *item,
  872. void *plContext);
  873. /*
  874. * FUNCTION: PKIX_List_DeleteItem
  875. *
  876. * Deletes the item at "index" from the List pointed to by "list". The index
  877. * counts from zero and must be less than the List's length. Note that this
  878. * function does not destroy the List. It simply decrements the reference
  879. * count of the item at "index" in the List, deletes that item from the list
  880. * and moves all subsequent entries to a lower index in the list. If there is
  881. * only a single element in the List and that element is deleted, then the
  882. * List will be empty.
  883. *
  884. * PARAMETERS:
  885. * "list"
  886. * Address of List to delete from. Must be non-NULL.
  887. * "index"
  888. * Position in List to delete. Must be less than List's length.
  889. * "plContext"
  890. * Platform-specific context pointer.
  891. * THREAD SAFETY:
  892. * Not Thread Safe - assumes exclusive access to "list"
  893. * (see Thread Safety Definitions in Programmer's Guide)
  894. * RETURNS:
  895. * Returns NULL if the function succeeds.
  896. * Returns a Fatal Error if the function fails in an unrecoverable way.
  897. */
  898. PKIX_Error *
  899. PKIX_List_DeleteItem(
  900. PKIX_List *list,
  901. PKIX_UInt32 index,
  902. void *plContext);
  903. /*
  904. * FUNCTION: PKIX_List_ReverseList
  905. * DESCRIPTION:
  906. *
  907. * Creates a new List whose elements are in the reverse order as the elements
  908. * of the Object pointed to by "list" and stores the copy at "pReversedList".
  909. * If "list" is empty, the new reversed List will be a copy of "list".
  910. * Changes to the new object will not affect the original and vice versa.
  911. *
  912. * PARAMETERS:
  913. * "list"
  914. * Address of List whose elements are to be reversed. Must be non-NULL.
  915. * "pReversedList"
  916. * Address where object pointer will be stored. Must be non-NULL.
  917. * "plContext"
  918. * Platform-specific context pointer.
  919. * THREAD SAFETY:
  920. * Conditionally Thread Safe
  921. * (see Thread Safety Definitions in Programmer's Guide)
  922. * RETURNS:
  923. * Returns NULL if the function succeeds.
  924. * Returns a Fatal Error if the function fails in an unrecoverable way.
  925. */
  926. PKIX_Error *
  927. PKIX_List_ReverseList(
  928. PKIX_List *list,
  929. PKIX_List **pReversedList,
  930. void *plContext);
  931. #ifdef __cplusplus
  932. }
  933. #endif
  934. #endif /* _PKIX_UTIL_H */