source: trunk/include/range_list.h @ 155

Last change on this file since 155 was 148, checked in by tim, 16 years ago

integrated talloc into range_list

fixed some uninitialized structure values in the winsec library

  • Property svn:keywords set to Id
File size: 5.4 KB
Line 
1/*
2 * Copyright (C) 2008-2009 Timothy D. Morgan
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; version 3 of the License.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
16 *
17 * $Id: range_list.h 148 2009-02-22 23:22:59Z tim $
18 */
19
20#ifndef _RANGE_LIST_H
21#define _RANGE_LIST_H
22
23#include <stdlib.h>
24#include <stdbool.h>
25#include <stdint.h>
26#include <string.h>
27#include <math.h>
28#include "talloc.h"
29
30typedef struct _range_list_element
31{
32  uint32_t offset;
33  uint32_t length;
34  void* data;
35} range_list_element;
36
37
38typedef struct _range_list
39{
40  range_list_element** elements;
41  uint32_t elem_alloced;
42  uint32_t size;
43} range_list;
44
45
46/* range_list_new():
47 *  Allocates a new range_list.
48 *
49 * Returns:
50 *  A newly allocated range_list, or NULL if an error occurred.
51 */
52range_list* range_list_new();
53
54
55/* range_list_free():
56 *  Frees the memory associated with a range_list, including the elements, but
57 *  not any data parameters referenced by those elements.  If rl is NULL, does
58 *  nothing.
59 *
60 * Arguments:
61 *  rl -- the range_list to be free()d.
62 */
63void range_list_free(range_list* rl);
64
65
66/* range_list_size():
67 *  Query the current number of elements on a range_list
68 *
69 * Arguments:
70 *  rl -- the range_list to query
71 *
72 * Returns:
73 *  The number of elements currently in the list.
74 */
75uint32_t range_list_size(const range_list* rl);
76
77
78/* range_list_add():
79 *  Adds an element to the range_list. 
80 *  The new element must not overlap with others.
81 *  NOTE: this is a slow operation.
82 *
83 * Arguments:
84 *  rl     -- the range list to update
85 *  offset -- the starting point for the range
86 *  length -- the length of the range
87 *  data   -- misc data associated with this range element
88 * Returns:
89 *  true on success, false on failure.
90 *  Failures can occur due to memory limitations, max_size limitations,
91 *  or if the submitted range overlaps with an existing element.  Other
92 *  errors may also be possible.
93 */
94bool range_list_add(range_list* rl, uint32_t offset, uint32_t length, void* data);
95
96
97/* range_list_remove():
98 *  Removes an element from the list.  The element data structure will be
99 *  freed, but the data property will not be.
100 *
101 * Arguments:
102 *  rl     -- the range_list to modify
103 *  index  -- the element index to remove
104 *
105 * Returns:
106 *  true if the element was successfully removed, false otherwise.
107 */
108bool range_list_remove(range_list* rl, uint32_t index);
109
110
111/* range_list_get():
112 *  Retrieves the element for a given index.
113 *
114 * Arguments:
115 *  rl    -- the range_list being queried.
116 *  index -- the element index desired.
117 *
118 * Returns:
119 *  The element for a given index, or NULL if the element is not available.
120 */
121const range_list_element* range_list_get(const range_list* rl, uint32_t index);
122
123
124/* range_list_find():
125 *  Attempts to find the unique element whose range encompasses offset.
126 *
127 * Arguments:
128 *  rl     -- the range_list being queried.
129 *  offset -- the location for which an element is desired.
130 *
131 * Returns:
132 *  A matching element index or a negative value if none could be found.
133 */
134int32_t range_list_find(const range_list* rl, uint32_t offset);
135
136
137/* range_list_find_data():
138 *  Same as range_list_find(), but returns the data associated with an element.
139 *
140 * Arguments:
141 *  rl     -- the range_list being queried.
142 *  offset -- the address to search for in the ranges
143 *
144 * Returns:
145 *  The data element of the matching element index or NULL if none could
146 *  be found.
147 *
148 *  NOTE: May also return NULL if an element matched but if the data
149 *        element was never set.
150 */
151void* range_list_find_data(const range_list* rl, uint32_t offset);
152
153
154/* range_list_split_element():
155 *  Splits an existing element into two elements in place.
156 *
157 *  The resulting list will contain an additional element whose offset
158 *  is the one provided and whose length extends to the end of the old element
159 *  (the one identified by the index).  The original element's offset will
160 *  remain the same while it's length is shortened such that it is contiguous
161 *  with the newly created element.  The newly created element will have an index
162 *  of one more than the current element.
163 *
164 *  Both the original element and the newly created element will reference the
165 *  original element's data.
166 *
167 * Arguments:
168 *  rl     -- the range_list to modify
169 *  index  -- the index of the element to be split
170 *  offset -- the at which the element will be split
171 *
172 * Returns:
173 *  true if the element was successfully split, false otherwise.
174 *   
175 *
176 */
177bool range_list_split_element(range_list* rl, uint32_t index, uint32_t offset);
178
179
180/* range_list_has_range():
181 *  Determines whether or not a specified range exists contiguously within the
182 *  range_list.
183 *
184 * Arguments:
185 *  rl     -- the range_list to search
186 *  start  -- the offset at the beginning of the range
187 *  length -- the length of the range
188 *
189 * Returns:
190 *  true if the specified range exists and is complete, false otherwise.
191 */
192bool range_list_has_range(range_list* rl, uint32_t start, uint32_t length);
193
194#endif
Note: See TracBrowser for help on using the repository browser.