CreateFile
The CreateFile function creates or opens the following objects and returns a handle that can be used to access
the object:
files
pipes
mailslots
communications resources
disk devices(Windows NT only)
consoles
directories(open only)
CreateFile 函數創建或打開下列對象，並返回一個可以用來訪問這些對象的句柄。
文件
pipes
郵槽
通信資源
磁盤驅動器（僅適用於 windowsNT ）
控制檯
文件夾（僅用於打開）
HANDLE CreateFile(
LPCTSTR lpFileName, // 指向文件名的指針
DWORD dwDesiredAccess, // 訪問模式（寫 / 讀）
DWORD dwShareMode, // 共享模式
LPSECURITY_ATTRIBUTES lpSecurityAttributes, // 指向安全屬性的指針
DWORD dwCreationDisposition, // 如何創建
DWORD dwFlagsAndAttributes, // 文件屬性
HANDLE hTemplateFile // 用於複製文件句柄
);
Parametes
參數列表
|
參數 |
類型及說明 |
|
|
lpFileName |
String ，要打開的文件的名字 |
|
|
dwDesiredAccess |
Long ，如果爲 GENERIC_READ 表示允許對設備進行讀訪問；如果爲 GENERIC_WRITE 表示允許對設備進行寫訪問（可組合使用）；如果爲零，表示只允許獲取與一個設備有關的信息 |
|
|
dwShareMode |
Long ，零表示不共享； FILE_SHARE_READ 和 / 或 FILE_SHARE_WRITE 表示允許對文件進行共享訪問 |
|
|
lpSecurityAttributes |
SECURITY_ATTRIBUTES ，指向一個 SECURITY_ATTRIBUTES 結構的指針，定義了文件的安全特性（如果操作系統支持的話） |
|
|
dwCreationDisposition |
Long ，下述常數之一： |
|
|
CREATE_NEW |
創建文件；如文件存在則會出錯 |
|
|
CREATE_ALWAYS |
創建文件，會改寫前一個文件 |
|
|
OPEN_EXISTING |
文件必須已經存在。由設備提出要求 |
|
|
OPEN_ALWAYS |
如文件不存在則創建它 |
|
|
TRUNCATE_EXISTING |
講現有文件縮短爲零長度 |
|
|
dwFlagsAndAttributes |
Long ，一個或多個下述常數 |
|
|
FILE_ATTRIBUTE_ARCHIVE |
標記歸檔屬性 |
|
|
FILE_ATTRIBUTE_COMPRESSED |
將文件標記爲已壓縮，或者標記爲文件在目錄中的默認壓縮方式 |
|
|
FILE_ATTRIBUTE_NORMAL |
默認屬性 |
|
|
FILE_ATTRIBUTE_HIDDEN |
隱藏文件或目錄 |
|
|
FILE_ATTRIBUTE_READONLY |
文件爲只讀 |
|
|
FILE_ATTRIBUTE_SYSTEM |
文件爲系統文件 |
|
|
FILE_FLAG_WRITE_THROUGH |
操作系統不得推遲對文件的寫操作 |
|
|
FILE_FLAG_OVERLAPPED |
允許對文件進行重疊操作 |
|
|
FILE_FLAG_NO_BUFFERING |
禁止對文件進行緩衝處理。文件只能寫入磁盤卷的扇區塊 |
|
|
FILE_FLAG_RANDOM_ACCESS |
針對隨機訪問對文件緩衝進行優化 |
|
|
FILE_FLAG_SEQUENTIAL_SCAN |
針對連續訪問對文件緩衝進行優化 |
|
|
FILE_FLAG_DELETE_ON_CLOSE |
關閉了上一次打開的句柄後，將文件刪除。特別適合臨時文件 |
|
|
也可在 Windows NT 下組合使用下述常數標記： |
||
|
SECURITY_ANONYMOUS ， SECURITY_IDENTIFICATION ， SECURITY_IMPERSONATION ， SECURITY_DELEGATION ，SECURITY_CONTEXT_TRACKING ， SECURITY_EFFECTIVE_ONLY |
||
|
hTemplateFile |
Long ，如果不爲零，則指定一個文件句柄。新文件將從這個文件中複製擴展屬性 |
|
返回值
如執行成功，則返回文件句柄。 INVALID_HANDLE_VALUE 表示出錯，會設置 GetLastError 。即使函數成功，但若文件存在，且指定了 CREATE_ALWAYS 或 OPEN_ALWAYS ， GetLastError 也會設爲ERROR_ALREADY_EXISTS
lpFileName
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, This limit is
related to how the CreateFile function parses paths.
如果 lpFileName 的對象是一個路徑，則有一個最大字符數的限制。不能超過常量 (MAX_PATH). 這個限制指示了
CreateFile 函數如何解析路徑 .
dwDesiredAccess
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
指定對象的訪問方式 , 程序可以獲得讀訪問權 , 寫訪問權 , 讀寫訪問權或者是詢問設備 ("device query") 訪問權 .
這個參數可以是下列值的任意組合
Value( 值 ) Meaning( 含義 )
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 組合
成爲 " 讀寫訪問權 ".
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 fro read-write access
指定寫訪問權 . 可以從文件中寫入數據 , 並且移動文件指針 . 可以和 GENERIC_READ 組合
成爲 " 讀寫訪問權 ".
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.
設置位標誌指明對象如休共享 . 如果參數是 0, 對象不能夠共享 . 後續的打開對象的操作將會失敗 , 直到該對象的句
柄關閉 .
To share the object, use a combination of one or more of the following values:
使用一個或多個下列值的組合來共享一個對象 .
Value( 值 ) Meaning( 含義 )
FILE_SHARE_DELETE WindowsNT: Subsequent open operations on the object will succeed only if
delete access is requested.
WINDOWS NT: 後續的僅僅請求刪除訪問權的打開操作將會成功 .
FILE_SHARE_READ Subsequent open operations on the object will successd only if read access
is requested.
後續的僅僅請求讀訪問權的打開操作將會成功 .
FILE_SHARE_WRITE Subsequent open operations on the object will succeed only if write access
is requested.
後續的僅僅請求寫訪問權的打開操作將會成功 .
lpSecurityAttributes
pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be
inherited by child processes, if lpSecurityAttributes is NULL, the handle cannot be inherited.
指向一個 SECURITY_ATTRIBUTES 結構的指針用於確定如何在子進程中繼承這個句柄 . 如果這個參數是 NULL,
則該句柄不可繼承 .
dwCreationDisposition
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( 值 ) Neaning( 含義 )
CREATE_NEW Creates a new file. The function fails if the specified file already exists
創建一個新文件 . 如果該文件已經存在函數則會失敗 .
CREATE_ALWAYS Creates a new file. If the file exsts, 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.
打開一個文件 , 如果文件不存在函數將會失敗 .
如查你使用 CreateFile 函數爲設備裝載控制檯 . 請查看批註中的 " 爲什麼使用
OPEN_EXISTING 標誌 " 的部分 .
OPEN_ALWAYS Opens the file, if it exsts. If the file does not exist, the function creates
the file as if dwCreationDisposition were CREATE_NEW.
如果文件存在 , 打開文件 . 如果文件不存在 , 並且參數中有 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.
打開一個文件 , 每次打開 , 文件將被截至 0 字節 . 調用進程必須用 GENERIC_WRITE 訪問模式打
開文件 . 如果文件不存在則函數就會失敗 .
dwFlagsAndatributes
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.
該參數可以接收下列屬性的任意組合 . 除非其它所有的文件屬性忽略 FILE_ATTRIBUTE_NORMAL.
Attribute( 屬性 ) Meaning( 標誌 )
FILE_ATTRIBUTE_ARCHIVE The ifle should be archived. Application 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_OFFLINE The data of the file is not immediately available. Indicates that the
file data has been physically moved to offline storage.
文件的數據沒有被立即用到。指出正在脫機使用該文件。
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 operation system.
文件是系統的一部分 , 或是系統專用的 .
FILE_ATTRIBUTE_TEMPORARY The file is being used for temporary storage. File systems attempt
to keep all of the data in memory for quicker access rather than
flushing the data back to mass storage. A temporary file should be
deleted by the application as soon as it is no longer needed.
文件被使用後，文件系統將努力爲（文件的）所有數據的迅迅訪問保持一塊
內存。臨時文件應當在程序不用時及時刪除。
Any combination of the following flags is acceptable for the dwFlagsAndAttributes parameter.
dwFlagAndAttributes 可以接受下列標誌的任意組合。
FLAG （標誌） Meaning( 含義 )
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 Instructs the system to initialize the object, so that operations that
take a significant amount of time to process return ERROR_IO_PENDING.
When the operation is finished, the specified event is set to the
signaled state.
指示系統初始化對象 , 此操作將對進程設置一個引用計數並返回 ERROR_IO_PENDING.
處理完成後 , 指定對象將被設置爲信號狀態 .
When you specify FILE_FLAG_OVERLAPPED, the file read and write functions
must specify an OVERLAPPED structure. That is, when FILE_FLAG_OVERLAPPED
is specified, an application must perform overlapped parameter(pointing
to an OVERLAPPED structure)to the file read and write functions.
This flag also enables more than one operation to be performed
simultaneously with the handle(a simultaneous read and write operation,
for example).
當你指定 FILE_FLAG_OVERLAPPED 時 , 讀寫文件的函數必須指定一個 OVERLAPPED 結構 .
並且 . 當 FILE_FLAG_OVERLAPPED 被指定 , 程序必須執行重疊參數 ( 指向 OVERLAPPED
結構 ) 去進行文件的讀寫 .
這個標誌也可以有超過一個操作去執行 .
FILE_FLAG_NO_BUFFERING Instructs the system to open the file with no intermediate buffering or
caching.When combined with FILE_FLAG_OVERLAPPED, the flag gives maximum
asynchronous performance, because the I/O does not rely on the synchronous
operations of the memory manager. However, some I/O operations will take
longer, because data is not being held in the cache.
指示系統不使用快速緩衝區或緩存，當和 FILE_FLAG_OVERLAPPED 組合 , 該標誌給出最
大的異步操作量 , 因爲 I/O 不依賴內存管理器的異步操作 . 然而 , 一些 I/O 操作將會運行
得長一些 , 因爲數據沒有控制在緩存中 .
An application must meet certain requirements when working with files
opened with FILE_FLAG_NO_BUFFERING:
當使用 FILE_FLAG_NO_BUFFERING 打開文件進行工作時 , 程序必須達到下列要求 :
File access must begin at byte offsets within the file that are
integer multiples of the volume's sector size.
文件的存取開頭的字節偏移量必須是扇區尺寸的整倍數 .
File access must be for numbers of bytes that are integer
multiples of the volume's sector size. For example, if the sector
size is 512 bytes, an application can request reads and writes of
512, 1024, or 2048 bytes, but not of 335, 981, or 7171bytes.
文件存取的字節數必須是扇區尺寸的整倍數 . 例如 , 如果扇區尺寸是 512 字節
程序就可以讀或者寫 512,1024 或者 2048 字節 , 但不能夠是 335,981 或者 7171
字節 .
buffer addresses for read and write operations must be sector
aligned(aligned on addresses in memory that are integer multiples
of the volume's sector size).
進行讀和寫操作的地址必須在扇區的對齊位置 , 在內存中對齊的地址是扇區
尺寸的整倍數 .
One way to align buffers on integer multiples of the volume sector size is
to use VirtualAlloc to allocate the buffers, It allocates memory that is
aligned on addresses that are integer multiples of the operating system's
memory page size. Because both memory page and volume sector sizes are
powers of 2, this memory is also aligned on addresses that are integer
multiples of a volume's sector size.
一個將緩衝區與扇區尺寸對齊的途徑是使用 VirtualAlloc 函數 . 它分配與操作系統
內存頁大小的整倍數對齊的內存地址 . 因爲內存頁尺寸和扇區尺寸 --2 都是它們的冪 .
這塊內存在地址中同樣與扇區尺寸大小的整倍數對齊 .
An application can determine a volume's sector size by calling the
GetDiskFreeSpace function
程序可以通過調用 GetDiskFreeSpace 來確定扇區的尺寸 .
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.
指定這個標誌可以提高程序以順序訪問模式讀取大文件的性能 , 性能的提高在許多
程序讀取一些大的順序文件時是異常明顯的 . 但是可能會有小範圍的字節遺漏 .
FILE_FLAG_DELETE_ON_CLOSE Indicates that the operating system is to delete the file immediately
after all of its handles have been closed, not just the handle for which
you specified FILE_FLAG_DELETE_ON_CLOSE.
指示系統在文件所有打開的句柄關閉後立即刪除文件 . 不只有你可以指定 FILE_FLAG_DELETE_ON_CLOSE
Subsequent open requests for the file will fail, unless FILE_SHARE_DELETE
is used.
如果沒有使用 FILE_SHARE_DELETE, 後續的打開文件的請求將會失敗 .
FILE_FLAG_BACKUP_SEMANTICS WINDOWS NT:Indicates that the file is being opened or created for a backup
or restore operation.The system ensures that the calling process overrides
file security checks, provided it has the necessary privileges. The
relevant privileges are SE_BACKUP_NAME and SE_RESTORE_NAME.
WINDOWS NT: 指示系統爲文件的打開或創建執行一個備份或恢復操作 . 系統保證調
用進程忽略文件的安全選項 , 倘若它必須有一個特權 . 則相關的特權則是 SE_BACKUP_NAME
和 SE_RESTORE_NAME.
You can also set this flag to obtain a handle to a directory. A directory
handle can be passed to some Win32 functions in place of a file handle.
你也可以使用這個標誌獲得一個文件夾的句柄，一個文件夾句柄能夠象一個文件句柄
一樣傳給某些 Win32 函數。
FILE_FLAG_POSIX_SEMANTICS Indicates that the file is to be accessed according to POSIX rules. This
includes allowing multiple files with names, differing only in case, for file
systems that support such naming. Use care when using this option because
files created with this flag may not be accessible by applications written
for MS-DOS or 16-bit Windows.
指明文件符合 POSIX 標準 . 這是在 MS-DOS 與 16 位 Windows 下的標準 .
FILE_FLAG_OPEN_REPARSE_POINT Specifying this flag inhibits the reparse behavior of NTFS reparse points.
When the file is opened, a file handle is returned, whether the filter that
controls the reparse point is operational or not. This flag cannot be used
with the CREATE_ALWAYS flag.
指定這個標誌制約 NTFS 分區指針 . 該標誌不能夠和 CREAT_ALWAYS 一起使用 .
FILE_FLAG_OPEN_NO_RECALL Indicates that the file data is requested,but it should continue to reside in
remote storage. It should not be transported back to local storage. This flag
is intended for use by remote storage systems or the Hierarchical Storage
Management system.
指明需要文件數據 , 但是將繼續從遠程存儲器中接收 . 它不會將數據存放在本地存儲器中 .
這個標誌由遠程存儲系統或等級存儲管理器系統使用 .
hTemplateFile
Specifies a handle with GENERIC_READ access to a template file. The template file supplies file attributes and
extended attributes for the file being created.
爲 GENERIC_READ 訪問的模式指定一個句柄到模板文件 . 模板文件在文件開始創建後提供文件屬性和擴展屬性 .
Return Values
返回值
If the function succeeds, the return value is an open handle to the specified file. If the specified file exists before
the function call and dwCreation 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.
如果函數成功 , 返回一個打開的指定文件的句柄 . 如果指定文件在函數調用前已經存在並且 dwCreation 參數是 CREATE_ALWAYS 或者
OPEN_ALWAYS, 調用 GetLastError 就會返回 ERROR_ALREADY_EXISTS( 表示函數成功 ). 如果函數文件在調用前不存在則會返回 0.
如果函數失敗 , 返會值會是 INVALID_HANDLE_VALUE. 更多的錯誤信息可以調用 GetLastError 來獲得 .
