DosEnumAttribute

Bindings:  C, MASM 

This call identifies extended attributes for a specific file or 
subdirectory. 

 DosEnumAttribute     (RefType, FileRef, EntryNum, EnumBuf, EnumBufSize, 
                      EnumCnt, InfoLevel, Reserved) 
 

 RefType (USHORT) - input 
    A value that indicates the contents of FileRef. 

    Value     Definition 
    0         Handle of a file. 
    1         ASCIIZ name of a file or subdirectory. 

 FileRef (PVOID) - input 
    Address of the handle of a file returned by a DosOpen or  DosOpen2 
    request; or the ASCIIZ name of a file or subdirectory. 

 EntryNum (ULONG) - input 
    Ordinal of an entry in the file object's EA list, which indicates 
    where in the list to begin the return of EA information. The value 0 
    is reserved.  A value of 1 indicates the file object's first EA; a 
    value of 2, the second; and so on. 

 EnumBuf (PVOID) - output 
    Address of the buffer where EA information is returned. Level 1 
    information is returned in the following format: 

    Reserved (UCHAR) 
       Zero. 

    cbName (UCHAR) 
       Length of name excluding NULL. 

    cbValue (USHORT) 
       Length of value. 

    szName (UCHAR) 
       Variable length asciiz name. 

 EnumBufSize (ULONG) - output 
    Size of EnumBuf. 

 EnumCnt (PULONG) - input/output 
    Address of, on input, the number of EAs for which information is 
    requested. A value of -1 requests information be returned for as many 
    EAs whose information fits in EnumBuf. 

    On output, the actual number of EAs for which information is returned. 
    When this value is greater than 1, enumerated information is returned 
    in a packed list.  That is, information for the next EA will be stored 
    adjacent to the previous one. 

 InfoLevel (ULONG) - input 
    Level of information required. Only the value 1 can be specified, 
    indicating return of level 1 information. 

 Reserved (ULONG) - input 
    Reserved and must be set to zero. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    3         ERROR_PATH_NOT_FOUND 
    5         ERROR_ACCESS_DENIED 
    6         ERROR_INVALID_HANDLE 
    8         ERROR_NOT_ENOUGH_MEMORY 
    87        ERROR_INVALID_PARAMETER 
    111       ERROR_BUFFER_OVERFLOW 
    124       ERROR_INVALID_LEVEL 
    206       ERROR_FILENAME_EXCED_RANGE 
 
 Remarks 

 The structure returned by DosEnumAttribute is used to calculate the size 
 of the buffer required to hold the full extended attribute (FEA) 
 information for a DosQPathInfo or DosQFileInfo call that actually gets 
 the FEA. The size of buffer required to hold the FEA information is 
 calculated as follows: 

 One byte (for fea_Reserved) +  
 One byte (for fea_cbName) +  
 Two bytes (for fea_cbValue) +  
 Value of cbName (for the name of the EA) +  
 One byte (for terminating NULL in fea_cbName) +  
 Value of cbValue (for the value of the EA) 
 

 A process can continue through a file's EA list by reissuing 
 DosEnumAttribute with EntryNum set to the value specified in the previous 
 call plus the value returned in EnumCnt. 

 DosEnumAttribute does not control the specific ordering of EAs; it merely 
 identifies them. Like the files they are associated with, extended 
 attributes can have multiple readers and writers. If a file is open in a 
 sharing mode that allows other processes to modify the file's EA list, 
 calling DosEnumAttribute repetitively to back up to an EA's position may 
 return inconsistent results. For example, it is possible for another 
 process to edit the EA list with DosSetFileInfo or DosSetPathInfo between 
 calls by your process to DosEnumAttribute. Thus, the EA returned when 
 EntryNum is 11 for the first call may not be the same EA returned when 
 EntryNum is 11 for the next call. 

 To prevent the modification of EAs between calls to DosEnumAttribute for 
 a specified file handle or file name, the caller must open the file in 
 deny-write sharing mode before it calls DosEnumAttribute. If a 
 subdirectory name is specified, modification by other processes is not a 
 concern , because no sharing is possible. 

 For RefType = 1, the EAs returned are current only when the call was 
 made, and they may have been changed by another thread or process in the 
 meantime.