1/**
2 * Copyright(c) 2011 Trusted Logic.   All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 *  * Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions and the following disclaimer.
10 *  * Redistributions in binary form must reproduce the above copyright
11 *    notice, this list of conditions and the following disclaimer in
12 *    the documentation and/or other materials provided with the
13 *    distribution.
14 *  * Neither the name Trusted Logic nor the names of its
15 *    contributors may be used to endorse or promote products derived
16 *    from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31#ifndef   __LIB_OBJECT_H__
32#define   __LIB_OBJECT_H__
33
34#include "s_type.h"
35
36typedef struct
37{
38   /* Type of storage: See S_STORAGE_TYPE_XXX */
39   uint32_t nStorageType;
40
41   /* Login type of the client: See S_LOGIN_XXX */
42   uint32_t nLoginType;
43
44   /* Identifier of the client (secure or non-secure client) */
45   S_UUID sClientUUID;
46}
47S_STORAGE_NAME;
48
49
50/**
51 * This library defines three types of objects and keys:
52 * - objects identified by a 16-bit handle
53 * - objects identified by a S_STORAGE_NAME
54 * - objects identified by a filename, which is a variable-size up-to-64 bytes byte array
55 * - unindexed objects
56 **/
57
58/* -------------------------------------------------------------------------
59   Useful macro to get a structure from a pointer to one of its fields.
60
61   Typical usage:
62   typedef struct
63   {
64      LIB_OBJECT_NODE_HANDLE16  sNodeInHandleTable;
65      LIB_OBJECT_NODE_UNINDEXED sNodeInList;
66   }
67   CONTEXT;
68
69   LIB_OBJECT_CONTAINER_OF(libObjectUnindexedNext(pList, pObject), CONTEXT, sNodeInList)
70
71
72   -------------------------------------------------------------------------*/
73#define LIB_OBJECT_CONTAINER_OF(ptr, type, member) (((type*)(((char*)(ptr)) - offsetof(type, member))))
74
75
76/* -------------------------------------------------------------------------
77   Table of objects indexed by 16-bit handles
78   -------------------------------------------------------------------------*/
79
80#define LIB_OBJECT_HANDLE16_MAX ((uint16_t)0xFFFF)
81
82/**
83 * NODE of an object in a table indexed by 16-bit handles
84 **/
85typedef struct
86{
87   /* Implementation-defined fields */
88   uint32_t _l[2];
89
90   /* Public field */
91   uint16_t   nHandle;
92}
93LIB_OBJECT_NODE_HANDLE16;
94
95/**
96 * A table of objects indexed by 16-bit handles
97 **/
98typedef struct
99{
100   LIB_OBJECT_NODE_HANDLE16* pRoot;
101}
102LIB_OBJECT_TABLE_HANDLE16;
103
104/**
105 * Add an object in a handle table. This function also
106 * assigns a new handle value to the object. The handle
107 * is guaranteed to be unique among all the objects
108 * in the table and non-zero.
109 *
110 * Returns false if the maximum number of handles has been reached
111 *    (i.e., there are already 65535 objects in the table)
112 **/
113bool libObjectHandle16Add(
114               LIB_OBJECT_TABLE_HANDLE16* pTable,
115               LIB_OBJECT_NODE_HANDLE16* pObject);
116
117/**
118 * Search an object by its handle. Return NULL if the
119 * object is not found
120 **/
121LIB_OBJECT_NODE_HANDLE16* libObjectHandle16Search(
122               LIB_OBJECT_TABLE_HANDLE16* pTable,
123               uint32_t nHandle);
124
125/**
126 * Remove an object from a handle table.
127 *
128 * The object must be part of the table
129 **/
130void libObjectHandle16Remove(
131               LIB_OBJECT_TABLE_HANDLE16* pTable,
132               LIB_OBJECT_NODE_HANDLE16* pObject);
133
134/**
135 * Remove one object from the table. This is useful when
136 * you want to destroy all the objects in the table.
137 *
138 * Returns NULL if the table is empty
139 **/
140LIB_OBJECT_NODE_HANDLE16* libObjectHandle16RemoveOne(
141               LIB_OBJECT_TABLE_HANDLE16* pTable);
142
143/**
144 * Get the object following pObject in the handle table.
145 * If pObject is NULL, return the first object in the list
146 * Return NULL if the object is the last in the table
147 **/
148LIB_OBJECT_NODE_HANDLE16* libObjectHandle16Next(
149               LIB_OBJECT_TABLE_HANDLE16* pTable,
150               LIB_OBJECT_NODE_HANDLE16* pObject);
151
152/* -------------------------------------------------------------------------
153   Table of objects indexed by storage name
154   -------------------------------------------------------------------------*/
155
156/**
157 * NODE of an object in a table indexed by storage name
158 **/
159typedef struct
160{
161   /* Implementation-defined fields */
162   uint32_t _l[2];
163
164   /* Public fields */
165   S_STORAGE_NAME sStorageName;
166}
167LIB_OBJECT_NODE_STORAGE_NAME;
168
169/**
170 * A table of objects indexed by storage name
171 **/
172typedef struct
173{
174   LIB_OBJECT_NODE_STORAGE_NAME* pRoot;
175}
176LIB_OBJECT_TABLE_STORAGE_NAME;
177
178/**
179 * Add an object in a storage name table.
180 *
181 * The object must not be part of the table yet. The caller
182 * must have set pObject->sStorageName with the storage name
183 **/
184void libObjectStorageNameAdd(
185               LIB_OBJECT_TABLE_STORAGE_NAME* pTable,
186               LIB_OBJECT_NODE_STORAGE_NAME* pObject);
187
188/**
189 * Search an object by its storage name. Return NULL if the
190 * object is not found
191 **/
192LIB_OBJECT_NODE_STORAGE_NAME* libObjectStorageNameSearch(
193               LIB_OBJECT_TABLE_STORAGE_NAME* pTable,
194               S_STORAGE_NAME* pStorageName);
195
196/**
197 * Remove an object from a storage name table.
198 *
199 * The object must be part of the table
200 **/
201void libObjectStorageNameRemove(
202               LIB_OBJECT_TABLE_STORAGE_NAME* pTable,
203               LIB_OBJECT_NODE_STORAGE_NAME* pObject);
204
205/**
206 * Remove one object from the table. This is useful when
207 * you want to destroy all the objects in the table
208 * Returns NULL if the table is empty
209 **/
210LIB_OBJECT_NODE_STORAGE_NAME* libObjectStorageNameRemoveOne(
211               LIB_OBJECT_TABLE_STORAGE_NAME* pTable);
212
213/**
214 * Get the object following pObject in the storage name table.
215 * If pObject is NULL, return the first object
216 * Return NULL if the object is the last in the table
217 **/
218LIB_OBJECT_NODE_STORAGE_NAME* libObjectStorageNameNext(
219               LIB_OBJECT_TABLE_STORAGE_NAME* pTable,
220               LIB_OBJECT_NODE_STORAGE_NAME* pObject);
221
222/* -------------------------------------------------------------------------
223   Table of objects indexed by filenames
224   -------------------------------------------------------------------------*/
225
226/**
227 * NODE of an object in a table indexed by filenames (varsize up-to-64 bytes)
228 **/
229typedef struct
230{
231   /* Implementation-defined fields */
232   uint32_t _l[2];
233
234   /* Public fields */
235   uint8_t  sFilename[64];
236   uint8_t  nFilenameLength;
237}
238LIB_OBJECT_NODE_FILENAME;
239
240/**
241 * A table of objects indexed by filenames
242 **/
243typedef struct
244{
245   LIB_OBJECT_NODE_FILENAME* pRoot;
246}
247LIB_OBJECT_TABLE_FILENAME;
248
249/**
250 * Add an object in a filename table.
251 *
252 * The object must not be part of the table yet. The caller
253 * must have set pObject->sFilename and pObject->nFilenameLength
254 * with the object filename
255 **/
256void libObjectFilenameAdd(
257               LIB_OBJECT_TABLE_FILENAME* pTable,
258               LIB_OBJECT_NODE_FILENAME* pObject);
259
260/**
261 * Search an object by its filename. Return NULL if the
262 * object is not found
263 **/
264LIB_OBJECT_NODE_FILENAME* libObjectFilenameSearch(
265               LIB_OBJECT_TABLE_FILENAME* pTable,
266               uint8_t* pFilename,
267               uint32_t  nFilenameLength);
268
269/**
270 * Remove an object from a filename table.
271 *
272 * The object must be part of the table
273 **/
274void libObjectFilenameRemove(
275               LIB_OBJECT_TABLE_FILENAME* pTable,
276               LIB_OBJECT_NODE_FILENAME* pObject);
277
278/**
279 * Remove one element from the table and return it. This is useful when
280 * you want to destroy all the objects in the table
281 * Returns NULL if the table is empty
282 **/
283LIB_OBJECT_NODE_FILENAME* libObjectFilenameRemoveOne(
284               LIB_OBJECT_TABLE_FILENAME* pTable);
285
286/**
287 * Get the object following pObject in the filename table.
288 * If pObject is NULL, return the first object
289 * Return NULL if the object is the last in the table
290 **/
291LIB_OBJECT_NODE_FILENAME* libObjectFilenameNext(
292               LIB_OBJECT_TABLE_FILENAME* pTable,
293               LIB_OBJECT_NODE_FILENAME* pObject);
294
295/* -------------------------------------------------------------------------
296   Unindexed table of objects
297   -------------------------------------------------------------------------*/
298/**
299 * NODE of an unindexed object
300 **/
301typedef struct
302{
303   /* Implementation-defined fields */
304   uint32_t _l[2];
305}
306LIB_OBJECT_NODE_UNINDEXED;
307
308/**
309 * A table of unindexed objects
310 **/
311typedef struct
312{
313   LIB_OBJECT_NODE_UNINDEXED* pRoot;
314}
315LIB_OBJECT_TABLE_UNINDEXED;
316
317
318/**
319 * Add an object in an unindexed table. The object must not be part of the table yet.
320 **/
321void libObjectUnindexedAdd(
322         LIB_OBJECT_TABLE_UNINDEXED* pTable,
323         LIB_OBJECT_NODE_UNINDEXED* pObject);
324
325/**
326 * Remove an object from an unindexed table. The object must be part of the table.
327 **/
328void libObjectUnindexedRemove(
329         LIB_OBJECT_TABLE_UNINDEXED* pTable,
330         LIB_OBJECT_NODE_UNINDEXED* pObject);
331
332/**
333 * Remove one object in the table. This is useful when you want to destroy all objects
334 * in the table.
335 * Returns NULL if the table is empty
336 **/
337LIB_OBJECT_NODE_UNINDEXED* libObjectUnindexedRemoveOne(LIB_OBJECT_TABLE_UNINDEXED* pTable);
338
339/**
340 * Get the object following pObject in the table.
341 * If pObject is NULL, return the first object
342 * Return NULL if the object is the last in the table
343 **/
344LIB_OBJECT_NODE_UNINDEXED* libObjectUnindexedNext(
345               LIB_OBJECT_TABLE_UNINDEXED* pTable,
346               LIB_OBJECT_NODE_UNINDEXED* pObject);
347
348#endif /* __LIB_OBJECT_H__ */
349