michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef _SECITEM_H_
michael@0: #define _SECITEM_H_
michael@0: 
michael@0: #include "utilrename.h"
michael@0: 
michael@0: /*
michael@0:  * secitem.h - public data structures and prototypes for handling
michael@0:  *	       SECItems
michael@0:  */
michael@0: 
michael@0: #include "plarena.h"
michael@0: #include "plhash.h"
michael@0: #include "seccomon.h"
michael@0: 
michael@0: SEC_BEGIN_PROTOS
michael@0: 
michael@0: /*
michael@0: ** Allocate an item.  If "arena" is not NULL, then allocate from there,
michael@0: ** otherwise allocate from the heap.  If "item" is not NULL, allocate
michael@0: ** only the data buffer for the item, not the item itself.  If "len" is
michael@0: ** 0, do not allocate the data buffer for the item; simply set the data
michael@0: ** field to NULL and the len field to 0.  The item structure is allocated
michael@0: ** zero-filled; the data buffer is not zeroed.  The caller is responsible
michael@0: ** for initializing the type field of the item.
michael@0: **
michael@0: ** The resulting item is returned; NULL if any error occurs.
michael@0: **
michael@0: ** XXX This probably should take a SECItemType, but since that is mostly
michael@0: ** unused and our improved APIs (aka Stan) are looming, I left it out.
michael@0: */
michael@0: extern SECItem *SECITEM_AllocItem(PLArenaPool *arena, SECItem *item,
michael@0: 				  unsigned int len);
michael@0: 
michael@0: /*
michael@0: ** This is a legacy function containing bugs. It doesn't update item->len,
michael@0: ** and it has other issues as described in bug 298649 and bug 298938.
michael@0: ** However, the function is  kept unchanged for consumers that might depend 
michael@0: ** on the broken behaviour. New code should call SECITEM_ReallocItemV2.
michael@0: **
michael@0: ** Reallocate the data for the specified "item".  If "arena" is not NULL,
michael@0: ** then reallocate from there, otherwise reallocate from the heap.
michael@0: ** In the case where oldlen is 0, the data is allocated (not reallocated).
michael@0: ** In any case, "item" is expected to be a valid SECItem pointer;
michael@0: ** SECFailure is returned if it is not.  If the allocation succeeds,
michael@0: ** SECSuccess is returned.
michael@0: */
michael@0: extern SECStatus SECITEM_ReallocItem( /* deprecated function */
michael@0: 				     PLArenaPool *arena, SECItem *item,
michael@0: 				     unsigned int oldlen, unsigned int newlen);
michael@0: 
michael@0: /*
michael@0: ** Reallocate the data for the specified "item".  If "arena" is not NULL,
michael@0: ** then reallocate from there, otherwise reallocate from the heap.
michael@0: ** If item->data is NULL, the data is allocated (not reallocated).
michael@0: ** In any case, "item" is expected to be a valid SECItem pointer;
michael@0: ** SECFailure is returned if it is not, and the item will remain unchanged.
michael@0: ** If the allocation succeeds, the item is updated and SECSuccess is returned.
michael@0:  */
michael@0: extern SECStatus SECITEM_ReallocItemV2(PLArenaPool *arena, SECItem *item,
michael@0: 				       unsigned int newlen);
michael@0: 
michael@0: /*
michael@0: ** Compare two items returning the difference between them.
michael@0: */
michael@0: extern SECComparison SECITEM_CompareItem(const SECItem *a, const SECItem *b);
michael@0: 
michael@0: /*
michael@0: ** Compare two items -- if they are the same, return true; otherwise false.
michael@0: */
michael@0: extern PRBool SECITEM_ItemsAreEqual(const SECItem *a, const SECItem *b);
michael@0: 
michael@0: /*
michael@0: ** Copy "from" to "to"
michael@0: */
michael@0: extern SECStatus SECITEM_CopyItem(PLArenaPool *arena, SECItem *to, 
michael@0:                                   const SECItem *from);
michael@0: 
michael@0: /*
michael@0: ** Allocate an item and copy "from" into it.
michael@0: */
michael@0: extern SECItem *SECITEM_DupItem(const SECItem *from);
michael@0: 
michael@0: /*
michael@0: ** Allocate an item and copy "from" into it.  The item itself and the 
michael@0: ** data it points to are both allocated from the arena.  If arena is
michael@0: ** NULL, this function is equivalent to SECITEM_DupItem.
michael@0: */
michael@0: extern SECItem *SECITEM_ArenaDupItem(PLArenaPool *arena, const SECItem *from);
michael@0: 
michael@0: /*
michael@0: ** Free "zap". If freeit is PR_TRUE then "zap" itself is freed.
michael@0: */
michael@0: extern void SECITEM_FreeItem(SECItem *zap, PRBool freeit);
michael@0: 
michael@0: /*
michael@0: ** Zero and then free "zap". If freeit is PR_TRUE then "zap" itself is freed.
michael@0: */
michael@0: extern void SECITEM_ZfreeItem(SECItem *zap, PRBool freeit);
michael@0: 
michael@0: PLHashNumber PR_CALLBACK SECITEM_Hash ( const void *key);
michael@0: 
michael@0: PRIntn PR_CALLBACK SECITEM_HashCompare ( const void *k1, const void *k2);
michael@0: 
michael@0: extern SECItemArray *SECITEM_AllocArray(PLArenaPool *arena,
michael@0:                                         SECItemArray *array,
michael@0:                                         unsigned int len);
michael@0: extern SECItemArray *SECITEM_DupArray(PLArenaPool *arena,
michael@0:                                       const SECItemArray *from);
michael@0: extern void SECITEM_FreeArray(SECItemArray *array, PRBool freeit);
michael@0: extern void SECITEM_ZfreeArray(SECItemArray *array, PRBool freeit);
michael@0: 
michael@0: SEC_END_PROTOS
michael@0: 
michael@0: #endif /* _SECITEM_H_ */