Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / common / inc / ulinklist.h
1 /* ****************************************************************
2  *
3  * Copyright 2015 Samsung Electronics All Rights Reserved.
4  *
5  *
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *      http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  ******************************************************************/
20
21 #ifndef U_LINKLIST_H_
22 #define U_LINKLIST_H_
23
24 /**
25  * @todo Do performance comparision with array list.
26  */
27
28 #include <stdint.h>
29 #include "cacommon.h"
30
31 #ifdef __cplusplus
32 extern "C"
33 {
34 #endif
35 #ifndef OICDEFINE
36 #include <stdbool.h>
37
38 #endif
39
40 /**
41  * link list structure
42  */
43 typedef struct linked_list_data u_linklist_data_t;
44
45 typedef struct linked_list_data u_linklist_iterator_t;
46
47 typedef struct u_linklist
48 {
49     u_linklist_data_t *list;
50     int size;
51 }u_linklist_t;
52
53 struct linked_list_data
54 {
55     void *data;
56     u_linklist_data_t *next;
57 };
58
59 /**
60  * API to create link list and initializes the elements.
61  * @return  u_linklist_t if Success, NULL otherwise.
62  */
63 u_linklist_t *u_linklist_create(void);
64
65 /**
66  * Resets and deletes the link list
67  * Linklist elements are deleted, Calling function must take care of freeing
68  * dynamic memory allocated before freeing the linklist.
69  * @param[in,out] list      u_linklist pointer.
70  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_INVALID_PARAM if pointer to list is NULL.
71  */
72 CAResult_t u_linklist_free(u_linklist_t **list);
73
74 /**
75  * Add data to the head of the link list.
76  * @param[in,out]  list      pointer of link list.
77  * @param[in]      data      pointer of data.
78  * @return ::CA_STATUS_OK if Success, ::CA_MEMORY_ALLOC_FAILED if memory allocation fails.
79  */
80 CAResult_t u_linklist_add_head(u_linklist_t *list, void *data);
81
82 /**
83  * Add data to the tail of the link list.
84  * @param[in,out]  list      pointer of link list.
85  * @param[in]      data      pointer of data.
86  * @return ::CA_STATUS_OK if Success, ::CA_MEMORY_ALLOC_FAILED if memory allocation fails.
87  */
88 CAResult_t u_linklist_add(u_linklist_t *list, void *data);
89
90
91 /**
92  * This api deletes node pointed by iterator.
93  * Advances iterator to next node in the list.
94  * @param[in,out]   list         pointer of link list.
95  * @param[in,out]   iter         pointer of iterator pointing to previous node.
96  * @return ::CA_STATUS_OK if Success, ::CA_STATUS_INVALID_PARAM if iterator is NULL.
97  */
98 CAResult_t u_linklist_remove(u_linklist_t *list, u_linklist_iterator_t **iter);
99
100
101 /**
102  * Returns the length of the link list.
103  * @param[in] list               pointer of link list.
104  * @return length of the link list.
105  */
106 uint32_t u_linklist_length(const u_linklist_t *list);
107
108 /**
109  * Initializes the iterator, need to be called before calling u_linklist_get_next.
110  * @param[in]       list             pointer of link list.
111  * @param[in,out]   iter             iterator of link list.
112  * @return NONE
113  */
114 void u_linklist_init_iterator(const u_linklist_t *list, u_linklist_iterator_t **iter);
115
116 /**
117  * Returns the data of the node iterator points to from the link list.
118  * @param[in] iter             iterator of link list.
119  * @return the data of node to which iterator is pointing.
120  */
121 void *u_linklist_get_data(const u_linklist_iterator_t *iter);
122
123 /**
124  * Returns the data of the next node iterator points to from the link list
125  * Advances iterator to next node in the list.
126  * @param[in,out] iter             iterator of link list.
127  * @return the data of next node.
128  */
129 void *u_linklist_get_next(u_linklist_iterator_t **iter);
130
131 #ifdef __cplusplus
132 }
133 #endif
134
135 #endif /* U_LINKLIST_H_ */
136