Router/alList.h

   1 /**
   2  * OpenAL cross platform audio library
   3  * Copyright (C) 1999-2003 by authors.
   4  * This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU Library General Public
   6  *  License as published by the Free Software Foundation; either
   7  *  version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  *  Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  *  License along with this library; if not, write to the
  16  *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  *  Boston, MA  02111-1307, USA.
  18  * Or go to http://www.gnu.org/copyleft/lgpl.html
  19  */
  20
  21
  22
  23
  24 #ifndef _AL_LIST_H_
  25 #define _AL_LIST_H_
  26
  27 #include <al/al.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #include <windows.h>
  34
  35
  36
  37 //*****************************************************************************
  38 //*****************************************************************************
  39 //
  40 // Defines
  41 //
  42 //*****************************************************************************
  43 //*****************************************************************************
  44
  45 //
  46 // Some useful things to track parameters.
  47 //
  48 #ifndef IN
  49 #define IN
  50 #endif
  51
  52 #ifndef OPTIONAL
  53 #define OPTIONAL
  54 #endif
  55
  56 #ifndef OUT
  57 #define OUT
  58 #endif
  59
  60 //
  61 // The list entry.  This should not be modified outside the list routines.
  62 //
  63 typedef struct ALlistEntry_Struct
  64 {
  65     //
  66     // The previous list entry.
  67     //
  68     struct ALlistEntry_Struct* Previous;
  69
  70     //
  71     // The next list entry.
  72     //
  73     struct ALlistEntry_Struct* Next;
  74
  75     //
  76     // The data for the current entry.
  77     //
  78     ALvoid* Data;
  79
  80 } ALlistEntry;
  81
  82
  83 //
  84 // This is the context to pass to all the list calls.  It must be initialized
  85 // before any list calls are made.
  86 //
  87 typedef struct //ALlist_Struct
  88 {
  89     //
  90     // This is the pointer to the first item in the list.
  91     //
  92     ALlistEntry* Head;
  93
  94     //
  95     // This is the pointer to the last item in the list.
  96     //
  97     ALlistEntry* Tail;
  98
  99     //
 100     // This is the list iterator.
 101     //
 102     ALlistEntry* Current;
 103
 104     //
 105     // This is the list lock to prevent simultaneous addition and removal
 106     // of entries.
 107     //
 108     CRITICAL_SECTION Lock;
 109
 110     //
 111     // This maintains a count of the number of entries in the list.
 112     //
 113     ALint NumberOfEntries;
 114
 115     //
 116     // This is set if the list is locked.  For debug use only.
 117     //
 118 #if(DBG)
 119     ALint Locked;
 120 #endif
 121
 122 } ALlist;
 123
 124
 125
 126 //*****************************************************************************
 127 //*****************************************************************************
 128 //
 129 // List Functions
 130 //
 131 //*****************************************************************************
 132 //*****************************************************************************
 133
 134 //*****************************************************************************
 135 // alListAddEntry
 136 //*****************************************************************************
 137 // Adds an entry to the tail of the list.  Each entry must be unique.
 138 //
 139 ALvoid alListAddEntry
 140 (
 141     IN  ALlist* pList,
 142     IN  ALlistEntry* pEntry
 143 );
 144
 145 //*****************************************************************************
 146 // alListAddEntryToHead
 147 //*****************************************************************************
 148 // Adds an entry to the head of the list.  Each entry must be unique.
 149 //
 150 ALvoid alListAddEntryToHead
 151 (
 152     IN  ALlist* pList,
 153     IN  ALlistEntry* pEntry
 154 );
 155
 156 //*****************************************************************************
 157 // alListAcquireLock
 158 //*****************************************************************************
 159 // This is called to acquire the list lock for operations that span multiple
 160 // list calls like iterating over the list.
 161 //
 162 ALvoid alListAcquireLock
 163 (
 164     IN  ALlist* pList
 165 );
 166
 167 //*****************************************************************************
 168 // alListCreate
 169 //*****************************************************************************
 170 // Creates and initializes a list.
 171 //
 172 ALboolean alListCreate
 173 (
 174     OUT ALlist** ppList
 175 );
 176
 177 //*****************************************************************************
 178 // alListFree
 179 //*****************************************************************************
 180 // Destroys the list.  Dynamically allocated entries are not freed.
 181 //
 182 ALvoid alListFree
 183 (
 184     IN  ALlist* pList
 185 );
 186
 187 //*****************************************************************************
 188 // alListGetData
 189 //*****************************************************************************
 190 // Returns the data from the list entry.
 191 //
 192 ALvoid* alListGetData
 193 (
 194     IN  ALlistEntry* pEntry
 195 );
 196
 197 //*****************************************************************************
 198 // alListGetEntryAt
 199 //*****************************************************************************
 200 // Returns the entry in the list at the specified index of the list.
 201 //
 202 ALlistEntry* alListGetEntryAt
 203 (
 204     IN  ALlist* pList,
 205     IN  ALint Index
 206 );
 207
 208 //*****************************************************************************
 209 // alListGetEntryCount
 210 //*****************************************************************************
 211 // Returns the number of items stored in the list.
 212 //
 213 ALint alListGetEntryCount
 214 (
 215     IN  ALlist* pList
 216 );
 217
 218 //*****************************************************************************
 219 // alListGetHead
 220 //*****************************************************************************
 221 // Returns the first entry in the list.
 222 //
 223 ALlistEntry* alListGetHead
 224 (
 225     IN  ALlist* pList
 226 );
 227
 228 //*****************************************************************************
 229 // alListGetNext
 230 //*****************************************************************************
 231 // Returns the entry after to the entry pointed to by the iterator.  If
 232 // the iterator is at the last entry (or has finished iterating over the
 233 // list), the returned entry will be 0.
 234 //
 235 ALlistEntry* alListGetNext
 236 (
 237     IN  ALlist* pList
 238 );
 239
 240 //*****************************************************************************
 241 // alListGetPrevious
 242 //*****************************************************************************
 243 // Returns the entry previous to the entry pointed to by the iterator.  If
 244 // the iterator is at the first entry, the returned entry will be 0.
 245 //
 246 ALlistEntry* alListGetPrevious
 247 (
 248     IN  ALlist* pList
 249 );
 250
 251 //*****************************************************************************
 252 // alListGetTail
 253 //*****************************************************************************
 254 // Returns the last entry in the list.
 255 //
 256 ALlistEntry* alListGetTail
 257 (
 258     IN  ALlist* pList
 259 );
 260
 261 //*****************************************************************************
 262 // alListInitializeEntry
 263 //*****************************************************************************
 264 // Initializes a preallocated list entry.
 265 //
 266 ALvoid alListInitializeEntry
 267 (
 268     IN  ALlistEntry* pListEntry,
 269     IN  ALvoid* pData
 270 );
 271
 272 //*****************************************************************************
 273 // alListIsEmpty
 274 //*****************************************************************************
 275 // Returns the TRUE if the list is empty.
 276 //
 277 ALboolean alListIsEmpty
 278 (
 279     IN  ALlist* pList
 280 );
 281
 282 //*****************************************************************************
 283 // alListIteratorGet
 284 //*****************************************************************************
 285 // Returns the entry pointed to by the iterator.
 286 //
 287 ALlistEntry* alListIteratorGet
 288 (
 289     IN  ALlist* pList
 290 );
 291
 292 //*****************************************************************************
 293 // alListIteratorFindData
 294 //*****************************************************************************
 295 // Searches the list for the matching item and return the pointer to the
 296 // entry.  If the match is not found, the return will be 0.
 297 //
 298 ALlistEntry* alListIteratorFindData
 299 (
 300     IN  ALlist* pList,
 301     IN  ALvoid* pData
 302 );
 303
 304 //*****************************************************************************
 305 // alListIteratorNext
 306 //*****************************************************************************
 307 // This is called to advance the list iterator to the next entry in the list
 308 // and return that entry.
 309 //
 310 ALlistEntry* alListIteratorNext
 311 (
 312     IN  ALlist* pList
 313 );
 314
 315 //*****************************************************************************
 316 // alListIteratorPrevious
 317 //*****************************************************************************
 318 // This is called to advance the list iterator to the previous entry in the
 319 // list and return that entry.
 320 //
 321 ALlistEntry* alListIteratorPrevious
 322 (
 323     IN  ALlist* pList
 324 );
 325
 326 //*****************************************************************************
 327 // alListIteratorReset
 328 //*****************************************************************************
 329 // Returns the list iterator to the head of the list and returns the head
 330 // entry.
 331 //
 332 ALlistEntry* alListIteratorReset
 333 (
 334     IN  ALlist* pList
 335 );
 336
 337 //*****************************************************************************
 338 // alListIteratorRemove
 339 //*****************************************************************************
 340 // Removes the current item from the list and returns it.  The iterator will
 341 // equal the next item in the list.
 342 //
 343 ALlistEntry* alListIteratorRemove
 344 (
 345     IN  ALlist* pList
 346 );
 347
 348 //*****************************************************************************
 349 // alListIteratorSet
 350 //*****************************************************************************
 351 // Sets the current entry pointer to the entry passed in.  If the entry is not
 352 // found, the current entry will be 0.
 353 //
 354 ALlistEntry* alListIteratorSet
 355 (
 356     IN  ALlist* pList,
 357     IN  ALlistEntry* pEntry
 358 );
 359
 360 //*****************************************************************************
 361 // alListMatchEntry
 362 //*****************************************************************************
 363 // Matches the entry to an item in the list and returns the data in that
 364 // entry.  If the match is not found, the return will be 0.
 365 //
 366 ALvoid* alListMatchEntry
 367 (
 368     IN  ALlist* pList,
 369     IN  ALlistEntry* pEntry
 370 );
 371
 372 //*****************************************************************************
 373 // alListMatchData
 374 //*****************************************************************************
 375 // Searches the list for the matching item and return the pointer to the
 376 // entry.  If the match is not found, the return will be 0.
 377 //
 378 ALlistEntry* alListMatchData
 379 (
 380     IN  ALlist* pList,
 381     IN  ALvoid* pData
 382 );
 383
 384 //*****************************************************************************
 385 // alListReleaseLock
 386 //*****************************************************************************
 387 // This is called to release the list lock.
 388 //
 389 ALvoid alListReleaseLock
 390 (
 391     IN  ALlist* pList
 392 );
 393
 394 //*****************************************************************************
 395 // alListRemoveEntry
 396 //*****************************************************************************
 397 // Removes the item from the list and returns the data from the item.  If
 398 // this is the current item, the current item will equal the next item in the
 399 // list.
 400 //
 401 ALvoid* alListRemoveEntry
 402 (
 403     IN  ALlist* pList,
 404     IN  ALlistEntry* pEntry
 405 );
 406
 407 //*****************************************************************************
 408 // alListRemoveHead
 409 //*****************************************************************************
 410 // Removes the list entry at the head of the list.  If this is the current
 411 // item, the current item will equal the next item in the list.
 412 //
 413 ALlistEntry* alListRemoveHead
 414 (
 415     IN  ALlist* pList
 416 );
 417
 418 //*****************************************************************************
 419 // alListRemoveTail
 420 //*****************************************************************************
 421 // Removes the list entry at the tail of the list.  If this is the current
 422 // item, the current item will be null.
 423 //
 424 ALlistEntry* alListRemoveTail
 425 (
 426     IN  ALlist* pList
 427 );
 428
 429 #ifdef __cplusplus
 430 }
 431 #endif
 432
 433 #endif