Fires before navigation occurs in the given object (on either a window element or a frameset element).
void BeforeNavigate2( IDispatch *pDisp, VARIANT *url, VARIANT *Flags, VARIANT *TargetFrameName, VARIANT *PostData, VARIANT *Headers, VARIANT_BOOL *Cancel );
- [in] A pointer to the IDispatch interface for the WebBrowser object that represents the window or frame. This interface can be queried for the IWebBrowser2 interface.
- [in] A pointer to a VARIANT structure of type VT_BSTR that contains the URL to navigate to.
- [in] A pointer to a VARIANT of type VT_I4 that contains the following flag, or zero.
- Windows Internet Explorer 7 or later. This navigation is the result of an external window or tab that targets this browser.
- [in] A pointer to a VARIANT structure of type VT_BSTR that contains the name of the frame in which to display the resource, or NULL, if no named frame is targeted for the resource.
- [in] A pointer to a VARIANT structure of type VT_BYREF|VT_VARIANT that contains the data to send to the server if the HTTP POST transaction is used.
- [in] A pointer to a VARIANT structure of type VT_BSTR that contains additional HTTP headers to send to the server (HTTPURLs only). The headers can specify information, such as the action required of the server, the type of data passed to the server, or a status code.
- [in, out]
A pointer to a VARIANT structure of type VARIANT_BOOL that contains the cancel flag. An application can set this parameter to VARIANT_TRUE to cancel the navigation operation, or to VARIANT_FALSE to allow the navigation operation to proceed.Note The
Cancelparameter is an OUT parameter to cancel or allow navigation as above. However, because there is a chain of event handlers,
Cancelis also an IN parameter to provide notification of the value set by the previous handler.
No return value.
The DISPID for this event is defined in exdispid.h. Use this value to identify the event handler when implementing IDispatch::Invoke.
The post data specified by PostData is passed as a SAFEARRAY structure. The variant should be of type VT_BYREF|VT_VARIANT, which points to a SAFEARRAY. The SAFEARRAY should be of element type VT_UI1, dimension one, and have an element count equal to the number of bytes of post data.
The url parameter can be a pointer to an item identifier list (PIDL) in the case of a Shell namespace entity for which there is no URL representation.
The DWebBrowserEvents2::BeforeNavigate2 event replaces the
FrameBeforeNavigateevents, which should no longer be used. The pDisp parameter that specifies the corresponding WebBrowser object identifies where the navigation is to occur. Microsoft Internet Explorer 3.0 required the
FrameBeforeNavigateand a target frame name to identify the target of navigation. However, this solution was ambiguous, because frame names are not unique.Note Internet Explorer 4.0 and later continue to fire the
FrameBeforeNavigateevents for compatibility with Internet Explorer 3.0.
The pDisp parameter specifies the WebBrowser object of the top-level frame that corresponds to the navigation. Navigation to a different URL might occur as a result of external automation, internal automation from a script, or the user clicking a link or typing in the address bar. The processing of this navigation can be modified by setting the Cancel parameter to VARIANT_TRUE, and ignoring or resending a modified navigation method to the WebBrowser object.
When you resend a navigation for the WebBrowser object, the IWebBrowser2::Stop method must first be executed for pDisp. This prevents a web page that declares a canceled navigation from appearing while the new navigation is being processed.