IEShowSaveFileDialog function
Opens the Windows Common Save File dialog box from a medium integrity context.
Syntax
HRESULT IEShowSaveFileDialog(
_In_ HWND hwnd,
_In_ LPWSTR lpwstrInitialFileName,
_In_ LPWSTR lpwstrInitialDir,
_In_ LPCWSTR lpwstrFilter,
_In_ LPCWSTR lpwstrDefExt,
_In_ DWORD dwFilterIndex,
_In_ DWORD dwFlags,
_Out_ LPWSTR *lppwstrDestinationFilePath,
_In_ HANDLE *phState
);
Parameters
hwnd [in]
A handle to the owner window of the dialog box. Must be a valid handle to a window that the control owns.
lpwstrInitialFileName [in]
A string that specifies a file name used to initialize the File Name edit control.
lpwstrInitialDir [in]
A pointer to a NULL-terminated string that specifies the initial directory, or NULL.
lpwstrFilter [in]
A pointer to a buffer containing pairs of file filter strings that are terminated with the pipe escape character (|). The last string in the buffer must be terminated by the pipe escape character (|). For example, to specify two filter strings, one for text files and another for all files, the buffer contains Text Files|*.txt|All Files|*.*|
lpwstrDefExt [in]
A pointer to a buffer that contains the default extension. The IEShowSaveFileDialog function appends this extension to the file name, if the user does not type an extension. This string can 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 type an extension, no extension is appended.
dwFilterIndex [in]
The index of the currently selected file filter stringthat is pointed to by lpwstrFilter. The first pair of strings has an index value of 1, the second pair of strings has an index value of 2, and so on.
dwFlags [in]
An unsigned long integer that contains a combination of flags that are used to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user's input. These flags are the same as those defined for the dwFlags member of the OPENFILENAME structure. The following flags are valid.
OFN_DONTADDTORECENT (0)
OFN_ENABLESIZING (0)
OFN_FILEMUSTEXIST (0)
OFN_FORCESHOWHIDDEN (0)
OFN_HIDEREADONLY (0)
OFN_LONGNAMES (0)
OFN_NOCHANGEDIR (0)
OFN_NODEREFERENCELINKS (0)
OFN_NOLONGNAMES (0)
OFN_NONETWORKBUTTON (0)
OFN_NOREADONLYRETURN (0)
OFN_NOTESTFILECREATE (0)
OFN_OVERWRITEPROMPT (0)
OFN_PATHMUSTEXIST (0)
OFN_READONLY (0)
OFN_SHAREAWARE (0)
lppwstrDestinationFilePath [out]
A pointer to a buffer that, on successful return, contains the drive designator, path, file name, and extension of the file that the user selected. When no longer requires, call CoTaskMemFree to release it.
phState [in]
A pointer to a variable of type HANDLE that receives the handle used in a subsequent call to the IESaveFile function.
Return value
Returns S_OK if successful, S_FALSE if the user cancels the operation, or an error value otherwise.
Remarks
Like many applications, Windows Internet Explorer uses the Windows Common Dialog library when opening and saving files to a user's local computer. Because these dialog boxes inherit the integrity levels of the applications that call them, they also inherit access restrictions that apply to the applications. When running in protected mode, Internet Explorer is considered a low integrity application. As a result, Internet Explorer cannot use the common Save As dialog box to allow users to directly access their personal folders and other medium integrity objects on their hard drives. This is a security restriction designed to help prevent malicious behavior by untrusted sources.
The IEShowSaveFileDialog function works within these restructions by using a medium integrity broker process (IEUser.exe) to call the Windows Common Dialog library. This allows the Save As dialog to run at medium integrity, which in turn allows users to access their personal folders.
The IEShowSaveFileDialog function is the first step in a two-step save operation; the parameter values passed to the function are used to initialize a Save As dialog box in the broker process. After the user closes the dialog box, the broker process returns the name of the file selected by the user in the information about the user's selection to the lppwstrDestinationFilePath parameter. If the function succeeds, you must pass the lppwstrDestinationFilePath to IESaveFile in order to save the file.
The following algorithm is used to select the initial directory.
- If lpwstrInitialFileName contains a path, that path is the initial directory; otherwise, lpwstrInitialDir specifies the initial directory.
- If lpwstrInitialDir is NULL, the function scans for files that match the filter specified in lpwstrFilter by searching the current directory and the My Documents folder of the current user.
- If files matching the specified filter types are found, lpwstrInitialDir is set to the directory where they were found; otherwise, the initial directory uses the Desktop folder.
Requirements
Minimum supported client |
Windows Vista |
Minimum supported server |
Windows Server 2008 |
Product |
Internet Explorer 7 |
Header |
Iepmapi.h |
Library |
Iepmapi.lib |
DLL |
Ieframe.dll |