Back to index

lightning-sunbird  0.9+nobinonly
base.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef BASE_H
00038 #define BASE_H
00039 
00040 #ifdef DEBUG
00041 static const char BASE_CVS_ID[] = "@(#) $RCSfile: base.h,v $ $Revision: 1.17 $ $Date: 2005/01/20 02:25:45 $";
00042 #endif /* DEBUG */
00043 
00044 /*
00045  * base.h
00046  *
00047  * This header file contains basic prototypes and preprocessor 
00048  * definitions used throughout nss but not available publicly.
00049  */
00050 
00051 #ifndef BASET_H
00052 #include "baset.h"
00053 #endif /* BASET_H */
00054 
00055 #ifndef NSSBASE_H
00056 #include "nssbase.h"
00057 #endif /* NSSBASE_H */
00058 
00059 #include "plhash.h"
00060 #include "prthread.h"
00061 
00062 PR_BEGIN_EXTERN_C
00063 
00064 /*
00065  * NSSArena
00066  *
00067  * The nonpublic methods relating to this type are:
00068  *
00069  *  nssArena_Create  -- constructor
00070  *  nssArena_Destroy
00071  *  nssArena_Mark
00072  *  nssArena_Release
00073  *  nssArena_Unmark
00074  *
00075  *  nss_ZAlloc
00076  *  nss_ZFreeIf
00077  *  nss_ZRealloc
00078  *
00079  * Additionally, there are some preprocessor macros:
00080  *
00081  *  nss_ZNEW
00082  *  nss_ZNEWARRAY
00083  *
00084  * In debug builds, the following calls are available:
00085  *
00086  *  nssArena_verifyPointer
00087  *  nssArena_registerDestructor
00088  *  nssArena_deregisterDestructor
00089  *
00090  * The following preprocessor macro is also always available:
00091  *
00092  *  nssArena_VERIFYPOINTER
00093  *
00094  * A constant PLHashAllocOps structure is available for users
00095  * of the NSPL PLHashTable routines.
00096  *
00097  *  nssArenaHashAllocOps
00098  */
00099 
00100 /*
00101  * nssArena_Create
00102  *
00103  * This routine creates a new memory arena.  This routine may return
00104  * NULL upon error, in which case it will have set an error on the 
00105  * error stack.
00106  *
00107  * The error may be one of the following values:
00108  *  NSS_ERROR_NO_MEMORY
00109  *
00110  * Return value:
00111  *  NULL upon error
00112  *  A pointer to an NSSArena upon success
00113  */
00114 
00115 /*
00116  * XXX fgmr
00117  * Arenas can be named upon creation; this is mostly of use when
00118  * debugging.  Should we expose that here, allowing an optional
00119  * "const char *name" argument?  Should the public version of this
00120  * call (NSSArena_Create) have it too?
00121  */
00122 
00123 NSS_EXTERN NSSArena *
00124 nssArena_Create
00125 (
00126   void
00127 );
00128 
00129 extern const NSSError NSS_ERROR_NO_MEMORY;
00130 
00131 /*
00132  * nssArena_Destroy
00133  *
00134  * This routine will destroy the specified arena, freeing all memory
00135  * allocated from it.  This routine returns a PRStatus value; if 
00136  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
00137  * set an error on the error stack and return PR_FAILURE.
00138  *
00139  * The error may be one of the following values:
00140  *  NSS_ERROR_INVALID_ARENA
00141  *
00142  * Return value:
00143  *  PR_SUCCESS
00144  *  PR_FAILURE
00145  */
00146 
00147 NSS_EXTERN PRStatus
00148 nssArena_Destroy
00149 (
00150   NSSArena *arena
00151 );
00152 
00153 extern const NSSError NSS_ERROR_INVALID_ARENA;
00154 
00155 /*
00156  * nssArena_Mark
00157  *
00158  * This routine "marks" the current state of an arena.  Space
00159  * allocated after the arena has been marked can be freed by
00160  * releasing the arena back to the mark with nssArena_Release,
00161  * or committed by calling nssArena_Unmark.  When successful, 
00162  * this routine returns a valid nssArenaMark pointer.  This 
00163  * routine may return NULL upon error, in which case it will 
00164  * have set an error on the error stack.
00165  *
00166  * The error may be one of the following values:
00167  *  NSS_ERROR_INVALID_ARENA
00168  *  NSS_ERROR_NO_MEMORY
00169  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00170  *
00171  * Return value:
00172  *  NULL upon failure
00173  *  An nssArenaMark pointer upon success
00174  */
00175 
00176 NSS_EXTERN nssArenaMark *
00177 nssArena_Mark
00178 (
00179   NSSArena *arena
00180 );
00181 
00182 extern const NSSError NSS_ERROR_INVALID_ARENA;
00183 extern const NSSError NSS_ERROR_NO_MEMORY;
00184 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
00185 
00186 /*
00187  * nssArena_Release
00188  *
00189  * This routine invalidates and releases all memory allocated from
00190  * the specified arena after the point at which the specified mark
00191  * was obtained.  This routine returns a PRStatus value; if successful,
00192  * it will return PR_SUCCESS.  If unsuccessful, it will set an error
00193  * on the error stack and return PR_FAILURE.
00194  *
00195  * The error may be one of the following values:
00196  *  NSS_ERROR_INVALID_ARENA
00197  *  NSS_ERROR_INVALID_ARENA_MARK
00198  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00199  *
00200  * Return value:
00201  *  PR_SUCCESS
00202  *  PR_FAILURE
00203  */
00204 
00205 NSS_EXTERN PRStatus
00206 nssArena_Release
00207 (
00208   NSSArena *arena,
00209   nssArenaMark *arenaMark
00210 );
00211 
00212 extern const NSSError NSS_ERROR_INVALID_ARENA;
00213 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
00214 
00215 /*
00216  * nssArena_Unmark
00217  *
00218  * This routine "commits" the indicated mark and any marks after
00219  * it, making them unreleasable.  Note that any earlier marks can
00220  * still be released, and such a release will invalidate these
00221  * later unmarked regions.  If an arena is to be safely shared by
00222  * more than one thread, all marks must be either released or
00223  * unmarked.  This routine returns a PRStatus value; if successful,
00224  * it will return PR_SUCCESS.  If unsuccessful, it will set an error
00225  * on the error stack and return PR_FAILURE.
00226  *
00227  * The error may be one of the following values:
00228  *  NSS_ERROR_INVALID_ARENA
00229  *  NSS_ERROR_INVALID_ARENA_MARK
00230  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00231  *
00232  * Return value:
00233  *  PR_SUCCESS
00234  *  PR_FAILURE
00235  */
00236 
00237 NSS_EXTERN PRStatus
00238 nssArena_Unmark
00239 (
00240   NSSArena *arena,
00241   nssArenaMark *arenaMark
00242 );
00243 
00244 extern const NSSError NSS_ERROR_INVALID_ARENA;
00245 extern const NSSError NSS_ERROR_INVALID_ARENA_MARK;
00246 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
00247 
00248 #ifdef ARENA_DESTRUCTOR_LIST
00249 
00250 /*
00251  * nssArena_registerDestructor
00252  *
00253  * This routine stores a pointer to a callback and an arbitrary
00254  * pointer-sized argument in the arena, at the current point in
00255  * the mark stack.  If the arena is destroyed, or an "earlier"
00256  * mark is released, then this destructor will be called at that
00257  * time.  Note that the destructor will be called with the arena
00258  * locked, which means the destructor may free memory in that
00259  * arena, but it may not allocate or cause to be allocated any
00260  * memory.  This callback facility was included to support our
00261  * debug-version pointer-tracker feature; overuse runs counter to
00262  * the the original intent of arenas.  This routine returns a 
00263  * PRStatus value; if successful, it will return PR_SUCCESS.  If 
00264  * unsuccessful, it will set an error on the error stack and 
00265  * return PR_FAILURE.
00266  *
00267  * The error may be one of the following values:
00268  *  NSS_ERROR_INVALID_ARENA
00269  *  NSS_ERROR_NO_MEMORY
00270  *
00271  * Return value:
00272  *  PR_SUCCESS
00273  *  PR_FAILURE
00274  */
00275 
00276 NSS_EXTERN PRStatus
00277 nssArena_registerDestructor
00278 (
00279   NSSArena *arena,
00280   void (*destructor)(void *argument),
00281   void *arg
00282 );
00283 
00284 extern const NSSError NSS_ERROR_INVALID_ARENA;
00285 extern const NSSError NSS_ERROR_NO_MEMORY;
00286 
00287 /*
00288  * nssArena_deregisterDestructor
00289  *
00290  * This routine will remove the first destructor in the specified
00291  * arena which has the specified destructor and argument values.
00292  * The destructor will not be called.  This routine returns a
00293  * PRStatus value; if successful, it will return PR_SUCCESS.  If 
00294  * unsuccessful, it will set an error on the error stack and 
00295  * return PR_FAILURE.
00296  *
00297  * The error may be one of the following values:
00298  *  NSS_ERROR_INVALID_ARENA
00299  *  NSS_ERROR_NOT_FOUND
00300  *
00301  * Return value:
00302  *  PR_SUCCESS
00303  *  PR_FAILURE
00304  */
00305 
00306 NSS_EXTERN PRStatus
00307 nssArena_deregisterDestructor
00308 (
00309   NSSArena *arena,
00310   void (*destructor)(void *argument),
00311   void *arg
00312 );
00313 
00314 extern const NSSError NSS_ERROR_INVALID_ITEM;
00315 extern const NSSError NSS_ERROR_INVALID_ARENA;
00316 extern const NSSError NSS_ERROR_NOT_FOUND;
00317 
00318 #endif /* ARENA_DESTRUCTOR_LIST */
00319 
00320 /*
00321  * nss_ZAlloc
00322  *
00323  * This routine allocates and zeroes a section of memory of the 
00324  * size, and returns to the caller a pointer to that memory.  If
00325  * the optional arena argument is non-null, the memory will be
00326  * obtained from that arena; otherwise, the memory will be obtained
00327  * from the heap.  This routine may return NULL upon error, in
00328  * which case it will have set an error upon the error stack.  The
00329  * value specified for size may be zero; in which case a valid 
00330  * zero-length block of memory will be allocated.  This block may
00331  * be expanded by calling nss_ZRealloc.
00332  *
00333  * The error may be one of the following values:
00334  *  NSS_ERROR_INVALID_ARENA
00335  *  NSS_ERROR_NO_MEMORY
00336  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00337  *
00338  * Return value:
00339  *  NULL upon error
00340  *  A pointer to the new segment of zeroed memory
00341  */
00342 
00343 NSS_EXTERN void *
00344 nss_ZAlloc
00345 (
00346   NSSArena *arenaOpt,
00347   PRUint32 size
00348 );
00349 
00350 extern const NSSError NSS_ERROR_INVALID_ARENA;
00351 extern const NSSError NSS_ERROR_NO_MEMORY;
00352 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
00353 
00354 /*
00355  * nss_ZFreeIf
00356  *
00357  * If the specified pointer is non-null, then the region of memory 
00358  * to which it points -- which must have been allocated with 
00359  * nss_ZAlloc -- will be zeroed and released.  This routine 
00360  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
00361  * If unsuccessful, it will set an error on the error stack and return 
00362  * PR_FAILURE.
00363  *
00364  * The error may be one of the following values:
00365  *  NSS_ERROR_INVALID_POINTER
00366  *
00367  * Return value:
00368  *  PR_SUCCESS
00369  *  PR_FAILURE
00370  */
00371 
00372 NSS_EXTERN PRStatus
00373 nss_ZFreeIf
00374 (
00375   void *pointer
00376 );
00377 
00378 extern const NSSError NSS_ERROR_INVALID_POINTER;
00379 
00380 /*
00381  * nss_ZRealloc
00382  *
00383  * This routine reallocates a block of memory obtained by calling
00384  * nss_ZAlloc or nss_ZRealloc.  The portion of memory 
00385  * between the new and old sizes -- which is either being newly
00386  * obtained or released -- is in either case zeroed.  This routine 
00387  * may return NULL upon failure, in which case it will have placed 
00388  * an error on the error stack.
00389  *
00390  * The error may be one of the following values:
00391  *  NSS_ERROR_INVALID_POINTER
00392  *  NSS_ERROR_NO_MEMORY
00393  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00394  *
00395  * Return value:
00396  *  NULL upon error
00397  *  A pointer to the replacement segment of memory
00398  */
00399 
00400 NSS_EXTERN void *
00401 nss_ZRealloc
00402 (
00403   void *pointer,
00404   PRUint32 newSize
00405 );
00406 
00407 extern const NSSError NSS_ERROR_INVALID_POINTER;
00408 extern const NSSError NSS_ERROR_NO_MEMORY;
00409 extern const NSSError NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD;
00410 
00411 /*
00412  * nss_ZNEW
00413  *
00414  * This preprocessor macro will allocate memory for a new object
00415  * of the specified type with nss_ZAlloc, and will cast the
00416  * return value appropriately.  If the optional arena argument is 
00417  * non-null, the memory will be obtained from that arena; otherwise, 
00418  * the memory will be obtained from the heap.  This routine may 
00419  * return NULL upon error, in which case it will have set an error 
00420  * upon the error stack.
00421  *
00422  * The error may be one of the following values:
00423  *  NSS_ERROR_INVALID_ARENA
00424  *  NSS_ERROR_NO_MEMORY
00425  *
00426  * Return value:
00427  *  NULL upon error
00428  *  A pointer to the new segment of zeroed memory
00429  */
00430 
00431 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
00432 #define nss_ZNEW(arenaOpt, type) ((type *)nss_ZAlloc((arenaOpt), sizeof(type)))
00433 
00434 /*
00435  * nss_ZNEWARRAY
00436  *
00437  * This preprocessor macro will allocate memory for an array of
00438  * new objects, and will cast the return value appropriately.
00439  * If the optional arena argument is non-null, the memory will 
00440  * be obtained from that arena; otherwise, the memory will be 
00441  * obtained from the heap.  This routine may return NULL upon 
00442  * error, in which case it will have set an error upon the error 
00443  * stack.  The array size may be specified as zero.
00444  *
00445  * The error may be one of the following values:
00446  *  NSS_ERROR_INVALID_ARENA
00447  *  NSS_ERROR_NO_MEMORY
00448  *
00449  * Return value:
00450  *  NULL upon error
00451  *  A pointer to the new segment of zeroed memory
00452  */
00453 
00454 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
00455 #define nss_ZNEWARRAY(arenaOpt, type, quantity) ((type *)nss_ZAlloc((arenaOpt), sizeof(type) * (quantity)))
00456 
00457 /*
00458  * nss_ZREALLOCARRAY
00459  *
00460  * This preprocessor macro will reallocate memory for an array of
00461  * new objects, and will cast the return value appropriately.
00462  * This routine may return NULL upon error, in which case it will 
00463  *  have set an error upon the error stack.
00464  *
00465  * The error may be one of the following values:
00466  *  NSS_ERROR_INVALID_POINTER
00467  *  NSS_ERROR_NO_MEMORY
00468  *  NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD
00469  *
00470  * Return value:
00471  *  NULL upon error
00472  *  A pointer to the replacement segment of memory
00473  */
00474 #define nss_ZREALLOCARRAY(p, type, quantity) ((type *)nss_ZRealloc((p), sizeof(type) * (quantity)))
00475 
00476 /*
00477  * nssArena_verifyPointer
00478  *
00479  * This method is only present in debug builds.
00480  *
00481  * If the specified pointer is a valid pointer to an NSSArena object,
00482  * this routine will return PR_SUCCESS.  Otherwise, it will put an
00483  * error on the error stack and return PR_FAILURE.
00484  *
00485  * The error may be one of the following values:
00486  *  NSS_ERROR_INVALID_ARENA
00487  *
00488  * Return value:
00489  *  PR_SUCCESS if the pointer is valid
00490  *  PR_FAILURE if it isn't
00491  */
00492 
00493 #ifdef DEBUG
00494 NSS_EXTERN PRStatus
00495 nssArena_verifyPointer
00496 (
00497   const NSSArena *arena
00498 );
00499 
00500 extern const NSSError NSS_ERROR_INVALID_ARENA;
00501 #endif /* DEBUG */
00502 
00503 /*
00504  * nssArena_VERIFYPOINTER
00505  *
00506  * This macro is always available.  In debug builds it will call
00507  * nssArena_verifyPointer; in non-debug builds, it will merely
00508  * check that the pointer is not null.  Note that in non-debug
00509  * builds it cannot place an error on the error stack.
00510  *
00511  * Return value:
00512  *  PR_SUCCESS if the pointer is valid
00513  *  PR_FAILURE if it isn't
00514  */
00515 
00516 #ifdef DEBUG
00517 #define nssArena_VERIFYPOINTER(p) nssArena_verifyPointer(p)
00518 #else /* DEBUG */
00519 /* The following line exceeds 72 characters, but emacs screws up if I split it. */
00520 #define nssArena_VERIFYPOINTER(p) (((NSSArena *)NULL == (p))?PR_FAILURE:PR_SUCCESS)
00521 #endif /* DEBUG */
00522 
00523 /*
00524  * nssArenaHashAllocOps
00525  *
00526  * This constant structure contains allocation callbacks designed for
00527  * use with the NSPL routine PL_NewHashTable.  For example:
00528  *
00529  *  NSSArena *hashTableArena = nssArena_Create();
00530  *  PLHashTable *t = PL_NewHashTable(n, hasher, key_compare, 
00531  *    value_compare, nssArenaHashAllocOps, hashTableArena);
00532  */
00533 
00534 NSS_EXTERN_DATA PLHashAllocOps nssArenaHashAllocOps;
00535 
00536 /*
00537  * The error stack
00538  *
00539  * The nonpublic methods relating to the error stack are:
00540  *
00541  *  nss_SetError
00542  *  nss_ClearErrorStack
00543  */
00544 
00545 /*
00546  * nss_SetError
00547  *
00548  * This routine places a new error code on the top of the calling 
00549  * thread's error stack.  Calling this routine wiht an error code
00550  * of zero will clear the error stack.
00551  */
00552 
00553 NSS_EXTERN void
00554 nss_SetError
00555 (
00556   PRUint32 error
00557 );
00558 
00559 /*
00560  * nss_ClearErrorStack
00561  *
00562  * This routine clears the calling thread's error stack.
00563  */
00564 
00565 NSS_EXTERN void
00566 nss_ClearErrorStack
00567 (
00568   void
00569 );
00570 
00571 /*
00572  * NSSItem
00573  *
00574  * nssItem_Create
00575  * nssItem_Duplicate
00576  * nssItem_Equal
00577  */
00578 
00579 NSS_EXTERN NSSItem *
00580 nssItem_Create
00581 (
00582   NSSArena *arenaOpt,
00583   NSSItem *rvOpt,
00584   PRUint32 length,
00585   const void *data
00586 );
00587 
00588 NSS_EXTERN void
00589 nssItem_Destroy
00590 (
00591   NSSItem *item
00592 );
00593 
00594 NSS_EXTERN NSSItem *
00595 nssItem_Duplicate
00596 (
00597   NSSItem *obj,
00598   NSSArena *arenaOpt,
00599   NSSItem *rvOpt
00600 );
00601 
00602 NSS_EXTERN PRBool
00603 nssItem_Equal
00604 (
00605   const NSSItem *one,
00606   const NSSItem *two,
00607   PRStatus *statusOpt
00608 );
00609 
00610 /*
00611  * NSSUTF8
00612  *
00613  *  nssUTF8_CaseIgnoreMatch
00614  *  nssUTF8_Duplicate
00615  *  nssUTF8_Size
00616  *  nssUTF8_Length
00617  *  nssUTF8_CopyIntoFixedBuffer
00618  */
00619 
00620 /*
00621  * nssUTF8_CaseIgnoreMatch
00622  * 
00623  * Returns true if the two UTF8-encoded strings pointed to by the 
00624  * two specified NSSUTF8 pointers differ only in typcase.
00625  *
00626  * The error may be one of the following values:
00627  *  NSS_ERROR_INVALID_POINTER
00628  *
00629  * Return value:
00630  *  PR_TRUE if the strings match, ignoring case
00631  *  PR_FALSE if they don't
00632  *  PR_FALSE upon error
00633  */
00634 
00635 NSS_EXTERN PRBool
00636 nssUTF8_CaseIgnoreMatch
00637 (
00638   const NSSUTF8 *a,
00639   const NSSUTF8 *b,
00640   PRStatus *statusOpt
00641 );
00642 
00643 /*
00644  * nssUTF8_Duplicate
00645  *
00646  * This routine duplicates the UTF8-encoded string pointed to by the
00647  * specified NSSUTF8 pointer.  If the optional arenaOpt argument is
00648  * not null, the memory required will be obtained from that arena;
00649  * otherwise, the memory required will be obtained from the heap.
00650  * A pointer to the new string will be returned.  In case of error,
00651  * an error will be placed on the error stack and NULL will be 
00652  * returned.
00653  *
00654  * The error may be one of the following values:
00655  *  NSS_ERROR_INVALID_POINTER
00656  *  NSS_ERROR_INVALID_ARENA
00657  *  NSS_ERROR_NO_MEMORY
00658  */
00659 
00660 NSS_EXTERN NSSUTF8 *
00661 nssUTF8_Duplicate
00662 (
00663   const NSSUTF8 *s,
00664   NSSArena *arenaOpt
00665 );
00666 
00667 /*
00668  * nssUTF8_PrintableMatch
00669  *
00670  * Returns true if the two Printable strings pointed to by the 
00671  * two specified NSSUTF8 pointers match when compared with the 
00672  * rules for Printable String (leading and trailing spaces are 
00673  * disregarded, extents of whitespace match irregardless of length, 
00674  * and case is not significant), then PR_TRUE will be returned.
00675  * Otherwise, PR_FALSE will be returned.  Upon failure, PR_FALSE
00676  * will be returned.  If the optional statusOpt argument is not
00677  * NULL, then PR_SUCCESS or PR_FAILURE will be stored in that
00678  * location.
00679  *
00680  * The error may be one of the following values:
00681  *  NSS_ERROR_INVALID_POINTER
00682  *
00683  * Return value:
00684  *  PR_TRUE if the strings match, ignoring case
00685  *  PR_FALSE if they don't
00686  *  PR_FALSE upon error
00687  */
00688 
00689 NSS_EXTERN PRBool
00690 nssUTF8_PrintableMatch
00691 (
00692   const NSSUTF8 *a,
00693   const NSSUTF8 *b,
00694   PRStatus *statusOpt
00695 );
00696 
00697 /*
00698  * nssUTF8_Size
00699  *
00700  * This routine returns the length in bytes (including the terminating
00701  * null) of the UTF8-encoded string pointed to by the specified
00702  * NSSUTF8 pointer.  Zero is returned on error.
00703  *
00704  * The error may be one of the following values:
00705  *  NSS_ERROR_INVALID_POINTER
00706  *  NSS_ERROR_VALUE_TOO_LARGE
00707  *
00708  * Return value:
00709  *  nonzero size of the string
00710  *  0 on error
00711  */
00712 
00713 NSS_EXTERN PRUint32
00714 nssUTF8_Size
00715 (
00716   const NSSUTF8 *s,
00717   PRStatus *statusOpt
00718 );
00719 
00720 extern const NSSError NSS_ERROR_INVALID_POINTER;
00721 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
00722 
00723 /*
00724  * nssUTF8_Length
00725  *
00726  * This routine returns the length in characters (not including the
00727  * terminating null) of the UTF8-encoded string pointed to by the
00728  * specified NSSUTF8 pointer.
00729  *
00730  * The error may be one of the following values:
00731  *  NSS_ERROR_INVALID_POINTER
00732  *  NSS_ERROR_VALUE_TOO_LARGE
00733  *  NSS_ERROR_INVALID_STRING
00734  *
00735  * Return value:
00736  *  length of the string (which may be zero)
00737  *  0 on error
00738  */
00739 
00740 NSS_EXTERN PRUint32
00741 nssUTF8_Length
00742 (
00743   const NSSUTF8 *s,
00744   PRStatus *statusOpt
00745 );
00746 
00747 extern const NSSError NSS_ERROR_INVALID_POINTER;
00748 extern const NSSError NSS_ERROR_VALUE_TOO_LARGE;
00749 extern const NSSError NSS_ERROR_INVALID_STRING;
00750 
00751 /*
00752  * nssUTF8_Create
00753  *
00754  * This routine creates a UTF8 string from a string in some other
00755  * format.  Some types of string may include embedded null characters,
00756  * so for them the length parameter must be used.  For string types
00757  * that are null-terminated, the length parameter is optional; if it
00758  * is zero, it will be ignored.  If the optional arena argument is
00759  * non-null, the memory used for the new string will be obtained from
00760  * that arena, otherwise it will be obtained from the heap.  This
00761  * routine may return NULL upon error, in which case it will have
00762  * placed an error on the error stack.
00763  *
00764  * The error may be one of the following:
00765  *  NSS_ERROR_INVALID_POINTER
00766  *  NSS_ERROR_NO_MEMORY
00767  *  NSS_ERROR_UNSUPPORTED_TYPE
00768  *
00769  * Return value:
00770  *  NULL upon error
00771  *  A non-null pointer to a new UTF8 string otherwise
00772  */
00773 
00774 NSS_EXTERN NSSUTF8 *
00775 nssUTF8_Create
00776 (
00777   NSSArena *arenaOpt,
00778   nssStringType type,
00779   const void *inputString,
00780   PRUint32 size /* in bytes, not characters */
00781 );
00782 
00783 extern const NSSError NSS_ERROR_INVALID_POINTER;
00784 extern const NSSError NSS_ERROR_NO_MEMORY;
00785 extern const NSSError NSS_ERROR_UNSUPPORTED_TYPE;
00786 
00787 NSS_EXTERN NSSItem *
00788 nssUTF8_GetEncoding
00789 (
00790   NSSArena *arenaOpt,
00791   NSSItem *rvOpt,
00792   nssStringType type,
00793   NSSUTF8 *string
00794 );
00795 
00796 /*
00797  * nssUTF8_CopyIntoFixedBuffer
00798  *
00799  * This will copy a UTF8 string into a fixed-length buffer, making 
00800  * sure that the all characters are valid.  Any remaining space will
00801  * be padded with the specified ASCII character, typically either 
00802  * null or space.
00803  *
00804  * Blah, blah, blah.
00805  */
00806 
00807 extern const NSSError NSS_ERROR_INVALID_POINTER;
00808 extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
00809 
00810 NSS_EXTERN PRStatus
00811 nssUTF8_CopyIntoFixedBuffer
00812 (
00813   NSSUTF8 *string,
00814   char *buffer,
00815   PRUint32 bufferSize,
00816   char pad
00817 );
00818 
00819 /*
00820  * nssUTF8_Equal
00821  *
00822  */
00823 
00824 NSS_EXTERN PRBool
00825 nssUTF8_Equal
00826 (
00827   const NSSUTF8 *a,
00828   const NSSUTF8 *b,
00829   PRStatus *statusOpt
00830 );
00831 
00832 /*
00833  * nssList
00834  *
00835  * The goal is to provide a simple, optionally threadsafe, linked list
00836  * class.  Since NSS did not seem to use the circularity of PRCList
00837  * much before, this provides a list that appears to be a linear,
00838  * NULL-terminated list.
00839  */
00840 
00841 /*
00842  * nssList_Create
00843  *
00844  * If threadsafe is true, the list will be locked during modifications
00845  * and traversals.
00846  */
00847 NSS_EXTERN nssList *
00848 nssList_Create
00849 (
00850   NSSArena *arenaOpt,
00851   PRBool threadSafe
00852 );
00853 
00854 /*
00855  * nssList_Destroy
00856  */
00857 NSS_EXTERN PRStatus
00858 nssList_Destroy
00859 (
00860   nssList *list
00861 );
00862 
00863 NSS_EXTERN void
00864 nssList_Clear
00865 (
00866   nssList *list, 
00867   nssListElementDestructorFunc destructor
00868 );
00869 
00870 /*
00871  * nssList_SetCompareFunction
00872  *
00873  * By default, two list elements will be compared by comparing their
00874  * data pointers.  By setting this function, the user can control
00875  * how elements are compared.
00876  */
00877 NSS_EXTERN void
00878 nssList_SetCompareFunction
00879 (
00880   nssList *list, 
00881   nssListCompareFunc compareFunc
00882 );
00883 
00884 /*
00885  * nssList_SetSortFunction
00886  *
00887  * Sort function to use for an ordered list.
00888  */
00889 NSS_EXTERN void
00890 nssList_SetSortFunction
00891 (
00892   nssList *list, 
00893   nssListSortFunc sortFunc
00894 );
00895 
00896 /*
00897  * nssList_Add
00898  */
00899 NSS_EXTERN PRStatus
00900 nssList_Add
00901 (
00902   nssList *list, 
00903   void *data
00904 );
00905 
00906 /*
00907  * nssList_AddUnique
00908  *
00909  * This will use the compare function to see if the element is already
00910  * in the list.
00911  */
00912 NSS_EXTERN PRStatus
00913 nssList_AddUnique
00914 (
00915   nssList *list, 
00916   void *data
00917 );
00918 
00919 /*
00920  * nssList_Remove
00921  *
00922  * Uses the compare function to locate the element and remove it.
00923  */
00924 NSS_EXTERN PRStatus
00925 nssList_Remove(nssList *list, void *data);
00926 
00927 /*
00928  * nssList_Get
00929  *
00930  * Uses the compare function to locate an element.  Also serves as
00931  * nssList_Exists.
00932  */
00933 NSS_EXTERN void *
00934 nssList_Get
00935 (
00936   nssList *list, 
00937   void *data
00938 );
00939 
00940 /*
00941  * nssList_Count
00942  */
00943 NSS_EXTERN PRUint32
00944 nssList_Count
00945 (
00946   nssList *list
00947 );
00948 
00949 /*
00950  * nssList_GetArray
00951  *
00952  * Fill rvArray, up to maxElements, with elements in the list.  The
00953  * array is NULL-terminated, so its allocated size must be maxElements + 1.
00954  */
00955 NSS_EXTERN PRStatus
00956 nssList_GetArray
00957 (
00958   nssList *list, 
00959   void **rvArray, 
00960   PRUint32 maxElements
00961 );
00962 
00963 /*
00964  * nssList_CreateIterator
00965  *
00966  * Create an iterator for list traversal.
00967  */
00968 NSS_EXTERN nssListIterator *
00969 nssList_CreateIterator
00970 (
00971   nssList *list
00972 );
00973 
00974 NSS_EXTERN nssList *
00975 nssList_Clone
00976 (
00977   nssList *list
00978 );
00979 
00980 /*
00981  * nssListIterator_Destroy
00982  */
00983 NSS_EXTERN void
00984 nssListIterator_Destroy
00985 (
00986   nssListIterator *iter
00987 );
00988 
00989 /*
00990  * nssListIterator_Start
00991  *
00992  * Begin a list iteration.  After this call, if the list is threadSafe,
00993  * the list is *locked*.
00994  */
00995 NSS_EXTERN void *
00996 nssListIterator_Start
00997 (
00998   nssListIterator *iter
00999 );
01000 
01001 /*
01002  * nssListIterator_Next
01003  *
01004  * Continue a list iteration.
01005  */
01006 NSS_EXTERN void *
01007 nssListIterator_Next
01008 (
01009   nssListIterator *iter
01010 );
01011 
01012 /*
01013  * nssListIterator_Finish
01014  *
01015  * Complete a list iteration.  This *must* be called in order for the
01016  * lock to be released.
01017  */
01018 NSS_EXTERN PRStatus
01019 nssListIterator_Finish
01020 (
01021   nssListIterator *iter
01022 );
01023 
01024 /*
01025  * nssHash
01026  *
01027  *  nssHash_Create
01028  *  nssHash_Destroy
01029  *  nssHash_Add
01030  *  nssHash_Remove
01031  *  nssHash_Count
01032  *  nssHash_Exists
01033  *  nssHash_Lookup
01034  *  nssHash_Iterate
01035  */
01036 
01037 /*
01038  * nssHash_Create
01039  *
01040  */
01041 
01042 NSS_EXTERN nssHash *
01043 nssHash_Create
01044 (
01045   NSSArena *arenaOpt,
01046   PRUint32 numBuckets,
01047   PLHashFunction keyHash,
01048   PLHashComparator keyCompare,
01049   PLHashComparator valueCompare
01050 );
01051 
01052 NSS_EXTERN nssHash *
01053 nssHash_CreatePointer
01054 (
01055   NSSArena *arenaOpt,
01056   PRUint32 numBuckets
01057 );
01058 
01059 NSS_EXTERN nssHash *
01060 nssHash_CreateString
01061 (
01062   NSSArena *arenaOpt,
01063   PRUint32 numBuckets
01064 );
01065 
01066 NSS_EXTERN nssHash *
01067 nssHash_CreateItem
01068 (
01069   NSSArena *arenaOpt,
01070   PRUint32 numBuckets
01071 );
01072 
01073 /*
01074  * nssHash_Destroy
01075  *
01076  */
01077 NSS_EXTERN void
01078 nssHash_Destroy
01079 (
01080   nssHash *hash
01081 );
01082 
01083 /*
01084  * nssHash_Add
01085  *
01086  */
01087 
01088 extern const NSSError NSS_ERROR_HASH_COLLISION;
01089 
01090 NSS_EXTERN PRStatus
01091 nssHash_Add
01092 (
01093   nssHash *hash,
01094   const void *key,
01095   const void *value
01096 );
01097 
01098 /*
01099  * nssHash_Remove
01100  *
01101  */
01102 NSS_EXTERN void
01103 nssHash_Remove
01104 (
01105   nssHash *hash,
01106   const void *it
01107 );
01108 
01109 /*
01110  * nssHash_Count
01111  *
01112  */
01113 NSS_EXTERN PRUint32
01114 nssHash_Count
01115 (
01116   nssHash *hash
01117 );
01118 
01119 /*
01120  * nssHash_Exists
01121  *
01122  */
01123 NSS_EXTERN PRBool
01124 nssHash_Exists
01125 (
01126   nssHash *hash,
01127   const void *it
01128 );
01129 
01130 /*
01131  * nssHash_Lookup
01132  *
01133  */
01134 NSS_EXTERN void *
01135 nssHash_Lookup
01136 (
01137   nssHash *hash,
01138   const void *it
01139 );
01140 
01141 /*
01142  * nssHash_Iterate
01143  *
01144  */
01145 NSS_EXTERN void
01146 nssHash_Iterate
01147 (
01148   nssHash *hash,
01149   nssHashIterator fcn,
01150   void *closure
01151 );
01152 
01153 
01154 /*
01155  * nssPointerTracker
01156  *
01157  * This type and these methods are only present in debug builds.
01158  * 
01159  * The nonpublic methods relating to this type are:
01160  *
01161  *  nssPointerTracker_initialize
01162  *  nssPointerTracker_finalize
01163  *  nssPointerTracker_add
01164  *  nssPointerTracker_remove
01165  *  nssPointerTracker_verify
01166  */
01167 
01168 /*
01169  * nssPointerTracker_initialize
01170  *
01171  * This method is only present in debug builds.
01172  * 
01173  * This routine initializes an nssPointerTracker object.  Note that
01174  * the object must have been declared *static* to guarantee that it
01175  * is in a zeroed state initially.  This routine is idempotent, and
01176  * may even be safely called by multiple threads simultaneously with 
01177  * the same argument.  This routine returns a PRStatus value; if 
01178  * successful, it will return PR_SUCCESS.  On failure it will set an 
01179  * error on the error stack and return PR_FAILURE.
01180  *
01181  * The error may be one of the following values:
01182  *  NSS_ERROR_NO_MEMORY
01183  *
01184  * Return value:
01185  *  PR_SUCCESS
01186  *  PR_FAILURE
01187  */
01188 
01189 #ifdef DEBUG
01190 NSS_EXTERN PRStatus
01191 nssPointerTracker_initialize
01192 (
01193   nssPointerTracker *tracker
01194 );
01195 
01196 extern const NSSError NSS_ERROR_NO_MEMORY;
01197 #endif /* DEBUG */
01198 
01199 /*
01200  * nssPointerTracker_finalize
01201  *
01202  * This method is only present in debug builds.
01203  * 
01204  * This routine returns the nssPointerTracker object to the pre-
01205  * initialized state, releasing all resources used by the object.
01206  * It will *NOT* destroy the objects being tracked by the pointer
01207  * (should any remain), and therefore cannot be used to "sweep up"
01208  * remaining objects.  This routine returns a PRStatus value; if
01209  * successful, it will return PR_SUCCES.  On failure it will set an
01210  * error on the error stack and return PR_FAILURE.  If any objects
01211  * remain in the tracker when it is finalized, that will be treated
01212  * as an error.
01213  *
01214  * The error may be one of the following values:
01215  *  NSS_ERROR_TRACKER_NOT_EMPTY
01216  *
01217  * Return value:
01218  *  PR_SUCCESS
01219  *  PR_FAILURE
01220  */
01221 
01222 #ifdef DEBUG
01223 NSS_EXTERN PRStatus
01224 nssPointerTracker_finalize
01225 (
01226   nssPointerTracker *tracker
01227 );
01228 
01229 extern const NSSError NSS_ERROR_TRACKER_NOT_EMPTY;
01230 #endif /* DEBUG */
01231 
01232 /*
01233  * nssPointerTracker_add
01234  *
01235  * This method is only present in debug builds.
01236  *
01237  * This routine adds the specified pointer to the nssPointerTracker
01238  * object.  It should be called in constructor objects to register
01239  * new valid objects.  The nssPointerTracker is threadsafe, but this
01240  * call is not idempotent.  This routine returns a PRStatus value;
01241  * if successful it will return PR_SUCCESS.  On failure it will set
01242  * an error on the error stack and return PR_FAILURE.
01243  *
01244  * The error may be one of the following values:
01245  *  NSS_ERROR_NO_MEMORY
01246  *  NSS_ERROR_TRACKER_NOT_INITIALIZED
01247  *  NSS_ERROR_DUPLICATE_POINTER
01248  *
01249  * Return value:
01250  *  PR_SUCCESS
01251  *  PR_FAILURE
01252  */
01253 
01254 #ifdef DEBUG
01255 NSS_EXTERN PRStatus
01256 nssPointerTracker_add
01257 (
01258   nssPointerTracker *tracker,
01259   const void *pointer
01260 );
01261 
01262 extern const NSSError NSS_ERROR_NO_MEMORY;
01263 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
01264 extern const NSSError NSS_ERROR_DUPLICATE_POINTER;
01265 #endif /* DEBUG */
01266 
01267 /*
01268  * nssPointerTracker_remove
01269  *
01270  * This method is only present in debug builds.
01271  *
01272  * This routine removes the specified pointer from the 
01273  * nssPointerTracker object.  It does not call any destructor for the
01274  * object; rather, this should be called from the object's destructor.
01275  * The nssPointerTracker is threadsafe, but this call is not 
01276  * idempotent.  This routine returns a PRStatus value; if successful 
01277  * it will return PR_SUCCESS.  On failure it will set an error on the 
01278  * error stack and return PR_FAILURE.
01279  *
01280  * The error may be one of the following values:
01281  *  NSS_ERROR_TRACKER_NOT_INITIALIZED
01282  *  NSS_ERROR_POINTER_NOT_REGISTERED
01283  *
01284  * Return value:
01285  *  PR_SUCCESS
01286  *  PR_FAILURE
01287  */
01288 
01289 #ifdef DEBUG
01290 NSS_EXTERN PRStatus
01291 nssPointerTracker_remove
01292 (
01293   nssPointerTracker *tracker,
01294   const void *pointer
01295 );
01296 
01297 extern const NSSError NSS_ERROR_TRACKER_NOT_INITIALIZED;
01298 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
01299 #endif /* DEBUG */
01300 
01301 /*
01302  * nssPointerTracker_verify
01303  *
01304  * This method is only present in debug builds.
01305  *
01306  * This routine verifies that the specified pointer has been registered
01307  * with the nssPointerTracker object.  The nssPointerTracker object is
01308  * threadsafe, and this call may be safely called from multiple threads
01309  * simultaneously with the same arguments.  This routine returns a
01310  * PRStatus value; if the pointer is registered this will return 
01311  * PR_SUCCESS.  Otherwise it will set an error on the error stack and 
01312  * return PR_FAILURE.  Although the error is suitable for leaving on 
01313  * the stack, callers may wish to augment the information available by 
01314  * placing a more type-specific error on the stack.
01315  *
01316  * The error may be one of the following values:
01317  *  NSS_ERROR_POINTER_NOT_REGISTERED
01318  *
01319  * Return value:
01320  *  PR_SUCCESS
01321  *  PR_FAILRUE
01322  */
01323 
01324 #ifdef DEBUG
01325 NSS_EXTERN PRStatus
01326 nssPointerTracker_verify
01327 (
01328   nssPointerTracker *tracker,
01329   const void *pointer
01330 );
01331 
01332 extern const NSSError NSS_ERROR_POINTER_NOT_REGISTERED;
01333 #endif /* DEBUG */
01334 
01335 /*
01336  * libc
01337  *
01338  * nsslibc_memcpy
01339  * nsslibc_memset
01340  * nsslibc_offsetof
01341  */
01342 
01343 /*
01344  * nsslibc_memcpy
01345  *
01346  * Errors:
01347  *  NSS_ERROR_INVALID_POINTER
01348  *
01349  * Return value:
01350  *  NULL on error
01351  *  The destination pointer on success
01352  */
01353 
01354 NSS_EXTERN void *
01355 nsslibc_memcpy
01356 (
01357   void *dest,
01358   const void *source,
01359   PRUint32 n
01360 );
01361 
01362 extern const NSSError NSS_ERROR_INVALID_POINTER;
01363 
01364 /*
01365  * nsslibc_memset
01366  *
01367  * Errors:
01368  *  NSS_ERROR_INVALID_POINTER
01369  *
01370  * Return value:
01371  *  NULL on error
01372  *  The destination pointer on success
01373  */
01374 
01375 NSS_EXTERN void *
01376 nsslibc_memset
01377 (
01378   void *dest,
01379   PRUint8 byte,
01380   PRUint32 n
01381 );
01382 
01383 extern const NSSError NSS_ERROR_INVALID_POINTER;
01384 
01385 /*
01386  * nsslibc_memequal
01387  *
01388  * Errors:
01389  *  NSS_ERROR_INVALID_POINTER
01390  *
01391  * Return value:
01392  *  PR_TRUE if they match
01393  *  PR_FALSE if they don't
01394  *  PR_FALSE upon error
01395  */
01396 
01397 NSS_EXTERN PRBool
01398 nsslibc_memequal
01399 (
01400   const void *a,
01401   const void *b,
01402   PRUint32 len,
01403   PRStatus *statusOpt
01404 );
01405 
01406 extern const NSSError NSS_ERROR_INVALID_POINTER;
01407 
01408 #define nsslibc_offsetof(str, memb) ((PRPtrdiff)(&(((str *)0)->memb)))
01409 
01410 /*
01411  * nss_NewThreadPrivateIndex
01412  * 
01413  */
01414 
01415 NSS_EXTERN PRStatus
01416 nss_NewThreadPrivateIndex
01417 (
01418   PRUintn *ip,
01419   PRThreadPrivateDTOR dtor
01420 );
01421 
01422 /*
01423  * nss_GetThreadPrivate
01424  *
01425  */
01426 
01427 NSS_EXTERN void *
01428 nss_GetThreadPrivate
01429 (
01430   PRUintn i
01431 );
01432 
01433 /*
01434  * nss_SetThreadPrivate
01435  *
01436  */
01437 
01438 NSS_EXTERN void
01439 nss_SetThreadPrivate
01440 (
01441   PRUintn i,
01442   void *v
01443 );
01444 
01445 
01446 PR_END_EXTERN_C
01447 
01448 #endif /* BASE_H */