SKETCH OF HOW RESEARCH MIGHT CONTINUE AND RESULTS BE PRESENTED

ShowHTMLDialogEx

Creates a trusted dialog box from an HTML source.

Declaration

HRESULT
ShowHTMLDialogEx (
    HWND hwndParent,
    IMoniker *pMk,
    DWORD dwDialogFlags,
    VARIANT *pvarArgIn,
    PWSTR pchOptions,
    VARIANT *pvarArgOut);

Arguments

The hwndParent argument is the handle of the window that is to be the dialog box’s parent window, else is NULL.

The pMk argument is the address of an IMoniker interface for access to the HTML that is to be shown in the dialog box.

The dwDialogFlags argument is a combination of bit flags from the following table:

The pvarArgIn argument is the address of a VARIANT that describes input to the dialog box, else is NULL. The type of data that can be given as input is essentially arbitrary. If it passes to the dialog box, it becomes the dialog box’s dialogArguments property (or equivalently, menuArguments).

The pchOptions argument is the address of a case-insensitive Unicode string that specifies the dialog box styles, else is NULL.

The pvarArgOut argument is an address at which the function is to store a VARIANT that describes output from the dialog box, else is NULL. If the HTMLDLG_MODELESS flag is set, then the output is the dialog box’s window object (specifically, its IHTMLWindow2 interface). Otherwise, the function does not return until the dialog box is closed, and the output is whatever finished as the dialog box’s returnValue property. The type of data that can be received as output is essentially arbitrary.

Return Value

The function returns zero for success, else an error code.

Behaviour

The ShowHTMLDialogEx function is large and complex, with numerous interactions throughout MSHTML. Complete documentation may be beyond the resources of this site. However, at least one point must be noted if only because it might easily be missed by programmers who rely on the scant notes that Microsoft seems to think suffice.

Where Microsoft says simply that the ShowHTMLDialogEx function creates a trusted dialog box, it is important to understand that what is trusted is the HTML that is to be rendered in the dialog box. The caller of this function is telling MSHTML that the document can do no harm and is not to be denied anything. Not only are the implications likely to be missed by programmers, but they seem to have been missed by Microsoft. Look particularly at the status bar in the dialog box. A trusted dialog box ordinarily does not have a status bar, on the reasonable grounds that the information in the status bar is not needed for assurance about security. However, if the status bar is enabled (through the options string), it will be seen that the information is not so much unnecessary as actually misleading. It helps nobody if the status bar shows a document as having come from the Restricted Sites zone, yet MSHTML has happily run scripts from the document and permitted anything else that the document has wanted. Note that the document is not just elevated to a highly trusted zone where its permissions are relaxed but still configurable. The dialog box host provides its own IInternetSecurityManager interface which explicitly allows all URL actions if the dialog box is trusted. The only concession is that Java permissions are set to high.

Another point that seems more readily appreciable in Microsoft’s documentation only if you already know it as something to look for is that dialog-box trust is inherited. If the document in a trusted dialog box runs script that calls its window object’s showModalDialog or showModelessDialog method to create another dialog box, then this second dialog box is trusted also.

Availability

The ShowHTMLDialogEx function is exported from MSHTML by name in versions 5.50 and higher. The function is documented, though somehow has Internet Explorer 4.0 listed as its minimum availability.

The Windows SDK provides a prototype in the MSHTMHST.H header file, but it is not immediately useful to programmers because the SDK does not supply any import library for resolving a natural call to the function. Instead, the SDK tells programmers to write some supporting code that uses LoadLibrary to load MSHTML.DLL, and GetProcAddress to locate the function, and then the helpfully provided type SHOWHTMLDIALOGEXFN for an indirect call to the function. This is all plainly silly and anyone who anticipates doing this work more than once would obviously do better to synthesise the missing import library.