CeCreateFile (RAPI)

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function creates, opens, or truncates a file, pipe, communications resource, disk device, or console. It returns a handle that can be used to access the object. It can also open and return a handle to a directory.

CeCreateFileis a remote application interface (RAPI), which enables an application running on a desktop computer to make function calls on a Windows CE–based device.

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 lpFileNameis a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CeCreateFilefunction parses paths.

You can use paths longer than MAX_PATH characters by prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing. This lets you use paths that are nearly 32,000 Unicode characters long. However, each component in the path cannot be more than MAX_PATH characters long. You must use fully-qualified paths with this technique. This also works with Universal Naming Convention (UNC) names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private" and "\\?\UNC\tom_1\hotstuff\coolapps" is seen as "\\tom_1\hotstuff\coolapps."

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 dwShareModeis 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.

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 CeCreateFilefunction 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 dwCreationDispositionwere 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.

Any combination of the following attributes is acceptable for the dwFlagsAndAttributesparameter, 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 dwFlagsAndAttributesparameter.

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.

hTemplateFile

[in] Ignored; as a result, CeCreateFiledoes 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 dwCreationDispositionis CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastErrorreturns ERROR_ALREADY_EXISTS, even though the function has succeeded. If the file does not exist before the call, GetLastErrorreturns zero. INVALID_HANDLE_VALUE indicates failure. To determine if a function failed because of RAPI errors, call CeRapiGetError.

Remarks

When writing applications for Windows CE version 1.0 and 1.01, use the PegCreateFilefunction.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Rapi.h