Purpose

DosProtectQueryFileInfo gets file information.

Syntax

#define INCL DOSFILEMGR
#include  os2.h 

APIRET DosProtectQueryFileInfo

(HFILE hf, ULONG ulInfoLevel, PVOID pInfo, ULONG cbInfoBuf, FHLOCK fhFileHandleLockID)

Parameters

hf HFILE) input

File handle.
ulInfoLevel ULONG) input
Level of file information required.

Specify a value

• FIL_STANDARD

  Level 1 file information

  11

  FIL_STANDARDL

  Level 11 file information

  2
  FIL_QUERYEASIZE

  Level 2 file information

  12
  FIL_QUERYEASIZEL

  Level 12 file information

  3
  FIL_QUERYEASFROMLIST

  Level 3 file information

  The structures described in pInfo indicate the information returned for each of these levels.
pInfo PVOID) 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 DosProtectClose, DosResetBuffer, DosProtectSetFileInfo, or DosSetPathInfo.

Level 1 File Information (ulInfoLevel == FIL_STANDARD)

pInfo contains the FILESTATUS3 data structure, to which file information is returned.
Level 11 File Information (ulInfoLevel == FIL_STANDARDL)
pInfo contains the FILESTATUS3L data structure, to which file information is returned.
Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE)
pInfo contains the FILESTATUS4 data structure. This is similar to the Level 1 structure, with the addition of the cbList field after the attrFile field.

The cbList field is an ULONG. On output, this field contains the size, in bytes, of the file s entire extended attribute (EA) set on disk. You can use this value to calculate the size of the buffer required to hold the EA information returned when a value of 3 is specified for ulInfoLevel. The buffer size is less than or equal to twice the size of the file s entire EA set on disk.

Level 12 File Information (ulInfoLevel == FIL_QUERYEASIZEL)
pInfo contains the FILESTATUS4L data structure. This is similar to the Level 11 structure, with the addition of the cbList field after the attrFile field.

The cbList field is an ULONG. On output, this field contains the size, in bytes, of the file s entire extended attribute (EA) set on disk. You can use this value to calculate the size of the buffer required to hold the EA information returned when a value of 3 is specified for ulInfoLevel. The buffer size is less than or equal to twice the size of the file s entire EA set on disk.

Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST)

Input

pInfo contains an EAOP2 data structure. fpGEA2List points to a GEA2 list defining the attribute names whose values are returned. The GEA2 data structures must be aligned on a doubleword boundary. Each oNextEntryOffset field must contain the number of bytes from the beginning of the current entry to the beginning of the next entry in the GEA2 list. The oNextEntryOffset field in the last entry of the GEA2 list must be zero. fpFEA2List points to a data area where the relevant FEA2 list is returned. The length field of this FEA2 list is valid, giving the size of the FEA2 list buffer. oError is ignored.
Output
pInfo is unchanged. The buffer pointed to by fpFEA2List is filled in with the returned information. If the buffer that fpFEA2List points to is not large enough to hold the returned information (the return code is ERROR_BUFFER_OVERFLOW), cbList is still valid, assuming there is at least enough space for it. Its value is the size of the entire EA set on disk for the file, even though only a subset of attributes was requested.
cbInfoBuf ULONG) input
The length, in bytes, of pInfo.
fhFileHandleLockID FHLOCK) input
The filehandle lockid returned by a previous DosProtectOpenL.

Returns

ulrc (APIRET) returns

Return Code.

DosProtectQueryFile returns one of the following values

• NO_ERROR

• ERROR_ACCESS_DENIED

• 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

  In the FAT file system, only date and time information contained in level-1 file information can be modified. Zero is returned for the creation and access dates and times.

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

  DosProtectEnumAttribute returns the lengths of extended attributes. This information can be used to calculate what size pInfo needs to be to hold full-extended-attribute (FEA) information returned by DosProtectQueryFileInfo when Level 3 is specified. The size of the buffer is calculated as follows

  Four bytes (for oNextEntryOffset) + One byte (for fEA) +
  One byte (for cbName) +
  Two bytes (for cbValue) +
  Value of cbName (for the name of the EA) +
  One byte (for terminating NULL in cbName) +
  Value of cbValue (for the value of the EA)

  Related Functions

  • DosProtectClose

  • DosProtectOpenL

  • DosProtectEnumAttribute

  • DosProtectSetFileInfo

  • DosQueryPathInfo

  • DosResetBuffer

  • DosProtectSetFileSizeL

  • DosSetPathInfo

  Example Code

  This example creates a read-only file named DOSFDEL.DAT , then changes the file attributes to normal, and uses DosForceDelete to delete the file so that it can not be restored using UNDELETE.

  #define INCL_DOSFILEMGR   /* File Manager values */#define INCL_DOSERRORS    /* DOS error values    */
  #include  os2.h 
  #include  stdio.h 
  
  int main(VOID)  
  
  UCHAR       uchFileName     = "DOSFDEL.DAT";   /* File to delete    */
  HFILE       fhDelFile       = 0;               /* File handle from DosOpenL  */
  FILESTATUS3L fsts3FileInfo   =   0  ;  /* Information associated with file   */
  ULONG       ulBufferSize    = sizeof(FILESTATUS3L); /* File info buffer size */
  ULONG       ulOpenAction    = 0;                 /* Action taken by DosOpenL */
  APIRET      rc              = NO_ERROR;          /* Return code             */
  FHLOCK      FHLock          = 0;                 /* File handle lock        */
  
  /* Create a read-only file */
  
  rc = DosProtectOpenL(uchFileName,  fhDelFile,
   ulOpenAction, (longlong)10, FILE_READONLY,
  OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
  OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L,  FHLock);
  if (rc != NO_ERROR)  
  printf("DosProtectOpenL error  return code = %u\n", rc);
  return 1;
   
  
  rc = DosProtectQueryFileInfo(fhDelFile, FIL_STANDARDL,
   fsts3FileInfo, ulBufferSize, FHLock);   /* Get standard info */
  if (rc != NO_ERROR)  
  printf("DosProtectQueryFileInfo error  return code = %u\n", rc);
  return 1;
    else   printf("File %s created read-only.\n",uchFileName);  
  
  /*   Change the file attributes to be "normal"  */
  
  fsts3FileInfo.attrFile  = FILE_NORMAL;
  rc = DosProtectSetFileInfo(fhDelFile, FIL_STANDARDL,
   fsts3FileInfo, ulBufferSize, FHLock);
  if (rc != NO_ERROR)  
  printf("DosProtectSetFileInfo error  return code = %u\n", rc);
  return 1;
   
  rc = DosProtectClose(fhDelFile, FHLock);
  /* Should verify that (rc != NO_ERROR) here... *//* Delete the file */
  
  rc = DosForceDelete(uchFileName);
  if (rc != NO_ERROR)  
  printf("DosForceDelete error  return code = %u\n", rc);
  return 1;
    else  
  printf("File %s has been deleted.\n",uchFileName);
     /* endif */
  
  return NO_ERROR;
   
  

  ---

  [Back] [Next]