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 _SECITEM_H_
6#define _SECITEM_H_
7
8#include "utilrename.h"
9
10/*
11 * secitem.h - public data structures and prototypes for handling
12 * SECItems
13 */
14
15#include "plarena.h"
16#include "plhash.h"
17#include "seccomon.h"
18
19SEC_BEGIN_PROTOS
20
21/*
22** Allocate an item. If "arena" is not NULL, then allocate from there,
23** otherwise allocate from the heap. If "item" is not NULL, allocate
24** only the data buffer for the item, not the item itself. If "len" is
25** 0, do not allocate the data buffer for the item; simply set the data
26** field to NULL and the len field to 0. The item structure is allocated
27** zero-filled; the data buffer is not zeroed. The caller is responsible
28** for initializing the type field of the item.
29**
30** The resulting item is returned; NULL if any error occurs.
31**
32** XXX This probably should take a SECItemType, but since that is mostly
33** unused and our improved APIs (aka Stan) are looming, I left it out.
34*/
35extern SECItem *SECITEM_AllocItem(PLArenaPool *arena, SECItem *item,
36 unsigned int len);
37
38/* Allocate and make an item with the requested contents.
39 *
40 * We seem to have mostly given up on SECItemType, so the result is
41 * always siBuffer.
42 */
43extern SECStatus SECITEM_MakeItem(PLArenaPool *arena, SECItem *dest,
44 const unsigned char *data, unsigned int len);
45
46/*
47** This is a legacy function containing bugs. It doesn't update item->len,
48** and it has other issues as described in bug 298649 and bug 298938.
49** However, the function is kept unchanged for consumers that might depend
50** on the broken behaviour. New code should call SECITEM_ReallocItemV2.
51**
52** Reallocate the data for the specified "item". If "arena" is not NULL,
53** then reallocate from there, otherwise reallocate from the heap.
54** In the case where oldlen is 0, the data is allocated (not reallocated).
55** In any case, "item" is expected to be a valid SECItem pointer;
56** SECFailure is returned if it is not. If the allocation succeeds,
57** SECSuccess is returned.
58*/
59extern SECStatus SECITEM_ReallocItem(/* deprecated function */
60 PLArenaPool *arena, SECItem *item,
61 unsigned int oldlen, unsigned int newlen);
62
63/*
64** Reallocate the data for the specified "item". If "arena" is not NULL,
65** then reallocate from there, otherwise reallocate from the heap.
66** If item->data is NULL, the data is allocated (not reallocated).
67** In any case, "item" is expected to be a valid SECItem pointer;
68** SECFailure is returned if it is not, and the item will remain unchanged.
69** If the allocation succeeds, the item is updated and SECSuccess is returned.
70 */
71extern SECStatus SECITEM_ReallocItemV2(PLArenaPool *arena, SECItem *item,
72 unsigned int newlen);
73
74/*
75** Compare two items returning the difference between them.
76*/
77extern SECComparison SECITEM_CompareItem(const SECItem *a, const SECItem *b);
78
79/*
80** Compare two items -- if they are the same, return true; otherwise false.
81*/
82extern PRBool SECITEM_ItemsAreEqual(const SECItem *a, const SECItem *b);
83
84/*
85** Copy "from" to "to"
86*/
87extern SECStatus SECITEM_CopyItem(PLArenaPool *arena, SECItem *to,
88 const SECItem *from);
89
90/*
91** Allocate an item and copy "from" into it.
92*/
93extern SECItem *SECITEM_DupItem(const SECItem *from);
94
95/*
96** Allocate an item and copy "from" into it. The item itself and the
97** data it points to are both allocated from the arena. If arena is
98** NULL, this function is equivalent to SECITEM_DupItem.
99*/
100extern SECItem *SECITEM_ArenaDupItem(PLArenaPool *arena, const SECItem *from);
101
102/*
103** Free "zap". If freeit is PR_TRUE then "zap" itself is freed.
104*/
105extern void SECITEM_FreeItem(SECItem *zap, PRBool freeit);
106
107/*
108** Zero and then free "zap". If freeit is PR_TRUE then "zap" itself is freed.
109*/
110extern void SECITEM_ZfreeItem(SECItem *zap, PRBool freeit);
111
112PLHashNumber PR_CALLBACK SECITEM_Hash(const void *key);
113
114PRIntn PR_CALLBACK SECITEM_HashCompare(const void *k1, const void *k2);
115
116extern SECItemArray *SECITEM_AllocArray(PLArenaPool *arena,
117 SECItemArray *array,
118 unsigned int len);
119extern SECItemArray *SECITEM_DupArray(PLArenaPool *arena,
120 const SECItemArray *from);
121extern void SECITEM_FreeArray(SECItemArray *array, PRBool freeit);
122extern void SECITEM_ZfreeArray(SECItemArray *array, PRBool freeit);
123
124SEC_END_PROTOS
125
126#endif /* _SECITEM_H_ */
127

source code of include/nss/secitem.h