NavigateError event

  • Article

Fires when an error occurs during navigation.

Syntax

HTML Attribute <element NavigateError = "handler(event)">
attachEvent Method object.attachEvent("NavigateError", handler)

 

Event information

Synchronous No
Bubbles No
Cancelable No

 

Event handler parameters

pDisp [in]

C++ A pointer to an IDispatch interface for the WebBrowser object that represents the window or frame in which the navigation error occurred. This interface can be queried for the IWebBrowser2 interface.
VB IDispatch that evaluates to the top-level or frame WebBrowser object corresponding to the failed navigation.

URL [in]

C++ A pointer to a VARIANT structure of type VT_BSTR that contains the URL for which navigation failed.
VB BSTR expression that evaluates to the URL for which navigation failed.

TargetFrameName [in]

C++ 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 was targeted for the resource.
VB BSTR that evaluates to the name of the frame in which the resource is to be displayed, or NULL if no named frame is targeted for the resource.

StatusCode [in]

C++ A pointer to a VT_I4 containing an error status code, if available. For a list of the possible HRESULT and HTTP status codes, see NavigateError Event Status Codes.
VB VT_I4 that contains a status code corresponding to the error, if available. For a list of the possible status codes, see NavigateError Event Status Codes.

Cancel [in, out, ref]

C++ A pointer to a VARIANT structure of type VARIANT_BOOL that specifies whether to cancel the navigation to an error page or to any further autosearch.
VB VARIANT_BOOL that specifies whether to cancel the navigation to an error page and/or any further autosearch.

VARIANT_FALSE (False)

Default. Continue with navigation to an error page or autosearch.

VARIANT_TRUE (True)

Cancel navigation to an error page or autosearch.

Remarks

DWebBrowserEvents2::NavigateError was introduced in Microsoft Internet Explorer 6.

This event fires before Windows Internet Explorer displays an error page due to an error in navigation. An application has a chance to stop the display of the error page by setting the Cancel parameter to VARIANT_TRUE. However, if the server contacted in the original navigation supplies its own substitute page navigation, when you set Cancel to VARIANT_TRUE, it has no effect, and the navigation to the server's alternate page proceeds. For example, assume that a navigation to http://www.www.wingtiptoys.com/BigSale.htm causes this event to fire because the page does not exist. However, the server is set to redirect the navigation to http://www.www.wingtiptoys.com/home.htm. In this case, when you set Cancel to VARIANT_TRUE, it has no effect, and navigation proceeds to http://www.www.wingtiptoys.com/home.htm.

Use the pDisp parameter to match this event with its corresponding IWebBrowser2::Navigate event or IWebBrowser2::Navigate2 event. For example, multiple DWebBrowserEvents2::NavigateError events can fire for a single IWebBrowser2::Navigate request or IWebBrowser2::Navigate2 request. Reasons for this include navigation to a URL with multiple frames, or multiple attempts by an autosearch engine to resolve an invalid URL. In each of these cases, the URL passed into these events might not match the URL that was originally requested. However, each of these events has the same pDisp.

As with other events, you can trap the DWebBrowserEvents2::NavigateError event by implementing IDispatch::Invoke as your event sink, and connecting it to the WebBrowser control's DIID_DWebBrowserEvents2 connection point. You can then extract information, such as the status code, from the pDispParams parameter. The following shows how to trap the DWebBrowserEvents2::NavigateError event and extract the status code and IDispatch pointer.

HRESULT CAtlWbHost::Invoke(DISPID dispIdMember,
                           REFIID riid,
                           LCID lcid,
                           WORD wFlags,
                           DISPPARAMS *pDispParams,
                           VARIANT *pvarResult,
                           EXCEPINFO *pexcepinfo,
                           UINT *puArgErr)
{
    switch(dispIdMember)
    {
    ...
    case DISPID_NAVIGATEERROR : 
        //Extract the status code from the DISPPARAMS structure
        VARIANT * vt_statuscode = pDispParams->rgvarg[1].pvarVal;
        DWORD  dwStatusCode =  vt_statuscode->lVal;
        ...
        //Extract the event's IDispatch pointer
        IDispatch *pdispFiredEvent = pDispParams->rgvarg[4].pdispVal;
        ...
        break;
    ...
}

A URL passed into IWebBrowser2::Navigate or IWebBrowser2::Navigate2 might not match the URL passed into this event because the URL goes through a normalization process. For example, the URL string "www.wingtiptoys.co" might be passed into IWebBrowser2::Navigate2, but because of the normalization process, the URL parameter is set to "http://www.wingtiptoys.co/."