File/Directory Hierarchial Lists

Module Description

Fast and flexible list-of-lists directory trees.
#include <uLib/FileDir.h>

Although DirEntry and FileEntry started off as a fairly simple
directory hierarchy, they have now evolved into a very flexible, fast,
and easy to use hierarchial list-of-lists directory structure
that supports per-thread current directory for concurrent scans.
The primary API is the static DirEntry::ScanDir().

Classes
class	FileEntry
struct	ScanDirCtx
class	DirEntry

Macros
#define	SCF_FILES   0x0001
#define	SCF_DIRS   0x0002
#define	MAX_DIRECTORY_DEPTH   256

Typedefs
typedef FileEntry *	PFileEntry
typedef DirEntry *	PDirEntry
typedef ScanDirCtx *	PScanDirCtx
typedef bool(__stdcall *	PFnDirAddAction) (PDirEntry pDir, LPWIN32_FIND_DATA pFD, PScanDirCtx pCtx)
typedef bool(__stdcall *	PFnFileAddAction) (PFileEntry pFile, LPWIN32_FIND_DATA pFD, PScanDirCtx pCtx)
typedef bool(__stdcall *	PFnDirAction) (PDirEntry pDir, PScanDirCtx pCtx)
typedef bool(__stdcall *	PFnFileAction) (PFileEntry pFile, PScanDirCtx pCtx)
typedef bool(__stdcall *	PFnAbortScan) (PDirEntry pDir, PScanDirCtx pCtx)

Functions
CSTR	LongestCommonPath (CSTR PathName1, CSTR PathName2)
PFileEntry __stdcall	NewFileEntry (LPWIN32_FIND_DATA pfd, PDirEntry pDir, PScanDirCtx pCtx)
PDirEntry __stdcall	NewDirEntry (LPWIN32_FIND_DATA pfd, PDirEntry pDir, PScanDirCtx pCtx)
PFileEntry __stdcall	__new_FileEntry (LPWIN32_FIND_DATA pfd, PDirEntry pDir, PScanDirCtx pCtx)
PDirEntry __stdcall	__new_DirEntry (LPWIN32_FIND_DATA pfd, PDirEntry pDir, PScanDirCtx pCtx)

Variables
ScanDirCtx	_defScanCtx

Macro Definition Documentation

SCF_FILES

#define SCF_FILES   0x0001

Scan flag.. Add files.

Definition at line 253 of file FileDir.h.

SCF_DIRS

#define SCF_DIRS   0x0002

Scan flag.. Add directories.

Definition at line 254 of file FileDir.h.

MAX_DIRECTORY_DEPTH

#define MAX_DIRECTORY_DEPTH   256

No sane directory hierarchy should get this deep.

Definition at line 259 of file FileDir.h.

Typedef Documentation

PFileEntry

typedef FileEntry* PFileEntry

Pointer to a file entry.

Definition at line 42 of file FileDir.h.

PDirEntry

typedef DirEntry* PDirEntry

Pointer to a directory entry.

Definition at line 45 of file FileDir.h.

PScanDirCtx

typedef ScanDirCtx* PScanDirCtx

Pointer to a ScanDir context.

Definition at line 46 of file FileDir.h.

PFnDirAddAction

typedef bool(__stdcall * PFnDirAddAction) (PDirEntry pDir, LPWIN32_FIND_DATA pFD, PScanDirCtx pCtx)

PFnDirAddAction and PFnFileAddAction are callbacks optionally invoked
by DirEntry::Scan() after entry addition. F.ex, you might need to determine the
link count on a file (which takes time and therefore is not included in the base
implementation).

Parameters

pItem	Pointer to the newly allocated entry (PDirEntry or PFileEntry).
pFD	Pointer to the WIN32_FIND_DATA for the entry.

Definition at line 55 of file FileDir.h.

PFnFileAddAction

typedef bool(__stdcall * PFnFileAddAction) (PFileEntry pFile, LPWIN32_FIND_DATA pFD, PScanDirCtx pCtx)

See PFnDirAddAction

Definition at line 56 of file FileDir.h.

PFnDirAction

typedef bool(__stdcall * PFnDirAction) (PDirEntry pDir, PScanDirCtx pCtx)

PFnDirAction and PFnFileAction are generic entry callbacks.
See FileEntry::DelAction and DirEntry::DelAction, which are optionally invoked
on entry destruction. Use them f.ex to dispose of custom pData for your entries.

Parameters

pDir,pFile

Pointer to the item entry.

Definition at line 64 of file FileDir.h.

PFnFileAction

typedef bool(__stdcall * PFnFileAction) (PFileEntry pFile, PScanDirCtx pCtx)

See PFnDirAction

Definition at line 65 of file FileDir.h.

PFnAbortScan

typedef bool(__stdcall * PFnAbortScan) (PDirEntry pDir, PScanDirCtx pCtx)

Optional callback to abort a scan in progress.
Return false to continue.

Definition at line 70 of file FileDir.h.

Function Documentation

LongestCommonPath()

CSTR LongestCommonPath	(	CSTR	PathName1,
		CSTR	PathName2
	)

(Oops... Forgot about PathCommonPrefix()).
LongestCommonPath() returns the longest common part of two path names.

An internal static MAX_PATH buffer is used to return the result.
On error a blank string is returned, and GetLastError() returns a reason.
If the paths have nothing in common, the error is ERROR_NOT_FOUND, and
if the resulting path exceeds MAX_PATH, the error is ERROR_BUFFER_OVERFLOW.

Definition at line 756 of file FileDir.cpp.

NewFileEntry()

PFileEntry __stdcall NewFileEntry	(	LPWIN32_FIND_DATA	pfd,
		PDirEntry	pDir,
		PScanDirCtx	pCtx
	)

NewFileEntry and NewDirEntry are pointers to functions that
DirEntry::Scan() calls to allocate new FileEntry and DirEntry instances.
This enables a degree of polymorphism to be used, e.g. extended entry types.
If needed, write decendants of FileEntry/DirEntry, and then write functions
that return pointers to new instances of your descendants.

Note: For simple entry extension, you may use the pData member
and AddAction/DelAction functions instead of descendant classes.

NewFileEntry and NewDirEntry can also be used as entry filters, by
writing custom functions which return NULL for entries that should not
be added to the directory tree. This causes Scan() to reject them.

Parameters

pfd	Pointer to the WIN32_FIND_DATA for the item.
pDir	Pointer to the DirEntry currently being scanned.

Returns

Return a pointer to a FileEntry/DirEntry (or descendant), or NULL.

Warning

These function pointers must never be NULL, or your scanner will crash.

Pointer to FileEntry instanciator.

NewDirEntry()

PDirEntry __stdcall NewDirEntry	(	LPWIN32_FIND_DATA	pfd,
		PDirEntry	pDir,
		PScanDirCtx	pCtx
	)

Pointer to DirEntry instanciator. See NewFileEntry

__new_FileEntry()

PFileEntry __stdcall __new_FileEntry	(	LPWIN32_FIND_DATA	pfd,
		PDirEntry	pDir,
		PScanDirCtx	pCtx
	)

__new_FileEntry() and __new_DirEntry() are the default functions assigned to NewFileEntry and NewDirEntry .
They are exposed so you can restore them, or call them in customized entry allocators.

Definition at line 41 of file FileDir.cpp.

__new_DirEntry()

PDirEntry __stdcall __new_DirEntry	(	LPWIN32_FIND_DATA	pfd,
		PDirEntry	pDir,
		PScanDirCtx	pCtx
	)

See __new_FileEntry()

Definition at line 44 of file FileDir.cpp.

Variable Documentation

_defScanCtx

ScanDirCtx _defScanCtx

Default scanning context if none provided.

Definition at line 17 of file FileDir.cpp.