See Also
Call this method to create or open a file.
HRESULT Create( LPCTSTR szFilename, DWORD dwDesiredAccess, DWORD dwShareMode, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL, LPSECURITY_ATTRIBUTES lpsa = NULL, HANDLE hTemplateFile = NULL ) throw( );
Parameters
- szFilename
- The file name.
- dwDesiredAccess
- The desired access. See dwDesiredAccess in tabindex="0" keywords="_win32_CreateFile"/>CreateFile in the Platform SDK.
- dwShareMode
- The share mode. See dwShareMode in CreateFile.
- dwCreationDisposition
- The creation disposition. See dwCreationDisposition in CreateFile.
- dwFlagsAndAttributes
- The flags and attributes. See dwFlagsAndAttributes in CreateFile.
- lpsa
- The security attributes. See lpSecurityAttributes in CreateFile.
- hTemplateFile
- The template file. See hTemplateFile in CreateFile.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
[in] Pointer to a null-terminated string that specifies the name of the object to create or open.
In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "//?/" to the path. For more information, see Naming a File.
dwDesiredAccess
[in] Access to the object (reading, writing, or both). For a list of values, see File Security and Access Rights. You cannot request an access mode that conflicts with the sharing mode specified in a previous open request whose handle is still open.
If this parameter is zero, the application can query file and device attributes without accessing the device. This is useful if an application wants to determine the size of a floppy disk drive and the formats it supports without requiring a floppy in the drive. It can also be used to test for the file's or directory's existence without opening it for read or write access.
dwShareMode[in] Sharing mode of the object (reading, writing, both, or neither). You cannot request a sharing mode that conflicts with the access mode specified in a previous open request whose handle is still open. Doing so would result in a sharing violation (ERROR_SHARING_VIOLATION). See Creating and Opening Files for details and examples.
If this parameter is zero and CreateFile succeeds, the object cannot be shared and cannot be opened again until the handle is closed. For more information about sharing violations, see the Remarks section.
To enable other processes to share the object while your process has it open, use a combination of one or more of the following values to specify the access mode they can request when they open the object. These sharing options remain in effect until you close the handle to the object.
lpSecurityAttributes[in] Pointer to a tabindex="0" keywords="security.security_attributes" errorurl="../common/badjump.htm"/>SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.
The lpSecurityDescriptor member of the structure specifies a tabindex="0" keywords="security.security_descriptor" errorurl="../common/badjump.htm"/>security descriptor for the object. If lpSecurityAttributes is NULL, the object gets a default security descriptor. The ACLs in the default security descriptor for a file or directory are inherited from its parent directory. Note that the target file system must support security on files and directories for this parameter to have an effect on them. (This is indicated when GetVolumeInformation returns FS_PERSISTENT_ACLS.) CreateFile ignores lpSecurityDescriptor when opening an existing file, but continues to use the other structure members.
dwCreationDisposition[in] 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.
2.File Security and Access Rights
dwDesiredAccess:
The valid access rights for files and directories include the DELETE, READ_CONTROL, WRITE_DAC, and WRITE_OWNER tabindex="0" keywords="security.standard_access_rights" errorurl="../common/badjump.htm"/>standard. The following table lists the access rights that are specific to files and directories.
| Access right | Description |
|---|---|
| FILE_ADD_FILE | For a directory, the right to create a file in the directory. |
| FILE_ADD_SUBDIRECTORY | For a directory, the right to create a subdirectory. |
| FILE_ALL_ACCESS | All possible access rights for a file. |
| FILE_APPEND_DATA | For a file object, the right to append data to the file. For a directory object, the right to create a subdirectory. |
| FILE_CREATE_PIPE_INSTANCE | For a named pipe, the right to create a pipe. |
| FILE_DELETE_CHILD | For a directory, the right to delete a directory and all the files it contains, including read-only files. |
| FILE_EXECUTE | For a native code file, the right to execute the file. This access right given to scripts may cause the script to be executable, depending on the script interpreter. |
| FILE_LIST_DIRECTORY | For a directory, the right to list the contents of the directory. |
| FILE_READ_ATTRIBUTES | The right to read file attributes. |
| FILE_READ_DATA | For a file object, the right to read the corresponding file data. For a directory object, the right to read the corresponding directory data. |
| FILE_READ_EA | The right to read extended file attributes. |
| FILE_TRAVERSE | For a directory, the right to traverse the directory. By default, users are assigned the BYPASS_TRAVERSE_CHECKING tabindex="0" keywords="security.privileges" errorurl="../common/badjump.htm"/>privilege, which ignores the FILE_TRAVERSE tabindex="0" keywords="security.access_rights_and_access_masks" errorurl="../common/badjump.htm"/>access right. See the remarks later in this section for more information. |
| FILE_WRITE_ATTRIBUTES | The right to write file attributes. |
| FILE_WRITE_DATA | For a file object, the right to write data to the file. For a directory object, the right to create a file in the directory. |
| FILE_WRITE_EA | The right to write extended file attributes. |
| STANDARD_RIGHTS_READ | Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor. This does not include the information in the SACL. |
| STANDARD_RIGHTS_WRITE | Includes WRITE_CONTROL, which is the right to write to the directory object's security descriptor. This does not include the information in the SACL. |
| SYNCHRONIZE | The right to specify a file handle in one of the wait functions. However, for asynchronous file I/O operations, you should wait on the event handle in an tabindex="0" keywords="base.overlapped_str" errorurl="../common/badjump.htm"/>OVERLAPPED structure rather than using the file handle for synchronization. |
The following are the tabindex="0" keywords="security.generic_access_rights" errorurl="../common/badjump.htm"/>generic access rights for files and directories.
| Access right | Description |
|---|---|
| GENERIC_EXECUTE | FILE_READ_ATTRIBUTES STANDARD_RIGHTS_EXECUTE SYNCHRONIZE |
| GENERIC_READ | FILE_READ_ATTRIBUTES FILE_READ_DATA FILE_READ_EA STANDARD_RIGHTS_READ SYNCHRONIZE |
| GENERIC_WRITE | FILE_APPEND_DATA FILE_WRITE_ATTRIBUTES FILE_WRITE_DATA FILE_WRITE_EA STANDARD_RIGHTS_WRITE SYNCHRONIZE |
EXAMPLE:
hFile = CreateFile(fileName,
WRITE_OWNER|WRITE_DAC,
0,
NULL,
CREATE_ALWAYS,
FILE_FLAG_BACKUP_SEMANTICS,
NULL);The following table illustrates the valid combinations of accessmodes and sharing modes.
(Note that the table heading row uses abbreviations to reduce the table width.
The heading row should read the same as the first column.)
| G_R FS_R | G_R FS_W | G_R FS_R FS_W | G_W FS_R | G_W FS_W | G_W FS_R FS_W | G_R G_W FS_R | G_R G_W FS_W | G_R G_W FS_R FS_W | |
|---|---|---|---|---|---|---|---|---|---|
| GENERIC_READ FILE_SHARE_READ | X | X | |||||||
| GENERIC_READ FILE_SHARE_WRITE | X | X | |||||||
| GENERIC_READ FILE_SHARE_READ FILE_SHARE_WRITE | X | X | X | X | X | X | |||
| GENERIC_WRITE FILE_SHARE_READ | X | X | |||||||
| GENERIC_WRITE FILE_SHARE_WRITE | X | X | |||||||
| GENERIC_WRITE FILE_SHARE_READ FILE_SHARE_WRITE | X | X | X | X | X | X | |||
| GENERIC_READ GENERIC_WRITE FILE_SHARE_READ | X | ||||||||
| GENERIC_READ GENERIC_WRITE FILE_SHARE_WRITE | X | ||||||||
| GENERIC_READ GENERIC_WRITE FILE_SHARE_READ FILE_SHARE_WRITE | X | X |
dwShareMode
| Value | Meaning |
|---|---|
| FILE_SHARE_DELETE | Enables subsequent open operations on the object to request delete access. Otherwise, other processes cannot open the object if they request delete access. Windows Me/98/95: This flag is not supported. |
| FILE_SHARE_READ | Enables subsequent open operations on the object to request read access. Otherwise, other processes cannot open the object if they request read access. |
| FILE_SHARE_WRITE | Enables subsequent open operations on the object to request write access. Otherwise, other processes cannot open the object if they request write access. |
dwCreationDisposition
| Value | Meaning |
|---|---|
| CREATE_ALWAYS | Creates a new file. If the file exists, the function overwrites the file, clears the existing attributes, combines the specified file attributes and flags with FILE_ATTRIBUTE_ARCHIVE, but does not set the security descriptor specified by the SECURITY_ATTRIBUTES structure. |
| 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 dwCreationDisposition were CREATE_NEW. |
| OPEN_EXISTING | Opens the file. The function fails if the file does not exist. For a discussion of why you should use OPEN_EXISTING for devices, see Remarks. |
| TRUNCATE_EXISTING | Opens the file and truncates it so that its size is zero bytes. The calling process must open the file with the GENERIC_WRITE access right. The function fails if the file does not exist. |