DosProtectOpen

Opens a new file, an existing file, or a replacement for an existing file and returns a protected file handle. An open file can have extended attributes.

Syntax
DosProtectOpen(pszFileName, phf, pulAction,               cbFile, ulAttribute, fsOpenFlags,                fsOpenMode, peaop2, pfhFileHandleLockID)

Parameters

 * pszFileName (PSZ) - input: Address of the ASCIIZ path name of the file or device to be opened.
 * phf (PHFILE) - output: Address of the handle for the file.
 * pulAction (PULONG) - output: A pointer to the ULONG in which the value that specifies the action taken by DosProtectOpen is returned.
 * If DosProtectOpen fails, this value has no meaning. Otherwise, it is one of the following values:
 * 1 - FILE_EXISTED File already existed.
 * 2 - FILE_CREATED File was created.
 * 3 - FILE_TRUNCATED File existed and was changed to a given size (file was replaced).


 * cbFile (ULONG) - input: New logical size of the file (end of data, EOD), in bytes.
 * This parameter is significant only when creating a new file or replacing an existing one. Otherwise, it is ignored. It is an error to create or replace a file with a nonzero length if the fsOpenMode Access-Mode flag is set to read-only.


 * ulAttribute (ULONG) - input : File attributes.
 * This parameter contains the following bit fields:


 * These bits may be set individually or in combination. For example, an attribute value of 0x00000021 (bits 5 and 0 set to 1) indicates a read-only file that has been archived.


 * fsOpenFlags (ULONG) - input: The action to be taken depending on whether the file exists or does not exist.
 * This parameter contains the following bit fields:


 * fsOpenMode (ULONG) - input: The mode of the open function.
 * This parameter contains the following bit fields:

Any other value is invalid, as are any other combinations.

File sharing requires the cooperation of sharing processes. This cooperation is communicated through sharing and access modes. Any sharing restrictions placed on a file opened by a process are removed when the process closes the file with a DosClose request.

Sharing Mode: Specifies the type of file access that other processes may have. For example, if other processes can continue to read the file while your process is operating on it, specify Deny Write. The sharing mode prevents other processes from writing to the file but still allows them to read it.

Access Mode: Specifies the type of file access (access mode) needed by your process. For example, if your process requires read/write access, and another process has already opened the file with a sharing mode of Deny None, your DosProtectOpen request succeeds. However, if the file is open with a sharing mode of Deny Write, the process is denied access.

If the file is inherited by a child process, all sharing and access restrictions also are inherited.

If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions also are duplicated.


 * peaop2 (PEAOP2) - in/out : A pointer to an extended attribute buffer.
 * Input: The address of the extended-attribute buffer, which contains an EAOP2 structure. The fpFEA2List field in the EAOP2 structure. points to a data area where the relevant FEA2 list is to be found. The fpGEA2List and oError fields are ignored.
 * Output: fpGEA2List and fpFEA2List are unchanged. The area that fpFEA2List points to is unchanged. If an error occurred during the set, oError is the offset of the FEA2 entry where the error occurred. The return code from DosProtectOpen is the error code for that error condition. If no error occurred, oError is undefined. If peaop2 is zero, then no extended attributes are defined for the file. If extended attributes are not to be defined or modified, the pointer peaop2 must be set to zero.


 * pfhFileHandleLockID (PFHLOCK) - output: The address of the 32-bit lockid for the file handle.

Return Code

 * ulrc (APIRET) - returns:DosProtectOpen returns one of the following values:
 * 0 NO_ERROR
 * 2 ERROR_FILE_NOT_FOUND
 * 3 ERROR_PATH_NOT_FOUND
 * 4 ERROR_TOO_MANY_OPEN_FILES
 * 5 ERROR_ACCESS_DENIED
 * 12 ERROR_INVALID_ACCESS
 * 26 ERROR_NOT_DOS_DISK
 * 32 ERROR_SHARING_VIOLATION
 * 36 ERROR_SHARING_BUFFER_EXCEEDED
 * 82 ERROR_CANNOT_MAKE
 * 87 ERROR_INVALID_PARAMETER
 * 99 ERROR_DEVICE_IN_USE
 * 108 ERROR_DRIVE_LOCKED
 * 110 ERROR_OPEN_FAILED
 * 112 ERROR_DISK_FULL
 * 206 ERROR_FILENAME_EXCED_RANGE
 * 231 ERROR_PIPE_BUSY

Remarks
A successful DosProtectOpen request returns a handle and a 32-bit lockid for accessing the file. The read/write pointer is set at the first byte of the file. The position of the pointer can be changed with DosProtectSetFilePtr or by read and write operations on the file.

The file's date and time can be queried with DosProtectQueryFileInfo. They are set with DosProtectSetFileInfo.

The read-only attribute of a file can be set with the ATTRIB command.

ulAttribute cannot be set to Volume Label. To set volume-label information, issue DosProtectSetFileInfo with a logical drive number. Volume labels cannot be opened.

cbFile affects the size of the file only when the file is new or is a replacement. If an existing file is opened, cbFile is ignored. To change the size of the existing file, issue DosProtectSetFileSize.

The value in cbFile is a recommended size. If the full size cannot be allocated, the open request may still succeed. The file system makes a reasonable attempt to allocate the new size in an area that is as nearly contiguous as possible on the medium. When the file size is extended, the values of the new bytes are undefined.

The Direct Open bit provides direct access to an entire disk or diskette volume, independent of the file system. This mode of opening the volume that is currently on the drive returns a handle to the calling function; the handle represents the logical volume as a single file. The calling function specifies this handle with a DosDevIOCtl Category 8, DSK_LOCKDRIVE request to prevent other processes from accessing the logical volume. When you are finished using the logical volume, issue a DosDevIOCtl Category 8, DSK_UNLOCKDRIVE request to allow other processes to access the logical volume.

The file-handle state bits can be set by DosProtectOpen and DosProtectSetFHState. An application can query the file-handle state bits, as well as the rest of the Open Mode field, by issuing DosProtectQueryFHState.

You can use an EAOP2 structure to set extended attributes in peaop2 when creating a file, replacing an existing file, or truncating an existing file. No extended attributes are set when an existing file is just opened.

Example Code
This example opens or creates and opens a file named "DOSPROT.DAT", writes to it, reads from it, and finally closes it using DosProtect functions. 
 * 1) define INCL_DOSFILEMGR         /* File Manager values */
 * 2) define INCL_DOSERRORS          /* DOS Error values    */
 * 3) include 
 * 4) include 
 * 5) include 

int main(VOID) { HFILE hfFileHandle   = 0L; ULONG ulAction       = 0; ULONG ulBytesRead    = 0; ULONG ulWrote        = 0; ULONG ulLocal        = 0; UCHAR uchFileName[20]  = "dosprot.dat", uchFileData[100] = " "; FHLOCK FileHandleLock = 0;       /* File handle lock   */ APIRET rc            = NO_ERROR; /* Return code */

/* Open the file dosprot.dat. Make it read/write, open it */ /* if it already exists and create it if it is new. */  rc = DosProtectOpen(uchFileName,             /* File path name          */                &hfFileHandle,                  /* File handle             */                &ulAction,                      /* Action taken            */                100L,                           /* File primary allocation */                FILE_ARCHIVED | FILE_NORMAL,    /* File attribute          */                OPEN_ACTION_CREATE_IF_NEW |                OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type      */                OPEN_FLAGS_NOINHERIT |                OPEN_SHARE_DENYNONE  |                OPEN_ACCESS_READWRITE,          /* Open mode of the file   */                0L,                             /* No extended attribute   */                &FileHandleLock);               /* File handle lock id     */ if (rc != NO_ERROR) { printf("DosProtectOpen error: return code = %u\n", rc); return 1; } else { printf ("DosProtectOpen: Action taken = %u\n", ulAction); } /* endif */

/* Write a string to the file */ strcpy (uchFileData, "testing...\n3...\n2...\n1\n");

rc = DosProtectWrite (hfFileHandle,      /* File handle                  */                  (PVOID) uchFileData,       /* String to be written         */                  sizeof (uchFileData),      /* Size of string to be written */                  &ulWrote,                  /* Bytes actually written       */                  FileHandleLock);           /* File handle lock id          */ if (rc != NO_ERROR) { printf("DosProtectWrite error: return code = %u\n", rc); return 1; } else { printf ("DosProtectWrite: Bytes written = %u\n", ulWrote); } /* endif */

/* Move the file pointer back to the beginning of the file */ rc = DosProtectSetFilePtr (hfFileHandle,   /* File Handle          */                       0L,                     /* Offset               */                       FILE_BEGIN,             /* Move from BOF        */                       &ulLocal,               /* New location address */                       FileHandleLock);        /* File handle lock id  */ if (rc != NO_ERROR) { printf("DosSetFilePtr error: return code = %u\n", rc); return 1; }

/* Read the first 100 bytes of the file */ rc = DosProtectRead (hfFileHandle,        /* File Handle                 */                 uchFileData,                 /* String to be read           */                 100L,                        /* Length of string to be read */                 &ulBytesRead,                /* Bytes actually read         */                 FileHandleLock);             /* File handle lock id         */ if (rc != NO_ERROR) { printf("DosProtectRead error: return code = %u\n", rc); return 1; } else { printf("DosProtectRead: Bytes read = %u\n%s\n", ulBytesRead, uchFileData); } /* endif */

rc = DosProtectClose(hfFileHandle, FileHandleLock);  /* Close the file */ if (rc != NO_ERROR) { printf("DosProtectClose error: return code = %u\n", rc); return 1; }  return NO_ERROR; } 

Related Functions

 * DosDevIOCtl
 * DosDupHandle
 * DosProtectClose
 * DosProtectSetFileInfo
 * DosProtectSetFilePtr
 * DosProtectSetFileSize
 * DosQueryHType
 * DosSetMaxFH
 * DosSetRelMaxFH