typedef struct tagOFN { /* ofn */
DWORD lStructSize;
HWND hwndOwner;
HANDLE hInstance;
LPSTR lpstrFilter;
LPSTR lpstrCustomFilter;
DWORD nMaxCustFilter;
DWORD nFilterIndex;
LPSTR lpstrFile;
DWORD nMaxFile;
LPSTR lpstrFileTitle;
DWORD nMaxFileTitle;
LPSTR lpstrInitialDir;
LPSTR lpstrTitle;
DWORD Flags;
WORD nFileOffset;
WORD nFileExtension;
LPSTR lpstrDefExt;
DWORD lCustData;
LPOFNHOOKPROC lpfnHook;
LPSTR lpTemplateName;
} OPENFILENAME;
The OPENFILENAME structure contains information that the system uses to initialize the system-defined file-open or file-save dialog box. After the user dismisses the dialog box, the system returns information about the user's selection in this structure.
lStructSize
Specifies the length of the structure (in bytes).
hwndOwner
Identifies the window that owns the dialog box. This member can be any valid window handle, or NULL if the dialog box is to have no owner.
hInstance
Identifies a data block that contains a dialog template specified by the lpstrTemplateName member. This member is only used if the Flags member specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.
lpstrFilter
Points to a buffer containing pairs of null-terminated filter strings. The first string in each pair describes a filter (for example, “Text Files”), the second specifies the filter pattern (for example, “*.txt”). Multiple filters can be specified for a single item by separating the filter pattern strings with a semicolon (for example, “*.txt;*.doc;*.bak”). The last string in the buffer must be terminated by two NULL characters. If this parameter is NULL, the dialog box will not display any filters. The filter strings are assumed to be in the proper order—the system does not change the order.
lpstrCustomFilter
Points to a buffer containing a pair of user-defined filter strings. The first string describes the filter, and the second specifies the filter pattern (for example “WinWord, *.docnn”). The buffer is terminated by two NULL characters. The system copies the strings to the buffer when the user dismisses the dialog box. The system uses the strings to initialize the user-defined file filter the next the dialog box is created. If this parameter is NULL, the dialog box will list but not save user-defined filter strings.
nMaxCustFilter
Specifies the size (in bytes) of the buffer identified by the lpstrCustomFilter member. This buffer should be at least 40 bytes long. This parameter is ignored if the lpstrCustomFilter member is NULL or points to a NULL string.
nFilterIndex
Specifies an index into the buffer pointed to by the lpstrFilter member. The system uses the index value to obtain a pair of strings to use as the initial filter description and filter pattern for the dialog box. The first pair of strings has an index value of 1. When the user dismisses the dialog box, the system copies the index of the selected filter strings into this location. If the nFilterIndex member is 0, the custom filter will be used. If the nFilterIndex member is 0 and the lpstrCustomFilter member is NULL, the system uses the first filter in the buffer identified by the lpstrFilter member. If all three members are 0 or NULL, the system does not use any filters and does not show any files in the file list control of the dialog box.
lpstrFile
Points to a buffer that contains a filename used to initialize the File Name edit control. The first character of this buffer must be NULL if initialization is not necessary. When the GetOpenFileName or GetSaveFileName function returns, this buffer contains the drive designator, path, filename and extension of the selected file.
If the buffer is too small, the dialog procedure copies the required size into this field.
nMaxFile
Specifies the size (in bytes) of the buffer pointed to by the lpstrFile member. The GetOpenFileName and GetSaveFileName functions return FALSE if the buffer is too small to contain the file information. The buffer should be at least 256 bytes long. This member is ignored if the lpstrFile member is NULL.
lpstrFileTitle
Points to a buffer that receives the title of the selected file. For Windows version 3.0 and 3.1 this buffer receives the filename and extension but no path information. This application should use this string to display the file title. If this member is NULL, the function will not copy the file title.
nMaxFileTitle
Specifies the maximum length of the string that can be copied into the lpstrFileTitle buffer. This member is ignored if lpstrFileTitle is NULL.
lpstrInitialDir
Points to a string that specifies the initial file directory. If this member is NULL, the system uses current directory as the initial directory.
lpstrTitle
Points to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title (that is, “Save As” or “Open”).
Flags
Specifies the dialog-box creation flags. This member may be a combination of the following values:
| Value | Meaning |
| OFN_ALLOWMULTISELECT | Specifies that the File Name listbox allows multiple selections. (If the dialog is created using a private template, the LBS_EXTENDEDSEL constant must appear in the definition of the File Name listbox.) |
| OFN_CREATEPROMPT | Specifies that the dialog function should query the user as to whether or not they wish to create a file which does not currently exist. (This flag automatically sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags.) |
| OFN_ENABLEHOOK | Enables the hook function specified in the lpfnHook member. |
| OFN_ENABLETEMPLATE | Causes the system to create the dialog box using the dialog template identified by the hInstance and lpTemplateName members. |
| OFN_ENABLETEMPLATEHANDLE | Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified. |
| OFN_EXTENSIONDIFFERENT | Specifies that the user entered a file extension that differs from the extension specified by lpstrDefExt. The function will not set this flag if lpstrDefExt is NULL. |
| OFN_FILEMUSTEXIST | Specifies that the user can only enter names of existing files in the File Name entry field. If this flag is set and the user enters an invalid file name in the File Name entry field, the dialog function will display a warning in a message box. (This flag causes the OFN_PATHMUSTEXIST flag to also be set.) |
| OFN_HIDEREADONLY | Hides the read only checkbox. |
| OFN_NOCHANGEDIR | Forces the dialog box to set the current directory back to what it was when the dialog was invoked. |
| OFN_OVERWRITEPROMPT | Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file. |
| OFN_PATHMUSTEXIST | Specifies that the user can only enter valid path names. If this flag is set and the user enters an invalid path name in the File Name entry field, the dialog function will display a warning in a message box. |
| OFN_READONLY | Causes the “Read only” checkbox to be initially checked when the dialog box is created. Indicates the state of the “Read only” checkbox when the dialog box is dismissed. |
| OFN_SHOWHELP | Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. |
nFileOffset
Specifies a zero-based offset from the beginning of the pathname to the filename in the string at which lpstrFile points. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member will contain the value 13.
nFileExtension
Specifies a zero-based offset from the beginning of the pathname to the filename extension in the string at which lpstrFile points. For example, if lpstrFile points to the following string, “c:\dir1\dir2\file.ext”, this member will contain the value 18. If the user did not enter an extension and lpstrDefExt is NULL, this member specifies an offset to the NULL terminator. If the user entered “.” as the last character in the filename, this member will specify 0.
lpstrDefExt
Points to a buffer that contains the default extension. The GetOpenFileName and GetSaveFileName functions append this extension to the filename if the user fails to enter an extension. This string may be any length but only the first three characters are appended. The string should not contain a period “.”. If this member is NULL and the user fails to enter an extension, no extension is appended.
lCustData
Specifies application-defined data that the system passes to the hook function identified by the lpfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.
lpfnHook
Points to a hook function that processes messages intended for the dialog box. An application must specify the OFN_ENABLEHOOK function in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message on to the standard dialog procedure, or TRUE to discard the message.
lpstrTemplateName
Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog template. An application can use the MAKEINTRESOURCE macro for numbered dialog resources. This member is only used if the Flags member specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.
GetOpenFileName, GetSaveFileName