RtlLookupFirstMatchingElementGenericTableAvl - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTRTL_H

_Check_return_
NTSYSAPI
PVOID
NTAPI
RtlLookupFirstMatchingElementGenericTableAvl(
    _In_ PRTL_AVL_TABLE Table,
    _In_ PVOID Buffer,
    _Out_ PVOID *RestartKey
    );

#endif

View code on GitHub
// ntddk.h

NTSYSAPI PVOID RtlLookupFirstMatchingElementGenericTableAvl(
  [in]  PRTL_AVL_TABLE Table,
  [in]  PVOID          Buffer,
  [out] PVOID          *RestartKey
);
View the official Windows Driver Kit DDI reference

NtDoc

This function is documented in Windows Driver Kit.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntddk-rtllookupfirstmatchingelementgenerictableavl)

RtlLookupFirstMatchingElementGenericTableAvl function

Description

The RtlLookupFirstMatchingElementGenericTableAvl routine finds the left-most element in the tree that matches the indicated data.

Parameters

Table [in]

A pointer to the generic Adelson-Velsky/Landis (AVL) table (RTL_AVL_TABLE).

Buffer [in]

A buffer that contains the search data.

RestartKey [out]

On output, contains a search context to use with an enumeration routine, such as RtlEnumerateGenericTableWithoutSplayingAvl.

Return value

The RtlLookupFirstMatchingElementGenericTableAvlroutine returns a pointer to the matched data, or NULL if no match was found.

Remarks

A tree that implements a generic table might contain several file names that differ only in case. A search algorithm can use this routine to locate the first match, without reference to case, and use an enumeration routine, such as RtlEnumerateGenericTableWithoutSplayingAvl, to return each subsequent match.

By default, the operating system uses splay trees to implement generic tables, but the RtlLookupFirstMatchingElementGenericTableAvlroutine only works with Adelson-Velsky/Landis (AVL) trees. Under some circumstances, operations on a splay tree will make the tree deep and narrow and might even turn it into a straight line. Very deep trees degrade the performance of searches. You can ensure a more balanced, shallower tree implementation of generic tables by using Adelson-Velsky/Landis (AVL) trees. If you want to configure the generic table routines to use AVL trees instead of splay trees in your driver, insert the following define statement in a common header file before including Ntddk.h:

#define RTL_USE_AVL_TABLES 0

If RTL_USE_AVL_TABLES is not defined, you must use the AVL form of the generic table routines.

Callers of RtlLookupFirstMatchingElementGenericTableAvl must be running at <= APC_LEVEL if either of the following conditions holds:

See also

RtlEnumerateGenericTableWithoutSplayingAvl

View the official Windows Driver Kit DDI reference

Edit description on GitHub