winbase.h (OpenFile 函式)

  • 發行項

建立、開啟、重新開啟或刪除檔案。

注意 此函式具有有限的功能，不建議這麼做。 針對新的應用程式開發，請使用 CreateFile 函式。
 

語法

HFILE OpenFile(
  [in]  LPCSTR     lpFileName,
  [out] LPOFSTRUCT lpReOpenBuff,
  [in]  UINT       uStyle
);

參數

[in] lpFileName

檔案的名稱。

字串必須包含來自 8 位 Windows 字元集的字元。 OpenFile函式不支援 Unicode 檔案名或開啟具名管道。

[out] lpReOpenBuff

OFSTRUCT結構的指標，會在第一次開啟檔案時接收檔案的相關資訊。

結構可用於 後續對 OpenFile 函式的呼叫，以查看開啟的檔案。

OFSTRUCT結構包含長度限制為OFS_MAXPATHNAME字元的路徑字串成員，長度為 128 個字元。 因此，您無法使用 OpenFile 函式來開啟路徑長度超過 128 個字元的檔案。 CreateFile函式沒有此路徑長度限制。

[in] uStyle

要採取的動作。

此參數可以是下列一或多個值。

值 意義
OF_CANCEL
0x00000800
 忽略。

若要產生包含 [取消 ] 按鈕的對話方塊，請使用 OF_PROMPT。
OF_CREATE
0x00001000
 建立新檔案。

如果檔案存在，則會截斷為零 (0) 長度。
OF_DELETE
0x00000200
 刪除檔案。
OF_EXIST
0x00004000
 開啟檔案，然後關閉它。

使用此專案來測試檔案是否存在。
OF_PARSE
0x00000100
 填滿 OFSTRUCT 結構，但不會執行任何其他動作。
OF_PROMPT
0x00002000
 如果要求的檔案不存在，則會顯示對話方塊。

對話方塊會通知使用者系統找不到檔案，且其中包含 [重試 ] 和 [ 取消] 按鈕。 [ 取消] 按鈕會指示 OpenFile 傳回找不到檔案的錯誤訊息。
OF_READ
0x00000000
 開啟檔案為僅供讀取。
OF_READWRITE
0x00000002
 以讀取/寫入權限開啟檔案。
OF_REOPEN
0x00008000
 使用重新開啟緩衝區中的資訊開啟檔案。
OF_SHARE_COMPAT
0x00000000
 針對 MS-DOS 型檔案系統，開啟具有相容性模式的檔案，允許指定電腦上的任何進程任意次數開啟檔案。

開啟具有其他共用模式之檔案的其他工作失敗。 此旗標會對應至|CreateFile函式的FILE_SHARE_READ FILE_SHARE_WRITE旗標。
OF_SHARE_DENY_NONE
0x00000040
 開啟檔案，而不拒絕其他進程的讀取或寫入存取權。

在 MS-DOS 型檔案系統上，如果檔案已由任何其他進程以相容性模式開啟，則函式會失敗。

此旗標會對應至|CreateFile函式的FILE_SHARE_READ FILE_SHARE_WRITE旗標。
OF_SHARE_DENY_READ
0x00000030
 開啟檔案，並拒絕對其他進程的讀取存取。

在 MS-DOS 型檔案系統上，如果檔案已以相容性模式開啟，或供任何其他進程讀取存取，則函式會失敗。

此旗標會對應至CreateFile函式的FILE_SHARE_WRITE旗標。
OF_SHARE_DENY_WRITE
0x00000020
 開啟檔案，並拒絕其他進程的寫入存取權。

在 MS-DOS 型檔案系統上，如果檔案是以相容性模式開啟，或是任何其他進程的寫入存取權，則函式會失敗。

此旗標會對應至CreateFile函式的FILE_SHARE_READ旗標。
OF_SHARE_EXCLUSIVE
0x00000010
 開啟具有獨佔模式的檔案，並拒絕其他進程的讀取/寫入存取。 如果檔案已在任何其他模式中開啟以進行讀取/寫入存取，即使目前進程也一樣，函式也會失敗。
OF_VERIFY
 確認檔案的日期和時間與先前開啟的日期和時間相同。

這對於唯讀檔案的額外檢查很有用。
OF_WRITE
0x00000001
 以僅限寫入存取的形式開啟檔案。

傳回值

如果函式成功，傳回值會指定執行檔案 I/O 時要使用的檔案控制代碼。 若要關閉檔案，請使用這個控制碼呼叫 CloseHandle 函式。

如果函式失敗，傳回值會 HFILE_ERROR。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 lpFileName 參數只指定檔案名和副檔名，此函式會在下列目錄中搜尋相符的檔案，並依顯示的順序進行搜尋：

  1. 載入應用程式的目錄。
  2. 目前的目錄。
  3. Windows system 目錄。

    使用 GetSystemDirectory 函式來取得此目錄的路徑。

  4. 16 位 Windows 系統目錄。

    沒有可擷取此目錄路徑的函式，但會加以搜尋。

  5. Windows 目錄。

    使用 GetWindowsDirectory 函 式來取得此目錄的路徑。

  6. PATH 環境變數中所列的目錄。
lpFileName參數不能包含萬用字元。

OpenFile函式不支援 16 位 Windows OpenFile函式支援的OF_SEARCH旗標。 即使檔案名包含完整路徑， OF_SEARCH 旗標也會指示系統搜尋相符的檔案。 使用 SearchPath 函式來搜尋檔案。

如果嘗試在 uStyle 參數的值是 OF_DELETE存取旗 標或以任何其他存取旗標開啟遠端檔案或目錄，且遠端檔案或目錄尚未以共用存取權 FILE_SHARE_DELETE 開啟時，就會發生共用違規。 若要避免此案例中的共用違規，請只開啟 具有OF_DELETE 存取權的遠端檔案或目錄，或呼叫 DeleteFile 而不先開啟檔案或目錄以進行刪除。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

技術 支援
伺服器訊息區 (SMB) 3.0 通訊協定 Yes
SMB 3.0 透明容錯移轉 (TFO) Yes
具有向外延展檔案共用的 SMB 3.0 (SO) Yes
叢集共用磁片區檔案系統 (CsvFS) Yes
彈性檔案系統 (ReFS) Yes
 

CsvF 會針對壓縮檔進行重新導向的 IO。

規格需求

   
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 winbase.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CreateFile

檔案管理功能

GetSystemDirectory

GetWindowsDirectory

OFSTRUCT

SearchPath