Returns one or more directory entries.
#include <nks/dirio.h>
int NXDirEnumGetEntries (
NXHandle_t handle,
NXDirMark_t *start,
void *buffer,
size_t length,
size_t *entriesReturned,
NXDirMark_t *next,
NXBool_t *sequenceGuarantee);
(IN) Specifies the handle for the directory enumeration operation, as returned by NXDirEnumStart.
(IN) Points to the directory mark for the directory entry from which the enumeration operation has to begin.
(IN/OUT) Points to a buffer where the entries are to be returned. The buffer must be large enough to hold one or more of the requested entry structures.
(IN) Specifies the length of the buffer in which to return entries.
(OUT) Points to a location that is updated by NKS to indicate the total number of entries that were returned.
(OUT) Points to a structure that NKS updates to indicate the directory mark for the next directory entry to use when continuing the enumeration.
(OUT) Points to a value that NKS updates to indicate whether the entries returned so far can be considered a true representation of the directory at the time the function was called.
If the directory has not been modified since the enumeration began, returns TRUE.
If the directory has been modified (entries deleted, added, etc.), returns FALSE.
If successful, returns 0. Otherwise, returns a nonzero error code:
NXDirEnumGetEntries can be called iteratively to return all the entries in a directory. When all entries have been enumerated, the function returns NX_EEHAUSTED.
The directory entry enumeration operation must be initiated by calling NXDirEnumStart. The directory enumeration operation is stateless, which means that each call to NXDirEnumGetEntries must explicitly specify a directory mark (or bookmark) from where the enumeration operation needs to start.
For the first iteration, the start parameter is set by the user to the directory mark from where the enumeration should start. On a successful return, the location pointed by the next parameter is set by NKS to the directory mark that should be used to continue the enumeration. For sequential enumeration, use the value returned in the next parameter as the value for the start parameter for the next iteration.
Each directory entry contains a field that specifies the directory mark for that directory entry. Random access to already enumerated entries is possible by saving the directory mark field of a directory entry and passing it as the value for the start parameter in a subsequent call. The enumeration operation can be started (or restarted at anytime) again by calling NXDirMarkInit to initialize the location pointed by the start parameter. The only legal values for the start parameter are the following:
The value obtained by calling NXDirMarkInit to start or restart the enumeration.
The value returned in the next parameter because the enumeration was started or restarted.
The values returned in the directory mark field of a directory entry that was retrieved because the enumeration was started or restarted.
Directory mark values from a different enumeration session or those that were obtained before restarting an enumeration operation should not be passed to the start parameter.
If the directory mark field of an obtained directory entry is used for the start parameter, the enumeration operation is restarted from that directory entry and not the directory entry that comes after it. Therefore, the directory mark field of the last directory entry in the set of directory entries that are returned by NXDirEnumGetEntries and the directory mark that is returned in the next parameter are not the same. The value returned in the next parameter is the directory mark of the entry that comes after the last entry in the set that was returned.
The directory enumeration operation does not support any pattern matching mechanism to return, for example, only those entries that match 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 might be skipped. A directory enumeration operation does not prevent the directory that is being enumerated from being removed either. If that happens, an appropriate error is returned.
Because a directory that is being enumerated can change during the enumeration operation, these changes can potentially lead to an entry being skipped or duplicate entries being returned by the enumeration operation in some file systems. To allow you to detect such problems, the value of the sequenceGuarantee parameter is set to TRUE if NKS can guarantee that no entries were skipped and no duplicate entries were returned. Otherwise, it is set to FALSE. If an application finds the value of the sequenceGuarantee set to FALSE on successful return, you can either restart the enumeration operation (by calling NXDirMarkInit), attempt to filter out the duplicate entries, or ignore the value depending on the requirements of your application.
Depending on the level of directory entry information that is specified in NXDirEnumStart, the buffer (pointed to by the buffer parameter) is updated with as many directory entries as can fit in the buffer. If NXDirEnumGetEntries returns successfully, NKS sets the value of the entriesReturned parameter to indicate the actual number of entries that were returned in the buffer.
The structure that the buffer parameter can point to depends upon the level specified in the NXDirEnumStart function: basic, name, or extended.
If level is set to basic (NX_DELEVEL_BASIC), the buffer parameter returns NXDirEnum_t structures.
When multiple entries are returned, the embedded NXDeHeader_t field at the beginning of each entry makes it possible to easily retrieve the individual entries. Given the pointer to the first entry, the next entry is located at a byte offset that is specified by the length field in the embedded NXDeHeader_t structure (from the pointer to the first entry). All other entries can then be accessed in a similar manner.
If level is set to name (NX_DEVEL_NAME_ONLY), the buffer parameter returns NXDirAttrWithName_t structures.
In an enumeration of this type, only the name and the object type are returned.
If level is set to extended (NX_DELEVEL_EXTENDED) the buffer parameter returns one of the following structures, depending on the requested name space:
NXDirEnumMac_t
NXDirEnumUnix_t
The structure returned depends on the pathname format that is injected into the pathCtx parameter at the time of creation (by calling NXCreatePathContext). If pathCtx is zero, the NKS pathname format is assumed. If the operation cannot be completed, an appropriate error is returned.
The individual entries that are returned in the location specified by the buffer parameter have to be interpreted in a pathname format-specific way. The pathname format of the entries is determined by the pathname format that is associated with the path context that is passed to NXDirEnumStart. In order to specify a different pathname format, you must reinject the pathCtx parameter with the different format or retrieve another pathname context and inject it before it is passed to NXDirEnumStart.