创建或打开文件或I/O设备。最常用的I/O设备如下:文件、文件流、目录、物理磁盘、卷、控制台缓冲区、磁带驱动器、通信资源、邮件插槽和管道。函数返回一个句柄,可以根据文件或设备和指定的标志和属性来访问各种类型的I/O文件或设备。
要将此操作作为事务处理操作执行,这将导致可用于事务处理I/O的句柄,使用CreateFileTransacted事务处理函数。
HANDLE WINAPI CreateFile(
_In_ LPCTSTR lpFileName, // 创建或打开文件或I/O设备。
_In_ DWORD dwDesiredAccess, // 请求访问文件或设备,可以将其概括为读取写入两者都可以或为零。
_In_ DWORD dwShareMode, // 文件或设备的请求共享模式
_In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes, // 指向安全属性结构的指针
_In_ DWORD dwCreationDisposition, // 对存在或不存在的文件或设备采取的操作。
_In_ DWORD dwFlagsAndAttributes, // 文件或设备属性和标志
_In_opt_ HANDLE hTemplateFile // 具有GENERIC_READ 访问权限的模板文件的有效句柄。
);
lpFileName: 参数
要创建或打开的文件或设备的名称。
dwDesiredAccess: 参数GENERIC_READ, GENERIC_WRITE,0
如果此参数为零,应用程序可以查询某些元数据,例如文件、目录或设备属性,而无需访问该文件或设备,即使已拒绝Generic_Read访问。
你不能要求一个访问模式和共享模式,是通过在一个开放的要求已经公开处理dwShareMode参数指定的冲突。
dwShareMode: 参数
文件或设备的请求共享模式,可以读取、写入、删除、全部或空;对属性或扩展属性的访问请求不受此标志的影响。
如果此参数为零且CreateFile成功,则文件或设备无法共享,无法再次打开,直到文件或设备的句柄已关闭。
你不能要求一个共享的模式,因为这个模式与一个开放的处理现有请求中指定的访问模式的冲突。CreateFile将失败,GetLastError函数将返回Error_SHARING_VIOLATION
若要使进程能够在另一个进程打开文件或设备时共享文件或设备,请使用下列一个或多个值的兼容组合。
Note:每个打开句柄的共享选项一直有效,直到该句柄关闭为止,无论进程上下文如何。
0 0x00000000
如果其他进程请求删除、读取或写入访问,则阻止其他进程打开文件或设备。
FILE_SHARE_READ 0x00000001 允许随后在文件或设备上打开操作请求读取访问。否则,其他进程如果请求读取访问权限,则无法打开该文件或设备。
如果未指定此标志,但已打开该文件或设备以进行读取访问,则该函数将失败。
FILE_SHARE_WRITE 0x00000002 允许随后在文件或设备上打开操作请求写入访问。否则,其他进程如果请求写入访问,则无法打开该文件或设备。
如果未指定此标志,但已打开该文件或设备以进行写入访问,或具有带有写访问权限的文件映射,则该函数将失败。
FILE_SHARE_DELETE 0x00000004 允许随后在文件或设备上打开操作请求删除访问。否则,其他进程如果请求删除访问,则无法打开该文件或设备。
如果未指定此标志,但已打开用于删除访问的文件或设备,则该函数将失败。
Note:删除访问既允许删除操作也可以重命名操作。
lpSecurityAttributes: 参数
指向安全属性结构的指针,该结构包含两个独立但相关的数据成员:一个可选的安全描述符,以及一个布尔值,它确定返回的句柄是否可以由子进程继承。
如果此参数为NULL,则应用程序可能创建的任何子进程无法继承CreateFile返回的句柄,并且与返回句柄关联的文件或设备将获得默认的安全描述符。
结构的lpSecurityDescriptor成员指定文件或设备的安全描述符,如果此成员为空,则将为与返回句柄关联的文件或设备分配默认安全描述符。
CreateFile在打开现有文件或设备时忽略lpSecurityDescriptor成员,但继续使用bInheritHandle成员。
结构的bInheritHandlember指定是否可以继承返回的句柄。
dwCreationDisposition: 参数
对存在或不存在的文件或设备采取的操作。对于文件以外的设备,通常将此参数设置为OPEN_RESTANING。
此参数必须是下列值之一:
CREATE_NEW 1
创建一个新文件,只在它尚未存在时才创建。
如果指定的文件存在,则函数将失败,最后一个错误代码被设置为ERROR_FILE_EXISTS(80)。
如果指定的文件不存在,并且是可写入位置的有效路径,则会创建一个新文件。
CREATE_ALWAYS 2
总是创建一个新文件。
如果指定的文件存在并且是可写的,则函数覆盖文件,函数成功,最后错误代码被设置为ERROR_READ_EXISTUS(183)
如果指定的文件不存在,并且是一个有效的路径,则创建一个新文件,函数成功,最后一个错误代码设置为零。
OPEN_EXISTING 3
只在文件或设备存在的情况下打开它。
如果指定的文件或设备不存在,则函数失败,最后一个错误代码被设置为ERROR_FILE_NOT_FRED(2)。
OPEN_ALWAYS 4
总是打开一个文件。
如果指定的文件存在,函数成功,最后的错误代码设置为error_already_exists(183)。
如果指定的文件不存在,并且是可写位置的有效路径,则函数将创建一个文件,并将最后一个错误代码设置为零。
TRUNCATE_EXISTING 5
打开一个文件并截断它,只有当文件存在时,它的大小才是零字节。
如果指定的文件不存在,则函数失败,最后一个错误代码被设置为ERROR_FILE_NOT_FRED(2)。
调用进程必须使用设置为dwDesiredAccess参数GENERIC_WRITE位打开文件。
dwFlagsAndAttributes: 参数
文件或设备属性和标志,FILE_ATTRIBUTE_NORMAL 是文件最常用的默认值。
此参数可以包含可用文件属性的任何组合(FILE_ATTRIBUTE_*)。所有其他文件属性都覆盖FILE_ATTRIBUTE_NORMAL。
此参数还可以包含用于控制文件或设备缓存行为、访问模式和其他特殊用途标志的标志(FILE_FLAG_*) 的组合。这些值与任何FILE_ATTRIBUTE_* 值相结合。
此参数还可以通过指定SECURITY_SQOS_PRESENT标志来包含安全服务质量(SQOS)信息。属性和标志表后面的表中显示了其他与SQOS相关的标志信息。
Note:当CreateFile打开一个现有文件时,它通常会将文件标志与现有文件的文件属性组合起来,并忽略作为dwFlagsAndAttributes的一部分提供的任何文件属性。
以下一些文件属性和标志可能只适用于文件,而不一定适用于CreateFile可以打开的所有其他类型的设备。
Attribute:
FILE_ATTRIBUTE_ARCHIVE 32(0x20)
文件应该存档。应用程序使用此属性标记用于备份或删除的文件。
FILE_ATTRIBUTE_ENCRYPTED 16384(0x4000)
文件或目录加密。对于文件,这意味着文件中的所有数据都是加密的。对于目录,这意味着加密是新创建的文件和子 目录的默认设置。
如果还指定了FILE_ATTRIBUTE_SYSTEM ,则此标志无效。
这种标志不支持家庭,家庭高级,初学者或ARM版本的Windows。
FILE_ATTRIBUTE_HIDDEN 2(0x2)
文件是隐藏的。不要将其包含在普通目录列表中。
FILE_ATTRIBUTE_NORMAL 128 (0x80)
该文件没有设置其他属性。仅当单独使用此属性时,该属性才有效。
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)
文件的数据不能立即可用。此属性指示文件数据物理地移动到脱机存储。这个属性被分层存储管理软件 RemoteStorage所使用。应用程序不应任意更改此属性。
FILE_ATTRIBUTE_READONLY 1 (0x1)
文件是只读的。应用程序可以读取文件,但不能写入或删除该文件。
FILE_ATTRIBUTE_SYSTEM 4 (0x4)
该文件是操作系统的一部分或专用的。
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)该文件将用于临时存储。
hTemplateFile: 参数
具有GENERIC_READ 访问权限的模板文件的有效句柄。模板文件为正在创建的文件提供文件属性和扩展属性。
此参数可以为空。
打开现有文件时,CreateFile将忽略此参数。
打开新加密文件时,该文件从其父目录继承任意访问控制列表。
Return value:
如果函数成功,返回值是指定文件、设备、命名管道或邮件插槽的打开句柄。
如果函数失败,则返回值INVALID_HANDLE_VALUE。要获得扩展错误信息,请调用GetLastError。