/***************************************************************************
 *     Copyright (c) 2002, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile:$
 * $brcm_Revision:$
 * $brcm_Date:$
 *
 * Module Description: C Based List Header File
 *
 * Revision History:
 *
 * Created: 2002 by Marcus Kellerman
 *
 * $brcm_Log:$
 *
 * Here's a code sample of how to use genericlist.h:
 *
 *   #include "genericlist.h"
 *
 *   typedef struct {
 *     // your structure must have a LINKS_T as the first member.
 *     LINKS_T links;
 *     int x, y, z;
 *   } MyNode;
 *
 *   int main() {
 *     LIST_T list;
 *     MyNode *n;
 *
 *     initl(&list);
 *     inslt(&list, createNode());
 *     inslt(&list, createNode());
 *     inslt(&list, createNode());
 *     // pass the list to LHEAD, pass the current node to LNEXT.
 *     for (n = (MyNode*)LHEAD(&list); n; n = (MyNode*)LNEXT(n)) {
 *       doSomething(n);
 *     }
 *     for (n = (MyNode*)remlh(&list); n; n = (MyNode*)remlh(&list)) {
 *       deleteNode(n);
 *     }
 *   }
 *
 ***************************************************************************/
#ifndef LIST_H
#define LIST_H

#ifdef __cplusplus
extern "C" {
#endif

/* The data structure which describes the links. */
typedef struct links_struct
{
    struct links_struct    *p_next;
    struct links_struct    *p_prev;
    struct links_struct    *p_origin;
} LINKS_T;

/* The data structure which describes the list. */
typedef struct list_struct
{
    LINKS_T origin_links;
    unsigned short   count;	/* number of elements in the list */
} LIST_T;

/* Prototypes */
void *remlh(LIST_T *);
void inslt(LIST_T *, void *);
void inslh(LIST_T *, void *);
void inslb(LIST_T *p_list, void *p_element, void *p_newElement);
void reml(LIST_T *, void *);
void initl(LIST_T *);

/* Check to see if the list pointed to by (list) is empty. */
#define LEMPTY(list)   ((list)==0?1:(((LIST_T *)list)->count == 0 ? 1 : 0))

/* Return the head of a list pointed to by (list).  If the list is empty,
** LIST_HEAD returns zero.  In actuality, an empty list has it's p_next and
** p_prev pointers pointing to the list (which is (list)) for code simplistic
** reasons.  In this case, just check for (list) equal to p_next to determine
** if the list is empty. */
#define LHEAD(list)    ((list)==0?0:(((void *)(list) == ((LIST_T *)list)->origin_links.p_next) ? 0 : ((LIST_T *)list)->origin_links.p_next))

/* Return the tail of a list pointed to by (list).  If the tail is empty,
** LIST_TAIL returns zero.  In actuality, an empty list has it's p_next and
** p_prev pointers pointing to the list (which is (list)) for code simplistic
** reasons.  In this case, just check for (list) equal to p_next to determine
** if the list is empty. */
#define LTAIL(list)    ((list)==0?0:(((void *)(list) == ((LIST_T *)list)->origin_links.p_prev) ? 0 : ((LIST_T *)list)->origin_links.p_prev))

/* Return the number of elements in the list pointed to by (a). */
#define LSIZE(list)    ((list)==0?0:((LIST_T *)list)->count)

/* Return a pointer to next element of element a. If a is the tail of the list,
** LNEXT returns zero.*/
#define LNEXT(link)    ((link)==0?0:((((LINKS_T *)link)->p_next == ((LINKS_T *)link)->p_origin) ? 0 : ((LINKS_T *)link)->p_next))

/* Return a pointer to prev element of element a. If a is the head of the list,
** LPREV returns zero.*/
#define LPREV(link)    ((link)==0?0:((((LINKS_T *)link)->p_prev == ((LINKS_T *)link)->p_origin) ? 0 : ((LINKS_T *)link)->p_prev))

#ifdef __cplusplus
}
#endif

#endif /* LIST_H */