Starts a directory enumeration operation that can return all the entries in a directory.
#include <nks/dirio.h>
int NXDirEnumStart (
NXPathCtx_t pathCtx,
const void *pathname,
NXDeLevel_t level,
NXHandle_t *handle);
(IN) Specifies a file system path context. Along with the pathname parameter, it specifies the directory to enumerate.
(IN) Points to a null-terminated Unicode or ASCII string, which specifies the name of the directory to enumerate. This string cannot include any wildcard characters.
(IN) Specifies the level of information to be returned by the enumeration process (see NXDeLevel_t Enumeration).
(OUT) Points to where the handle for the enumeration process is returned.
If successful, returns 0. Otherwise, returns a nonzero error code:
NXDirEnumStart starts the enumeration of a directory's contents. You must call NXDirEnumGetEntries to retrieve the directory's entries, and you clean up and terminate the enumeration operation by calling NXDirEnumEnd.
Each call to NXDirEnumStart starts a new directory enumeration operation session. This is identified by the value returned in the handle parameter. Such an enumeration session lasts until you call NXDirEnumEnd to end the session. Each enumeration session is completely independent of any other enumeration session that may be in progress.The level parameter specifies the level of information to be returned for each directory entry and is explained in more detail in NXDirEnumGetEntries.
The directory enumeration operation does not support any pattern matching mechanism to return, for example, only those entries matching a specific pattern. If you want to retrieve entries that match a specific pattern, you must implement your own pattern matching techniques to filter out the unwanted entries.A directory enumeration operation does not lock the directory. The operation does not prevent new entries from being added or existing entries from being removed during the operation. If either of these actions occurs, it is possible that duplicate entries can be returned or that some entries can be skipped. See NXDirEnumGetEntries for details.