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.

1. If lpwstrInitialFileName contains a path, that path is the initial directory; otherwise, lpwstrInitialDir specifies the initial directory.
2. 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.
3. 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