Share via

IRAPISession::CeCreateFile (Windows Embedded CE 6.0)

  • Article

1/6/2010

This method creates, opens, or truncates a file, pipe, communications resource, disk device, or console on a remote Windows Embedded CE–based device. It returns a handle that can be used to access the object.

Syntax

HANDLE CeCreateFile (
  LPCWSTR lpFileName, 
  DWORD dwDesiredAccess, 
  DWORD dwShareMode, 
  LPSECURITY_ATTRIBUTES lpSecurityAttributes, 
  DWORD dwCreationDisposition, 
  DWORD dwFlagsAndAttributes, 
  HANDLE hTemplateFile 
);

Parameters

  • lpFileName
    [in] Long 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.

    If lpFileName is a path, there is a default string size limit of MAX_PATH characters.

  • dwDesiredAccess
    [in] Specifies the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. This parameter 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
    [in] 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 values specified in the following table.

    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.
  • lpSecurityAttributes
    Ignored; set to NULL.

  • dwCreationDisposition
    [in] 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. This parameter must be 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 IRAPISession::CeCreateFile 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 dwCreationDisposition were CREATE_NEW.

    TRUNCATE_EXISTING

    Opens the file. After it is 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.

    Any combination of the following attributes is acceptable for the dwFlagsAndAttributes parameter, except all other file attributes override FILE_ATTRIBUTE_NORMAL.

    Value Description

    FILE_ATTRIBUTE_ARCHIVE

    The file should be archived. Applications use this attribute to mark files for backup or removal.

    FILE_ATTRIBUTE_HIDDEN

    The file is hidden. It is not to be included in an ordinary directory listing.

    FILE_ATTRIBUTE_NORMAL

    The file has no other attributes set. This attribute is valid only if used alone.

    FILE_ATTRIBUTE_READONLY

    The file is read-only. Applications can read the file but cannot write to it or delete it.

    FILE_ATTRIBUTE_SYSTEM

    The file is part of or is used exclusively by the operating system.

    FILE_ATTRIBUTE_TEMPORARY

    This attribute flag is not supported; however, if you have an installed file system that supports FILE_ATTRIBUTE_TEMPORARY, you can set or receive this flag. For example, the network redirector shows this flag if you are talking to a computer running Windows NT. Also, if you have a flash card inserted, the attributes of \StorageCard include the temporary bit.

    Any combination of the following flags is acceptable for the dwFlagsAndAttributes parameter.

    Value Description

    FILE_FLAG_WRITE_THROUGH

    Instructs the system to write through any intermediate cache and go directly to disk. The system can still cache write operations, but cannot lazily flush them.

    FILE_FLAG_OVERLAPPED

    This flag is not supported; however, multiple reads/writes pending on a device at a time are allowed.

    FILE_FLAG_RANDOM_ACCESS

    Indicates that the file is accessed randomly. The system can use this as a hint to optimize file caching.

    FILE_FLAG_SEQUENTIAL_SCAN

    Indicates that the file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed. Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.
  • hTemplateFile
    [in] Ignored; as a result, IRAPISession::CeCreateFile 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 method call and dwCreationDisposition is CREATE_ALWAYS or OPEN_ALWAYS, a call to IRAPISession::CeGetLastError returns ERROR_ALREADY_EXISTS, even though the method has succeeded. If the file does not exist before the call, IRAPISession::CeGetLastError returns zero. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call IRAPISession::CeGetLastError. Call GetLastError to get information about errors that are not related to RAPI2.

Remarks

Use the IRAPISession::CeCloseHandle function to close an object handle returned by IRAPISession::CeCreateFile.

Specifying zero for dwDesiredAccess allows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a disk drive and the formats it supports without having a disk in the drive.

The following information shows how IRAPISession::CeCreateFile operates on files, communication resources, devices, services, consoles, and directories:

Ee496774.collapse(en-US,WinEmbedded.60).gifFiles

When creating a new file or truncating an existing file, the IRAPISession::CeCreateFile method performs the following actions:

  • Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.
  • Sets the file length to zero.

IRAPISession::CeCreateFile cannot be used to access files in the MODULES section of ROM. Modules are stored in a different format that applications cannot access. The only ROM files that can be accessed using IRAPISession::CeCreateFile are those in the FILES section.

When opening an existing file, IRAPISession::CeCreateFile ignores the file attributes specified by dwFlagsAndAttributes and sets the file length according to the value of dwCreationDisposition.

To store the maximum number of files on PC card storage devices, limit file names to eight uppercase characters and file extensions to three uppercase characters. Also, do not allow non-OEM characters in file names. File names that do not conform to these limits require more than one physical directory entry on a PC Card.

Using the FILE_FLAG_RANDOM_ACCESS flag in the RAM file system, which places files in the object store, will prevent a file from being compressed. If performance is an issue, this could be the correct solution. Read and write operations to a compressed file are slower than read and write operations to an uncompressed file.

The OS does not support the concept of a current directory. If a path to a file is not supplied along with the file name, the OS will look for the file in the Windows directory as well as in the root of the file system. To access a file in any other path, the application must supply the absolute path to the file. In some cases, the GetModuleFileName function can supply the working directory of the currently running executable file.

Ee496774.collapse(en-US,WinEmbedded.60).gifCOM ports

The IRAPISession::CeCreateFile method can create a handle to a COM port. By setting the dwCreationDisposition parameter to OPEN_EXISTING, read-only, write-only, or read/write access can be specified.

Ee496774.collapse(en-US,WinEmbedded.60).gifDevices

Volume handles may be opened as noncached at the discretion of the file system, even when the noncached option is not specified with IRAPISession::CeCreateFile. You should assume that all Microsoft file systems open volume handles as noncached. The restrictions on noncached I/O for files also apply to volumes.

A file system may or may not require buffer alignment even though the data is noncached. However, if the noncached option is specified when opening a volume, buffer alignment is enforced regardless of the file system on the volume. Microsoft recommends that all file systems open volume handles as noncached and follow the noncached I/O restrictions.

You can use IRAPISession::CeCreateFile to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device. That handle can be used with the DeviceIoControl function. The following list shows the requirements that must be met for such a call to succeed:

  • The caller must have administrative privileges for the operation to succeed on a hard disk drive.
  • The lpFileName string should be of the form DSKx: to open the hard disk x. Hard disk numbers start at one. For example, DSK2: obtains a handle to the second physical drive on the user's computer.
  • The dwCreationDisposition parameter must have the OPEN_EXISTING value.
  • When opening a disk or a partition on a hard disk, you must set the FILE_SHARE_WRITE flag in the dwShareMode parameter.

Ee496774.collapse(en-US,WinEmbedded.60).gifServices

For information on using IRAPISession::CeCreateFile with services, see Services.exe.

Ee496774.collapse(en-US,WinEmbedded.60).gifConsoles

If Console.dll is present in the OS image, an application can use the direct console name, CONn:, to open the console with IRAPISession::CeCreateFile, if it has been previously registered. In the console name, n specifies a number between 0 and 9.

Ee496774.collapse(en-US,WinEmbedded.60).gifDirectories

An application cannot create a directory with IRAPISession::CeCreateFile. It must call IRAPISession::CeCreateDirectory.

Requirements

Header rapi2.h
Library ole32.lib, rapiuuid.lib
Windows Embedded CE Windows Embedded CE 6.0 and later

See Also

Reference

IRAPISession
IRAPISession::CeDeleteFile
IRAPISession::CeCopyFile
IRAPISession::CeMoveFile