Module Description

Double- and Single-linked lists.
#include <uLib/ListFunc.h> or <uLib/ListEx.h>

For C there are function equivalents of the NTDDK macros, and a few addendums.
For C++ the main feature is DLinkList, a thoroughly enhanced double linked list class.
There is also a single linked list class, SLinkList, which is a simple class wrap around
function equivalents of the ntddk macros, with a couple of easy iteration methods added.

Note: ListFunc.h, ListFunc.c and ListCls.cpp maintain a level of independency
from the rest of uLib, and can be compiled separately if needed.
This makes it easy to incorporate the powerful DLinkList in kernel mode,
or on other platforms, anywhere C++ is permitted.

Classes
struct	LIST_ENTRY

struct	SINGLE_LIST_ENTRY

class	DLinkList

class	SLinkList

Macros
#define	InitializeListEntry(E) (E)->Flink = (E)->Blink = (E)

#define	_InitializeListEntry(E) _InitializeListHead( (PLIST_ENTRY)(E) )

#define	UnlinkListEntry(E) InitializeListEntry( E )

Typedefs
typedef struct _LIST_ENTRY *	PLIST_ENTRY

typedef struct _SINGLE_LIST_ENTRY *	PSINGLE_LIST_ENTRY

typedef class DLinkList *	PDLinkList

typedef bool(__stdcall *	PDListFunc) (PLIST_ENTRY Entry, void *UserData)

typedef int(__stdcall *	PDListComp) (PLIST_ENTRY X, PLIST_ENTRY Y, void *UserData)

typedef class SLinkList *	PSLinkList

typedef bool(__stdcall *	PSListFunc) (PSINGLE_LIST_ENTRY Entry, void *UserData)

Functions
void	_InitializeListHead (PLIST_ENTRY ListHead)

bool	_IsListEmpty (PLIST_ENTRY ListHead)

void	_InsertTailList (PLIST_ENTRY ListHead, PLIST_ENTRY Entry)

void	_InsertHeadList (PLIST_ENTRY ListHead, PLIST_ENTRY Entry)

void	_RemoveEntryList (PLIST_ENTRY Entry)

PLIST_ENTRY	_RemoveHeadList (PLIST_ENTRY ListHead)

PLIST_ENTRY	_RemoveTailList (PLIST_ENTRY ListHead)

UINT	GetListEntryCount (PLIST_ENTRY ListHead)

bool	ListForEach (PLIST_ENTRY ListHead, bool(__stdcall Action)(PLIST_ENTRY Entry, void UserData), void *UserData)

void	AttachHeadlessList (OUT PLIST_ENTRY Head, IN PLIST_ENTRY Circular)

void	_InitializeEntryList (PSINGLE_LIST_ENTRY EntryOrHead)

void	_PushEntryList (PSINGLE_LIST_ENTRY ListHead, PSINGLE_LIST_ENTRY Entry)

PSINGLE_LIST_ENTRY	_PopEntryList (PSINGLE_LIST_ENTRY ListHead)

Macro Definition Documentation

◆ InitializeListEntry

#define InitializeListEntry ( E ) (E)->Flink = (E)->Blink = (E)

Initialize a LIST_ENTRY with "self-pointers".
_InitializeListHead() does the same thing, but the intuitive understanding
of that Id in such a context would be confusing, so use this macro instead.

Definition at line 88 of file ListFunc.h.

◆ _InitializeListEntry

#define _InitializeListEntry ( E ) _InitializeListHead( (PLIST_ENTRY)(E) )

Definition at line 89 of file ListFunc.h.

◆ UnlinkListEntry

#define UnlinkListEntry ( E ) InitializeListEntry( E )

Used by DLinkList to "self-link" an entry when removed, to prevent cross-links.
Also used by the C APIs _RemoveEntryList, _RemoveHeadList, and _RemoveTailList .
Redefine as an empty macro to not unlink them (not recommended).

Definition at line 95 of file ListFunc.h.

Typedef Documentation

◆ PLIST_ENTRY

typedef struct _LIST_ENTRY * PLIST_ENTRY

◆ PSINGLE_LIST_ENTRY

typedef struct _SINGLE_LIST_ENTRY * PSINGLE_LIST_ENTRY

◆ PDLinkList

typedef class DLinkList* PDLinkList

Pointer to a DLinkList.

Definition at line 143 of file ListFunc.h.

◆ PDListFunc

typedef bool(__stdcall * PDListFunc) (PLIST_ENTRY Entry, void *UserData)

PDListFunc is the callback for DLinkList::FirstThat(), DLinkList::LastThat(), and DLinkList::ForEach().

Parameters

Entry	Pointer to whatever LIST_ENTRY descendant your list contains. Cast as needed.
UserData	Whatever you passed in to the originating method call.

Returns: With ForEach, PDListFunc should return true to contine, or false to discontinue.
With [First/Last]That, it should return true for a match, or false for a non-match.

Definition at line 152 of file ListFunc.h.

◆ PDListComp

typedef int(__stdcall * PDListComp) (PLIST_ENTRY X, PLIST_ENTRY Y, void *UserData)

PDListComp is the comparator callback for DLinkList::QuickSort().

Parameters

X,Y	Pointers to whatever LIST_ENTRY descendant your list contains. Cast as needed.
UserData	Whatever you passed in to the QuickSort call.

Returns: PDListComp should return a normal C tristate comparison value -x..0..+x

Definition at line 159 of file ListFunc.h.

◆ PSLinkList

typedef class SLinkList* PSLinkList

Pointer to SLinkList.

Definition at line 367 of file ListFunc.h.

◆ PSListFunc

typedef bool(__stdcall * PSListFunc) (PSINGLE_LIST_ENTRY Entry, void *UserData)

Callback function for SLinkList::RemoveAll, SLinkList::FirstThat, SLinkList::ForEach.

Definition at line 369 of file ListFunc.h.

Function Documentation

◆ _InitializeListHead()

void _InitializeListHead ( PLIST_ENTRY ListHead )

See [MSDN] InitializeListHead.

Definition at line 17 of file ListFunc.c.

◆ _IsListEmpty()

bool _IsListEmpty ( PLIST_ENTRY ListHead )

See [MSDN] IsListEmpty.

Definition at line 22 of file ListFunc.c.

◆ _InsertTailList()

void _InsertTailList	(	PLIST_ENTRY	ListHead,
		PLIST_ENTRY	Entry
	)

See [MSDN] InsertTailList.

Definition at line 62 of file ListFunc.c.

◆ _InsertHeadList()

void _InsertHeadList	(	PLIST_ENTRY	ListHead,
		PLIST_ENTRY	Entry
	)

See [MSDN] InsertHeadList.

Definition at line 71 of file ListFunc.c.

◆ _RemoveEntryList()

void _RemoveEntryList ( PLIST_ENTRY Entry )

See [MSDN] RemoveEntryList.

Definition at line 47 of file ListFunc.c.

◆ _RemoveHeadList()

PLIST_ENTRY _RemoveHeadList ( PLIST_ENTRY ListHead )

See [MSDN] RemoveHeadList.

Definition at line 37 of file ListFunc.c.

◆ _RemoveTailList()

PLIST_ENTRY _RemoveTailList ( PLIST_ENTRY ListHead )

See [MSDN] RemoveTailList.

Definition at line 27 of file ListFunc.c.

◆ GetListEntryCount()

UINT GetListEntryCount ( PLIST_ENTRY ListHead )

Self explanatory...

Definition at line 82 of file ListFunc.c.

◆ ListForEach()

bool ListForEach	(	PLIST_ENTRY	ListHead,
		bool(__stdcall Action)(PLIST_ENTRY Entry, void UserData)	,
		void *	UserData
	)

ListForEach facilitates solid iterative processing of DDK lists.
It uses the same Action callback signature as DLinkList iterators.

Parameters

ListHead	Head of the list who's items you want to process.
Action	Callback function to process each entry. See PDListFunc.
UserData	Arbitrary. Anything your Action might need.

Returns: Returns false if your Action aborted by returning false, else true.

Definition at line 92 of file ListFunc.c.

◆ AttachHeadlessList()

void AttachHeadlessList	(	OUT PLIST_ENTRY	Head,
		IN PLIST_ENTRY	Circular
	)

AttachHeadlessList attaches a circular list to Head without changing the Circular list.
(Useful for items like e.g. PEB_LDR_DATA::InLoadOrderModuleList.)
Note: Head is overwritten.

Definition at line 108 of file ListFunc.c.

◆ _InitializeEntryList()

void _InitializeEntryList ( PSINGLE_LIST_ENTRY EntryOrHead )

Initalize a single-linked listhead or list entry.

Definition at line 143 of file ListFunc.c.

◆ _PushEntryList()

void _PushEntryList	(	PSINGLE_LIST_ENTRY	ListHead,
		PSINGLE_LIST_ENTRY	Entry
	)

See [MSDN] PushEntryList.

Definition at line 151 of file ListFunc.c.

◆ _PopEntryList()

PSINGLE_LIST_ENTRY _PopEntryList ( PSINGLE_LIST_ENTRY ListHead )

See [MSDN] PopEntryList.

Definition at line 156 of file ListFunc.c.

Module Description

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ InitializeListEntry

◆ _InitializeListEntry

◆ UnlinkListEntry

Typedef Documentation

◆ PLIST_ENTRY

◆ PSINGLE_LIST_ENTRY

◆ PDLinkList

◆ PDListFunc

◆ PDListComp

◆ PSLinkList

◆ PSListFunc

Function Documentation

◆ _InitializeListHead()

◆ _IsListEmpty()

◆ _InsertTailList()

◆ _InsertHeadList()

◆ _RemoveEntryList()

◆ _RemoveHeadList()

◆ _RemoveTailList()

◆ GetListEntryCount()

◆ ListForEach()

◆ AttachHeadlessList()

◆ _InitializeEntryList()

◆ _PushEntryList()

◆ _PopEntryList()