DosProtectSetFileInfo

Sets file information.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

HFILE     hf;                  /* File handle. */
ULONG     ulInfoLevel;         /* Level of file information being set. */
PVOID     pInfoBuf;            /* Address of the storage area containing the structures
                                  for file information levels. */
ULONG     cbInfoBuf;           /* The length, in bytes, of pInfoBuf. */
FHLOCK    fhFileHandleLockID;  /* The filehandle lockid obtained from DosProtectOpen. */
APIRET    ulrc;                /* Return Code. */

ulrc = DosProtectSetFileInfo(hf, ulInfoLevel, pInfoBuf, cbInfoBuf, fhFileHandleLockID);

Parameters

hf (HFILE) - input

File handle.

ulInfoLevel (ULONG) - input

Level of file information being set.

A value of 1 or 2 can be specified, as shown in the following list.

• 1 FIL_STANDARD - Level 1 file information
• 2 FIL_QUERYEASIZE - Level 2 file information

The structures described in pInfoBuf indicate the information being set for each of these levels.

pInfoBuf (PVOID) - input

Address of the storage area containing the structures for file information levels.

Level 1 File Information (ulInfoLevel == FIL_STANDARD)

• pInfoBuf contains the FILESTATUS3 data structure.

Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE)

• pInfoBuf contains an EAOP2 data structure.

Level 2 sets a series of EA name/value pairs. On input, pInfoBuf is an EAOP2 data structure. fpGEA2List is ignored. fpFEA2List points to a data area where the relevant is an FEA2 list is to be found. oError is ignored.

On output, fpGEA2List and fpFEA2List are unchanged. The area pointed to by fpFEA2List is unchanged. If an error occurred during the set, oError is the offset of the FEA2 where the error occurred. The return code is the error code corresponding to the condition generating the error. If no error occurred, oError is undefined.

cbInfoBuf (ULONG) - input

The length, in bytes, of pInfoBuf.

fhFileHandleLockID (FHLOCK) - input

The filehandle lockid obtained from DosProtectOpen.

Return Code

ulrc (APIRET) - returns

DosProtectSetFileInfo returns one of the following values:

• 0 NO_ERROR
• 1 ERROR_INVALID_FUNCTION
• 5 ERROR_ACCESS_DENIED
• 6 ERROR_INVALID_HANDLE
• 87 ERROR_INVALID_PARAMETER
• 122 ERROR_INSUFFICIENT_BUFFER
• 124 ERROR_INVALID_LEVEL
• 130 ERROR_DIRECT_ACCESS_HANDLE
• 254 ERROR_INVALID_EA_NAME
• 255 ERROR_EA_LIST_INCONSISTENT

Remarks

DosProtectSetFileInfo is successful only when the file is opened for write access, and access by other processes is prevented by a deny-both sharing mode. If the file is already opened with conflicting sharing rights, any call to DosProtectOpen will fail.

A value of 0 in the date and time components of a field does not change the field. For example, if both "last write date" and "last write time" are specified as 0 in the Level 1 information structure, then both attributes of the file are left unchanged. If either "last write date" or "last write time" are other than 0, both attributes of the file are set to the new values.

In the FAT file system, only the dates and times of the last write can be modified. Creation and last-access dates and times are not affected.

The last-modification date and time will be changed if the extended attributes are modified.

Example Code

This example creates a read-only file named "DOSFDEL.DAT", then changes its attributes to normal file, and finally uses DosForceDelete to delete the file so that it cannot be restore 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 we want to delete    */
 HFILE       fhDelFile       = 0;               /* File handle from DosOpen  */
 FILESTATUS3 fsts3FileInfo   = {{0}};  /* Information associated with file   */
 ULONG       ulBufferSize    = sizeof(FILESTATUS3); /* File info buffer size */
 ULONG       ulOpenAction    = 0;                 /* Action taken by DosOpen */
 APIRET      rc              = NO_ERROR;          /* Return code             */
 FHLOCK      FHLock          = 0;                 /* File handle lock        */

                 /* Create a read-only file */

  rc = DosProtectOpen(uchFileName, &fhDelFile,
               &ulOpenAction, 10L, 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("DosProtectOpen error: return code = %u\n", rc);
     return 1;
  }

  rc = DosProtectQueryFileInfo(fhDelFile, FIL_STANDARD,
               &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_STANDARD,
                        &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;
}

Related Functions

• DosProtectClose
• DosProtectEnumAttribute
• DosProtectOpen
• DosProtectQueryFileInfo
• DosQueryPathInfo
• DosResetBuffer
• DosSetFileSize
• DosSetPathInfo