DosQFileInfo

Bindings:  C, MASM 

This call returns information for a specific file. 

 DosQFileInfo     (FileHandle, FileInfoLevel, FileInfoBuf, 
                  FileInfoBufSize) 
 

 FileHandle (HFILE) - input 
    File handle. 

 FileInfoLevel (USHORT) -  input 
    Level of file information required. A value of 1, 2, or 3 can be 
    specified. Level 4 is reserved. The structures described in 
    FileInfoBuf indicate the information returned for each of these 
    levels. 

 FileInfoBuf (PBYTE) -  output 
    Address of the storage area where the system returns the requested 
    level of file information. File information, where applicable, is at 
    least as accurate as the most recent DosClose, DosBufReset, 
     DosSetFileInfo, or DosSetPathInfo. 

    Level 1 Information 
       FileInfoBuf contains the following structure, to which file 
       information is returned: 

       filedate (FDATE) 
          Structure containing the date of file creation. 

          Bit       Description 
          15-9      Year, in binary, of file creation 
          8-5       Month, in binary, of file creation 
          4-0       Day, in binary, of file creation. 

       filetime (FTIME) 
          Structure containing the time of file creation. 

          Bit       Description 
          15-11     Hours, in binary, of file creation 
          10-5      Minutes, in binary, of file creation 
          4-0       Seconds, in binary number of two-second increments, of 
                    file creation. 

       fileaccessdate (FDATE) 
          Structure containing the date of last access. See FDATE in 
          filedate. 

       fileaccesstime (FTIME) 
          Structure containing the time of last access. See FTIME in 
          filetime. 

       writeaccessdate (FDATE) 
          Structure containing the date of last write. See FDATE in 
          filedate. 

       writeaccesstime (FTIME) 
          Structure containing the time of last write. See FTIME in 
          filetime. 

       filesize (ULONG) 
          File size. 

       filealloc (ULONG) 
          Allocated file size. 

       fileattrib (USHORT) 
          Attributes of the file, defined in DosSetFileMode. 

    Level 2 Information 
       FileInfoBuf contains a structure similar to the Level 1 structure, 
       with the addition of the cbList field after the fileattrib field. 

       cbList (ULONG) 
          On output, this field contains the length of the entire EA set 
          for the file object.  This value can be used to calculate the 
          size of the buffer required to hold EA information returned when 
          FileInfoLevel = 3 is specified. 

    Level 3 Information 
       FileInfoBuf contains an EAOP structure, which has the following 
       format: 

       fpGEAList (PGEALIST) 
          Address of GEAList. GEAList is a packed array of variable length 
          "get EA" structures, each containing an EA name and the length 
          of the name. 

       fpFEAList (PFEALIST) 
          Address of FEAList. FEAList is a packed array of variable length 
          "full EA" structures, each containing an EA name and its 
          corresponding value, as well as the lengths of the name and the 
          value. 

       oError (ULONG) 
          Offset into structure where error has occurred. 

          On input, FileInfoBuf is an EAOP structure.  fpGEAList points to 
          a GEA list defining the attribute names whose values are 
          returned.  fpFEAList points to a data area where the relevant 
          FEA list is returned.  The length field of this FEA list is 
          valid, giving the size of the FEA list buffer. oError points to 
          the offending GEA entry in case of error. Following is the 
          format of the GEAList structure: 

       cbList (ULONG) 
          Length of the GEA list, including the length itself. 

       list (GEA) 
          List of GEA structures.  A GEA structure has the following 
          format: 

          cbName (BYTE) 
             Length of EA ASCIIZ name, which does not include the null 
             character. 

          szName (CHAR) 
             ASCIIZ name of EA. 

             On output, FileInfoBuf is unchanged.  The buffer pointed to 
             by fpFEAList is filled in with the returned information.  If 
             the buffer fpFEAList points to isn't large enough to hold the 
             returned information (ERROR_BUFFER_OVERFLOW) cbList is still 
             valid, assuming there's at least enough space for it.  Its 
             value is the size of the entire EA set for the file, even 
             though only a subset of attributes was requested. Following 
             is the format of the FEAList structure: 

       cbList (ULONG) 
          Length of the FEA list, including the length itself. 

       list (FEA) 
          List of FEA structures.  An FEA structure has the following 
          format: 

          Flags (BYTE) 
             Bit indicator describing the characteristics of the EA being 
             defined. 

             Bit       Description 
             7         Critical EA. 
             6-0       Reserved and must be set to zero. 

            
             If bit 7 is set to 1, this indicates a critical  EA.  If bit 
             7 is 0, this means the EA is noncritical; that is, the EA is 
             not essential to the intended use by an application of the 
             file with which it is associated. 

          cbName (BYTE) 
             Length of EA ASCIIZ name, which does not include the null 
             character. 

          cbValue (USHORT) 
             Length of EA value, which cannot exceed 64KB. 

          szName (PSZ) 
             Address of the ASCIIZ name of EA. 

          aValue (PSZ) 
             Address of the free-format value of EA. 

             Note:  The szName and aValue fields are not included as part 
                    of header or include files.  Because of their variable 
                    lengths, these entries must be built manually. 

 FileInfoBufSize (USHORT) - output 
    Length of FileInfoBuf. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    5         ERROR_ACCESS_DENIED 
    6         ERROR_INVALID_HANDLE 
    111       ERROR_BUFFER_OVERFLOW 
    124       ERROR_INVALID_LEVEL 
    130       ERROR_DIRECT_ACCESS_HANDLE 
    254       ERROR_INVALID_EA_NAME 
    255       ERROR_EA_LIST_INCONSISTENT 
 
 Remarks 

 The FAT file system supports modification of only date and time 
 information contained in file information level 1. Zero is returned for 
 the creation and access dates and times. 

 To return information contained in any of the file information levels, 
 DosQFileInfo has to be able to read the open file.  DosQFileInfo works 
 only when the file is opened for read access, with a deny-write sharing 
 mode specified for access by other processes. If the file is already 
 opened by another process that has specified conflicting sharing and 
 access modes, a call to DosOpen or  DosOpen2 fails. 

 DosEnumAttribute returns the lengths of EAs.  This information can be 
 used to calculate the size of FileInfoBuf needed to hold full extended 
 attribute (FEA) information returned by DosQFileInfo when Level 3 is 
 specified.  The size of the buffer is calculated as follows: 

 One byte (for fea_usFlags) +  
 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)