Enumerates files, data streams, deleted files, or extended attributes contained by another file object and returns metadata information for the next entry that matches the search criteria.
#include <zPublics.h> STATUS zEnumerate ( Key_t key, QUAD cookie, NINT nameType, NINT match, QUAD getInfoMask, NINT sizeRetGetInfo, NINT infoVersion, void *retGetInfo QUAD *nextCookie);
(IN) Specifies the directory type object (or file) that will be scanned for subcomponents. The key must be obtained by opening a file/directory with zRR_SCAN_ACCESS.
(IN) Specifies the starting position in the directory. Pass zero the first time you call zEnumerate. On subsequent calls, this value can be set to values previously returned from zEnumerate.
(IN) Specifies the type of name to be enumerated: zNTYPE_FILE, zNTYPE_DATA_STREAM, zNTYPE_EXTENDED_ATTRIBUTE, or zNTYPE_DELETED_FILE (see Name Type Values).
(IN) Specifies the attributes that the file objects must match (optional). File objects that do not satisfy the match criteria are skipped.
(IN) Specifies the information to be returned (see Get Info Mask Values).
(IN) Specifies the total size (in bytes) of the zInfo_s structure passed to retGetInfo, which includes the size of the variable size portion that is used to store any variable-sized pieces returned in the structure.
(IN) Specifies the version of the zInfo structure that is being used. For NetWare 6.x versions, there are two supported versions: zINFO_VERSION_A and zINFO_VERSION_B. zINFO_VERSION_B enables the ability to obtain directory quotas.
(OUT) Is a caller-supplied structure—either zInfo_s or zInfoB_s—in which the requested information is returned. If NULL, no information about this file or directory object is returned.
(OUT) Points to a cookie that points to the next file object.
|
zOK |
The operation completed successfully. |
|
non-0 |
An error occurred (see Section 4.1, Return Values for a description). |
|
zERR_BUFFER_TOO_SMALL |
The variable size portion of retGetInfo was not big enough to contain all of the requested optional data. Only the fixed data and any optional data that completely fit in the structure was returned. |
|
zERR_NAME_NOT_FOUND_ IN_DIRECTORY |
No more files were found in the directory. |
zEnumerate reads the next entry contained in the file object identified by key and returns information for the next contained file object that is associated with that directory entry. The key maintains a current directory position that is updated for each function iteration.
The cookie parameter can be used to reposition the cursor in the directory.
The type of file object being enumerated is dependent on the nameType associated with the key parameter. This nameType was associated with the key by calling zOpen.
zEnumerate can also return type-specific information about the file object. If zERR_BUFFER_TOO_SMALL is returned, all of the fixed length data was returned but some of the variable length was not returned because the buffer did not have enough room for all of the requested variable length data. Call zEnumerate again with a larger buffer to retrieve all of the information, ensuring that the value that is passed to the cookie parameter is the same value that was passed in the previous call.
All of the variable length data is indexed by the fixed portion of the structure. If the data is filled in, the index to that data is also filled in. If the data does not fit, the index to that data will be set to zero.
The returned data consists of the data specified by the bits set in getInfoMask.