OPENFILENAMEA 結構 (commdlg.h)

[從 Windows Vista 開始，通用專案對話方塊已取代[開啟] 和 [另存新檔] 通用對話方塊。 我們建議您使用通用專案對話方塊 API，而不是來自通用對話方塊程式庫的這些對話方塊。

包含 GetOpenFileName 和 GetSaveFileName 函式用來初始化 [開啟 ] 或 [ 另存新 檔] 對話方塊的資訊。 使用者關閉對話方塊之後，系統會傳回此結構中使用者選取專案的相關資訊。

語法

typedef struct tagOFNA {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCSTR        lpstrFilter;
  LPSTR         lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPSTR         lpstrFile;
  DWORD         nMaxFile;
  LPSTR         lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCSTR        lpstrInitialDir;
  LPCSTR        lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCSTR        lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCSTR        lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEA, *LPOPENFILENAMEA;

成員

lStructSize

類型： DWORD

結構的長度，以位元組為單位。 用於 sizeof (OPENFILENAME) 此參數。

hwndOwner

類型： HWND

擁有對話方塊之視窗的控制碼。 此成員可以是任何有效的視窗控制碼，如果對話方塊沒有擁有者，則為 Null 。

hInstance

類型： HINSTANCE

如果在Flags成員中設定OFN_ENABLETEMPLATEHANDLE旗標，hInstance是包含對話方塊範本的記憶體物件控制碼。 如果 已設定OFN_ENABLETEMPLATE 旗標， hInstance 是模組的控制碼，其中包含 由 lpTemplateName 成員命名的對話方塊範本。 如果兩個旗標都未設定，則會忽略這個成員。 如果 已設定OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話方塊，該對話方塊是預設 Explorer 樣式對話方塊的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代預設對話方塊的舊樣式對話方塊。

lpstrFilter

類型： LPCTSTR

緩衝區，包含以 Null 結尾的篩選字串配對。 緩衝區中的最後一個字串必須以兩個 Null 字元終止。

每個配對中的第一個字串都是一個顯示字串，描述篩選 (例如「文字檔」) ，而第二個字串則指定篩選模式 (例如 ".TXT" ，) 。 若要指定單一顯示字串的多個篩選模式，請使用分號分隔模式 (，例如 「 .TXT;.DOC;。BAK」 ) 。 模式字串可以是有效檔案名字元和星號 (*) 萬用字元的組合。 請勿在模式字串中包含空格。

系統不會變更篩選的順序。 它會以lpstrFilter中指定的順序，在[檔案類型] 下拉式方塊中顯示它們。

如果 lpstrFilter 為 Null，對話方塊就不會顯示任何篩選。

在快捷方式的情況下，如果未設定任何篩選， GetOpenFileName 和 GetSaveFileName 會擷取 .lnk 檔案的名稱，而不是其目標。 此行為與在Flags成員中設定OFN_NODEREFERENCELINKS旗標相同。 若要在不篩選的情況下擷取快捷方式的目標，請使用字串 "All Files\0*.*\0\0" 。

lpstrCustomFilter

類型： LPTSTR

靜態緩衝區，其中包含一對以 Null 終止的篩選字串，以保留使用者所選擇的篩選模式。 第一個字串是描述自訂篩選的顯示字串，而第二個字串則是使用者選取的篩選模式。 第一次應用程式建立對話方塊時，您會指定第一個字串，可以是任何無空字串。 當使用者選取檔案時，對話方塊會將目前的篩選模式複製到第二個字串。 保留的篩選模式可以是 lpstrFilter 緩衝區中指定的其中一個模式，也可以是使用者輸入的篩選模式。 系統會使用字串，在下次建立對話方塊時初始化使用者定義檔案篩選。 如果 nFilterIndex 成員為零，對話方塊會使用自訂篩選。

如果這個成員是 Null，對話方塊就不會保留使用者定義的篩選模式。

如果這個成員不是 Null， nMaxCustFilter 成員的值必須指定 lpstrCustomFilter 緩衝區的大小，以字元為單位。

nMaxCustFilter

類型： DWORD

lpstrCustomFilter所識別之緩衝區的大小，以字元為單位。 此緩衝區長度至少應為 40 個字元。 如果 lpstrCustomFilter 為 Null 或指向 Null 字串，則會忽略這個成員。

nFilterIndex

類型： DWORD

[ 檔案類型 ] 控制項中目前選取篩選的索引。 lpstrFilter所指向的緩衝區包含定義篩選準則的字串組。 第一組字串的索引值為 1、第二對 2 等等。 零的索引表示 lpstrCustomFilter所指定的自訂篩選。 您可以在輸入上指定索引，以指出對話方塊的初始篩選描述和篩選模式。 當使用者選取檔案時， nFilterIndex 會傳回目前顯示之篩選的索引。 如果 nFilterIndex 為零， 且 lpstrCustomFilter 為 Null，則系統會使用 lpstrFilter 緩衝區中的第一個篩選。 如果這三個成員都是零或 Null，則系統不會使用任何篩選，也不會在對話方塊的檔案清單控制項中顯示任何檔案。

lpstrFile

類型： LPTSTR

用來初始化檔案名編輯控制項的 檔案名 。 如果不需要初始化，此緩衝區的第一個字元必須是 Null 。 當 GetOpenFileName 或 GetSaveFileName 函式成功傳回時，此緩衝區會包含所選檔案的磁片磁碟機指示項、路徑、檔案名和副檔名。

如果 已設定OFN_ALLOWMULTISELECT 旗標，且使用者選取多個檔案，則緩衝區會包含目前的目錄，後面接著所選檔案的檔案名。 針對 [總管樣式] 對話方塊，目錄和檔案名字串會以 Null 分隔，並在姓氏後面加上額外的 Null 字元。 針對舊樣式對話方塊，字串會以空格分隔，而函式會針對具有空格的檔案名使用簡短檔案名。 您可以使用 FindFirstFile 函式，在 long 和 short 檔案名之間轉換。 如果使用者只選取一個檔案， lpstrFile 字串在路徑和檔案名之間沒有分隔符號。

如果緩衝區太小，函式會傳回 FALSE ， 而 CommDlgExtendedError 函式會傳回 FNERR_BUFFERTOOSMALL。 在此情況下， lpstrFile 緩衝區的前兩個位元組包含所需的大小，以位元組或字元為單位。

nMaxFile

類型： DWORD

lpstrFile所指向之緩衝區的大小，以字元為單位。 緩衝區必須夠大，才能儲存路徑和檔案名字串或字串，包括終止 的 Null 字元。 如果緩衝區太小而無法包含檔案資訊， GetOpenFileName 和 GetSaveFileName 函式會傳回 FALSE 。 緩衝區長度至少應為 256 個字元。

lpstrFileTitle

類型： LPTSTR

檔案名和副檔名 (，沒有所選檔案的路徑資訊) 。 這個成員可以是 Null。

nMaxFileTitle

類型： DWORD

lpstrFileTitle所指向之緩衝區的大小，以字元為單位。 如果 lpstrFileTitle 為 Null，則會忽略這個成員。

lpstrInitialDir

類型： LPCTSTR

初始目錄。 選取初始目錄的演算法會因不同平臺而異。

Windows 7：

1. 如果lpstrInitialDir第一次使用[開啟] 或[另存新檔] 對話方塊時傳遞了相同的值，則使用者最近選取的路徑會當做初始目錄使用。
2. 否則，如果 lpstrFile 包含路徑，該路徑就是初始目錄。
3. 否則，如果 lpstrInitialDir 不是 Null，它會指定初始目錄。
4. 如果 lpstrInitialDir 是 Null ，而目前的目錄包含指定之篩選類型的任何檔案，則初始目錄是目前的目錄。
5. 否則，初始目錄是目前使用者的個人檔案目錄。
6. 否則，初始目錄是 Desktop 資料夾。

1. 如果 lpstrFile 包含路徑，該路徑就是初始目錄。
2. 否則， lpstrInitialDir 會指定初始目錄。
3. 否則，如果應用程式在過去使用了 [開啟 ] 或 [ 另存 新檔] 對話方塊，則會選取最近使用的路徑作為初始目錄。 不過，如果應用程式未長時間執行，則會捨棄其已儲存的路徑。
4. 如果 lpstrInitialDir 是 Null ，而目前的目錄包含指定之篩選類型的任何檔案，則初始目錄是目前的目錄。
5. 否則，初始目錄是目前使用者的個人檔案目錄。
6. 否則，初始目錄是 Desktop 資料夾。

lpstrTitle

類型： LPCTSTR

要放在對話方塊標題列中的字串。 如果此成員為 Null，系統會使用預設標題 (，也就是 [另存 新檔] 或 [ 開啟 ]) 。

Flags

類型： DWORD

一組可用來初始化對話方塊的位旗標。 當對話方塊傳回時，它會設定這些旗標來指出使用者的輸入。 這個成員可以是下列旗標的組合。

nFileOffset

類型： WORD

以零起始的位移，以字元為單位，從 lpstrFile所指向字串中檔案名的路徑開頭。 針對 ANSI 版本，這是位元組數目;針對 Unicode 版本，這是字元數。 例如，如果 lpstrFile 指向下列字串 「c：\dir1\dir2\file.ext」，此成員會包含值 13，表示 「file.ext」 字串的位移。 如果使用者選取多個檔案， 則 nFileOffset 是第一個檔案名的位移。

nFileExtension

類型： WORD

以零起始的位移，以字元為單位，從 lpstrFile指向之字串中副檔名的路徑開頭。 針對 ANSI 版本，這是位元組數目;針對 Unicode 版本，這是字元數。 副檔名通常是子字串，後面接著最後一個出現的點 (「。」) 字元。 例如，txt 是檔案名的副檔名 readme.txt，html 為 readme.txt.html 的副檔名。 因此，如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt」，此成員會包含值 20。 如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt.html」，此成員會包含值 24。 如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt.html.」。，此成員會包含值 29。 如果 lpstrFile 指向不包含任何 「.」 字元的字串，例如 「c：\dir1\dir2\readme」，這個成員會包含零。

lpstrDefExt

類型： LPCTSTR

預設延伸模組。 如果使用者無法輸入副檔名，GetOpenFileName和GetSaveFileName會將此副檔名附加至檔案名。 此字串可以是任何長度，但只會附加前三個字元。 字串不應包含句點 (.) 。 如果此成員為 Null ，且使用者無法輸入延伸模組，則不會附加任何延伸模組。

lCustData

類型： LPARAM

系統傳遞至 lpfnHook 成員所識別的攔截程式的應用程式定義資料。 當系統將 WM_INITDIALOG 訊息傳送至攔截程式時，訊息的 lParam 參數是建立對話方塊時所指定的 OPENFILENAME 結構的指標。 攔截程式可以使用這個指標來取得 lCustData 值。

lpfnHook

類型： LPOFNHOOKPROC

攔截程式的指標。 除非 Flags 成員包含 OFN_ENABLEHOOK 旗標，否則會忽略此成員。

如果未在Flags成員中設定OFN_EXPLORER旗標，lpfnHook是OFNHookProcOldStyle攔截程式的指標，可接收用於對話方塊的訊息。 攔截程式會傳回 FALSE ，以將訊息傳遞至預設對話方塊程式或 TRUE 以捨棄訊息。

如果 已設定OFN_EXPLORER ， lpfnHook 是 OFNHookProc 攔截程式的指標。 攔截程式會接收從對話方塊傳送的通知訊息。 攔截程式也會接收您藉由指定子對話方塊範本所定義之任何其他控制項的訊息。 攔截程式不會接收用於預設對話方塊之標準控制項的訊息。

lpTemplateName

類型： LPCTSTR

hInstance成員所識別模組中的對話方塊範本資源名稱。 對於編號對話方塊資源，這可以是 MAKEINTRESOURCE 宏所傳回的值。 除非在Flags成員中設定OFN_ENABLETEMPLATE旗標，否則會忽略此成員。 如果已設定 OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話方塊，這是預設 Explorer 樣式對話方塊的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代預設對話方塊的舊樣式對話方塊。

lpEditInfo

此成員會使用 #ifdef _MAC) 有條件地編譯 (，因此僅適用于 Motorola 68K Macintosh 電腦，不適用於 Windows 用戶端作業系統。

lpstrPrompt

此成員會使用 #ifdef _MAC) 有條件地編譯 (，因此僅適用于 Motorola 68K Macintosh 電腦，不適用於 Windows 用戶端作業系統。

pvReserved

類型： void*

此成員已保留。

dwReserved

類型： DWORD

此成員已保留。

FlagsEx

類型： DWORD

一組可用來初始化對話方塊的位旗標。 目前，此成員可以是零或下列旗標。

備註

基於相容性考慮，如果 Flags 設定為 OFN_ENABLEHOOK 且 lStructSizeOPENFILENAME_SIZE_VERSION_400，則會隱藏 [位置列]。

規格需求

另請參閱

通用對話方塊程式庫

概念

GetOpenFileName

GetSaveFileName

其他資源

參考

SHGetSpecialFolderLocation