GetSaveFileName

3.1

#include <commdlg.h>

	BOOL GetSaveFileName(lpofn)
	OPENFILENAME FAR* lpofn;	/* address of structure with initialization data	*/

The GetSaveFileName function creates a system-defined dialog box that makes it possible for the user to select a file to save.

Parameters

lpofn

Points to an OPENFILENAME structure that contains information used to initialize the dialog box. When the GetSaveFileName function returns, this structure contains information about the user's file selection.

The OPENFILENAME structure has the following form:

#include <commdlg.h>

typedef struct tagOPENFILENAME { /* ofn */
    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;
    UINT      nFileOffset;
    UINT      nFileExtension;
    LPCSTR    lpstrDefExt;
    LPARAM    lCustData;
    UINT      (CALLBACK* lpfnHook) (HWND, UINT, WPARAM, LPARAM);
    LPCSTR    lpTemplateName;
} OPENFILENAME;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

Return Value

The return value is nonzero if the user selects a file to save. It is zero if an error occurs, if the user clicks the Cancel button, if the user chooses the Close command on the System menu to close the dialog box, or if the buffer identified by the lpstrFile member of the OPENFILENAME structure is too small to contain the string that specifies the selected file.

Errors

The CommDlgExtendedError retrieves the error value, which may be one of the following values:

CDERR_FINDRESFAILURE
CDERR_INITIALIZATION
CDERR_LOCKRESFAILURE
CDERR_LOADRESFAILURE
CDERR_LOADSTRFAILURE
CDERR_MEMALLOCFAILURE
CDERR_MEMLOCKFAILURE
CDERR_NOHINSTANCE
CDERR_NOHOOK
CDERR_NOTEMPLATE
CDERR_STRUCTSIZE
FNERR_BUFFERTOOSMALL
FNERR_INVALIDFILENAME
FNERR_SUBCLASSFAILURE

Comments

If the hook function (to which the lpfnHook member of the OPENFILENAME structure points) processes the WM_CTLCOLOR message, this function must return a handle for the brush that should be used to paint the control background.

Example

The following example copies file-filter strings (filename extensions) into a buffer, initializes an OPENFILENAME structure, and then creates a Save As dialog box.

The file-filter strings are stored in the resource file in the following form:

STRINGTABLEBEGIN
  IDS_FILTERSTRING  "Write Files(*.WRI)|*.wri|Word Files(*.DOC)|*.doc|"
END

The replaceable character at the end of the string is used to break the entire string into separate strings, while still guaranteeing that all the strings are continguous in memory.

OPENFILENAME ofn;
char szDirName[256];
char szFile[256], szFileTitle[256];
UINT  i, cbString;
char  chReplace;    /* string separator for szFilter */
char  szFilter[256];
HFILE hf;

/*
 * Retrieve the system directory name and store it in
 * szDirName.
 */
GetSystemDirectory(szDirName, sizeof(szDirName));


if ((cbString = LoadString(hinst, IDS_FILTERSTRING,
        szFilter, sizeof(szFilter))) == 0) {
    ErrorHandler();
    return 0;
}

chReplace = szFilter[cbString - 1]; /* retrieve wild character */

for (i = 0; szFilter[i] != '\0'; i++) {
    if (szFilter[i] == chReplace)
       szFilter[i] = '\0';
}

/* Set all structure members to zero. */

memset(&ofn, 0, sizeof(OPENFILENAME));

/* Initialize the OPENFILENAME members. */

szFile[0] = '\0';

ofn.lStructSize = sizeof(OPENFILENAME);
ofn.hwndOwner = hwnd;
ofn.lpstrFilter = szFilter;
ofn.lpstrFile= szFile;
ofn.nMaxFile = sizeof(szFile);
ofn.lpstrFileTitle = szFileTitle;
ofn.nMaxFileTitle = sizeof(szFileTitle);
ofn.lpstrInitialDir = szDirName;
ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT;

if (GetSaveFileName(&ofn)) {
    .
    . /* Perform file operations. */
    .
}
else
    ErrorHandler();