MyFSD_CreateFileW

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, use the corresponding standard Win32 function CreateFile. The file system driver (FSD) Manager determines the file system type and calls the MyFSD_CreateFileW implementation of the function.

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

Parameters

  • pVolume
    Pointer to the value that the file system driver (FSD) defines in its DLL and passes to the FSDMGR_RegisterVolume function when registering the volume. The definition of pVolume can point to private structures.

  • hProc
    Handle to the process that is calling CreateFile. This parameter is the same value that the FSD must pass to the FSDMGR_CreateFileHandle function when creating the handle to return to the application.

  • pwsFileName
    Pointer to a null-terminated string that specifies the name of the object (file, pipe, mailslot, communications resource, disk device, console, or directory) to create or open.

  • dwAccess
    Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. It can be any combination of the following values:

    Value Description
    0 Specifies device query access to the object. An application can query device attributes without accessing the device.
    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.
  • dwShareMode
    Set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

    To share the object, use a combination of one or more of the following values:

    Value Description
    FILE_SHARE_READ Subsequent open operations on the object will succeed only if read access is requested.
    FILE_SHARE_WRITE Subsequent open operations on the object will succeed only if write access is requested.
  • pSecurityAttributes
    Ignored; set to NULL.

  • dwCreate
    Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the Remarks section. It is one of the following values:

    Value Description
    CREATE_NEW Creates a new file. The function fails if the specified file already exists.
    CREATE_ALWAYS Creates a new file. If the file exists, the function overwrites the file and clears the existing attributes.
    OPEN_EXISTING Opens the file. The function fails if the file does not exist.
      See the Remarks section for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function for devices, including the console.
    OPEN_ALWAYS Opens the file, if it exists. If the file does not exist, the function creates the file as if dwCreate were CREATE_NEW.
    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
    Specifies the file attributes and flags for the file.

  • hTemplateFile
    Ignored; as a result, CreateFile does not copy the extended attributes to the new file.

Return Values

An open handle to the specified file indicates success. If the specified file exists before the function call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to 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 wants to support the CreateFile function. All FSD functions can be called reentryly, therefore, FSD developers must take this into account when developing an FSD.

The Fsdmgr component is a dynamic-link library (DLL) that manages all operating system interaction with installable files systems. Each installable file system requires an FSD, which is a DLL that exports an API needed to support an installable file system. The name of the DLL for the 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, then its DLL is MyFSD.dll and its exported functions are prefaced with MyFSD_*.

Fsdmgr provides service functions to FSDs. The FSDMGR_RegisterVolume, FSDMGR_CreateFileHandle, and FSDMGR_CreateSearchHandle functions record a DWORD of volume-specific data the FSD needs to keep associated 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 wants to create a folder on a device that contains an installable file system, it calls CreateDirectory. 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.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 2.10 and later Fsdmgr.h    

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CreateFile, CreateDirectory, FSDMGR_CreateFileHandle, FSDMGR_CreateSearchHandle, FSDMGR_RegisterVolume, GetLastError, MyFSD_CloseFile, MyFSD_CreateDirectoryW, VirtualAlloc

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.