list.h File Reference

#include <mupnp/typedef.h>

Data Structures
struct	_mUpnpList
	The generic list interface in mUPnP. More...

Macros
#define	MUPNP_LIST_STRUCT_MEMBERS
#define	mupnp_list_gets(headList)

Typedefs
typedef void(*	MUPNP_LIST_DESTRUCTORFUNC) (void *)
typedef struct _mUpnpList	mUpnpList
	The generic list interface in mUPnP.

Functions
void	mupnp_list_header_init (mUpnpList *list)
	Initialize a list node as a list header (sentinel node)
void	mupnp_list_node_init (mUpnpList *list)
	Initialize a list node as a regular data node.
void	mupnp_list_insert (mUpnpList *prevList, mUpnpList *list)
	Insert a node or list segment after a given node.
void	mupnp_list_add (mUpnpList *headList, mUpnpList *list)
	Add a node to the end of a list.
void	mupnp_list_remove (mUpnpList *list)
	Remove a node from its list.
int	mupnp_list_size (mUpnpList *headList)
mUpnpList *	mupnp_list_get (mUpnpList *headList, int index)
mUpnpList *	mupnp_list_prev_circular (mUpnpList *list)
mUpnpList *	mupnp_list_prev (mUpnpList *list)
mUpnpList *	mupnp_list_next_circular (mUpnpList *list)
mUpnpList *	mupnp_list_next (mUpnpList *list)
void	mupnp_list_clear (mUpnpList *headList, MUPNP_LIST_DESTRUCTORFUNC destructorFunc)

Macro Definition Documentation

mupnp_list_gets

#define mupnp_list_gets

(

headList

)

Value:

mupnp_list_next(headList)

Get the first actual item from a list for iteration

Parameters

headList

List header

MUPNP_LIST_STRUCT_MEMBERS

#define MUPNP_LIST_STRUCT_MEMBERS

Value:

     \
  bool headFlag;                           \
     \
  struct _mUpnpList* prev;                 \
 \
  struct _mUpnpList* next;

Macro for list node members

Typedef Documentation

MUPNP_LIST_DESTRUCTORFUNC

typedef void(* MUPNP_LIST_DESTRUCTORFUNC) (void *)

Prototype for individual list node destructor functions

mUpnpList

typedef struct _mUpnpList mUpnpList

The generic list interface in mUPnP.

Each struct in mUPnP, that is designed to be a part of a list, must have these elements in their definition before the actual struct definition. The struct pointers are then cast to mUpnpList* and operated with mupnp_list_* functions.

Function Documentation

mupnp_list_add()

void mupnp_list_add	(	mUpnpList *	headList,
		mUpnpList *	list )

Add a node to the end of a list.

Appends a node to the end of a list (just before the header node). This is a convenience function for adding elements to the tail of a list.

Parameters

headList	The list header node. Must not be NULL and must be initialized with mupnp_list_header_init().
list	The node to add. Must not be NULL and should be initialized with mupnp_list_node_init().

Note

Thread-safe: This function is NOT thread-safe. The caller must ensure exclusive access to the list when modifying structure.

Side effect: Updates prev/next pointers of the last node and header.

Todo

Review implementation for potential edge cases with empty lists.

See also

mupnp_list_insert()

mupnp_list_remove()

mupnp_list_clear()

void mupnp_list_clear	(	mUpnpList *	headList,
		MUPNP_LIST_DESTRUCTORFUNC	destructorFunc )

Clear the list and delete all of its contents with MUPNP_LIST_DESTRUCTORFUNC

Parameters

headList	List header
destructorFunc	Function pointer that clears the contents of individual nodes

mupnp_list_get()

mUpnpList * mupnp_list_get	(	mUpnpList *	headList,
		int	index )

Get an item from the list by the item's index

Parameters

headList	List header
index	The index of the item to get

mupnp_list_header_init()

void mupnp_list_header_init

(

mUpnpList *

list

)

Initialize a list node as a list header (sentinel node)

Initializes a node to act as a circular doubly-linked list header. The header is a sentinel node that marks the beginning and end of the list. It simplifies list operations by eliminating special cases for empty lists.

After initialization:

• prev and next point to the node itself (empty circular list)
• headFlag is set to true

Parameters

list	The node to initialize as a header. Must not be NULL.

Note

Thread-safe: Can be called from any thread, but typically called during list creation before the list is shared between threads.

The header node itself does not contain data; it only manages links.

See also

mupnp_list_node_init()

mupnp_list_add()

mupnp_list_insert()

void mupnp_list_insert	(	mUpnpList *	prevList,
		mUpnpList *	list )

Insert a node or list segment after a given node.

Inserts a single node or an entire list segment immediately after the specified node in the list. This maintains the circular doubly-linked structure and properly updates all prev/next pointers.

If inserting multiple nodes, they should already be linked together (forming a chain).

Parameters

prevList	The node after which to insert. Must not be NULL and should be part of a properly initialized list.
list	The node or list segment to insert. Must not be NULL.

Note

Thread-safe: This function is NOT thread-safe. The caller must ensure exclusive access to the list (e.g., via mutex) when modifying list structure.

Side effect: Updates prev/next pointers of adjacent nodes.

See also

mupnp_list_add()

mupnp_list_remove()

mupnp_list_next()

mUpnpList * mupnp_list_next

(

mUpnpList *

list

)

Get the next node. Returns NULL if end has been reached.

Parameters

list	Current node

mupnp_list_next_circular()

mUpnpList * mupnp_list_next_circular

(

mUpnpList *

list

)

Get the next node. Wrap around if the end has been reached.

Parameters

list	Current node

mupnp_list_node_init()

void mupnp_list_node_init

(

mUpnpList *

list

)

Initialize a list node as a regular data node.

Initializes a node to act as a regular list member (not a header). The node is initially not linked to any list.

After initialization:

• prev and next are set to NULL
• headFlag is set to false

Parameters

list	The node to initialize. Must not be NULL.

Note

Thread-safe: Can be called from any thread, but typically called before the node is added to a shared list.

The node must be properly populated with data before adding to a list.

See also

mupnp_list_header_init()

mupnp_list_insert()

mupnp_list_add()

mupnp_list_prev()

mUpnpList * mupnp_list_prev

(

mUpnpList *

list

)

Get the previous node. Returns NULL if beginning has been reached

Parameters

list	Current node

mupnp_list_prev_circular()

mUpnpList * mupnp_list_prev_circular

(

mUpnpList *

list

)

Get the previous node. Wrap around if the beginning has been reached.

Parameters

list	Current node

mupnp_list_remove()

void mupnp_list_remove

(

mUpnpList *

list

)

Remove a node from its list.

Removes a node from the list it belongs to by updating the prev/next pointers of adjacent nodes. This does NOT free any memory; it only unlinks the node from the list structure.

After removal, the node's prev and next pointers point to itself, making it safe to check if a node is in a list.

Parameters

list	The node to remove. Must not be NULL and should be part of a list (not a standalone node).

Note

Thread-safe: This function is NOT thread-safe. The caller must ensure exclusive access to the list when modifying structure.

Memory management: The caller is responsible for freeing the node's memory if needed after removal.

Side effect: Updates prev/next pointers of adjacent nodes.

Safe to call on an already removed node (has no effect).

See also

mupnp_list_add()

mupnp_list_clear()

mupnp_list_size()

int mupnp_list_size

(

mUpnpList *

headList

)

Get the number of nodes in the current list structure. Counts forwards from the given node, so if you want to get the complete size, give a header node as the parameter.

Parameters

headList

List header