Open a file and return a handle for a file object.

RTHANDLE CreateRtFile(
    LPSTR lpFileName, 
    DWORD dwAccessMode, 
    DWORD dwShareMode, 
    DWORD dwOpenMode, 
    DWORD dwAttributesAndFlags); 

Parameters

lpFileName

The name of the file or device to be opened or created. You may use either forward or back slashed in the path name. The name is limited to MAX_PATH characters.

dwAccessMode

The requested access to the file or device. Possible values include FILE_MODE_READ_ONLY, FILE_MODE_WRITE_ONLY, or FILE_MODE_READ_WRITE.

dwShareMode

The requested sharing mode of the file or device. Possible values include FILE_SHARE_NONE, FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_SHARE_DELETE and FILE_SHARE_ALL. If this parameter is FILE_SHARE_NONE and CreateRtFile succeeds, the file cannot be opened again until the file object is deleted. You cannot request a sharing mode which conflicts with the requested access mode.

Note: FILE_SHARE_DELETE is ignored in INtime Distributed RTOS.

dwOpenMode

Specifies an action to take on a file which exists or does not exist. For devices other than data files this parameter is usually set to FILE_OPEN_EXISTING. The parameter must be set to one of the following:

FILE_CREATE_ALWAYS	Creates a new file, always. If the specified file exists and is writable, the function overwrites the file and the call succeeds. If the path does not exist and is valid, a new file is created and the function succeeds.
FILE_CREATE_NEW	Creates a file, only if it does not already exist. If the specified file exists, the function fails and the last error is set to E_FEXIST. If the specified file does not exist and the location path is writable, then a new file is created and function succeeds.
FILE_OPEN_ALWAYS	Opens a file, always. If the specified file exists, the function succeeds. If the specified file does not exist, and the location is writable, the file is created and the function succeeds.
FILE_OPEN_EXISTING	Opens a file or device, only if it exists. If the specified file does not exist, the function fails and last error is set to E_FNEXIST.
FILE_TRUNCATE_EXISTING	Opens a file and truncates it to zero bytes in length, only if it exists. If the specified file does not exist, the function fails and last error is set to E_FNEXIST. The caller must open the file with a writable access mode (WRITE_ONLY or READ_WRITE).

dwAttributesAndFlags

A bitfield representing the file attributes to assign to a file being created by this call, and flags to determine the mode in which the file is to be used. The attributes bits are ignored when an existing file is opened. Bit definitions are as follows:

FILE_ATTR_READONLY	File is read-only
FILE_ATTR_HIDDEN	File is hidden
FILE_ATTR_SYSTEM	File is marked as a system file
FILE_ATTR_ARCHIVE	File is marked for archiving
FILE_ATTR_NORMAL	File is a normal file (no other attribute bits are set)
FILE_FLAG_ASYNCHRONOUS	File is opened for asynchronous operations. See the section Synchronous and asynchronous I/O operations for further details.

Return value

If the function succeeds, the return value is a handle for an open file object. If the function fails, the return value is BAD_RTHANDLE. To get extended information call GetLastRtError().

Remarks

When an application is finished using the handle, call DeleteRtFile to close the file object and delete it. This not only frees up the resources associated with the handle but has influence on other things such as the accessibility of the file through sharing, committing the data to the underlying medium and so on. Specifics are described elsewhere in this topic as appropriate.

The only file attributes currently supported on INtime Distributed RTOS are FILE_ATTR_READONLY and FILE_ATTR_HIDDEN.

Directories

A directory cannot be created using CreateRtFile. Therefore to open a directory only the OPEN_EXISTING flags value is valid. Use CreateRtDirectory to create a directory.

Requirements