nssbase.h (6672B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 #ifndef NSSBASE_H 6 #define NSSBASE_H 7 8 /* 9 * nssbase.h 10 * 11 * This header file contains the prototypes of the basic public 12 * NSS routines. 13 */ 14 15 #ifndef NSSBASET_H 16 #include "nssbaset.h" 17 #endif /* NSSBASET_H */ 18 19 PR_BEGIN_EXTERN_C 20 21 /* 22 * NSSArena 23 * 24 * The public methods relating to this type are: 25 * 26 * NSSArena_Create -- constructor 27 * NSSArena_Destroy 28 * NSS_ZAlloc 29 * NSS_ZRealloc 30 * NSS_ZFreeIf 31 */ 32 33 /* 34 * NSSArena_Create 35 * 36 * This routine creates a new memory arena. This routine may return 37 * NULL upon error, in which case it will have created an error stack. 38 * 39 * The top-level error may be one of the following values: 40 * NSS_ERROR_NO_MEMORY 41 * 42 * Return value: 43 * NULL upon error 44 * A pointer to an NSSArena upon success 45 */ 46 47 NSS_EXTERN NSSArena *NSSArena_Create(void); 48 49 extern const NSSError NSS_ERROR_NO_MEMORY; 50 51 /* 52 * NSSArena_Destroy 53 * 54 * This routine will destroy the specified arena, freeing all memory 55 * allocated from it. This routine returns a PRStatus value; if 56 * successful, it will return PR_SUCCESS. If unsuccessful, it will 57 * create an error stack and return PR_FAILURE. 58 * 59 * The top-level error may be one of the following values: 60 * NSS_ERROR_INVALID_ARENA 61 * 62 * Return value: 63 * PR_SUCCESS upon success 64 * PR_FAILURE upon failure 65 */ 66 67 NSS_EXTERN PRStatus NSSArena_Destroy(NSSArena *arena); 68 69 extern const NSSError NSS_ERROR_INVALID_ARENA; 70 71 /* 72 * The error stack 73 * 74 * The public methods relating to the error stack are: 75 * 76 * NSS_GetError 77 * NSS_GetErrorStack 78 */ 79 80 /* 81 * NSS_GetError 82 * 83 * This routine returns the highest-level (most general) error set 84 * by the most recent NSS library routine called by the same thread 85 * calling this routine. 86 * 87 * This routine cannot fail. It may return NSS_ERROR_NO_ERROR, which 88 * indicates that the previous NSS library call did not set an error. 89 * 90 * Return value: 91 * 0 if no error has been set 92 * A nonzero error number 93 */ 94 95 NSS_EXTERN NSSError NSS_GetError(void); 96 97 extern const NSSError NSS_ERROR_NO_ERROR; 98 99 /* 100 * NSS_GetErrorStack 101 * 102 * This routine returns a pointer to an array of NSSError values, 103 * containingthe entire sequence or "stack" of errors set by the most 104 * recent NSS library routine called by the same thread calling this 105 * routine. NOTE: the caller DOES NOT OWN the memory pointed to by 106 * the return value. The pointer will remain valid until the calling 107 * thread calls another NSS routine. The lowest-level (most specific) 108 * error is first in the array, and the highest-level is last. The 109 * array is zero-terminated. This routine may return NULL upon error; 110 * this indicates a low-memory situation. 111 * 112 * Return value: 113 * NULL upon error, which is an implied NSS_ERROR_NO_MEMORY 114 * A NON-caller-owned pointer to an array of NSSError values 115 */ 116 117 NSS_EXTERN NSSError *NSS_GetErrorStack(void); 118 119 /* 120 * NSS_ZNEW 121 * 122 * This preprocessor macro will allocate memory for a new object 123 * of the specified type with nss_ZAlloc, and will cast the 124 * return value appropriately. If the optional arena argument is 125 * non-null, the memory will be obtained from that arena; otherwise, 126 * the memory will be obtained from the heap. This routine may 127 * return NULL upon error, in which case it will have set an error 128 * upon the error stack. 129 * 130 * The error may be one of the following values: 131 * NSS_ERROR_INVALID_ARENA 132 * NSS_ERROR_NO_MEMORY 133 * 134 * Return value: 135 * NULL upon error 136 * A pointer to the new segment of zeroed memory 137 */ 138 139 #define NSS_ZNEW(arenaOpt, type) ((type *)NSS_ZAlloc((arenaOpt), sizeof(type))) 140 141 /* 142 * NSS_ZNEWARRAY 143 * 144 * This preprocessor macro will allocate memory for an array of 145 * new objects, and will cast the return value appropriately. 146 * If the optional arena argument is non-null, the memory will 147 * be obtained from that arena; otherwise, the memory will be 148 * obtained from the heap. This routine may return NULL upon 149 * error, in which case it will have set an error upon the error 150 * stack. The array size may be specified as zero. 151 * 152 * The error may be one of the following values: 153 * NSS_ERROR_INVALID_ARENA 154 * NSS_ERROR_NO_MEMORY 155 * 156 * Return value: 157 * NULL upon error 158 * A pointer to the new segment of zeroed memory 159 */ 160 161 #define NSS_ZNEWARRAY(arenaOpt, type, quantity) \ 162 ((type *)NSS_ZAlloc((arenaOpt), sizeof(type) * (quantity))) 163 164 /* 165 * NSS_ZAlloc 166 * 167 * This routine allocates and zeroes a section of memory of the 168 * size, and returns to the caller a pointer to that memory. If 169 * the optional arena argument is non-null, the memory will be 170 * obtained from that arena; otherwise, the memory will be obtained 171 * from the heap. This routine may return NULL upon error, in 172 * which case it will have set an error upon the error stack. The 173 * value specified for size may be zero; in which case a valid 174 * zero-length block of memory will be allocated. This block may 175 * be expanded by calling NSS_ZRealloc. 176 * 177 * The error may be one of the following values: 178 * NSS_ERROR_INVALID_ARENA 179 * NSS_ERROR_NO_MEMORY 180 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD 181 * 182 * Return value: 183 * NULL upon error 184 * A pointer to the new segment of zeroed memory 185 */ 186 187 NSS_EXTERN void *NSS_ZAlloc(NSSArena *arenaOpt, PRUint32 size); 188 189 /* 190 * NSS_ZRealloc 191 * 192 * This routine reallocates a block of memory obtained by calling 193 * nss_ZAlloc or nss_ZRealloc. The portion of memory 194 * between the new and old sizes -- which is either being newly 195 * obtained or released -- is in either case zeroed. This routine 196 * may return NULL upon failure, in which case it will have placed 197 * an error on the error stack. 198 * 199 * The error may be one of the following values: 200 * NSS_ERROR_INVALID_POINTER 201 * NSS_ERROR_NO_MEMORY 202 * NSS_ERROR_ARENA_MARKED_BY_ANOTHER_THREAD 203 * 204 * Return value: 205 * NULL upon error 206 * A pointer to the replacement segment of memory 207 */ 208 209 NSS_EXTERN void *NSS_ZRealloc(void *pointer, PRUint32 newSize); 210 211 /* 212 * NSS_ZFreeIf 213 * 214 * If the specified pointer is non-null, then the region of memory 215 * to which it points -- which must have been allocated with 216 * nss_ZAlloc -- will be zeroed and released. This routine 217 * returns a PRStatus value; if successful, it will return PR_SUCCESS. 218 * If unsuccessful, it will set an error on the error stack and return 219 * PR_FAILURE. 220 * 221 * The error may be one of the following values: 222 * NSS_ERROR_INVALID_POINTER 223 * 224 * Return value: 225 * PR_SUCCESS 226 * PR_FAILURE 227 */ 228 229 NSS_EXTERN PRStatus NSS_ZFreeIf(void *pointer); 230 231 PR_END_EXTERN_C 232 233 #endif /* NSSBASE_H */