Share via

MyFSD_CreateFileW (Compact 2013)

  • Article

3/26/2014

This function creates, opens, or truncates a file, pipe, communications resource, disk device, or console in an installable file system. It returns a handle that can be used to access the object. It can also open and return a handle to a directory. The application does not call this function directly. Instead, it uses the corresponding standard Win32 function CreateFile. The File System Disk Manager (FSDMGR) determines the file system type and calls the MyFSD_CreateFileW implementation of the function.

Syntax

HANDLE MyFSD_CreateFileW( 
  PVOLUME pVolume, 
  HANDLE hProc, 
  PCWSTR pwsFileName, 
  DWORD dwAccess, 
  DWORD dwShareMode,
  PSECURITY_ATTRIBUTES pSecurityAttributes, 
  DWORD dwCreate,
  DWORD dwFlagsAndAttributes, 
  HANDLE hTemplateFile
);

Parameters

  • pVolume
    [in] Pointer to the value that an FSD defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of this parameter can point to private structures.
  • hProc
    [in] Handle to the process that is calling CreateFile. This parameter is the same value that an FSD must pass to the FSDMGR_CreateFileHandle function when creating the handle to return to the application.
  • pwsFileName
    [in] Pointer to a null-terminated string that specifies the name of the object, such as a file, pipe, mailslot, communications resource, disk device, console, or directory, to create or open.

  • dwAccess
    [in] Type of access to the object. The following table shows possible values.

    Value

    Description

    GENERIC_READ

    Specifies read access to the object. Data can be read from the file, and the file pointer can be moved. Combine with GENERIC_WRITE for read/write access.

    GENERIC_WRITE

    Specifies write access to the object. Data can be written to the file, and the file pointer can be moved. Combine with GENERIC_READ for read/write access.

    Zero

    Specifies device query access to the object. An application can query device attributes without accessing the device.

  • dwShareMode
    [in] Bit flags that specifies how the object can be shared.

    The following table shows possible values.

    Value

    Description

    FILE_SHARE_READ

    Subsequent open operations on the object succeed only if read access is requested.

    FILE_SHARE_WRITE

    Subsequent open operations on the object succeed only if write access is requested.

    Zero

    The object cannot be shared. Subsequent open operations on the object fail until the handle is closed.
  • pSecurityAttributes
    [in] Ignored. Set to NULL.

  • dwCreate
    [in] Action to take. The following table shows possible values.

    Value

    Description

    CREATE_ALWAYS

    Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.

    CREATE_NEW

    Creates a new file. The function fails, if the specified file already exists.

    OPEN_ALWAYS

    Opens the file if it exists. If the file does not exist, the function creates the file as if this parameter were set to CREATE_NEW.

    OPEN_EXISTING

    Opens the file. The function fails if the file does not exist.

    TRUNCATE_EXISTING

    Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.
  • dwFlagsAndAttributes
    [in] File attributes and flags for the file.
  • hTemplateFile
    Ignored. CreateFile does not copy the extended attributes to the new file.

Return Value

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is set to CREATE_ALWAYS or OPEN_ALWAYS, GetLastError returns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastError returns zero.

INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

An FSD exports this function, if it supports the CreateFile function. All FSD functions can be called on re-entry. Therefore, take this into account when developing an FSD.

FSDMGR is a DLL that manages all OS interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that supports an installable file system. The name of the DLL for an FSD and the names of the functions it exports start with the name of the associated installable file system. For example, if the name of file system is MyFSD, its DLL is MyFSD.dll, and its exported functions are prefaced with MyFSD_*.

FSDMGR provides service functions to FSDs. The FSDMGR_RegisterVolume, the FSDMGR_CreateFileHandle, and the FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data that an FSD associates with volume. This volume-specific data is passed as the first parameter of these three functions.

Applications that access an installable file system use standard Win32 functions. For example, when an application creates a folder on a device that contains an installable file system, it calls the CreateDirectory function. FSDMGR recognizes that the path is to a device containing an installable file system and calls the appropriate function, which in the case of the MyFSD file system is MyFSD_CreateDirectoryW. That is, the application calls CreateDirectory, causing FSDMGR to call **MyFSD_CreateDirectoryW.

A file system must mask off any file attributes that it does not suppor in this function and MyFSD_SetFileAttributesW.

Requirements

Header

fsdmgr.h

Library

Fsdmgr.lib

See Also

Reference

MyFSD Functions
CreateFile
CreateDirectory
FSDMGR_CreateFileHandle
FSDMGR_CreateSearchHandle
FSDMGR_RegisterVolume
MyFSD_CloseFile
MyFSD_CreateDirectoryW

Other Resources

VirtualAlloc