Function Reference

_IEAttach

Attach to the specified instance of Internet Explorer where the search string sub-string matches (based on the selected mode).

#include <IE.au3>
_IEAttach($s_string [, $s_mode = "Title" [, $i_instance = 1]])

Parameters

$s_string String to search for (for "embedded" or "dialogbox", use Title sub-string or HWND of window)
$s_mode [optional] specifies search mode
Title = (Default) sub-string of main document title
WindowTitle = sub-string of full window title (instead of document title)
URL = sub-string or url of the current page
Text = sub-string in text from the body of the current page
HTML = sub-string in html from the body of the current page
HWND = hwnd of the browser window
Embedded = title sub-string or hwnd of of the window embedding the control
DialogBox = title sub-string or hwnd of modal/modeless dialogbox
Instance = $s_string is ignored, one browser reference returned (by matching instance number) from all available browser instances
$i_instance [optional] 1-based index into group of browsers or embedded browsers matching $s_string and $s_mode. See Remarks.

Return Value

Success: Returns an object variable pointing to the InternetExplorer Object for all but Embedded and DislogBox modes which return a Window Object
Failure: Returns 0 and sets @ERROR
@Error: 0 ($_IEStatus_Success) = No Error
5 ($_IEStatus_InvalidValue) = Invalid Value
7 ($_IEStatus_NoMatch) = No Match
@Extended: Contains invalid parameter number

Remarks

_IEAttach provides the "dialogbox" parameter to attach to modal and modeless dialogs created by the browser. It is important to note that not all dialogs created through browser interaction can be attached to and controlled in this way. Many of these dialogs are actually standard windows and can be controlled through the traditional AutoIt window functions. A reliable way to tell the difference between these types of windows is to use the "AutoIt Window Info" tool to examine it -- if the window contains a control called "Internet Explorer_Server" then you can attach to it with this function, if it does not it is a standard window and traditional AutoIt windows functions must be used to control it.

HyperTextApplication (.hta) windows may be attached to using the "embedded" option.

The advanced Window Title selection syntax available to the standard Win* functions may be used in place of a title sub-string for the modes "dialogbox" and "embedded".

Use of "$i_instance" with the "embedded" mode: used to return a reference to a specific instance of a WebBrowser and is particularly useful when more than one exists in a particular window. If you pass a window title in $s_string using embedded mode, only the first window matching that title will be used. If the WebBrowser control you desire is in another window you must pass the HWnd of that window rather than the title, or use the advanced Window Title selection syntax available to the standard Win* functions.

Use of "$i_instance" with all modes other than "embedded": used to return a browser reference from a groups of all windows that match the criteria from $s_string and $s_mode. Instance order for DialogBox mode determined by the order returned by WinList() matching the title. For all other modes the Instance order is determined by the Shell.Windows collection.

"$i_instance" values > 1 are set to 1 and a warning message is displayed when used with "hwnd" mode or with "DialogBox" mode when an HWnd is passed in $s_string.

DialogBox and Embedded modes can be used to attach to standard browser windows, but the object returned is that if the top level Window in the browser and not the InternetExplorer object. Window objects do not offer access to all of the attributes of the InternetExplorer object (e.g. status text, address bar etc.). As well, if you attempt to use a function like _IENavigate on such an object you may receive COM errors due to the way that IE7 has implemented Tabs. It may be useful to find browser instances in this way, but it is recommended that you immediately use _IEAttach using one of the other modes and using information that you may have obtained from the Window object in order to get a reference to the associated InternetExplorer object.

Related

_IECreate, _IECreateEmbedded, _IEQuit

Example


; *******************************************************
; Example 1 - Attach to a browser with "AutoIt" in its title, display the URL
; *******************************************************

#include <IE.au3>

Local $oIE = _IEAttach("AutoIt")
MsgBox(0, "The URL", _IEPropertyGet($oIE, "locationurl"))

; *******************************************************
; Example 2 - Attach to a browser with "The quick brown fox"
;               in the text of it's top-level document
; *******************************************************

#include <IE.au3>

$oIE = _IEAttach("The quick brown fox", "text")

; *******************************************************
; Example 3 - Attach to a browser control embedded in another window
; *******************************************************

#include <IE.au3>

$oIE = _IEAttach("A Window Title", "embedded")

; *******************************************************
; Example 4 - Attach to the 3rd browser control embedded in another window
;               Use the advanced window title syntax to use the 2nd window
;               with the string 'ICQ' in the title
; *******************************************************

#include <IE.au3>

$oIE = _IEAttach("[REGEXPTITLE:ICQ; INSTANCE:2]", "embedded", 3)

; *******************************************************
; Example 5 - Create an array of object references to all current browser instances
;               The first array element will contain the number of instances found
; *******************************************************

#include <IE.au3>

Local $aIE[1]
$aIE[0] = 0

Local $i = 1
While 1
    $oIE = _IEAttach("", "instance", $i)
    If @error = $_IEStatus_NoMatch Then ExitLoop
    ReDim $aIE[$i + 1]
    $aIE[$i] = $oIE
    $aIE[0] = $i
    $i += 1
WEnd

MsgBox(0, "Browsers Found", "Number of browser instances in the array: " & $aIE[0])