IWebBrowser2::Navigate Method

Navigates to a resource identified by a URL or to a file identified by a full path.

Syntax

HRESULT Navigate(
    BSTR url,
    VARIANT *Flags,
    VARIANT *TargetFrameName,
    VARIANT *PostData,
    VARIANT *Headers
);

Parameters

• url
  [in] Required. A BSTR expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) location and name of the resource to display.
• Flags
  [in] Pointer to a VARIANT of type VT_I4 or VT_I2 that specifies a combination of the values defined by the BrowserNavConstants enumeration.
• TargetFrameName
  [in] Pointer to a case-sensitive string that contains the name of the frame in which to display the resource. The possible values for this parameter are.
  • _blank
    Load the link into a new unnamed window.
  • _parent
    Load the link into the immediate parent of the document the link is in.
  • _self
    Load the link into the same window the link was clicked in.
  • _top
    Load the link into the full body of the current window.
  • WindowName
    A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.
• PostData
  [in] A pointer to a VARIANT of type VT_ARRAY|VT_UI1 that is sent to the server as part of a HTTP POST transaction. A POST transaction is typically used to send data gathered by an HTML form. If this parameter does not specify any post data, this method issues an HTTP GET transaction. This parameter is ignored if the URL is not an HTTP URL.
• Headers
  [in] Pointer to a VARIANT of type VT_BSTR that contains additional HTTP headers to send to the server. These headers are added to the default Windows Internet Explorer headers. For example, headers can specify the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if the URL is not an HTTP URL.

Return Value

Returns one of the following values.

S_OK	The operation was successful.
E_INVALIDARG	One or more parameters are invalid.
E_OUTOFMEMORY	Out of memory.

Remarks

The WebBrowser control or InternetExplorer object can browse to any location in the local file system, on the network, or on the World Wide Web.

The post data specified by PostData is passed as a SAFEARRAY Data Type structure. The VARIANT should be of type VT_ARRAY|VT_UI1 and point to a SAFEARRAY Data Type. The SAFEARRAY Data Type should be of element type VT_UI1, dimension one, and have an element count equal to the number of bytes of post data.

In Microsoft Internet Explorer 6 or later, you can navigate through code only within the same domain as the application hosting the WebBrowser control. Otherwise, this method and IWebBrowser2::Navigate2 are disabled.

In Internet Explorer 7, when you specify the navOpenInNewTab flag or the navOpenInBackgroundTab flag, do not combine them with other parameters ( TargetFrameName, PostData, Headers) or with other BrowserNavConstants flags. If tabbed browsing is disabled, or if a tab cannot be created, the call will fail. If this happens, choose another navigation method, such as navOpenInNewWindow.

Note    New tabs are opened asynchronously; this method returns as soon as the tab is created, which can be before navigation in the new tab has started. The IWebBrowser2 interface for the destination tab is not available to the caller. Tab order is not guaranteed, especially if this method is called many times quickly in a row.

When navOpenInNewWindow or navOpenInNewTab is specified, the caller does not receive a pointer to the IWebBrowser2 interface for the new window, so there is no immediate way to manipulate it.

See Also

DWebBrowserEvents2::BeforeNavigate2, DWebBrowserEvents2::NavigateComplete2, IWebBrowser2::Navigate2