list.c File Reference

#include <mupnp/util/list.h>
#include <mupnp/util/log.h>

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.
int	mupnp_list_size (mUpnpList *headList)
mUpnpList *	mupnp_list_get (mUpnpList *headList, int index)
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.
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)

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