Dynamic HTML

Dynamic HTML is a set of innovative features in Microsoft® Internet Explorer 4.0. By enabling authors to dynamically change the rendering and content of a document, Dynamic HTML gives authors the ability to create visually outstanding HTML documents that interact with the user without the burden of relying on server-side programs or complicated sets of HTML pages to achieve special effects.

With Dynamic HTML, you can easily add effects to your documents that were previously difficult to achieve. For example, you can:

  • Hide text and images in your document and keep this content hidden until a given time elapses or the user interacts with the page.
  • Animate text and images in your document, independently moving each element from any starting point to any ending point, following a path that you choose or that you let the user choose.
  • Create a ticker that automatically refreshes its content with the latest news, stock quotes, or other data.
  • Create a form, then instantly read, process, and respond to the data the user enters in the form.

Dynamic HTML achieves these effects by modifying the current document and automatically reformatting and redisplaying the document to show changes. It does not need to reload the document or load a new document, or require a distant server to generate new content. Instead, it uses the power of the user's computer to calculate and carry out changes. This means a user does not have to wait for text and data to complete time-consuming round-trips to and from a server before seeing results. Furthermore, Dynamic HTML does not require additional support from applications or embedded controls to carry out changes. Typically, Dynamic HTML documents are self-contained, using styles and a little script to process user input and directly manipulate the HTML tags, attributes, styles, and text in the document.

The HTML elements, attributes, and styles in Dynamic HTML are based on existing HTML and cascading style sheet (CSS) specifications. Users can view your documents whether they use Internet Explorer version 4.0 or some other browser. Naturally, the dynamic and interactive features that you add to your documents may not be fully functional when viewed with a browser that does not support Dynamic HTML. But Dynamic HTML is designed to "degrade gracefully"—by following some basic guidelines, the content of your document can be viewable in other browsers.

Dynamic HTML works well with applications, ActiveX™ Controls, and other embedded objects. You can use existing applications and controls, or you can create new ones that specifically take advantage of the features of Dynamic HTML. Applications and controls work best when you rely on them to do computationally difficult tasks, and use Dynamic HTML to display output and process user input. For example, you can create a document that lets the user query, display, and modify the content of a large, server-based database by combining the data binding features of Dynamic HTML with a data source object. The data source object retrieves and sets data in a database, and Dynamic HTML does the rest: processing user queries, displaying the data, and carrying out the necessary interaction with the object.

In short, Dynamic HTML eliminates the shortcomings of previous browser technologies. Authors can create innovative Web sites, whether on the Internet or an intranet, without having to sacrifice performance for interactivity and special effects. Not only does Dynamic HTML enhance the user's perception of your documents, it also improves server performance by reducing requests to the server and subsequently server load.

The following topics explain Dynamic HTML in more detail and introduce you to the topics in this section that will help you begin using Dynamic HTML.

  • Dynamic Styles
  • Dynamic Content
  • Positioning and Animation
  • Filters and Transitions
  • Font Download
  • Data Binding
  • Dynamic HTML Object Model

Microsoft is working with Internet standards bodies such as the W3C (World Wide Web Consortium) to provide the best standards-based solutions that make the Web a better open environment for building efficient and interactive multimedia content. Dynamic HTML represents the next step in that effort—all the HTML and CSS extensions for Dynamic HTML conform to W3C specifications or have been submitted to the W3C for consideration. Microsoft will enhance future versions of Internet Explorer to conform to future specifications recommended by the W3C.

Dynamic Styles

Dynamic styles are a key feature of Dynamic HTML. By using styles and style sheets, you can quickly change the appearance and formatting of elements in a document without adding or removing elements. This helps keep your documents small and the scripts that manipulate the document fast.

The object model gives you programmatic access to styles. This means you can change inline styles on individual elements and change style rules in a document's cascading style sheets (CSS) using simple script-based programming. These scripts can be written in JavaScript, JScript, or VBScript.

Inline styles are CSS style assignments that have been applied to an element using the STYLE attribute. You can examine and set these styles by retrieving the style object for an individual element. For example, if you want to highlight the text in a heading when the user moves the mouse over it, you can use the heading's inline style to enlarge the font and change its color, as in the following simple document.

<HTML>
<HEAD><TITLE>Dynamic Styles</TITLE>
<SCRIPT LANGUAGE="JScript">
function doChanges() {
    window.event.srcElement.style.color = "green";
    window.event.srcElement.style.fontSize = "20px";
}
</SCRIPT>
<BODY>
<H3 ID=heading onmouseover="doChanges()" STYLE="color:black;font-size:18">Welcome to Dynamic HTML!</H3>
<P>You can do the most amazing things with the least bit of effort.
</BODY>
</HTML>

In the above example, the process (also known as an event handler) that responds when the onscreen cursor moves over an HTML tag that contains a onmouseover statement receives control when the user first moves the mouse into the heading (known as an event). The handler uses the srcElement property of the event object to determine which element is the source of the event (in this case, the H3 element). It then uses the color and fontSize properties of the style object for the element to change the color and font size. Setting these properties changes the CSS "color" and "font-size" attributes given in the STYLE attribute for the heading, and the browser immediately updates the onscreen text to show these new attribute values.

By using styles, you can create a simple document, such as the following, in which all items in a bullet list are hidden until the user clicks the mouse.

<HTML>
<HEAD><TITLE>Dynamic Styles</TITLE>
<SCRIPT LANGUAGE="JScript">
function showMe() {
    document.all.MyHeading.style.color = "red";
    document.all.MyList.style.display = "";
}
</SCRIPT>
<BODY onclick="showMe()">
<H3 ID=MyHeading>Welcome to Dynamic HTML!</H3>
<P>You can do the most amazing things with the least bit of effort. Just click and see!
<UL ID=MyList STYLE="display:none">
<LI>Change the color, size, and typeface of text
<LI>Show and hide text
<LI>And much, much more
</UL>
<P>And this is just the beginning!
</BODY>
</HTML>

In the above example, the CSS display attribute is set to "none", causing the UL list to be hidden from view. When the user clicks the document, the event handler clears the value of this attribute, making the browser display the list onscreen. Notice how any content that comes after the list shifts down to accommodate the new text rendering.

Dynamic styles are based on the W3C Recommendation for Cascading Style Sheets (CSS) specification for static style sheets. For a list of topics that describe and explain dynamic styles in full detail, see Dynamic Styles.

Dynamic Content

With Dynamic HTML, you can change the content of a document after it is loaded. Internet Explorer gives you a rich set of properties and methods to dynamically construct and alter documents, from inserting and deleting elements to modifying the text and attributes in individual elements.

The Dynamic HTML object model gives you access to all elements in the document. Consider the following simple document. You can replace and change elements as well as change colors and text by using a few lines of script.

<HTML>
<HEAD><TITLE>Welcome!</TITLE>
<SCRIPT LANGUAGE="JScript">
function changeMe() {
    document.all.MyHeading.outerHTML = "<H1 ID=MyHeading>Dynamic HTML!</H1>";
    document.all.MyHeading.style.color = "green";
    document.all.MyText.innerText = "You can do the most amazing things with the least bit of effort.";
    document.all.MyText.align = "center";
    document.body.insertAdjacentHTML("BeforeEnd", "<P ALIGN=\"center\">Just give it a try!</P>");
}
</SCRIPT>
<BODY onclick="changeMe()">
<H3 ID=MyHeading>Welcome to Dynamic HTML!</H3>
<P ID=MyText>Click anywhere on this page.</P>
</BODY>
</HTML>

When the user clicks on the page above, the script replaces the H3 element with an H1 element, centers the paragraph, and inserts a new paragraph at the end of the document. Using script in this way, you can add, delete, and replace any elements and text in the document.

For a list of topics that describe and explain dynamic content in full detail, see Dynamic Content.

Positioning and Animation

Positioning is the ability to place an HTML element at a specific point in a document by assigning an x- and y-coordinate and a z-plane to that element. This means you can place elements—images, controls, and text—exactly where you want them and achieve special, overlapping effects by defining in what order elements at the same point should be stacked atop one another.

Positioning is an extension of cascading style sheets. This means that you set the position of an element by setting the appropriate CSS attributes for that element. The following simple document shows how you can set the absolute position of an image.

<HTML>
<HEAD><TITLE>Positioning</TITLE>
<BODY>
<H3>Welcome to Dynamic HTML!</H3>
<P>With positioning, you can place images exactly where you want them, even behind text and other images.
<IMG STYLE="position:absolute;top:0; left:0; z-index:-1" SRC="banner.gif">
</BODY>
</HTML>

In the above example, the image is placed at the top left corner of the document. Setting the z-index attribute to -1 causes the image to be placed behind the text on the page.

Internet Explorer 4.0 supports positioning and animation of elements even after a document has been loaded. Because the object model gives you access to styles and style sheets, you can set and change the position of an element as simply as you set and change its color. This makes it especially easy to change the position of elements based on how the user is viewing the document, and to even animate the elements. For animation, all you need is to slightly modify the position of an element on some interval. For example, the following document presents an image that glides across the top of the document and comes to rest at the upper-left corner.

<HTML>
<HEAD><TITLE>Dynamic Positioning</TITLE>
<SCRIPT LANGUAGE="JScript">
var id;
function StartGlide()
{
    document.all.Banner.style.pixelLeft =
        document.body.offsetWidth;
    document.all.Banner.style.visibility = "visible";
    id = window.setInterval("Glide()",50);
}
function Glide()
{
    document.all.Banner.style.pixelLeft -= 10;
    if (document.all.Banner.style.pixelLeft<=0) {
        document.all.Banner.style.pixelLeft=0;
        window.clearInterval(id);
    }
}
</SCRIPT>
<BODY onload="StartGlide()">
<H3>Welcome to Dynamic HTML!</H3>
<P>With dynamic positioning, you can move images anywhere in the document even while the user views the document.
<IMG ID="Banner" STYLE="visibility:hidden;position:absolute;top:0; left:0; z-index:-1" SRC="banner.gif">
</BODY>
</HTML>

In this example, the "StartGlide" function is called when the document is loaded. The function sets the absolute position of the "Banner" image to the top and far right edge of the document body, shows the image, and starts an interval. The "Glide" function is called repeatedly in 50-millisecond intervals. The function moves the image to the left by 10 pixels, and when the image is finally at the left edge, it cancels the interval.

Dynamic positioning has many uses in consumer and business applications. By combining dynamic styles, positioning, transparent images, and transparent ActiveX Controls, you can present a rich set of animation effects in your documents.

Dynamic positioning and animation is based on the W3C Working Draft on Positioning HTML with Cascading Style Sheets and will be adapted as needed to conform to the final recommendation. Documents that use positioning will be compatible with browsers that support this standard.

For a list of topics that describe and explain CSS positioning in full detail, see Positioning.

Filters and Transitions

Internet Explorer 4.0 supports an extensible architecture that enables you to specify filters and transitions using CSS properties. Visual filters can be used to apply visual effects to an element without requiring any scripts. The syntax is:

filter: filter_name( param1, param2, ...)

Transitions are effects that can be applied when changing the display of an element—switching from one image to another, for example. Both interpage transitions and transitions on specific elements within a page are supported. Transitions are most commonly seen in "slide show" presentations. Filters are effects (such as text drop shadows) that can be applied to content on Web pages. In addition to the set of standard filters and transitions included in Internet Explorer 4.0, the standard filters and transitions can be supplemented by additional third-party filters and transitions. For more information on filters, see Creating Multimedia Effects with Visual Filters and Transitions.

Font Download

Internet Explorer 4.0 supports the use of dynamically downloaded fonts. Using the @font-face style attribute, a document can reference a font that is automatically downloaded, used for the page only, and discarded once the page is no longer displayed. The following example shows the use of downloaded fonts.

<HTML><HEAD>
<STYLE>@font-face {font-family:comic;0 src:url(http://abc.domain.com/fonts/comicbold.eot);}
</STYLE>
</HEAD>
<BODY>
<p style="font-family:comic;font-size:18pt">this line uses the @font-face style element to display this text using the Comic Sans MS font in 18-point size and bold.
<p>
</BODY></HTML>

Data Binding

Data binding is a great feature of Dynamic HTML that lets you easily bind individual elements in your document to data from another source, such as a database or comma-delimited text file. When the document is loaded, the data is automatically retrieved from the source and formatted and displayed within the element.

One very practical way to use data binding is to automatically and dynamically generate tables in your document. You can do this by binding a TABLE element to a data source. When the document is viewed, a new row is created in the table for each record retrieved from the source, and the cells of each row are filled with text and data from the fields of the record. Because this generation is dynamic, the user can view the document even while new rows in the table are being created. Additionally, once all the table data is present, you can manipulate the data, such as sorting or filtering, without requiring the server to send additional data. The table is simply regenerated, using the previously retrieved data to fill the new rows and cells of the table.

Another practical use is to bind one or more elements in the document to specific fields of a given record. When the document is viewed, the elements are filled with text and data from the fields in that record, sometimes called the "current" record. A simple example is a form letter in which the name, e-mail address, and other details about an individual are filled from a database. To adapt the letter for a given individual, you simply specify which record should be the current record. No other changes to the letter are needed.

Yet another practical use is to bind the fields in a form to fields in a record. Not only can the user view the content of the record, but the user can also change that content by changing the settings and values of the form. The user can then submit these changes so that the new data is uploaded to the source—for example, to the HTTP server or database.

To provide data binding in your documents, you must add a data source object to your document. This invisible object is simply an ActiveX control or Java applet that knows how to communicate with the data source. Microsoft provides two data source objects with Internet Explorer 4.0: one to access comma-delimited data in text files, and another to access SQL data in SQL Server and other ODBC sources. Additional data source objects, such as a JDBC data source, will also be available from Microsoft and third parties.

The following simple document shows how easy it is to bind to a data source. When viewed, this document displays the first three fields from all the comma-delimited records of the file "sampdata.csv" in a clear, easy-to-read table.

<HTML>
<BODY>
<OBJECT CLASSID="clsid:333C7BC4-460F-11D0-BC04-0080C7055A83" ID=sampdata>
   <PARAM NAME="DataURL" VALUE="sampdata.csv">
   <PARAM NAME="UseHeader" VALUE="True">
</OBJECT>
<TABLE BORDER=1 DATASRC="#sampdata">
<THEAD>
<TR><TH>First Field<TH>Second Field<TH>Third Field
<TBODY>
<TR><TD><SPAN DATAFLD=A></SPAN><TD><SPAN DATAFLD=B></SPAN><TD><SPAN DATAFLD=C></SPAN>
</TABLE>
</BODY>
</HTML>

For a list of topics that describe and explain data binding in full detail, see Data Binding.

Dynamic HTML Object Model

The object model is the foundation of Dynamic HTML, providing the interface that allows scripts and components to access Dynamic HTML features.

Using the object model, you can access and manipulate virtually anything within the document. The HTML elements in the document are available as individual objects, meaning you can examine and modify an element and its attributes by reading and setting properties and by calling methods. The text is available through properties and methods on the elements.

The object model also makes user actions, such as pressing a key and clicking the mouse, available as events. You can intercept and process these and other events by creating event handler functions and routines. The event handler receives control each time a given event occurs and can carry out any appropriate action, including using the object model to change the document.

The following simple HTML document shows how you can use the object model to modify a document. This document changes the color of the heading and adds a line of text when the user clicks the mouse in the document.

<HTML>
<HEAD><TITLE>Welcome!</TITLE>
<SCRIPT LANGUAGE="JScript">
function changeMe() {
    document.all.MyHeading.style.color = "green";
    document.all.MyText.innerText = "You can do the most amazing things with the least bit of effort.";
}
</SCRIPT>
<BODY onclick="changeMe()">
<H3 ID=MyHeading>Welcome to Dynamic HTML!</H3>
<P ID=MyText>Click anywhere in this document.</P>
</BODY>
</HTML>

The example above contains an event handler, named "changeMe", that processes mouse clicks for the document. The handler uses the all collection of the document object to pick out the H3 and P elements using their ID values. It changes the color of the heading by setting the color property of the style object for that element. It replaces the text in the paragraph by setting the innerText property.

The object model is a superset of the JavaScript object model found in Netscape Navigator. This means that portions of the model are compatible with other browsers, even if they do not support Dynamic HTML. By following basic guidelines, you can write scripts that take full advantage of the object model when run in Internet Explorer and that provide reasonable results when run in browsers that do not support Dynamic HTML.

For lists of topics describing important aspects of the object model, see Working with Windows, Frames, and Dialogs, Scripting with Elements and Collections, and Understanding the Event Model.

For a complete listing of the objects, properties, methods, collections, and methods of the object model, see DHTML References.

Recommended Reading

Dynamic HTML provides authors with total creative control over all aspects of an HTML document. It extends traditional HTML and cascading style sheets to let you access and manipulate all elements of a document—tags, attributes, styles, images, objects, and text—creating, moving, and modifying these elements when and as needed.

If you are not familiar with HTML, cascading style sheets, and scripting languages, you should review the following documents before creating your own Dynamic HTML pages.

  • HTML 3.2 Reference Specification
  • W3C Recommendation for Cascading Style Sheets (CSS)
  • W3C Working Draft on Positioning HTML with Cascading Style Sheets
  • VBScript Tutorial & VBScript Language Reference
  • JScript Tutorial & JScript Language Reference


Dynamic Styles

You can dynamically change the style of any HTML element in a document. You can change colors, typefaces, spacing, indentation, position, and even the visibility of text. Because the Dynamic HTML object model makes every HTML element and attribute accessible, it is easy to use scripts to dynamically read and change styles. The following section describes dynamic styles and provides a general explanation of how to use the object model to examine and modify styles.

Making Styles Dynamic

Web authors gained unprecedented control over the look of documents with the introduction of cascading style sheets (CSS) in Internet Explorer 3.0. CSS allows authors and readers to attach a style to Web pages that defines the presentation of content by modifying style attributes of corresponding HTML elements.

Microsoft® Internet Explorer 4.0 takes CSS technology a step further, providing the ability to dynamically change any HTML attribute, at any time, on any element. Using simple JavaScript, JScript, or VBScript (Visual Basic® Scripting Edition), the attributes for any HTML element can be modified in response to any document or user event, and the page will automatically reflow without reloading the page from the server. This means that, for example, the STYLE element can be changed to change an element's inline CSS style, or any other HTML attribute (such as the SRC attribute on an IMG element).

Dynamic Styles Are Easy

You might expect that this new functionality will require that you learn a new set of HTML tags. However, dynamic styles have been designed to require no new HTML. CSS attributes can be set from the style sub-object for each element, while regular HTML attributes are accessed as properties on each element. For instance, to change the color of text within an H1 heading to red when the user moves the mouse over the heading, all you need to add is a simple piece of code known as an event handler.

<H1 onmouseover="this.style.color = 'red';">Make me red</H1>

The event handler, onmouseover="this.style.color = 'red';" takes a predefined action (onmouseover) and assigns an action for it to carry out when it fires (this.style.color = 'red'). It is just as easy to change not only the style but the content of a SRC attribute in the same manner.

<IMG src="before.gif" onmouseover="this.src = 'after.gif';">

In this example, as the mouse moves over the image, its source changes from "before.gif" to "after.gif". For more information on using event handlers, see Understanding the Event Model.

Documents Are Dynamic

When the color of an element is changed dynamically, it still fits into the same physical space in the document as it did before the color change. This is a relatively simple task for the browser to carry out. However, there are other styles, such as fontSize or fontFamily, that, when changed, actually change the size of the element and the amount of space required to display that element in the document. Internet Explorer 4.0 handles each such change automatically by reflowing a document to ensure that all the elements fit perfectly without reloading the document from the server.

<html>
<body>
This is some text.
<span style="color:blue" onclick="this.style.fontSize = '30'">

This is more text.</span>
This is even more text.
</body>
</html>

Initially, the document has two lines of text, identical in font size and color. After clicking "This is more text," the text changes, increasing in size and changing to blue. The browser automatically adjusts the line spacing to accommodate the new text size.

Powerful Attributes

Because Internet Explorer 4.0 automatically reflows the document when attribute values change, some very powerful functionality can be built with very small amounts of code. For example, using the CSS display attribute, you can make elements on the page disappear, and treat them as if they were never on the page in the first place.

<html>
<body>
<div style="cursor: hand" onclick="toggle(document.all.HideShow);">
Click Here</div>
<span style="color: blue" id=HideShow>This will go away</span><br>
This is some text
<script>
function toggle(e) {
  if (e.style.display == "none") {
     e.style.display = "";
  } else {
     e.style.display = "none";
  }
}
</script>
</body>
</html>

This HTML displays three lines. When the user clicks the line that says "Click Here", the browser changes the display attribute of the SPAN element with the text "This will go away" to display: none, and the text beneath shifts up to occupy its space. When clicked again, the display attribute is reset so that the "Click Here" text is visible again.

Notice that by simply setting display: none on an element, it disappears and the browser automatically reclaims the space it occupied. This mechanism can be used to create pages that display new information, such as an expandable table of contents, as the user interacts with individual entries. The two supported values for the display property are none and "" (or null).

The sample above also makes use of the CSS cursor attribute. The cursor attribute allows a Web author to specify what the cursor will look like when it is over an element. In this case, the hand cursor was chosen to indicate that the text titled "Click Here" would perform an action when clicked, just like a text link on a Web page. Using the cursor attribute eliminates the need to use an anchor tag to have the cursor change to a hand, indicating the contents are "clickable".

The set of valid values for the cursor attribute are crosshair, default, hand, move, e-resize, ne-resize, nw-resize, n-resize, se-resize, sw-resize, s-resize, w-resize, text, wait, and help.

While the display property makes an element invisible and allows the browser to reclaim the space that it occupied, the visibility property can be used to simply make an element disappear, but still reserve its space in the document.

The following example is identical to the previous demonstration, except it uses the visibility property instead of the display property.

<html>
<body>
<div style="cursor: hand" onclick="toggle(document.all.HideShow);">

Click Here</div>
<span style="color: blue" id=HideShow>This will go away</span><br>
This is some text
<script>
function toggle(e) {
  if (e.style.visibility == "hidden") {
     e.style.visibility = "visible";
  } else {
     e.style.visibility = "hidden";
  }
}
</script>
</body>
</html>

Notice how in this example the line of text will become invisible, but the content below does not shift up to reclaim its space.

Special Considerations

You might have noticed that many CSS properties have a dash in their name (such as background-color). The dash, as you may know, isn't a valid character for identifiers in most scripting languages. To get around this little problem, continue to use the dashed name when specifying the CSS attribute in HTML or in a style sheet, but when accessing the attribute as a script property, remove the dash, and capitalize the next letter. For example:

background-color becomes backgroundColor

border-left becomes borderLeft

margin-bottom becomes marginBottom

The CSS attribute names specified in the HTML or style sheet are listed in the CSS Attributes section of the SDK. The corresponding scriptable properties are listed as properties of the style object in the Objects section of the SDK.

Also notice that while any CSS property can be set at any time, the current settings on the STYLE element will only reflect its inline styles, and not any inherited styles that are defined in a global style sheet with a STYLE or LINK tag. The following example shows what happens when a style is defined both globally and inline.

<html>
<head>
<style>
.class1 {font-family: arial}
</style>
</head>
<body>
<div id=SetByClass class=Class1>Set By Class</div>
<div style="font-family: arial">
      <div id=Inherited>Inherited</div>
</div>
<div id=DirectlySet style="font-family: arial">Directly Set</div>
<div id=SetWithScript>Set with Script</div>
<script>
      alert(SetByClass.style.fontFamily);
      alert(Inherited.style.fontFamily);
      alert(DirectlySet.style.fontFamily);
      SetWithScript.style.fontFamily = "arial";
      alert(SetWithScript.style.fontFamily);
</script>
</body>
</html>

When this document loads, four alert dialog boxes pop up successively. The first two are blank, while the next two contain the text "arial." While all the text on the document is Arial, referencing style.fontFamily will show "arial" only on the DIV that had the font-family property set with an inline style or was previously set with script.

Additional Topics

With Internet Explorer 4.0, authors have total control over all attributes of all elements, at any time. Changes made to attributes that cause the page to change shape are handled automatically, with no additional script intervention by the author. Changing attributes through script can be done simply with inline script, or by pointing to a function where the element is accessed through a collection on the document. For more information about accessing elements through collections, see Scripting with Elements and Collections, or simply dive into the reference for details on the document collections and details on each HTML attribute that can be changed. You might also want to check out the event bubbling information for how to bind event handlers to one of the many events that the document can fire. The following topics describe some specific topics of dynamic styles:

  • Changing Element Styles
  • Managing Style Sheets
  • Style Sheets and Printing

Related SDK sections:

  • Scripting with Elements and Collections
  • Understanding the Event Model
  • CSS Attributes
  • HTML Elements
  • Objects


Changing Element Styles

Dynamic HTML allows you to write script that can change the HTML attributes that modify a given element. These attributes can be things such as the SRC attribute on an IMG or IFRAME element, or the STYLE attribute for a DIV element. This document shows you how to change the SRC= attribute on an IFRAME element so that the contents of IFRAME change on the fly. The same example also shows you how to change the background color of the body for the SRC= document of the IFRAME. The next set of examples shows how to change the class name of the element so that it is associated with a different style sheet.

Dynamic HTML gives you scriptable access to all HTML elements, attributes, and CSS styles. You as the author can use these techniques to design some pretty cool DHTML Web pages.

Changing the Style of an IFRAME

Changing Element Classes

Scripting CSS Attributes

Changing the Style of an IFRAME

The following example shows how to change the contents of IFRAME as well as change the style attribute of the BODY element of the contained IFRAME. Click the Show Me button to show the page, and then look at the code.

<HTML>
<HEAD><TITLE>Changing Element Attributes</TITLE>
<SCRIPT LANGUAGE="JavaScript">
 function change_image() {
   document.all.myiframe.src="frame_content2.htm";
   //use the all collection to access attributes of the IFRAME element
}
function change_background() {
     document.frames.myiframe.document.body.style.backgroundColor="green";
     // use the frames collection to access the document contained in the IFRAME.
}
</SCRIPT>
</HEAD>
<BODY>
    <IFRAME id=myiframe src="frame_content.htm">
    </IFRAME>
    <BUTTON onclick=change_image()>Change contents of the IFRAME</BUTTON>
    <BUTTON onclick=change_background()>Change the background color of the IFRAME</BUTTON>
</BODY>
</HTML>

Changing Element Classes

There are two primary ways to change the inline style for an element—either change the element's STYLE attribute, or change the className of the element to match a defined class in a global style sheet. The following example shows how straightforward it is to change the inline STYLE attribute with an event.

<H1 id=myStyle onclick="this.style.color=blue">This text will change to blue when clicked </H1>

This changes the property "color" of the style sub-object for the H1 element.

However, to change the style for more than one element, use global style sheets, which let you define styles based on a "contextual selector"—styles can apply to tag names, element identifiers, or all elements in a class. The DHTML class attribute on every element lets you associate any element with any class name. This way, multiple elements can belong to a single class, and setting a global style for a class means that the style sheet applies to every element with that class name.

Because the class attribute can be scripted, you can dynamically change class associations with elements in a document, as in the following example.

<HTML>
<HEAD><TITLE>Changing Element Attributes</TITLE>
<STYLE>
.textRed {color:red}
.textBlue {color:blue}
</STYLE>
</HEAD>
<BODY>
<H1 class=textBlue onmouseover="this.className='textRed'" onmouseout="this.className='textBlue'">Mouse over this text to see
the color change from blue to red and back to blue</H1>
</BODY>
</HTML>

In the example, global rules are defined for two classes, "textRed" and "textBlue". The H1 initially is a part of the textBlue class and therefore is displayed in blue. Moving the mouse over the text fires the onmouseover event, and the inline event handler changes the association of the H1 element to the textRed class, which renders the text red. Note that the class attribute is referenced through the className property.

Note The scriptable properties for CSS styles are all read/write except position. You cannot dynamically set a nonpositioned element to be positioned. If you want to absolutely position an element using an event handler script, be sure that the element has its initial position set to relative using either a global style sheet or an inline style.

Scripting CSS Attributes

All style attributes are strings. Several properties have been added to the style object to help manipulate values as nonstrings. For example, pixelHeight is an integer so that the height of an object can be mathematically manipulated in base pixel units regardless of how the height attribute was set. The posHeight property is an integer that describes the height attribute in the units to which the author originally set the CSS height attribute.

If a style property represents some number of units, you can include a units designator when assigning the value. The "pt" (points) and "px" (pixels) designators are used in the following examples.

document.all.MyElement.style.fontSize = "24pt";
document.all.MyElement.style.fontSize = "120px";

If you don't supply a units designator, the default unit of measure for the property is used. One benefit of this is that you can assign a number or the result of an expression (rather than a string) and it will be converted automatically. For example, the assignments below are the same—they both set the font size to 72 pixels.

document.all.MyElement.style.fontSize = "72";
document.all.MyElement.style.fontSize = 72;


Managing Style Sheets

Dynamically changing cascading style sheet (CSS) styles that are applied to documents is not limited to the inline styles (styles defined with the STYLE= attribute). Global style sheets defined with a LINK or STYLE tag in the HEAD section of the document can be manipulated through script. Manipulating the global style sheet is a powerful way to dynamically change the styles that apply to Web pages.

styleSheets Collection

Global style sheets are made accessible to script through the styleSheets collection on the document object. This collection represents instances of STYLE and LINK elements in the HEAD section of the document with a type (or type attribute) of "text/css". Style sheets of other types are not supported. Imported style sheets are contained within a STYLE element, and are surfaced by the containing STYLE element as type styleSheet. STYLE and LINK elements can be added to the document through the createElement method on the window object. This method adds a new style sheet object to the styleSheets collection on the document. Style rules and imported style sheets can then be added to this style sheet with the addImport and addRule methods.

You can use identifiers to access style sheets in the document. You set an identifier for a style sheet by setting the ID attribute of the LINK or STYLE element.

Disabling Style Sheets

A powerful feature of the styleSheet object is that you can turn a style sheet off and on dynamically. The disabled property defaults to false, but can be set to "true" to remove the style sheet from being applied to the document. Toggling the application of style sheets is another technique for dynamically changing the style of a Web page.

Replacing Style Sheets

You can replace one style sheet with another by setting the href property of the style sheet to the URL of the replacement, as in the following example:

if (document.styleSheets(0).href != null)
    document.styleSheets(0).href = "newstyle.css";

When you replace a style sheet, the styleSheets collection is immediately updated to reflect the change. Replacing a style sheet in this way is available only for style sheets that have been included using the LINK element or the @import statement. The href property is null for style sheets defined using the STYLE element.

Dynamically Changing Style Sheet Rules

Each style sheet is a collection of rules. The rules collection of the styleSheet object enumerates these rules. This collection can be accessed even if the style sheet is disabled. Rules are added and removed from the rules collection with add and remove methods on the individual style sheet. A rule that is added to a disabled style sheet will not apply to the document unless the style sheet's disabled property is changed to "false".

The rules in the rules collection are in the source order of the document. Style rules linked in using the "@import" syntax of CSS are expanded in-place in the rules collection per the CSS1 specification.

As rules are added or deleted, a rule's absolute position in the rule collection may change, but its position relative to other rules will remain the same. The default location to add a new rule (without specifying an index) is at the end of the collection, which is the highest precedence (not accounting for selector specificity, as per the CSS specification) and is applied to the document last. If an index is supplied, the rule should be inserted before the rule currently in that ordinal position in the collection, or, if the index is larger than the number of rules in the collection, it should be added to the end .

The following is an example of using the addRule method.

<HTML>
<HEAD>
<SCRIPT LANGUAGE="JScript">
function newRule() {
    document.styleSheets.MyStyles.addRule("P","color:blue");
}
</SCRIPT>
<STYLE ID="MyStyles">
H1 {color:red}
H2 {color:red;font-style:italic}
</STYLE>
</HEAD>
<BODY onclick="newRule()">
<H1>Welcome!</H1>
<P>This document uses style sheets.</P>
<H2>Ways to Include Style Sheets</H2>
<UL>
<LI>LINK
<LI>STYLE
<LI>@import
</UL>
</BODY>
</HTML>

Each rule has a selector, identifying the elements to apply the rule to, and a list of style assignments, identifying the style attributes to apply to these elements. The selector is typically the name of an element, class, or identifier, but can also be a combination of names, such as a comma-separated list of element names. Each style assignment consists of a style attribute name and a value separated by a colon. If there is more than one assignment, the assignments are separated by semicolons. The rule object has a readOnly property that indicates whether the particular rule is from an editable source. Imported and linked styles cannot be edited, so the readOnly property for the contained rule would return "true".

As an example of manipulating style rules, consider the following simple style sheet:

<STYLE
ID="MyStyles">
H1 {color:red}
H2 {color:red;font-style:italic}
</STYLE>

The rules collection would contain two rules. Each rule has two parts (and corresponding properties): the selector and the style. The selector in the first rule in the above style sheet is "H1".

alert(document.styleSheets[0].rules[0].selectorText); // this returns "H1"

To change the style of the first rule in the first style sheet, use the following:

document.styleSheets[0].rules[0].style.color = "blue";

User-Defined Style Sheets

Through the Options dialog box of the browser, users can specify a style sheet that they want to have applied to all pages that they view. This style sheet will be applied to the document first, meaning the author has the final say of how a CSS attribute is defined. Style sheets defined in the document override the user-defined style sheet. The user-defined style sheet is simply a "preference" that will affect the page if the author has not defined a rule for that CSS attribute. User-defined style sheets specified by the user in the Options box dialog of the browser are not listed in the styleSheets collection.


Style Sheets and Printing

The STYLE and LINK elements support the MEDIA attribute, which defines the output device for the style sheet. Values for MEDIA are SCREEN, PRINT and ALL. The default is SCREEN, so not setting the MEDIA attribute causes the style sheet to always be applied to the page for the screen as well as printing. The PRINT value specifies that the style sheet is used when the page is printed; this value does not affect how the document will be displayed onscreen. The ALL value determines that the document is formatted for both the screen and print.

Note that all filter: styles, including visual effects filters, are ignored when printing. Internet Explorer renders this content for printing with any applicable text style properties.

Setting Page Breaks For Printing

You can control the placement of page breaks in your documents by using the page-break-before and page-break-after attributes. These attributes indicate when to break to a new page when printing the document and on what page (left or right) to resume printing. These attributes are useful when you want to print long documents into logical sections.

For example, the following document defines a class "page" in a style sheet and uses it to set page breaks in the document.

<HTML>
<HEAD><TITLE>Dynamic Styles: Page Breaking</TITLE>
<STYLE>
    BR.page { page-break-after: always }
</STYLE>
</HEAD>
<BODY>
    .
    content on page 1
    .
<BR CLASS=page>
    .
    content on page 2
    .
</BODY>
</HTML>

You can set page breaks from within a script by setting the pageBreakBefore and pageBreakAfter properties on the style object. The following example sets a page break immediately before each H1 element in the document. The heading is subsequently printed on a right-hand page.

var coll = document.all.tags("H1");
for (i=0; i<coll.length; i++) {
    coll(i).style.pageBreakBefore = "always right";
}


Dynamic Content

Before Microsoft® Internet Explorer 4.0, once a Web page was loaded into a user's browser, changing the information displayed on the page required another round-trip to the server. The user interacted with the page (submitted a form, or clicked a link to another page), and the server delivered a new page to the client. Any customization of the information (such as building the page on the fly from a template) required that the server spend additional time processing a page request. Furthermore, the only way to maintain the context for the page's content was to use frame sets, where one frame's content stays constant and another frame changes its content based on the user's activity on the initial page.

Dynamic content is all about changing the content of the HTML document—inserting and deleting elements or the contents of an element before or after the document has been loaded. To see an example of how dynamic content works, enter text in the text box to change the following text:

Dynamic content is cool

Internet Explorer 4.0 gives you a rich set of properties and methods to dynamically construct and alter Web pages on the fly. For example, a script can insert a list of section titles at the beginning of the document, or replace that list with a list of links to the actual sections in the document.

The following topics show how to dynamically access and modify the content in your Web pages.

Changing HTML Content

Adding Document Content

Example: Building a Table of Contents

Advanced Topics

For more information about advanced text manipulation that can be done using a TextRange object, see Using the TextRange Object.

Changing HTML Content

Internet Explorer 4.0 provides a set of properties and methods on each element that are designed to make it quite simple to change the document. There are four properties that provide the ability to see what's inside an element on the page and replace that content with new information: innerText, outerText, innerHTML, and outerHTML.

Assigning new text (also called a "string") to one of these properties replaces the contents of the element, including any elements contained by that element, with the new string. Consider the following HTML for an H1 heading.

<H1 id=myH1>Dynamic Content is Very Cool!</H1>

The content of the H1 can be changed with the innerText property.

document.all.myH1.innerText = "DHTML is Very Cool"

The H1 element remains in the document, while the content of the H1 changes to contain the new string "DHTML is Very Cool". The string assigned to innerText renders any HTML tags as text, and does not process the HTML. To insert HTML code into the contents of another element, you must use the innerHTML property.

document.all.myH1.innerHTML = "DHTML is <I>Very</I> Cool!"

The new string replaces the original content of the H1, and the word "Very" appears in italic.

The outerText and outerHTML properties represent the element itself, as well as the contents of the element. Assuming that the preceding example is contained by a BODY element, using an outerText property on the H1 replaces the entire element with the string attached. The following script causes the H1 to go away entirely, and the text string appears where the element was in the flow of the BODY 's content.

document.all.myspan.outerText = "DHTML is VERY Cool!"

The outerHTML property replaces the element with rich HTML. Much like the example above where HTML was inserted in the H1, using the outerHTML property will do the same, except the H1 would also be removed.

document.all.myH1.outerHTML = "<SPAN STYLE='height:0;width:200;FILTER:Shadow(color=#00FF00)'>RICH HTML</SPAN>";

Adding Document Content

The properties described above replace the entire contents of an element with a new string. What if you only want to insert new text or HTML and don't want to change what is already in the document? There are two helper methods on most elements that help you do just this.

These methods, insertAdjacentHTML and insertAdjacentText, place the new content at the beginning or end of the element, leaving the existing content intact. These methods all take a parameter that indicates one of four possible places the new content can be inserted with regard to the element: BeforeBegin, AfterBegin, BeforeEnd, and AfterEnd.

The following example appends a new paragraph to the end of the document when it loads.

<HTML>
<HEAD>
<TITLE>Dynamic Content: Inserting Elements</TITLE>
<SCRIPT LANGUAGE="JScript">
function insertPara()
{
   document.body.insertAdjacentHTML("BeforeEnd", "<P>But adding a line makes it less so.");
}
</SCRIPT>
</HEAD>
<BODY onload="insertPara()">
<P>This is a <B>very</B> short document.
</P>
</BODY>
</HTML>

Example: Building a Table of Contents

Building a table of contents is a good example of dynamic content at its best. By using a relatively small amount of script, you can automatically generate a detailed list of the contents of any document.

This example consists of three functions: buildTOC, setAnchor, and setLink. The buildTOC function creates the table of contents, calling the other two functions to apply anchors and insert the links. The example depends on the document having an element, such as DIV or P, that has the identifier "MyTOC". The setLink function inserts the links there. To build the table successfully, buildTOC cannot be called until the document is fully loaded.

Once buildTOC is called, it uses the all collection to check each element to see whether it is a header element: H1, H2, H3, or H4. It starts the search at the first element after the BODY element since no links are possible before this. When it finds a header, it sets the "level" variable and calls the setAnchor and setLink functions.

function buildTOC() {
    var coll = document.all;
    var level;
    var id;
    for (i=document.body.sourceIndex+1; i<coll.length; i++) {
        switch (coll[i].tagName) {
        case "H1":
            level = 0;
            break;
        case "H2":
            level = 1;
            break;
        case "H3":
            level = 2;
            break;
        case "H4":
            level = 3;
            break;
        default:
            level = -1;
        }
        if (level!=-1) {
            id = i;
            setAnchor(coll[i], id);
            i++;
            setLink(coll[i], level, id);
            i+=2;
        }
    }
}

Notice how the variable "i" is updated after the call to setAnchor and setLink. These functions insert new elements into the document, causing the all collection to be immediately updated and requiring a new index value for the heading. The setAnchor function inserts one element before the heading, so the index is increased by one; the setLink function inserts two elements at the top of the document, so the index is increased by two.

The setAnchor function adds an A element to the document, inserting the start and ends tags for this element immediately before and after the header tag, and setting the NAME= attribute of the new element to be equal to the "id" parameter passed to the function.

function setAnchor(el, id) {
    el.insertAdjacentHTML("BeforeBegin", "<A NAME=\"" + id + "\">");
    el.insertAdjacentHTML("AfterEnd", "</A>");
}

The setLink function adds another A element to the document. This time the element is a link to the heading that setAnchor just created an anchor for. The HREF= attribute is set to the same "id" value as was set in the matching anchor. Notice that the setLink function places the link just before the end of the element having the identifier "MyTOC", separating it from the previous link with a BR element and inserting zero or more nonbreaking spaces for a very simple way to indicate the heading level.

function setLink(el, level, id) {
    document.all.MyTOC.insertAdjacentHTML("BeforeEnd", "
");
    var s = "&nbsp;";
    for (j=0; j<level; j++)
        s = s + s;
    document.all.MyTOC.insertAdjacentHTML("BeforeEnd",
        s + "<A HREF=\"#" + id + "\">" + el.innerText + "</A>");
}

There are a few things to keep in mind when you are dynamically changing content in your Web page.

Can't modify the content until after the document has been loaded: Keep in mind that you cannot assign a string to these properties until the document has been completely loaded, that is, until the onload event occurs. If you attempt to do so before loading, an error occurs.

Be careful! When you add an element to a document, the all and other element collections are automatically updated to reflect the change. This also affects the value of the sourceIndex for elements that follow the new elements. If you have saved the index value of an element, be careful to update that value or retrieve a new value whenever you add or delete elements in a document.

Can't put invalid HTML in the document: You cannot assign a string to innerHTML or outerHTML that contains invalid HTML. For example, trying to replace the content of the P element with another P will fail. A P element can only contain text and inline elements. However, replacing the entire P element with another P would work just fine.

Which Elements Will This Work For?

Here are a few guidelines for which elements you can expect these properties and methods to work.

Only elements that appear in the BODY of the document can be changed with these properties. You can replace the contents of the BODY, but you can't replace the BODY itself.

This should be obvious, but deserves mention anyway: you can't replace the contents of an element where the element type doesn't have any contents like the replaced elements, INPUT and IMG.

The contents of a TD can be changed (innerText and innerHTML) and the TABLE element itself can be replaced (outerText and outerHTML), but no other table elements and their contents can be changed with these properties.

Advanced Topics

The following sections provide information on more advanced text manipulation.

Using the TextRange Object

Finding Text in the Document


Using the TextRange Object

Most users will only want to use the innerText/innerHTML and outerText/outerHTML properties and methods discussed previously. However, there is some more advanced text manipulation that can be done using a "text range" object. The TextRange object can be used to:

  • Locate the text for a given element or a given point.
  • Search for words and characters in the text of the document.
  • Move through the text in logical units.
  • Provide read/write access to the plain text and the HTMLText in the document.

This feature might not be available on non-Win32® platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Overview of the TextRange Object

Text range objects are an advanced feature of Dynamic HTML that you can use to carry out useful tasks related to dynamic content, such as searching for and selecting text. Text ranges let you selectively pick out characters, words, and sentences from a document. The TextRange object is an abstract object that creates a start and end position over the stream of text that would appear in the HTML document. Consider the following simple HTML document:

<HTML>
<BODY>
<H1>Welcome</H1>
<CENTER><H2>Overview<H2></CENTER>
<P>Be sure to <B>Refresh</B> this page.</P>
</BODY>
</HTML>

In this document, creating a text range over the BODY would position the start at the beginning of the textual content of the BODY, and the end at the end of the textual content of the BODY. This text range would contain the plain text "Welcome Overview Be Sure to Refresh this page."

What Do I Do with a TextRange Object?

There are two parts to manipulating text with a TextRange object. The first is to create a text range so that the start and end positions encompass the desired text. The next step is to apply a method to the text range, or make a copy of the text to be used elsewhere in the document. Once the text range is positioned, you can search for text, select the text, and make a copy of the text and use it elsewhere in your document.

See the TextRange object in the Object Model Reference for the properties and methods supported.

Positioning the TextRange Object

Each text range has a start and an end position defining the scope of the text that is encompassed by the TextRange object. When you create a new text range, the start and end positions encompass the entire content by default. Use methods such as move, moveStart, and moveEnd to change the scope of the text range.

Other methods can position the TextRange object with respect to a particular element, or a point on the page. For example, moveToElementText positions the text range so that it encompasses the text contained by the given element. moveToPoint positions the text range at a given point where the user clicked a mouse button. The x and y positions of the user's click are known by the window.event object and can be used to position the range over a given point. From this collapsed point, the range can then be expanded to encompass a word, sentence, or a whole textEdit (the entire possible TextRange object).

<HTML><HEAD>
<TITLE>moveToPoint Example</TITLE>
<script>
function selectMe() {
var r=document.body.createTextRange();
r.moveToPoint(window.event.x, window.event.y);
r.expand("word");
r.select();
}
</script>
</HEAD>
<BODY>

<H1 id=myH1 onclick=selectMe()>Click on a word and it will highlight</H1>

</BODY></HTML>

You create a TextRange object by applying the createTextRange method to a BODY, TEXTAREA, or BUTTON element. You can also create a text range from a selection made by the user. The createRange method on the selection object returns a text range. You can use the same methods and properties on this range as you do for ranges created using createTextRange.

Creating a TextRange object on the body will not include the content inside a TEXTAREA or BUTTON. Conversely, you cannot change the start or end position of a text range over the TEXTAREA or BUTTON to move outside the scope of these particular elements. Use the properties provided on each element, isTextEdit and parentTextEdit, to walk the hierarchy. If the document above contained a TEXTAREA, a createTextRange on the body object would not find the position where the user actually clicked. The following reworks the above example to handle this case.

<HTML><HEAD>
<TITLE>moveToPoint Example</TITLE>
<script for=document event=onclick>
     var r
     if(window.event.srcElement.isTextEdit)
           {
            r=window.event.srcElement.createTextRange();
     }else{
            var el=window.event.srcElement.parentTextEdit;
            r=el.createTextRange();
           }
     r.moveToPoint(window.event.x, window.event.y);
     r.expand("word");
     r.select();
</script>
</HEAD>
<BODY>

<H1 id=myH1>Click on a word and it will highlight</H1>

<TEXTAREA>
There's text in this element too that you could click on
</TEXTAREA>

</BODY></HTML>

Getting the Content of a TextRange

The content of a TextRange object can be viewed with the text or HTMLtext property on the TextRange object. The text property is a read/write property that is similar to the innerText properties on the element objects, only this replaces the text encompassed by a TextRange object.

HTMLtext is a read-only property that lets you examine the HTML that is contained within the start and end points of the TextRange object. To add rich HTML content to the text range, use the pasteHTML method. Although you can paste any HTML text that you want into a text range, the pasteHTML method does not preserve the hierarchy of the document, as do the innerHTML and outerHTML properties. Although pasteHTML won't fail if you paste invalid or inappropriate tags into the range, the resulting document may not look or behave the way you expect. If you paste an HTML fragment, the fragment is automatically closed to prevent it from affecting subsequent text and elements. For example, this means if your scripts rely on ordinal positions in the document's all collection, after a pasteHTML, the sourceIndex into the document.all collection may point to a different element.

Comparing Ranges

You can create more than one text range at a time, using them for independent, simultaneous access to different portions of the text in an element. You can also copy a text range by using the duplicate method. This is useful if you want temporary access to a portion of the original range but don't want to bother recreating or restoring the original range. You can determine the relationship of one text range to another by using methods such as isEqual and inRange.

Because the object model never holds on to a text range, you'll need to recreate any range whenever control leaves and then reenters your code. For example, any text range objects created by an event handler are discarded when the event handler returns.

You can determine whether one range in entirely contained within another text range by using the inRange method. You can determine whether two text ranges are identical by using the isEqual method. Text ranges are identical if they start and end at exactly the same positions. Note that identical text ranges are always considered to be within one another, meaning the inRange method returns true for these.

You can set the start or end point of a range to match the start or end point of another range by using the setEndPoint method. The method takes two parameters: a string describing which end points to transfer, and a range from which the source end point is taken. The following example sets the end of the range "r1" to the start of "r2".

r1.setEndPoint( "StartToEnd", r2 )

You can also use "StartToStart", "EndToStart", and "EndToEnd" to set the end points.

You can compare the start or end points of two ranges by using the compareEndPoints method. This method compares the end points and returns -1, 0, or 1, indicating whether the end point of the first range is less than, equal to, or greater than that of the second.

A bookmark is an easy way to save the current start and end positions of a text range and quickly restore these positions when you need them. You create a bookmark for a given range by using the getBookmark method, which returns an opaque string that uniquely identifies the bookmark. (Opaque means the string cannot be examined or modified.) You use the string with the moveToBookmark method to move the text range back to the same start and end positions as when the bookmark was created.

Commands

You can use commands to apply formatting and to carry out special actions on the text of a text range. You execute a command by using the execCommand method. You supply a command identifier and provide any additional command parameters. For example, you can change text to bold by using the Bold command as in the following JScript example.

var rng = document.body.createTextRange();
rng.collapse();
rng.expand("sentence");
rng.execCommand("Bold");

The above example makes bold all text up to the first period in the document.

Not all commands are available at all times. You can determine whether a command is available for a given text range by using the queryCommandEnabled and queryCommandSupported methods. For a list of commands, see Command Identifiers.

To determine whether a given command has already been applied to a text range, use the queryCommandState method to retrieve the state of the command. The state is true if the command has been applied.


Finding Text in the Document

You can search for a given string of text in a document by using the findText method on a TextRange object. This method starts the search at the beginning of the range and, if it finds the string, positions the range so that it entirely encloses the string. The following example uses findText to search for each instance of the word "sample" and displays a message identifying how many instances it found.

var rng = document.body.createTextRange();
for (i=0; rng.findText("sample")!=false; i++) {
    rng.collapse( );
}
alert("There are " + i + " instances of sample");

In the above example, the collapse method moves the start of the text range to the same position as the end point, ensuring that the same instance of "sample" is not counted twice.

You can carry out a global search and replace by using findText and the text property. The following example searches for each instance of "sample" and replaces it with the word "final".

var rng = document.body.createTextRange();
for (i=0; rng.findText("sample")!=false; i++) {
    rng.text = "final";
}

You can select the text that you find, making it easier for the user to see, by using the select method. Similarly, you can scroll the text into the user's view by using the scrollIntoView method. Together, these methods give you a way to make the result of a search clearly visible to the user. The following JScript example searches for the word "sample", selects the word, and then scrolls the word to the top of the window.

var rng = document.body.createTextRange();
if (rng.findText("sample")==true) {
    rng.select();
    rng.scrollIntoView();
}

Note that you can also create a text range from a selection made by the user. The createRange method on the selection object returns a text range. You can use the same methods and properties on this range as you do for ranges created using createTextRange.


Positioning

Microsoft® Internet Explorer 4.0 supports the ability to position HTML elements in x- and y-coordinates, as well as overlap elements in planes along the z-axis, which extends toward and away from the viewer in a Web document. This capability allows authors to place elements—images, controls, or text—exactly where they want on the page. By using scripts to manipulate the position coordinates and other dynamic styles, authors can move elements around a page, creating animated effects. The combination of dynamic styles, positioning, transparent ActiveX™ Controls, and transparent images presents authors with a rich set of animation options.

What Is Positioning?

Absolute Positioning

Relative Positioning

Positioning Considerations

Controlling Content Visibility

Element Visibility

What Is Positioning?

CSS Positioning defines the placement of elements on a page, and is an extension of cascading style sheets as specified in the W3C Working Draft on Positioning HTML with Cascading Style Sheets. By default, elements "flow" one after another in the same order as they appear in the HTML source, with each element having a size and position that depends on the type of element, the contents of the element, and the display context for the element as it will render on the page. This default "flow" model for HTML layout doesn't provide the author a high level of control over the placement of elements on the page. By applying a small set of CSS attributes to the elements that are defined for the page, you can control the precise position of elements by giving exact coordinates, or specifying placement relative to the position of other objects on the page.

Just like any other HTML or CSS attribute, the CSS attributes used to control an element's position are available for scripting. The position of these elements on the page can thus be dynamically changed with script. This is very powerful! The position of these elements can be recalculated and redrawn after the document is loaded without needing to reload the page from the server.

Controlling the position of an element uses several other layout control techniques. These include controlling the display of the object—that is, whether or not the element is displayed on the page, and how much of the element can be viewed by the user.

There are two ways to position an element in x- and y-coordinates. The type of positioning to use depends on the layout of the content and the purpose of the document. Absolute positioning means that the element is precisely placed relative to the parent coordinate system, regardless of any other content. Relative positioning places the item with respect to other elements on the page. Relative positioning depends on the default flow of the document, and reflows content should the user resize the browser.

Absolute Positioning

An absolutely positioned element is always relative to either the next positioned parent or, if there isn't one, the BODY by default. Values for left and top are relative to the upper-left corner of the next positioned element in the hierarchy. For example, to place an image at the top left corner of the document, you set the attributes to 0 as follows:

<IMG SRC="sample.gif" STYLE="position:absolute; left:0; top:0">

This positions the image within the border of the BODY element. Remember, there is a default border on the BODY, so if no border is desired, set the border of the BODY to 0 to position the image at the 0,0 coordinates of the client area.

To see how a positioned parent affects the absolute position, consider the following example.

<DIV STYLE="position:relative;left:50;top:30;height:100;width:100">
        Some text inside the DIV that will be hidden by the image because the image will be positioned over this flowing text.
    <IMG SRC="sample.gif" STYLE="position:absolute; left:0; top:0">
</DIV>

This example places the IMG element at the upper-left corner of the DIV element, which is itself positioned on the page.

Setting an absolute position pulls the element out of the "flow" of the document and positions it regardless of the layout of surrounding elements. If other elements already occupy the given position, they do not affect the positioned element, nor does the positioned element affect them. Instead, all elements are drawn at the same place, causing the objects to overlap. You can control this overlap by using the z-index attribute to specify the order in which elements are stacked at the same location.

The contents of a positioned element flow within the given dimensions as default HTML would flow. For instance, text would wrap normally based on the width of the element, and various inline elements contained within the positioned elements will be placed next to each other in source order according to the constraints of size and shape of the "container" (that is, the positioned element).

Relative Positioning

Setting the CSS position attribute to "relative" places the element in the natural HTML flow of the document but offsets the position of the element based on the preceding content. For example, placing a piece of text within a paragraph with "relative" positioning renders the text relative to the text in the paragraph that precedes it.

<P>The superscript in this name<SPAN STYLE="position: relative; top:-3px">xyz</SPAN> is "xyz".

Should the user resize the window, the "xyz" still appears three pixels above the natural baseline of the text. You can set the left attribute in a similar way to change the horizontal spacing between "name" and "xyz". If the contents of the SPAN were absolutely positioned, the "xyz" would be placed relative to the BODY (or the next positioned element in the hierarchy), and the "xyz" would be barely visible at the upper corner of the client area—not the effect the author probably intended!

Text and elements that follow a relatively positioned element occupy their own space and do not overlap the natural space for the positioned element. Contrast this with an absolutely positioned element where subsequent text and elements occupy what would have been the natural space for the positioned element before the positioned element was pulled out of the flow.

It is quite possible that relatively positioned elements will overlap with other objects and elements on the page. As with absolute positioning, you can use the z-index attribute to set the z-index of the positioned element relative to other elements that might occupy the same area. By default, a positioned element always has a higher z-coordinate than its parent element so that it will always be on top of its parent element.

Positioning Considerations

The type of positioning to use depends on the layout of the content and the purpose of the document. Relative positioning depends on the default flow of the document and will reflow content should the user resize the browser. However, absolute positioning gives you the control to precisely place images and text no matter what the user does to the display.

Here is an example of nesting an absolutely positioned element within a relatively positioned element. The desired effect is to center text in a rectangle. In the past, you might build tables and use attributes to center the content inside a table cell. However, this layout restricts you to a static table. Using positioning, this content can be worked into a larger layout, and then you can add scripting that might, for instance, have each of these elements fall into place from somewhere outside the document as the user loads the page!

<HTML>
<HEAD><TITLE>Center the DIV</TITLE>
<SCRIPT LANGUAGE="JScript">
function doPosition() {
document.all.two.style.top = document.all.one.offsetHeight/2 -
document.all.two.offsetHeight/2;
document.all.two.style.left = document.all.one.offsetWidth/2 -
document.all.two.offsetWidth/2;
}
</SCRIPT>
</HEAD>
<BODY onload="doPosition()">
<P>Some text in the beginning.</P>
<DIV ID=one STYLE="position:relative; top:10;height:200;width:200;background-color:green">
Some text in the outer DIV
<DIV ID=two STYLE="position:absolute;left:50;width:100;color:red;border:red 2px solid">
text in the inner DIV - color should be red
</DIV>
</DIV>
</BODY>
</HTML>

In the example above, the outer DIV "flows" with the contents of the document that precedes it, meaning it is positioned 10 pixels immediately after the first paragraph. The inner DIV has an initial absolute position, but this position is modified by the script function "doPosition" when the document is loaded. The offsetWidth and offsetHeight properties are used to calculate the new absolute position for an element. In the example above, you can also use the posLeft or pixelLeft property to center the images. These properties give alternate access to the left property, letting you set the position using a floating point number or an integer. There are similar pos* and pixel* properties that provide alternate access to the top, width, and height properties.

Combining Dynamic Positioning Techniques

The previous example can be expanded to manipulate multiple items on the page. Or, to animate this script, you might rework the scripting function on the "onload" of the document to have the inner piece of text "fly in" from offscreen. This function could be based on a timer that would move the inner DIV from an initial top and left coordinate somewhere off the visible portion of the page, and, over a given amount of time, move it to a position that would be in the center of the outer DIV.

The following example makes the DIV element visible and animates the content to glide across the screen. By setting an interval using the setInterval method on the window object, you can move one or more elements each time the interval elapses.

<HTML>
<HEAD><TITLE>Glide the DIV</TITLE>
<SCRIPT LANGUAGE="JScript">
var action;
function StartGlide() {
    document.all.Banner.style.pixelLeft =
        document.body.offsetWidth;
    document.all.Banner.style.visibility = "visible";
    action = window.setInterval("Glide()",50);
}
function Glide() {
    document.all.Banner.style.pixelLeft -= 10;
    if (document.all.Banner.style.pixelLeft<=0) {
        document.all.Banner.style.pixelLeft=0;
        window.clearInterval(action);
    }
}
</SCRIPT>
</HEAD>
<BODY onload="StartGlide()">
<P>With dynamic positioning, you can move elements and their content
anywhere in the document even
after the document has loaded!
<DIV ID="Banner" STYLE="visibility:hidden;position:absolute;top:0; left:0">Welcome to Dynamic HTML!</DIV>
</BODY>
</HTML>

Note that you cannot dynamically change an element from nonpositioned to positioned. The position attribute should be set in the HTML source, as setting the position attribute in script will not work with Internet Explorer 4.0.

For more ideas on how to integrate positioning with other DHTML techniques, check out Filters and Transitions to learn how to incorporate visual filter affects.

Controlling Content Visibility

In addition to controlling where on the page the element is positioned, the content of positioned elements can be restricted from the user's view in several ways. The display and visibility attributes control whether the element appears on the screen at all, and the clip and overflow attributes control how much of the content the user can see. As mentioned previously, authors can also control the visibility of overlapping elements by manipulating the z-index ordering.

Clipping Regions and Overflow

You can set a clipping region for a positioned element by using the clip attribute. The clipping region defines a rectangle within which the element is visible. Any portion of the element that extends outside the clipping region is "clipped," that is, not displayed. The clipping region does not alter the HTML, but simply changes how the element is displayed.

For example, the following document uses clip to define a clipping region for the absolutely positioned DIV. The region, a 30-by-30 pixel square, displays only a portion of the text; the rest is clipped from view.

<HTML>
<HEAD><TITLE>Clip the DIV</TITLE>
</HEAD>
<BODY>
<DIV
STYLE="position:absolute;top:50;left:50;height:100;width:100;clip:rect(0 30 30 0);background-color:green">
some content some content some content some content some content
some content some content some content some content some content
some content some content some content some content some content
some content some content
</DIV>
</BODY>
</HTML>

Be careful when you define a clipping region—the parameter order (top, right, bottom, left) is important. For example, setting clip:rect to (0 0 30 30) causes the region not to display because the top and right have been defined as zero. The correct definition for a 30-by-30 clipping region based off the top left corner of the positioned object is to set clip:rect to (0 30 30 0).

You can change the clipping region dynamically by using the clip property, as in the following example.

document.all.MyDiv.style.clip = "rect(0 50 75 0)";

Overflow occurs when there is more content in a positioned element than can fit within the area defined for it. By default, any extra content is displayed but flows beyond the end of the area and therefore may overlap other elements in the document. You can prevent this overflow by using the "overflow" attribute to either hide the overflow or enable scroll bars to let the user view it by scrolling.

For example, the following document uses "overflow" to apply scroll bars. Only the portion of the text that fits within the 100-by-100 area is initially displayed, but the user can scroll the rest into view by using the scroll bars.

<HTML>
<HEAD><TITLE>Scroll the Overflow</TITLE>
</HEAD>
<BODY>
<DIV STYLE="position:absolute;top:50;left:50;height:100;width:100;overflow:scroll">
some content some content some content some content some content
some content some content some content some content some content
some content some content some content some content some content
some content some content
</DIV>
</BODY>
</HTML>

You can hide any overflow by setting "overflow" to "hidden". Similarly, you can let the overflow flow beyond the end of the area by setting it to "visible".

You can change the overflow dynamically by using the overflow property, as in the following example.

if (document.all.MyDiv.style.overflow != "scroll")
    document.all.MyDiv.style.overflow = "scroll";

Z-Index Ordering

The z-index specifies in what order elements should be drawn when two or more elements occupy the same area. Setting the z-index is useful whenever you have absolute or relative positioned elements that overlap other elements in the document.

You set the z-index by using the z-index attribute. Setting this to a positive value causes the element to be stacked on top of other elements; negative values cause it to be stacked below. The following document uses z-index to stack text on top of the image.

<HTML>
<HEAD><TITLE>Stack the Image</TITLE>
</HEAD>
<BODY>
<P STYLE="position:absolute; top:0; left:0">Text Over Image</P>
<IMG SRC="sample.jpg" STYLE="position:absolute; top:0; left:0; z-index:-1">
</BODY>
</HTML>

The element with the greatest z-index is always placed at the very top of the stack, and the element with the least z-index at the very bottom. If two elements have the same z-index, their source order determines the stacking—the last element is stacked highest.

You can change the z-index dynamically by setting the zIndex property, as in the following example.

document.all.MyImg.style.zIndex = 2;

In general, all elements are "windowless" and will participate in z-order overlapping. However, some objects are "windowed". ActiveX Controls that have not been specifically written to be windowless will not overlap with other objects. IFRAME elements represent a window object, and window objects do not participate in z-order. Another exception in Internet Explorer 4.0 is the SELECT element.

Element Visibility

The visibility of a positioned element determines whether the user can see the element. Visibility is useful for temporarily hiding an element, such as when time is needed to calculate its position or when carrying out simple transition effects. You can set the visibility by using the visibility attribute. The following example uses the attribute to make the DIV element invisible.

<p> A paragraph above the DIV element</p>
<DIV ID=MyDiv STYLE="position:absolute;top:50;left:50;height:100;width:100;visibility:hidden">
<p> A paragraph below the DIV element</p>

You can set the visibility of an element from script by using the visibility property. For example, assume that the DIV in the previous example is loaded. Initially, it is invisible, but you can change this to visible by using the following:

document.all.MyDiv.style.visibility = "visible";

An invisible element continues to affect the document layout; that is, the space that the element would occupy remains in the document even though it is empty. This is unlike the display attribute, which does not reserve space. The following sample demonstrates the difference between visibility and display.


Filters and Transitions

With the introduction of Microsoft® Internet Explorer 4.0, Web page authors now can apply multimedia-style effects to their content through the use of visual filters and transitions. These effects are implemented in Web pages using a Cascading Style Sheets (CSS) attribute. Visual filters and transitions can be applied to standard HTML controls, such as text containers, images, and any other windowless object. Transitions are time-varying filters that can create a transition from one visual state to another. By combining filters and transitions with basic scripting, authors have a powerful tool for creating visually engaging and interactive documents.

Creating Multimedia Effects with Visual Filters and Transitions

Defining Visual Filters

Scripting Filters

Migrating from OBJECT-based Filters

Filter Design Considerations

Visual Filter Scenarios

Transitions

Interpage Transitions

Transition Design Considerations

Transition Scenarios

Visual and Transition Filters Reference

Visual Filter Effects Reference

Properties, Methods, and Events Reference

Creating Multimedia Effects with Visual Filters and Transitions

Visual filters are extensions to Internet Explorer 4.0 behavior that create onscreen effects in a document's contents. In some cases, filter effects are little more than prepackaged behavior that could have been done otherwise as script. In other cases, they go far beyond script and modify the rendered appearance of a control. Using visual filters greatly simplifies the task of incorporating sophisticated effects in Web documents.

Filters are applied to HTML controls through the filter style sheet property. The filter property is a string of filter descriptions that uses a function-like notation but does not require any knowledge of scripting. The syntax for a filter property in a style attribute is:

filter:filtername(parameters)

Here's an example of how filters are written as style attributes.

<img id=sample src="sample.jpg" style="filter:blur(strength=50) flipv()">

The sample HTML above attaches two filters to the IMG control. The first causes the image to blur over a specified number of pixels. The second filter flips the image vertically.

Each filter can have a set of optional parameters to define the precise nature of the effect, such as color or duration of behavior. Some filters, such as FlipV and FlipH for vertical and horizontal mirror images, have no parameters (although all filters and transitions have an enabled property, and all transitions have a Duration property). Multiple filters can be applied so that in the above example the "flipv" and "blur" filters are applied in combination to the IMG.

Filters often create effects that can also be generated with script. This raises the question, "Why use filters if script can do the job?" There are several reasons for using filters. Probably the most important is because they don't require script. For better or for worse, many HTML authors shy away (or are kept away) from scripting. Filters are a convenient package for the same functionality that scripting can provide. Another benefit of filters over script is that because they use the declarative and inherited syntax of CSS, they are easier to author and can be applied to entire classes of elements.

Another reason for using filters is because they provide a good downlevel story. Browsers that don't support the filter property or even style sheets simply ignore them. Even browsers that do support the filter property can do so in totally different ways without affecting the author. For instance, while filters in Internet Explorer 4.0 are implemented as special COM objects and can be easily extended, it is likely that the Windows® 3.1 implementation will be built in and represent a subset of the Internet Explorer 4.0 functionality.

Although all the filters that ship with Internet Explorer 4.0 are "visual," it is not a requirement. An example of a nonvisual filter would be a filter that changed various style sheet attributes (such as color, font size, bold, and even position) on the filtered element. These filters can be applied to any element (not just controls).

What Are HTML Controls?

Visual filters can be applied only to HTML elements that are controls. A control element defines a rectangular space within a browser window when the browser renders the Web document. Controls cannot be windowed, such as an IFRAME. Valid HTML controls are:
BODY
BUTTON
DIV (with a defined height, width, or absolute positioning)
IMG
INPUT
MARQUEE
SPAN (with a defined height, width, or absolute positioning)
TABLE
TD
TEXTAREA
TFOOT
TH
THEAD
TR

Windowless controls, such as structured graphics and ActiveX™ Controls, can also apply filter attributes. Filters follow the standard CSS attribute inheritance scheme (if it exists for the object) except for the exceptions noted below.

Filters are ignored for any positioned elements nested inside nonpositioned elements, such as a positioned SPAN inside a nonpositioned DIV. The simple solution is to always position or define a width for your outermost element.

Elements and windowed objects that cannot have filters applied to them include Java™ applets, IFRAME, the SELECT and OPTION form elements, P paragraph elements, Hn headings, and EM and STRONG logical text style elements.

Defining Visual Filters

Visual filters modify the appearance of a control. In fact, they can totally take over the visual output of a control when applying their effect. A good example of a visual filter is the alpha filter. It blends its target into the background. The author controls the amount of blend (or opacity). Opacity is expressed as a percentage. For example, the following HTML causes the image to be 20 percent opaque:

<img id=sample src=sample.jpg style="filter:alpha(opacity=20)">

Internet Explorer 4.0 supports a range of visual filters, shown in the following table, from the aforementioned alpha blend to a light filter that simulates colored lights shining on the control.
Filter effect | Description
Alpha | Sets a transparency level.
Blur | Creates the impression of moving at high speed.
Chroma | Makes a specific color transparent.
Drop Shadow | Creates an offset solid silhouette.
FlipH | Creates a horizontal mirror image.
FlipV | Creates a vertical mirror image.
Glow | Adds radiance around the outside edges of the object.
Grayscale | Drops color information from the image.
Invert | Reverses the hue, saturation, and brightness values.
Light | Projects light sources onto an object.
Mask | Creates a transparent mask from an object.
Shadow | Creates a solid silhouette of the object.
Wave | Creates a sine wave distortion along the x-axis and y-axis.
XRay | Shows just the edges of the object.

To experiment with filters use the following samples provided with the Internet Client SDK. Filters Wizard
Wave Filter Wizard

Scripting Filters

A filters collection is available on every element to provide script with access to their individual filters. The collection can be accessed like any other object model collection. For example, the following line of script addresses the first filter in the collection of filters on the element with id=theDiv.

theDiv.filters.item(0).enabled = true;

Filters are considered sub-objects of the control to which they are attached. Like other objects, they expose properties and methods for changing their internal state. Like other object model collections, the filters collection supports several kinds of access.

<img id=sample src="sample.jpg" style="filter: alpha(opacity=50) fliph(enabled=0) blur(amount=10); position: relative">
<script language="JavaScript">
function foo()
{
sample.filters.alpha        // sub object
sample.filters["alpha"]    // named index
sample.filters[0]              // numeric index
}
</SCRIPT>

The numeric access is particularly useful when more than one filter of the same type is applied or when the type of filter isn't known in advance (if it is set through script or data binding, for instance). This is particularly important for filters and transitions that have common properties and methods such as Amount, Color, and Play.

In the following example, the opacity of a control is dynamically changed by changing the opacity property on the alpha filter.

<img id=sample src=sample.jpg style="filter: alpha(opacity=50)">
<script language="javascript">
function foo()
{
     sample.filters.alpha.opacity += 10;
}

This same syntax can be used to call the methods needed to make the transition revealTrans work in the following example.

<div id=mydiv style="height:50;width:50;filter:wave(strength=100) revealTrans(transition=3 duration=4)"> This is a div </div>

<script language="JavaScript">
mydiv.filters.revealTrans.apply()
mydiv.innerText = "This is different text"
mydiv.filters.revealTrans.play()
</script>

Alternately, revealTrans can be accessed by index.

<script language="JavaScript">
mydiv.filters[1].apply()
mydiv.innerText = "This is different text"
mydiv.filters[1].play()
</script>

The Filter String

The style object also has a filter property. This is a read/write string that can be used to manipulate the CSS filters of an element directly. For instance, using the DIV defined above, the following code:

<div id=mydiv style="height:50;width:50;filter:wave(strength=100) revealTrans(transition=3 duration=4)"> This is a div </div>

<script>
...
alert(mydiv.style.filter)
...
</script>

Would produce an alert with the following string:

wave(strength=100) revealTrans(transition=3 duration=4)

Writing to this property is especially useful to change an element's filters dynamically. Note that writing to this property overwrites the existing value and the browser renders the new string immediately. The following example adds a FlipH filter to a collection on the fly.

<div id=mydiv style="height:50;width:50;filter:wave(strength=100) revealTrans(transition=3 duration=4)"> This is a div </div>

<script>
...
mydiv.style.filter = mydiv.style.filter +  " fliph()"
...
</script>

After the change, the new filter string would now look like this:

wave(strength=100) revealTrans(transition=3 duration=4) fliph()

Any additional changes to that collection's filter string will modify the new string. For complex filter manipulation, authors need to keep track of the current states of their element filter collections.

Note It is strongly recommended that CSS filters be accessed through the object model whenever possible, and the filter string be accessed only under special circumstances where object model functionality is not adequate. Even in the case of dynamically adding filters, it is recommended in most cases to actually add the filter in the initial filter attributes of the element's style sheet with enabled=0. When the script wants the filter to be displayed, it can then simply set that filter to enabled=1 and the filter will be displayed.

This Web page demonstrates a simple example of changing filter properties from script. This page uses a more complex script that calls filter methods and manipulates properties.

Migrating from OBJECT-based Filters

As Internet Explorer 4.0 was developed, filters were initially supported as OBJECT elements. With the release of the final version of Internet Explorer 4.0, filters made the logical switch to the CSS model for implementation. While this switch won't have any effect on new Web pages, existing documents that employed filter effects as objects are now broken. Authors who are accustomed to using objects and enjoyed the ability to apply a single object to many different controls at once must now specify the filters on each control that will use them. However, since you can change the style.filter string in script, the old-style syntax can be approximated as follows:

<object id=aFilter clsid=...><param name=param-name value=param-value> ... </object>
site.filter = aFilter

This becomes:

site.style.filter = "someFilter(param-name=param-value, ...)"

However, this solution is hardly the best way to use filters. The new CSS syntax allows multiple filters to be attached and active at once. The Enabled property can be used to turn a given filter on and off.

Filter Design Considerations

Some filters require transparency to function properly. These include Shadow, DropShadow, Glow, and Mask. Text automatically has "transparency," or space around the characters that shows through to the object (or page) behind it. GIF images must be in gif89a format with a transparent color to display these filters properly.

Margins can affect how some filters are applied and rendered. "Clipping" can occur when a margin or DIV boundary is set too close to an object that has a filter applied to it. For instance, applying a glow to text without a margin may have some of the glow effect clipped by the DIV boundary if the text is directly next to it.

Performance is an important factor to consider when designing Web pages with filters. Internet Explorer 4.0 requires processing time to calculate the visual display of filter effects, and some require more time than others to apply. It is useless to try to apply and change a filter on an element before the browser can even render it (such as manipulating a light effect quickly in a looping script function).

While selecting text in the browser window, any applied filter effects are ignored. Once the mouse button is released, the browser reapplies the filter effects to the text. This operation is subject to any performance limitations that were previously experienced.

It is possible to apply one or more filter effects to a group of elements by wrapping them in a DIV. Take care that the DIV itself is positioned if the enclosed elements are positioned. As noted previously, filters require that all containers be either positioned or have defined widths, and parent elements be positioned to display filter effects properly on child elements.

Filters have different methods for creating their effects on elements. For example, the alpha filter affects each pixel as a function of itself (creating either a uniform or gradient effect), while with the glow filter, each pixel inherits from the pixels directly around it, creating a diminishing effect. Your choice of content might be affected by the application method a filter requires to achieve its effect.

Visual Filter Scenarios

There are unlimited uses for filters in both static and dynamic Web pages. The following scenarios explore some of the more common or interesting applications of filter styles and combinations of script and filters.

Creating Static Visual Effects

Static visual effects are the most common use of style filters. These include simply applying a filter to a DIV or object to create a nonchanging effect, such as a text drop shadow. Static effects are an easy way to enhance a Web page's design with minimum effort and bandwidth, and often without scripting.

No-script example

The following example shows how television-style effects can be created using dynamic HTML positioning and the alpha visual filter.

<HTML>
<HEAD><TITLE>Static Alpha Filter Demo</TITLE>
</HEAD>
<BODY>
<DIV style="position:absolute; top:20; left:15; width:50%; height:35; background-color: black; filter: alpha(opacity=50)"></DIV>
<DIV style="color:red; position:absolute; top:20; width:50%; height:100; margin-top:5; margin-left:5;"><P style="font-size:14pt; font-weight:bold; text-align:center">HERE IS CAPTION TEXT</P></DIV>
<IMG src="sam2.jpg">
</BODY>
</HTML>

Timer script example

Visual effects can be "animated" using a timer script. The following sample shows two filters, alpha and glow, and two different timer methods.

<HTML>
<HEAD><TITLE>Timer Demos</TITLE>
<SCRIPT>
function init()  {
    makeFlash(bob)
    setInterval("fred.filters.alpha.opacity = (fred.filters.alpha.opacity + 5) % 101", 100)
    setInterval("foo(dave)", 100)
}
var delta = 5
function foo(obj)  {
    if ((obj.filters.alpha.opacity + delta > 100)
    ||  (obj.filters.alpha.opacity + delta < 0))
        delta = - delta
    obj.filters.alpha.opacity += delta
}
function makeFlash(obj)  {
    obj.flashTimer = setInterval("bob.filters.glow.enabled = !bob.filters.glow.enabled", 1000)
}
function stopFlash(obj)  {
    clearInterval(obj.flashTimer)
}
</SCRIPT>
</HEAD>
<BODY onload="init()">
<DIV id=bob style="width:50%; filter:glow(Color=#FAF900,Strength=2,enabled=0);" onclick="stopFlash(this)"><H1>Here is some text</H1></DIV>
<DIV id=fred style="width:50%; filter:alpha(opacity=100);"><H1>Here is some text</H1></DIV>
<DIV id=dave style="width:50%; filter:alpha(opacity=50); color: blue"><H1>Here is some text</H1></DIV>
</BODY>
</HTML>

Creating Dynamic Visual Effects

Dynamic visual effects bring a basic level of interactivity to Web documents. Dynamic effects require an event to prompt a change in the document—this can be a mouse rollover or click event, a timer interval, or a sequence of script functions calling the new content states.

Event script example

Here an interactive step has been added to the previous "television caption" sample that displays the caption only when the mouse is over the inline image.

<HTML>
<HEAD><TITLE>Dynamic Alpha Filter Demo</TITLE>
<SCRIPT>
function caption()  {
    if (bob.style.visibility == "hidden")    {
        bob.style.visibility = ""
        fred.style.visibility = ""
    }
    else  {
        bob.style.visibility = "hidden"
        fred.style.visibility = "hidden"
    }
}
</SCRIPT>
</HEAD>
<BODY>
<DIV id="bob" style="visibility:hidden; position:absolute; top:20; left:15; width:50%; height:35; background-color: black; filter: alpha(opacity=50)"></DIV>
<DIV id="fred" style="visibility:hidden; color:red; position:absolute; top:20; width:50%; height:100; margin-top:5; margin-left:5;"><P style="font-size:14pt; font-weight:bold; text-align:center">HERE IS CAPTION TEXT</P></DIV>
<IMG src="sam2.jpg" onmouseover="caption()" onmouseout="caption()">
</BODY>
</HTML>

Timer script example

Timers create cyclical effects, as in the following interactive demonstration.

Creating a Disabled UI Element Effect

Web authors often resort to the trick of using multiple graphics to indicate a user state for a single graphic, such as a navigation bar button. With visual filters, these are no longer required—any graphic can be displayed in such a manner as to indicate whether it is available for user interaction or not. Best of all, it's all done in code, and doesn't require an additional download from a server.

No script example

This page shows how both the gray and alpha filters can visually represent unavailable link states.

Event script example

As interactive objects, links can change state in response to mouse events, as this page demonstrates.

Creating Complex Visual Effects

Combining visual filters, transitions, and sophisticated programming allows Web authors to create complex and compelling visual designs and interactivity. The following examples provide just a glimpse into the versatility of visual effects that are available in authoring for Internet Explorer 4.0.

Simple script example

The following Web page shows how the mask filter can be combined with a series of style changes to create an interesting effect.

Event script example

The light filter is the most unique and complex visual filter. The following sample shows how the filter can be combined with mouse events to create a unique DHTML experience.

Programming example

The same light filter can be controlled by sophisticated programming, as the following sample shows. Watch for additional examples of sophisticated Internet Explorer 4.0-enhanced Web site design on Microsoft Site Builder.

Transitions

Transitions are time-varying visual filters. Their role is to visually transition a control from one state to the next. A common example is changing the SRC of an image to change one image to another onscreen. A transition would provide some kind of animated effect to bring in the new image. Transitions can also be applied to make a control gradually fade in or fade out by changing the visibility property.

Transition filters have methods and events for manipulation. When the filter wants to fire an event, the onfilterchange event is fired. This event can be used to script the srcFilter property on the event object, and then supplies all the necessary information about the event. In this way a script can know when a transition has completed. The methods for the filters allow a transition to be applied and played.

The Apply method freezes the visual appearance of the control by first applying the transition, allowing changes to be made without an immediate repaint such as specifying a new image. The Play method then invokes the transition. At any time, the script can "cut to the chase" and finish the transition by calling Stop. The following example shows how to perform an automatic slide show between images.

<HTML>
<HEAD><TITLE>Transition Blend Demo</TITLE>
<SCRIPT language="JavaScript">
var fRunning = 0
function startTrans()
{
    if (fRunning == 0)
    {
        fRunning = 1
        SampleID.filters.blendTrans.Apply();
        SampleID.src = "sunset.jpg";
        SampleID.filters.blendTrans.Play()
    }
}
</SCRIPT>
<SCRIPT for="SampleID" event="onfilterchange">
fRunning = 0
</SCRIPT>
</HEAD>
<BODY>
<IMG id="SampleID" src="beach.jpg" style="filter:blendTrans(duration=3)" onclick="startTrans()"><BR>
Click image for Transition Filter: Blend
</BODY>
</HTML>

Two transition filters ship with Internet Explorer 4.0, blend and reveal. The blend transition allows a simple fade-in or fade-out with a specified duration, while the reveal transition specifies multiple effects such as boxin, boxout, horizontal blinds, and so on.

The following HTML is an example of a simple transition between two images. Clicking the button runs the doTrans script, which first calls Apply on the revealTrans filter to stop painting of the image. It then sets an alternative image and calls Play on the filter to proceed with the transition. In this case the transition type is set to 8, which corresponds to the vertical blinds transition effect. This is applied using an inline style on the IMG tag.

<HTML>
<HEAD><TITLE>Transition Sample</TITLE>
<SCRIPT LANGUAGE=JavaScript>
Function doTrans()
{
    theImg.filters.item[0].Apply();
    theImg.src="circles.bmp";
    theImg.filters.item[0].Play();
}
</SCRIPT>
</HEAD>
<BODY style="background-color:darkblue">
<IMG ID=theImg width=200 height=200
src="clouds.bmp" style="filter:revealTrans(Duration=3.3, Transition=8);">
<BR>
<INPUT type=button value="Start Transition" onClick="doTrans()">
<IMG src="clouds.bmp" style="position:relative; width:1; height:1;visibility:hidden">
<IMG src="circles.bmp" style="position:relative; width:1; height:1; visibility:hidden">
</BODY>
</HTML>

This example also demonstrates the differences between asynchronous and synchronous changes. Changing the innerText of an element is synchronous—the action is completed by the time the statement has executed. Changing the src is effectively asynchronous. Although the actual src property changes immediately, the visual state of the IMG element isn't fully updated until the actual download of the new image is complete. A careful script would wait for the onload event on the image. "Pre-loading" graphics with separate IMG tags is a good way to avoid the synchronicity issue but it will only work if the transition is applied after all image downloads are complete.

Interpage Transitions

Interpage transitions make it possible to provide visual effects to the entire window as a Web page is loaded or exited. Just as programs such as PowerPoint® allow for transitions between slides, you can provide wipes, fades, and even create custom transition types.

Transitions are implemented with META tags placed in the HEAD section of Web pages. The META tag specifies the type of transition, duration, and other variables, as well as whether the transition should occur as the following page is loaded or as it is exited.

Transition Syntax

The syntax for transitions consists of three parts: specifying when the event should be played, the duration of the transition, and what kind of transition effect to use. The following two examples show how to set transitions upon entry and exit of a page.

<META http-equiv="Page-Enter"
CONTENT="RevealTrans(Duration=4,Transition=1)>

<META http-equiv="Page-Exit"
CONTENT="RevealTrans(Duration=2.500,Transition=6)>

The first META tag causes transition 1 to play when the user enters the page, lasting 4 seconds; the second META tag causes transition 6 to play when the user leaves the page, lasting 2.5 seconds (written as 2 seconds and 500 milliseconds).

There are four events that can initiate interpage transitions: Page-Enter , Page-Exit, Site-Enter, and Site-Exit. Duration has a maximum value of 30 seconds.

Transitions Reference

The available reveal transitions that are supported in Internet Explorer 4.0 are described below.
Transition name | Value
Box in | 0
Box out | 1
Circle in | 2
Circle out | 3
Wipe up | 4
Wipe down | 5
Wipe right | 6
Wipe left | 7
Vertical blinds | 8
Horizontal blinds | 9
Checkerboard across | 10
Checkerboard down | 11
Random dissolve | 12
Split vertical in | 13
Split vertical out | 14
Split horizontal in | 15
Split horizontal out | 16
Strips left down | 17
Strips left up | 18
Strips right down | 19
Strips right up | 20
Random bars horizontal | 21
Random bars vertical | 22
Random | 23

To easily construct and experiment with these transitions use the following wizard distributed with the Internet Client SDK.

  • Transitions Wizard HTML-based wizard that generates basic code for the different Transitions, based on the parameters entered by the user.

    Transition Design Considerations

    The primary concern of designers when implementing transitions is that, since they run asynchronously, it is necessary to track each transition state through events (onfilterchange) to determine when a particular transition is finished. Remember that image downloading is asynchronous and that the visual state of IMG elements isn't fully updated until after images are completely downloaded.

    Transition Scenarios

    There are unlimited uses for transitions in both static and dynamic Web pages. The following scenarios explore some of the more common or interesting applications of filter styles combined with transitions and, as in the more complex demonstrations, script functions.

    Creating Non-Event Transitions

    Non-event transitions are analogous to static visual filters—they are used frequently to enhance the visual appearance of a page without changing the level of interactivity of the document.

    Simple script example

    The following demonstration uses transitions to display information in an interesting manner as the page loads.

    Creating Event-Driven Transitions

    Event script example

    This demonstration shows how a mouse event can trigger a sequence of transitions.

    Creating Complex Transitions

    Combining visual filters and transitions allows Web authors to create complex and compelling visual designs and interactivity. The following example provides just a glimpse into the versatility of visual effects that are available in authoring for Internet Explorer 4.0.

    Event Script Example

    Intermediate Web pages (sometimes called "logo pages") provide an opportunity to be creative with transitions.

    Timer script example

    Computer-based training applications can use timed transitions to demonstrate their subject matter, as the following example shows.

    Programming

    Transitions can be combined with visual filters and scripting to develop complex site designs. Watch for examples of sophisticated Internet Explorer 4.0-enhanced Web site design on Microsoft Site Builder.


Visual and Transition Filters Reference Visual and Transition Filters Reference *
  * Previous Topic: Filters and Transitions
  * Next Topic: Blend Transition Filter

Visual and Transition Filters Reference

Internet Explorer 4.0 ships with the following filters:
Blend Transition Filter
Reveal Transition Filter
Visual Filters


Blend Transition Filter

Description

Performs a fade (in or out) of the selected visual object.

Syntax

{ filter: blendTrans(Duration=duration)}

Parameter | Description
duration | Length of time the transition should take to complete. Value, float. Value is expressed in seconds.milliseconds (0.000).

Remarks

This attribute is not inherited. An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR

See Also

Reveal Transition Filter, Visual Filter, Properties, Methods, and Events Reference


Reveal Transition Filter

Description

Allows you to show or hide visual objects, using any of the 23 predefined types of patterns.

Syntax

{ filter: revealtrans(duration=duration, transition=transitionshape)}

Parameter | Description
duration | Length of time the transition should take to complete. Value, float. Value is expressed in seconds.milliseconds (0.000).
transitionshape Shape of the transition (Reveal transition only). Integer. A value from 0 to 23. The transition shape is determined by one of the values shown in the following table.
Transition type | Value
Box in | 0
Box out | 1
Circle in | 2
Circle out | 3
Wipe up | 4
Wipe down | 5
Wipe right | 6
Wipe left | 7
Vertical blinds | 8
Horizontal blinds | 9
Checkerboard across | 10
Checkerboard down | 11
Random dissolve | 12
Split vertical in | 13
Split vertical out | 14
Split horizontal in | 15
Split horizontal out | 16
Strips left down | 17
Strips left up | 18
Strips right down | 19
Strips right up | 20
Random bars horizontal | 21
Random bars vertical | 22
Random | 23

Remarks

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR

See Also

Blend Transition Filter, Visual Filter, Properties, Methods, and Events Reference


Visual Filter

Description

Allows you to manipulate visible objects, with any of the several predefined filter effects listed below.

Syntax

{ filter: filtername(fparameter1, fparameter2...)}

Parameter Description
filtername Identifier for a particular visual effect. Possible values are shown in the following table.
Filter effect | Description
Alpha | Sets a transparency level.
Blur | Creates the impression of moving at high speed.
Chroma | Makes a specific color transparent.
DropShadow | Creates an offset solid silhouette.
FlipH | Creates a horizontal mirror image.
FlipV | Creates a vertical mirror image.
Glow | Adds radiance around the outside edges of the object.
Grayscale | Drops color information from the image.
Invert | Reverses the hue, saturation, and brightness values.
Light | Projects a light source onto an object.
Mask | Creates a transparent mask from an object.
Shadow | Creates a solid silhouette of the object.
Wave | Creates a sine wave distortion along the x-axis.
XRay | Shows just the edges of the object.

Remarks

The Visual Filter control can be applied to any visible object on the HTML page that supports the Filter property, such as DIV and IMG tags.

Visual filters can be chained together to produce interesting effects. To chain multiple filters together, simply set the filter attribute to include more than one filter. For example

<DIV STYLE="position:absolute;filter:blur(direction=315) dropshadow()">
   Fantastic Effects!
</DIV>

In this example, the blur is applied first and then the dropshadow. When working with filters and transitions, the order in which they are applied will often affect the results. Click the Show Me to see the difference.

Each visual object to be filtered requires its own visual filter control. You can apply a visual filter object to a DIV tag to utilize a single set of filter effects on all the visual objects in that region. Since each visual filter object can support multiple concurrent effects, you can use multiple filter effects on a particular object.

Remarks

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR

See Also

Reveal Transition Filter, Blend Transition Filter, Properties, Methods, and Events Reference


Visual Filter Effects Reference

Visual Filters allow you to manipulate the display of other visible objects, with any of several predefined filter effects. This section describes the specific filter effects.

Alpha Filter Effect
Blur Filter Effect
Chroma Filter Effect
Drop Shadow Filter Effect
Flip Horizontal Filter Effect
Flip Vertical Filter Effect
Glow Filter Effect
Grayscale Filter Effect
Invert Filter Effect
Light Filter Effect
Mask Filter
Shadow Filter Effect
Wave Filter Effect
XRay Filter Effect


Alpha Filter Effect

Description

Sets the level of opacity for your visual object. The opacity can be set as uniform or graded, in a linear or radial fashion.

Syntax

{ FILTER: Alpha(Opacity=opacity, FinishOpacity=finishopacity, Style=style, StartX=startX, StartY=startY, FinishX=finishX, FinishY=finishY)"}

Parameter | Description
opacity | Level of the opacity. 0, the default, is fully transparent; 100 is fully opaque.
finishopacity | (Optional) Ranges from 0 (fully transparent) to 100 (fully opaque).
style | Specifies the shape characteristics of the opacity gradient. Possible values are 0 (uniform), 1 (linear), 2 (radial), or 3 (rectangular).
startX | X coordinate for opacity gradient to begin.
startY | Y coordinate for opacity gradient to begin.
finishX | X coordinate for opacity gradient to end.
finishY | Y coordinate for opacity gradient to end.


Blur Filter Effect

Description

Averages the pixels of the visible object for a specified length and direction, creating the impression that the object is moving at high speed.

Syntax

{FILTER: Blur(Add=add, Direction=direction, Strength=strength)}

Parameter | Description
add | Boolean switch specifying whether to add the original image to the motion-blurred image. If true (nonzero integer), the image is added to the motion blurred image; if false (zero), the image is not added to the motion blurred image.
direction Direction of the motion blur clockwise from the vertical orientation of the object, rounded to 45-degree increments. The default value is 0 (straight up). Possible values are shown in the following table.
Value | Description
0 | Top
45 | Top right
90 | Right
135 | Bottom right
180 | Bottom
225 | Bottom left
270 | Left
315 | Top left
strength | Long value that specifies the number of pixels the blur will extend.

Remarks

You can create a nice effect for fonts by setting add to 1.

For the direction parameter, negative values or values larger than 360 degrees will wrap around to their equivalent angle (for example, -45 degrees is equivalent to 315-degree orientation). This allows mathematical manipulations to be carried out easily in code.


Chroma Filter Effect

Description

Selectively renders a specific color transparent for the selected visual object.

Syntax

{FILTER: Chroma(Color=color)}

Parameter | Description
color | Value of the color to be subject to chromakey transparency. Color is expressed in #RRGGBB format, where RR is the red hexadecimal value, GG is the green hexadecimal value, and BB is the blue hexadecimal value.

Remarks

This effect is not recommended for files that have been dithered from 24 to 8 bit. In particular, JPEG files, as dithered and compressed files, do not produce an entirely solid chromakey color, resulting in uneven effects. Chromakey doesn't work well on anti-aliased sources, in which sharp lines are smoothed by blending the colors of surrounding pixels. Choosing a specific chromakey color will cause some colors that would otherwise be transparent to be fully opaque.


Drop Shadow Filter Effect

Description

Paints a solid silhouette of the selected visual object, offset in the specified direction. This creates the illusion that the visual object is floating above the page and is casting a shadow onto the page.

Syntax

{FILTER: DropShadow(Color=color, OffX=offX, OffY=offY, Positive=positive)}

Parameter | Description
color | Specific color for the drop shadow effect. Color is expressed in #RRGGBB format, where RR is the red hexadecimal value, GG is the green hexadecimal value, and BB is the blue hexadecimal value.
offX | Number of pixels the drop shadow is offset from the visual object, along the x-axis. Expressed in integers. Positive integers move the drop shadow to the right. Negative integers move the drop shadow to the left.
offY | Number of pixels the drop shadow is offset from the visual object, along the y-axis. Expressed in integers. Positive integers move the drop shadow down. Negative integers move the drop shadow up.
positive | Boolean. A true (nonzero) value, the default, creates a drop shadow of any nontransparent pixel of the visual object. If false (zero), drop shadows are created for any transparent pixel of the visual object.

Remarks

If you have a transparent object but still want the usual shadow effect, set positive to zero. The transparent object will have a drop shadow outside the transparent region, rather than a drop shadow inside the transparent region.


Flip Horizontal Filter Effect Flip Horizontal Filter Effect *
  * Previous Topic: Drop Shadow Filter Effect
  * Next Topic: Flip Vertical Filter Effect

Flip Horizontal Filter Effect

Description

Renders the visual object as a mirror image of itself along the horizontal plane.

Syntax

{FILTER: FlipH}


Flip Vertical Filter Effect Flip Vertical Filter Effect *
  * Previous Topic: Flip Horizontal Filter Effect
  * Next Topic: Glow Filter Effect

Flip Vertical Filter Effect

Description

Renders the visual object as a mirror image of itself along the vertical plane.

Syntax

{FILTER: FlipV}


Glow Filter Effect

Description

Adds radiance around the outside edges of the object, giving it the appearance of a glow.

Syntax

{FILTER: Glow(Color=color, Strength=strength)}

Parameter | Description
color | Specific color for the shadow effect. Color is expressed in the #RRGGBB format, where RR is the red value, GG is the green value, and BB is the blue value.
strength | Intensity of the glow. 1—255.


Grayscale Filter Effect

Description

Drops the color information from the visual object's color palette, rendering the object in grayscale.

Syntax

{FILTER: Gray}


Invert Filter Effect

Description

Reverses the hue, saturation, and brightness values of the visual object.

Syntax

{FILTER: Invert}


Light Filter Effect

Description

Simulates the projection of a light source onto the selected visual object.

Syntax

{FILTER: Light}

Remarks

Once you have defined your Light Filter effect collection for your object, you call its methods to set or change its properties.
Light Filter method | Description
AddAmbient Method | Adds ambient light source.
AddCone Method | Adds cone light source.
AddPoint Method | Adds point light source.
ChangeColor Method | Changes light color.
ChangeStrength Method | Changes light strength.
Clear Method | Clears all lights.
MoveLight Method | Moves light source.

You can control the virtual position of the light source, the x and y coordinates of the focus of the light, the type of light (point or cone) and whether the light has hard or diffuse edges, the color of the light, and its intensity. The maximum number of lights available to each Visual Filter control is 10, so to add more than 10 lights to your page, you will need multiple Visual Filter controls.

When a light effect is created, it has a default ambient light associated with it. The first light you add to the object replaces this default ambient light.

You can associate only one object per light effect. To light several different separate objects (for example, a text phrase and a bitmap image), you need a separate instance of the Lights Filter effect for each object. However, if you combine several objects into a single object by using a DIV tag, you can use one light object to light the combined object.


Mask Filter

Description

Takes the selected visual object, paints the transparent pixels a specific color, and makes a transparent mask from its nontransparent pixels.

Syntax

{FILTER: Mask(Color=color)}

Parameter | Description
color | Color that the transparent regions are painted. Color is expressed in #RRGGBB format, where RR is the red hexadecimal value, GG is the green hexadecimal value, and BB is the blue hexadecimal value.


Shadow Filter Effect

Description

Paints a solid silhouette of the selected visual object along one of its edges, in the specified direction. This creates the illusion of a shadow around the visual object.

Syntax

{FILTER: Shadow(Color=color, Direction=direction)}

Parameter | Description
color | Specific color for the shadow effect. Color is expressed in #RRGGBB format, where RR is the red hexadecimal value, GG is the green hexadecimal value, and BB is the blue hexadecimal value.
direction Directional offset for the shadow effect. Direction is expressed in terms of degrees clockwise from vertical orientation of the object, in 45-degree increments. The default orientation is 225 degrees, which places the shadow to the bottom left side of the object.
Value | Description
0 | Top
45 | Top right
90 | Right
135 | Bottom right
180 | Bottom
225 | Bottom left
270 | Left
315 | Top left

Remarks

For the direction parameter, negative values or values larger than 360 degrees will wrap around to their equivalent angle (for example, -45 degrees is equivalent to 315-degree orientation). This allows mathematical manipulations to be carried out easily in code.


Wave Filter Effect

Description

Performs a sine wave distortion of the visual display of the object along the vertical axis.

Syntax

{FILTER: Wave(Add=add, Freq=freq, LightStrength=strength, Phase=phase, Strength=strength)}

Parameter | Description
add | Boolean. If true (nonzero value), adds the original image to the waved image. If false (0), it does not.
freq | Number of waves to appear in the visual distortion. Integer.
light | Strength of the light on the wave effect in percent, from 0 to 100.
phase | Phase offset for the start of the sine wave effect, which is normally 0 degrees. Value between 0 and 100, which expresses the percentage of the wavelength at which offset should start. For example, a value of 25 starts sine wave effect at 90 degrees. A value of 360 is the equivalent of 0.
strength | Intensity of the wave effect.

Remarks

Using a sequencer to change the phase parameter can create some interesting effects.


XRay Filter Effect

Description

Changes the color depth of the visual object and renders the object in black and white, making the visual display look like a black and white x-ray.

Syntax

{FILTER: Xray}


Properties, Methods, and Events Reference

This section describes the properties, methods, and events associated with the visual and transition filters.
Properties
Duration
Status
enabled

Methods
Apply
Play
Stop
AddAmbient Method (Light Filter Effect)
AddCone Method (Light Filter Effect)
AddPoint Method (Light Filter Effect)
ChangeColor Method (Light Filter Effect)
ChangeStrength Method (Light Filter Effect)
Clear Method (Light Filter Effect)
MoveLight_Method (Light Filter Effect)

Event
Onfilterchange


Duration Property

Description

Sets the default length of time the transition will take to complete.

Syntax

STYLE="FILTER: transitiontype(duration=duration, transition=transitionshape)"

Parameter | Description
duration | Length of time the transition should take to complete. Value, float. Value is expressed in seconds.milliseconds (0.000). Read-write at run time. If transition has been applied or is playing, read-only.
transitionshape | Shape of the transition (Reveal transition only). Integer. Value from 0 to 23. For information on the available transition shapes, see the Reveal Transition topic.

Remarks

A transition's playback duration can also be set as a parameter of the Play method.

Applies to

Transition filters


enabled

Description

Specifies whether the filter is enable or disabled

Syntax

status = object.filter.enabled=fValue

Parameter | Description
fValue | Boolean value indicating whether the filter is enabled (true) or disabled (false). The property is read-write.

Remarks

<img id=image1 src="sample.jpg" style="filter:blur(strength=50) flipv()">

<SCRIPT>
   image1.filters[1].enabled = false; // disable the flip filter
</SCRIPT>

Applies to

Transition filters


Status Property

Description

Returns the current status of the transition.

Syntax

nStatus = object.filter.Status

Parameter | Description
status | Integer. Values are 0 (transition stopped), 1 (transition applied), or 2 (transition playing). Read-only.

Applies to

Transition filters


Onfilterchange Event

Description

Fires when a visual filter changes state or completes a transition.

Remarks

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

If you have multiple objects with transitions on a page, you can determine which object fired the Object_onfilterchange event by checking Window.Event.srcElement. The filters and transitions that ship with Internet Explorer 4.0 fire the event when a transition completes, although the underlying architecture allows future filters to fire at any time their internal states change.

<HTML>
<HEAD>
<TITLE>Microsoft Cascading Style Sheets Controls Samples </TITLE>
</HEAD>
<Div ID = "TextRegion"
    STYLE="Position:absolute;LEFT: 0; TOP: 200; WIDTH: 100%; VISIBILITY: visible; FILTER: revealTrans(Transition = 1, Duration = 1.25)">
Some Text
</DIV>
<DIV ID="ImageRegion"
    STYLE="Position:absolute;LEFT: 0; TOP: 200; WIDTH: 100%; VISIBILITY: hidden; FILTER: revealTrans(Transition = 1, Duration = 1.25)">
<IMAGE SRC="Image1.jpg">
</DIV>
<SCRIPT LANGUAGE=VBScript>
Sub Window_onload
    Call TextRegion.filters.revealTrans.Apply ()
    Region.filters.RevealTrans(transition=23)
    Call ImageRegion.filters.revealTrans.Apply()
    Image1.filters.revealTrans(transition=12)
    Call Start
End Sub

Sub Start
    If TextRegion.style.visibility = "visible"   then
        ImageRegion.style.visibility = "hidden"
    Else
        ImageRegion.style.visibility = "visible"
        TextRegion.style.visibility = "hidden"
    End if
    Call TextRegion.Style.filters.revealTrans.Play(1.5)
End Sub

Sub Region_onfilterchange
Select case Window.Event.srcElement
    Case "Region"
        If Region.filters.revealTrans.Status = 0 then
                Call ImageRegion.filters.revealTrans.Play(1.5)
        End If
    End select
End Sub
</SCRIPT>
</BODY>
</HTML>

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR


Apply Method

Description

Applies a transition to the designated object.

Syntax

Call object.filters.item(index).apply()

Parameter | Description
object | Identifier of the object to which the filter is to be applied.
index | Integer. Index (position in the collection of transitions for this object) number of the transition. Value can be 0-n, where n is the last transition made available to this object.

Applies to

Transition filters


Play Method

Description

Plays the transition.

Syntax

Call object.filters.item(index).play(duration)

Parameter | Description
object | Identifier of the object to which the filter has been applied.
duration | Float, seconds.milliseconds (0.000). Valid values are 0.0-N.n. Optional parameter, read-write at run time.

Remarks

If a playback duration is explicitly specified as a parameter of the this method, it will override the Duration property assigned to the transition for that instance of the transition's playback.

Applies to

Transition filters


Stop Method

Description

Stops transition playback.

Syntax

Call object.filters.item(index).stop()

Parameter | Description
object | Identifier of the object to which the filter is attached.
index | Index number of the transition whose playback is to be stopped.

Remarks

Fires the Onfilterchange event.

Applies to

Transition filters


AddAmbient Method

Description

Adds an ambient light to the Lights Filter Effect object. Ambient light is nondirectional light that sheds parallel beams perpendicular to the surface of the page. Ambient light has color and strength values and can be used to add more color to the page; it is often used in conjunction with other lights.

Syntax

call object.filters.Light.addAmbient(R,G,B,strength)

Parameter | Description
object | Name of the object to which the Light filter is applied.
R | Red value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
G | Green value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
B | Blue value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
strength | Intensity setting.

Remarks

This example shows how to create a blue ambient light with a fairly low intensity.

call object.filters.Light.addAmbient(0,0,255,10)

Applies To

Light Filter


AddCone Method

Description

Adds a cone light to the Lights Filter Effect object to cast a directional light on the page.

Syntax

call object.filters.Light.addCone(x1,y1,z1,x2,y2,R,G,B,strength,spread)

Parameter | Description
object | Name of the object to which the Light filter is applied.
x1, y1, z1 | Source light's coordinates.
x2, y2 | Target focus coordinates. Note: z2=0 is implied.
R | Red value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
G | Green value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
B | Blue value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
strength | Intensity setting. Integer value. Note: strength specified pertains to the target coordinates. When the light is later moved, the strength is re-scaled to still pertain to the new target.
spread | Angle of light spread in the relationship between the vertical position of the light source and the surface of the visual object. 0 to 90 degrees. Low spread (such as low integer values) produces a smaller shaped cone of light. High angle of spread produces an oblique oval or circle of light.

Remarks

The cone light fades with distance from the target x,y position. It displays a hard edge at the near edge of the cone light's focus and fades gradually as it reaches the cone light's distance threshold.

Applies To

Light Filter


AddPoint Method

Description

Adds a point light source, like a light bulb.

Syntax

call object.filters.Light.addPoint(x,y,z,R,G,B,strength)

Parameter | Description
object | Name of the object to which the Light filter is applied.
x, y, z | Point light's coordinates.
R | Red value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
G | Green value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
B | Blue value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
strength | Intensity setting. Integer value.

Remarks

Intensity on the page is controlled by the angle of light on the surface. Add several for great multipoint gradients.

Applies To

Light Filter


ChangeColor Method

Description

Changes the light color for any light on the page.

Syntax

call object.filters.Light.ChangeColor(lightnumber, r,g,b, fAbsolute)

Parameter | Description
object | Name of the object to which the Light filter is applied.
lightnumber | Identifying number for the light, for use in script.
r | Red value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
g | Green value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
b | Blue value, integer from 0 to 255. 0 is lowest saturation, 255 is highest.
fAbsolute | If this flag is true (nonzero), ChangeColor sets the value to be that new value. If this flag is false (zero), ChangeColor increments or decrements the color value by that amount.

Applies To

Light Filter


ChangeStrength Method

Description

Changes the intensity of the light.

Syntax

call object.filters.Light.ChangeStrength(lightnumber, strength, fAbsolute)

Parameter | Description
object | Name of the object to which the Light filter is applied.
lightnumber | Identifying number for the light, for use in script.
strength | New intensity.
fAbsolute | If this flag is true (nonzero), ChangeStrength sets the strength value to be the new value. If this flag is false (zero), ChangeStrength increments or decrements the strength value by that amount.

Applies To

Light Filter


Clear Method

Description

Deletes all lights associated with the specified Lights Filter.

Syntax

call object.filters.Light.Clear

Parameter | Description
object | Name of the object to which the Light filter is applied.

Remarks

This will clear all light sources on the object.

Applies To

Light Filter


MoveLight Method

Description

Moves the light effect on the page.

Syntax

call object.filters.Light.MoveLight(lightnumber, x, y, z, fAbsolute)

Parameter | Description
object | Name of the object to which the Light filter is applied.
lightnumber | Identifying number for the light, for use in script.
x, y, z | Location to move the light to.
fAbsolute | Whether the movement is absolute or relative.

Remarks

For cone lights, this method changes the position of the light's focus, the target x,y values. For point lights, this method changes the source location, the source x,y,z values. This method has no effect for ambient lights.

Applies To

Light Filter


Font Embedding

Web page designers are at a disadvantage compared to print desktop publishers when creating documents; desktop publishers control every aspect of the layout and choose which fonts their content will be printed in. On the other hand, Web authors are at the mercy of the browser and the user's font support when their content is displayed.

Font embedding has been a feature of Microsoft applications such as Microsoft Word and PowerPoint® for several years. It allows fonts used in the creation of a document to travel with that document, assuring that a user sees the pages exactly as the author intended them to be seen. Now, Microsoft® Internet Explorer 4.0 brings embedded font support to the Web. This technology gives site designers the confidence that Internet Explorer 4.0 users will see their pages exactly as intended.

Embedded Font Technology

Embedded Font Examples

Limitations in Internet Explorer 4.0

Internet Explorer 4.0 Security Alert

Using Microsoft WEFT

Embedded Font Technology

In the early years of the World Wide Web, browsers had full control over which font was used to display pages. Later, the FONT element and Cascading Style Sheets (CSS) font-family property were introduced to provide the Web author more control and access to fonts installed on the user's system. However, if the font was not previously installed on the user's computer, the author and user had no recourse but to display the document in a default or secondary font face. Today, Internet Explorer 4.0 supports font embedding, allowing authors to temporarily install fonts on user systems so that Web page content can be rendered exactly as intended.

At this time there is no defined industry standard for font embedding. The Microsoft TrueType font embedding technology is one proposed implementation. The World Wide Web Consortium (W3C) has a working draft available that provides the latest proposed specifications.

Microsoft font embedding uses CSS notation to indicate font styles in Web documents. Designers can limit the frequency that embedded fonts must be transferred to the users' computers if they anticipate fonts that might already be installed. The following example uses an embedded font as a secondary font face, if by chance the preferred font is not already installed on the client computer.

<STYLE>
<SPAN style="COLOR: red">@font-face myfont { src:url(garamond.eot); }</SPAN>
P { font-family: "Garamond, <SPAN class=blue>myfont</SPAN>" }
</STYLE>

For information about the current implementation of embedded fonts in Internet Explorer 4.0, see Limitations in Internet Explorer 4.0.

Different Levels of Font Embedding

TrueType fonts have embedding permissions encoded within them that determine how they can be used by tools that convert them into the embedded font format. There are four levels of embedding:

  • No-embedding permissions are used by a small proportion of available fonts. The creators of these fonts have decided not to allow embedding. Some foundries set their fonts to no-embedding but offer upgrades to embeddable versions. If you come across a no-embedding font that you would really like to use, contact the supplier and ask about a possible upgrade.
  • Print and preview fonts can be embedded, but only within pages that remain static on the client side. If a page allows client-side interaction that results in content displayed using the font changing, "editable" or "installable" fonts must be used. An example of such a page might be one that contains an inline Java™-based word processor, or an e-mail editor.
  • Editable fonts can be embedded using a tool such as WEFT (Web Embedding Fonts Tool) without the restrictions imposed on "print and preview" fonts.
  • Installable fonts are treated as editable fonts by Internet Explorer 4.0. Installable fonts will not be installed in your visitors fonts folder. The main reason for this is that during the course of users' Web travels, they could easily find their fonts folder stuffed with hundreds of full and subsetted fonts that they do not want or need.

Embedded Font Examples

The following demonstrations located on the Microsoft Typography Web site show how font embedding is a dramatic improvement over the traditional use of fonts on the Web.

Note You must be online and using Microsoft Internet Explorer 4.0 to view these examples.

Example 1: Healthy eating recipe

Design process. Some type designers don't allow their fonts to be embedded, so the fonts used in this example were first checked using Microsoft's font properties extension. Checking the embedding permissions of the fonts first is the best way to avoid disappointment later.

The page itself was designed around a simple HTML table. Cascading Style Sheet features were used to specify fonts and ensure the correct alignment of the text and symbols. At this stage the fonts used were all installed locally.

When the copy and layout were set, Microsoft WEFT (Web Embedding Fonts Tool) was used to create "font-objects" that were linked to the page. The WEFT tool analyzes the font usage of Web pages, gathers the required characters from each font used, and creates the compressed font objects. It also modifies the HTML page by writing in the Cascading Style Sheet code linking the font objects to that page. If you use View Source on the demonstration page, you'll see the format of the code added.

@font-face {
    font-family: Goudy Stout;
    font-style:  normal;
    font-weight: 700;
    src: url(GOUDYST0.eot);

This code tells Internet Explorer 4.0 to use the GOUDYST0.eot font object whenever there is text on the page specified in the Goudy Stout font. The following table shows the fonts used by the page, the number of unique characters used, and the size of the font object that contains them.
Font used | Unique characters | Object size
Pie | 9 | 4.27K
Goudy Stout Bold | 15 | 7.43K
Garamond Bold | 15 | 10.3K
Garamond | 19 | 10.3K
Script MT Bold | 49 | 3.97K

How the page looks in other browsers. Browsers that don't support embedding will ignore the code linking the font objects to the page. Users of browsers that support Cascading Style Sheets will see text displayed in the real font if it's installed. Since Goudy Stout and Garamond come with Microsoft Office, they may be in luck. If the first-choice font isn't available, the browser displays the text using the second- or third-choice font (if they are installed). Users of older browsers see all the text displayed using their default font.

One thing to bear in mind is that symbol fonts appear as ordinary characters in browsers other than Internet Explorer 4.0—even CSS browsers do not display the symbols properly. For this reason, using symbol fonts in this way is recommended only for content specific to Internet Explorer 4.0.

Example 2: A blot on the copybook

Design process. This demonstration consists of four pages and shows how one font object can be used across any number of pages. The French Script MT font object contains all the letters and punctuation used in the story and is referenced by all four pages.

Unlike the characters used in the text of the story, the pictures only appear once. For this reason, four font objects were created, each one containing only the pictures used by the page that references it.

The third font is a custom font created specifically for this demonstration. The phrase "A Blot on the Copybook" was drawn as a single character using Macromedia Fontographer, and mapped to the letter Q. The phrase "fin" was also drawn and mapped to the letter K.
Font used | Unique characters | Object size
French Script MT | 52 | 11.1K
Copyblot | 2 | 4.23K
Dingblots (p. 1) | 3 | 2.56K
Dingblots (p. 2) | 27 | 8.42K
Dingblots (p. 3) | 17 | 5.47K
Dingblots (p. 4) | 13 | 3.57K

How the page looks in other browsers. Like the previous demonstration, this uses an embedded symbol font. Two pages also use a custom font that maps the phrases "A Blot on the Copybook" and "fin" to the Q and K keys, respectively. Using custom and symbol fonts in this way means that the pages are Internet Explorer 4.0-specific.

Example 3: Typographic ornament

Design process. These pages use HTML tables to achieve checkerboard patterns, which are colored and filled with various symbols taken from the Border Web and Kingston inline fonts.
Font used | Unique characters | Object size
Kingston Inline | 36 | 17.1K
Runic MT Condensed | 33 | 9.85K
BorderWeb | 10 | 8.36K

How the page looks in other browsers. Like the previous demonstrations, these pages also use embedded symbol fonts, making them Internet Explorer 4.0- specific.

Example 4: Progressive rendering

Design process. Internet Explorer 4.0 will not render a page until the font objects referenced by that page have been downloaded, decompressed, and temporarily installed. In some cases you might want to have a page displayed using an installed font that is dynamically replaced by the font stored within the font object.

The code required to implement this progressive rendering is very compact, and takes the following form:

<SCRIPT LANGUAGE="VBSCRIPT">
Sub Window_onLoad
Msgbox("Click here to continue the demo")
document.stylesheets(<SPAN class=red>i</SPAN>).href="ftembed.css"
End Sub
</SCRIPT>

The stylesheets(<SPAN class=red>i</SPAN>) section is the element of the style sheet collection you want to replace. In this example, a null style sheet corresponding to stylesheets(0) is dimensioned so as to create a style sheet element. This requires the following code to be added in the HEAD element of your HTML code.

<LINK rel=stylesheet href=null>

The font object links are contained in the external style sheet and are therefore referenced only after the page itself has downloaded. The Msgbox code has been inserted so that those lucky enough to have fast connections can see how the progressive rendering effect works. This line can be removed if you implement this code on your own pages.
Font used | Unique characters | Object size
Braggadocio | 18 | 3.16K
Curlz MT | 36 | 10.4K
OCR A Extended | 19 | 4.75K
Gradl | 23 | 4.08K
Snap ITC | 29 | 7.09K

Limitations in Internet Explorer 4.0

At present Microsoft Internet Explorer 4.0 downloads, decompresses, and privately installs font objects even if the real font is installed on a user's system. Future versions will check if the real version of the font is available before downloading the linked font object. Currently this behavior has to be simulated using VBscript (Visual Basic® Scripting Edition) or JScript.

The W3C font embedding draft also describes the way in which browsers should be able to combine font objects containing different subsets of the same font. This way you could link to a font object that contains the uppercase letters from a particular font and another font object containing lowercase letters. At present Internet Explorer 4 uses only the first font object specified.

Internet Explorer 4.0 Security Alert

Depending on how Internet Explorer 4.0 security settings are set, you might get a warning every time a page accesses an embedded font. Although your security level settings can easily be modified, you should first access the Internet Explorer online help and read the sections discussing security before making the following changes:

  1. On the View menu, click Options and then click the Security tab.
  2. Select Custom and click Settings.
  3. Scroll down to the Downloads section.
  4. Change the Font Download setting from Prompt to Enable.

Using Microsoft WEFT

The Microsoft Web Embedding Fonts Tool is being released to coincide with the release of Internet Explorer 4.0. WEFT is a free utility that lets site designers create font objects that are linked to their Web pages.

Download the current version of WEFT for Windows® 95 and Windows NT® from the Microsoft Typography Web site.

The font objects created by WEFT differ from traditional font files in a number of ways. The font objects are compressed and are usually subsetted so that they contain only the characters used by a particular site or page. They are also privately installed by Internet Explorer 4.0 so that they can't be accessed by other applications, and they can't be linked to sites that don't have permission to use them. In the future, WEFT features will be built into popular Web authoring tools.

WEFT Style Code

WEFT adds a STYLE section to the HEAD part of each HTML page that uses one or more font objects.

<STYLE TYPE="text/css">
  @font-face {
    font-family: Garamond;
    font-style:  italic;
    font-weight: normal;
    src: url(Garamond1.eot); }
</STYLE>

This code tells Internet Explorer 4.0 to use the Garamond1.eot font object whenever the Garamond Italic font is specified within the page. The browser will use the font object regardless of whether the font is specified using the FONT FACE tag, a linked or inline Cascading Style Sheet, or some other method.

Cascading Style Sheet Files

WEFT uses Internet Explorer 4.0 to determine the fonts and characters used on each page. If a page references a linked style sheet, this style sheet usually determines the fonts Internet Explorer 4.0 uses to display the page. Note that WEFT does not modify linked style sheets. Instead, the tool modifies the HTML pages by adding code that links the font objects to pages that require them.

In some cases it will be more efficient to reference the font objects within one or more linked style sheets. If you'd like to try this, skip the option asking if you want to publish the modified pages back to your Web site. Instead, cut and paste the relevant code from the modified pages (by default these will be stored in the My Documents folder) into your linked style sheet.

A word of caution is needed. As style sheets cascade, a font specified in a linked style sheet may be overridden by one specified inline. Also, because a style sheet can be linked to any number of pages, care should be taken when choosing an appropriate subsetting level.

For more information about Cascading Style Sheets, see Microsoft Site Builder.

Frequently Asked Questions

Q. Which fonts can I use?

There are thousands of TrueType fonts available, and most of these can be embedded within Web pages using the Microsoft Web Embedding Fonts Tool. However, WEFT will not let you embed certain categories of fonts, such as "no embedding" fonts, and those that contain serious errors.

Q. How can I check the embedding permissions of my fonts?

You can check the embedding permissions of any font using the Microsoft Font Properties Extension. WEFT also has a font check feature that reports the permissions of fonts you have installed on your system.

You may come across very old TrueType fonts, or converted Macintosh® TrueType fonts that do not have any embedding permissions encoded within them. WEFT treats these as "no embedding" fonts. In the unlikely event that you encounter such a font, your best option is to contact the foundry that created the font, and ask about an upgrade.

Q. Should I embed common core fonts such as Arial or Times New Roman?

WEFT will identify common fonts that your readers are likely to have installed. These include Windows core fonts such as Arial, Times New Roman, and Courier New. You can still embed these fonts; however, Internet Explorer 4.0 will download, decompress, and temporarily install font objects even if the real font is present on the user's computer.

The current version of WEFT does not identify the fonts supplied with Internet Explorer 4.0 as common core fonts. Users who have installed Internet Explorer 4.0 will have added Verdana, Comic Sans MS, Arial Black, Impact, and Webdings to their system. Although it is possible that a few users might remove these fonts from their system, it is not recommended that you embed them.

Q. Can I use Type 1 fonts?

If you have specified Type 1 fonts as your first-choice fonts and have Adobe Type Manager installed, these fonts will be identified by WEFT. However, they will be flagged as "status unknown", and you will not be able to embed them using the public preview version of WEFT.


Data Binding

Microsoft® Internet Explorer 4.0 enables content providers to develop data-centric Web applications that support retrieval and update through native data binding facilities. The use of HTML extensions and pluggable data source objects makes data-driven pages easy to author with minimal scripting required. Because data is downloaded to the client asynchronously, pages render quickly and provide immediate interactivity. Once downloaded, the data can be sorted and filtered without requiring additional trips to the server. Compare that to traditional Web pages and those generated by server-side scripts. Once the data reaches the client, it's static, and any manipulation of that data requires another server request.

Consider a simple example, the list of samples in the Internet Client SDK. While the list could be hard-coded into this text, a better solution is to store the data external to the document in a delimited text file. If the samples change, only the data in the database needs to be modified. Once the modifications are made, this page and any others that display that data will reflect the changes.

While this maintenance issue justifies the use of data binding in place of a static page, consider a slightly more complex scenario, an online classical music catalog maintained on a server in a relational database management system. Using today's server-side technologies such as the Common Gateway Interface (CGI), the Internet Server API (ISAPI), or one of its derivatives such as Active Server Pages (ASP), a developer can write a script to extract a subset of data based on criteria specified by the client, such as all titles by a particular composer. The script might generate and return to the client a Web page including a tabular view of this data, including the title, the year composed, the type of composition, and a list of the movements in the composition. While the page may contain the information in date order, if the user wants to view the compositions in alphabetical order or to limit their view to orchestral works or fugues, the user is forced to submit additional requests to the server. This is an expensive way to view the same data in only a slightly different way. The problem is compounded if the Web author decides to present each composition in single record view, that is, one record per page. A full round-trip to the server is required to obtain each subsequent record.

If Web authors want to allow the user to add or update the data, they typically create HTML forms and submit GET and POST requests to an application running on the server. The server application parses out the data from an HTTP data stream and then logs the data to a database. For every update request, the page containing the Submit button and the form data is reloaded. This is not a seamless experience for the user.

The following sections show how the various components in the data binding architecture offer solutions to these problems and make the most efficient use of the Web.

Data Binding Architecture

Adding a Data Source Object to a Page

Binding HTML Elements to Data

DHTML Object Model Support for Data Binding

DHTML Event Model Support for Data Binding

Microsoft Tabular Data Control (TDC)

Microsoft Remote Data Service (formerly ADC)


Data Binding Architecture

Data binding is based on a component architecture consisting of four major pieces—data source objects, data consumers, the binding agent, and the table repetition agent. Data source objects provide the data to a page, data-consuming HTML elements display the data, and the agents ensure that both provider and consumer are synchronized. The following diagram illustrates how the components fit together.

Data Source Objects

To bind data to the elements of an HTML page in Internet Explorer 4.0, a data source object (DSO) must be present on that page. DSOs implement an open specification that leaves it to the DSO developer to determine the following:

  • How the data is transmitted to the page. A DSO can use any transport protocol it chooses. This might be a standard Internet protocol such as HTTP or simple file I/O. A DSO also determines whether the transmission occurs synchronously or asynchronously. Asynchronous transmission is preferred, as it provides the most immediate interactivity to the user.
  • How the data set is specified. A DSO might require an ODBC connection string and an SQL statement, or it might accept a simple URL.
  • How the data is manipulated through scripts. Since the DSO maintains the data on the client, it also manages how the data is sorted and filtered.
  • Whether updates are allowed.

A DSO typically exposes this functionality through an object model accessible to scripts.

The only strict requirement imposed upon a DSO is that it must provide access to its data through the OLE DB or OLE DB Simple Provider APIs. Because all DSOs provide data access through a standard set of interfaces, MSHTML extends the object model of the DSO with a standard set of properties, methods, and events. It is through this object model that scripts can manipulate the data.

Specifics on adding a DSO to a page are provided below. Information on implementing custom data source objects is available in IE4/MSHTML Data Binding Interfaces.

Data Consumers

Data consumers are elements on the HTML page capable of rendering the data supplied by a DSO. Elements include many of those intrinsic to HTML, as well as custom objects implemented as Java applets or ActiveX™ Controls. Internet Explorer 4.0 supports HTML extensions to allow authors to bind an element to a specific column of data in a data set exposed by a DSO. Applets and ActiveX Controls support additional binding semantics described below.

Elements support the consumption of either single-valued or tabular data. Single-valued consumers such as INPUT elements consume a single value from the current record provided by a data source. Tabular data consumers such as the TABLE element repeat an entire set of records from a data provider. This is called set binding.

The section on HTML extensions explains the extended attributes that allow Web authors to bind elements to the data supplied by a DSO. For further information on the individual elements that support data binding, see Binding an HTML Element to Data.

Binding Agents

The binding and repetition agents are implemented by Mshtml.dll, the HTML viewer for Internet Explorer 4.0, and they work completely behind the scenes. When a page is first loaded, the binding agent finds the DSOs and the data consumers among those elements on the page. Once the binding agent recognizes all DSOs and data consumers, it maintains the synchronization of the data that flows between them. For example, when the DSO receives more data from its source, the binding agent transmits the new data to the consumers. Conversely, when a user updates a data bound element on the page, the binding agent notifies the DSO.

To signal the Web author of important changes in the state of the data caused by providers and consumers, the binding agent fires a variety of scriptable events.

Table Repetition Agent

The repetition agent works with tabular data consumers such as the HTML TABLE element to repeat the entire data set supplied by a DSO. Note that individual elements in the table are synchronized through interaction with the binding agent.

HTML Extensions for Data Binding

To enable Web authors to add data binding to their pages, Internet Explorer 4.0 provides support for several new HTML attributes. All data binding-related HTML attributes correspond to a similarly named property in the Document Object Model. The following section introduces these attributes and describes their use.

The key to data binding is connecting a data source object to a data consumer. To achieve a binding between a data source object (DSO) and a data consumer, Internet Explorer 4.0 extends HTML to support the following attributes:
DATASRC | Specifies the identification of the DSO to which a consumer is bound.
DATAFLD | Identifies the specific column exposed by the DSO to which the element is bound.
DATAFORMATAS | Indicates how the data in the specified column should be rendered.
DATAPAGESIZE | Indicates how many records are displayed in a table at once.

Bound elements fall into two specific categories:

  • Single-valued consumers
  • Tabular data consumers

The binding agent takes a single value from the current record of a data source and passes it to a single-valued consumer. The repetition agent works with the binding agent to pass the entire set of records to a tabular data consumer.

By specifying the DATASRC and DATAFLD attributes on a single-valued data consuming element of a Web page, the Web author fully specifies the binding of an element to data. By specifying DATAFORMATAS on a single-valued element, the Web author indicates how the data should be interpreted. DATAPAGESIZE allows the author to restrict the number of records that are displayed by a tabular consumer. All these properties can be set at run time through the document object model.

Here's a sample declaration for a single-valued data consuming element that might appear on an HTML page.

<SPAN DATASRC=#dsoComposer DATAFLD=compsr_first></SPAN>

The DATASRC attribute in this example is set to the ID (dsoComposer) of a data source object (DSO) embedded on the page. The DATAFLD is set to the name of a column in the data set provided by the DSO. For this binding to succeed, the data set retrieved by the DSO must contain a column named "compsr_first".

Click the Show Me button to see a working example.

The following example shows how a table, a tabular data consumer, can be bound to a data source object. The repetition agent uses the table row (TR) in the table body as a template. As the DSO identified in this example as "dsoComposer" supplies each record in the data set, the template including the DIV is repeated, until all composers' first names are displayed.

<TABLE DATASRC=#dsoComposer>
    <TR><TD><DIV DATAFLD=compsr_first></DIV></TD></TR>
</TABLE>

Click the Show Me button to see a working example that uses the TDC to display a table of composers, including their first and last name, date of birth and death, and country of origin.

Specifying Data Rendering with the DATAFORMATAS Attribute

The data supplied by a DSO can be in a variety of formats, and the page author can use the DATAFORMATAS attribute on single-valued consumer elements that support the attribute to indicate how the data should be rendered. In Internet Explorer 4.0, HTML and TEXT are the valid values for this attribute.

<MARQUEE DATASRC=#dsoAdvertisement DATAFLD=banner
    DATAFORMATAS=html>
</MARQUEE>

The previous example describes a MARQUEE that calls upon a data source object that supplies various banners for display in a page. Click the Show Me button to see how a timer can be used to randomly select and display an advertisement supplied by a data source.

Optimizing Table Viewing with the DATAPAGESIZE Attribute

When binding a TABLE to a data source, all the records in the data set will be displayed by default. If the data set is large, the page may grow beyond what is visible to the user. In addition, any content positioned below the table will get pushed off the screen. The DATAPAGESIZE attribute can be applied to a TABLE to specify the maximum number of records that should be displayed at any one time. To enable the user to move to the next and previous page of records viewed in the table, Web authors can use the nextPage and previousPage methods exposed by the TABLE object in the document object model. Authors can also change the page size of the table at run time by setting the dataPageSize property. Click the Show Me button to see how it works.

In addition to limiting table size, Web authors should investigate the specific functionality exposed by the DSO they have chosen for use on their HTML page. Both the TDC and RDS provide filtering capabilities.


Adding a Data Source Object to a Page

Once a Web author has identified the data that she wishes to display on a page, the next step is to choose the data source object (DSO) that will supply that data and to add a reference to that DSO to that page. Internet Explorer 4.0 ships with a number of data source objects. These include

  • Tabular Data Control (TDC)
  • Remote Data Service (formerly ADC)
  • JDBC Applet
  • XML Data Source
  • MSHTML Data Source

In addition to these data providers, Microsoft maintains a gallery of data source objects. Jump to this site to learn about other data providers as they become available.

A DSO can be implemented as an ActiveX control or as a Java applet. The OBJECT tag is used to embed an ActiveX control on the page; the APPLET tag is used to embed a Java applet on the page. In general, Web authors can copy and paste the appropriate OBJECT or APPLET declaration corresponding to the DSO of their choosing and modify the PARAM tags appropriately. So that elements on the page can bind to the data source, the declaration should include the ID attribute.

Because the data source object specification imposes no requirements on the DSO regarding the object model it exposes, Web authors should familiarize themselves with the documentation associated with the DSO they select to provide data to their page.

Tabular Data Control (TDC)

The TDC is a simple DSO that provides access to delimited text files. This is the DSO used in the majority of the samples provided with this section. Consider using the TDC if:

  • You have a simple data set to display. TDC supports some simple data types.
  • You need to browse your data offline. The file transmitted by the TDC can be cached on the client and read offline.
  • You want to prevent direct access to your DBMS. A server script can be written to dump data from your database into a delimited text file. In addition, most DBMSs support this feature.

The following example represents a declaration specific to the Tabular Data Control (TDC).

<OBJECT CLASSID="clsid:333C7BC4-460F-11D0-BC04-0080C7055A83"
    ID=dsoComposer WIDTH=0 HEIGHT=0>
    <PARAM NAME="DataURL" VALUE="composer.csv">
</OBJECT>

DataURL is a property specific to the TDC. The TDC uses this property to allow an author to specify the data set that should get loaded along with the page. For more information about the TDC, see the companion documentation for this component in the Component Library included with the Internet Client SDK.

Remote Data Service (RDS)

The Remote Data Service is a more sophisticated DSO that ships with Internet Explorer 4.0. RDS obtains its data from a database using OLE-DB or ODBC. Consider using RDS if:

  • You have existing data in an OLE-DB or ODBC-compliant database management system (DBMS) such as SQL Server, Microsoft® Access, or Oracle.
  • You want to specify the data using a SQL statement.
  • You need to provide update, insert, and delete capabilities.
  • You want direct, real-time access to the data.

A declaration specific to RDS follows:

<OBJECT classid="clsid:BD96C556-65A3-11D0-983A-00C04FC29E33"
    ID=dsoComposer HEIGHT=0 WIDTH=0>
    <PARAM NAME="Server"  VALUE="http://musicserver">
    <PARAM NAME="Connect" VALUE="dsn=music;uid=guest;pwd=">
    <PARAM NAME="SQL"     VALUE="select compsr_name from composer">
</OBJECT>

First, note the class identifier (CLSID) specific to RDS. Every ActiveX component requires a CLSID to differentiate it from other objects registered on the system. Next, note that the base properties exposed by RDS differ significantly from those exposed by the TDC. That's because the TDC derives its data from a flat text file, while the RDS is capable of retrieving and updating data from any OLE-DB or ODBC-compliant database. The following are the properties specified in the example declaration above:
Server | String identifying the protocol and the server that supplies the data.
Connect | Standard ODBC connection string identifying the data source name configured on the server.
SQL | SQL query identifying the table and columns to be selected from the database.

For the specifics on how to use RDS, see the companion documentation in the Component Library of the Internet Client SDK.

JDBC DataSource Applet

The JDBC DataSource Applet is a DSO available for download from the Microsoft Data Source Object Gallery. Consider using this applet if:

  • You have existing data in an ODBC-compliant database management system (DBMS) such as SQL Server, Microsoft® Access, or Oracle.
  • You want to specify the data using a SQL statement.
  • You need to provide update, insert, and delete capabilities.
<APPLET CODE=JDC.class NAME="DSA1" ID="DSA1" WIDTH=0 HEIGHT=0>
    <PARAM NAME=cabbase VALUE=
        "http://www.microsoft.com/gallery/files/datasrc/jdbcapplet/jdc.cab">
    <PARAM NAME=dbURL VALUE="jdbc:odbc:Northwind">
    <PARAM NAME=showUI VALUE=false>
    <PARAM NAME=sqlStatement VALUE="select ProductName, CompanyName,
        CategoryName from Products, Suppliers, Categories where
        Suppliers.SupplierID=Products.SupplierID and Categories.CategoryID =
        Products.CategoryID and Categories.CategoryID < 5">
    <PARAM NAME=allowInsert VALUE="true">
    <PARAM NAME=allowDelete VALUE="true">
    <PARAM NAME=allowUpdate VALUE="false">
    <PARAM NAME=user        VALUE="">
    <PARAM NAME=password    VALUE="">
</APPLET>

Instead of a CLSID, the CODE attribute uniquely identifies the DSO. Note that the basic properties exposed by this DSO differ from those exposed by the TDC or RDS. The following properties are specified in the example declaration above:
cabbase | General property, applicable to all applets, that specifies the location of the code for the applet. The code will be downloaded to the client if not already installed.
dbURL | Required string that identifies the ODBC data source name (DSN) configured in the user's control panel.
showUI | Optional Boolean value indicating whether a user interface should be displayed.
sqlStatement | SQL string identifying the table and columns to be selected from the database.
allowInsert | Boolean value indicating whether new records can be inserted into the data set.
allowDelete | Boolean value indicating whether existing records can be deleted.
allowUpdate | Boolean value indicating whether existing records can be updated.
user | Optional string identifying the user. Some ODBC data sources require authentication.
password | Optional string identifying the specified user's password.

XML Data Source

Extensible Markup Language (XML) describes data and structured text on the Web in a standard way. Internet Explorer 4.0 ships with an application that serves as an XML data provider. While the XML DSO is a read-only data provider, Web authors should consider using it to display hierarchical data.

To use the XML data source object, add an APPLET tag to your page, as in the following:

<APPLET
    CLASS=com.ms.xml.dso.XMLDSO.class
    ID=xmldso
    WIDTH=0
    WIDTH=0
    MAYSCRIPT=true>
    <PARAM NAME=URL VALUE="composer.xml">
</APPLET>

Since the DSO is implemented in Java, embedding it on the page requires the use of the APPLET tag. The CLASS attribute specifies the package in which the code is implemented. The URL property specifies the location of the data. The XML DSO retrieves the XML from this location, parses it, and provides the data to bound elements on the page. The data consuming elements are isolated from the details of XML.

Click the Show Me button to see a simple example that uses the XML DSO to display an XML data set in a tabular format.

Using the XML DSO to view hierarchical data

The following example shows how the XML DSO can be used to bind nested tables to hierarchical XML data. The XML data contains a list of CUSTOMERS. Each customer contains a list of ORDERS. Each order contains a list of ITEMS yielding three levels of repetition bound to three nested tables.

Additional XML resources

For additional information on XML, see the following resources:

  • Latest working draft published by the XML working group at the W3C
  • Information on the XML standard
  • W3C XML Resources

MSHTML Data Source

In addition to using external components as data source objects, Web authors can define their data sets within an HTML document and use MSHTML itself to provide read-only data to a page. For the purposes of this section, the page supplying the data is called the data page.

When MSHTML is used as a DSO, it parses through the data page in search of elements with an ID attribute. The set of unique IDs defines the columns in the data set, and Web authors use these ID attributes as the value for the DATAFLD attribute on elements of the bound page. For example, given the following SPAN from a data page, MSHTML interprets compsr_last as the name of a column and Mozart as data in that column.

<SPAN ID=compsr_last>Mozart</SPAN>

Multiple elements on the page sharing the same ID identify additional records in the data set. A column that is not represented is given the null value in the corresponding data set. Only elements with an opening and closing tag (for example, DIV, SPAN, H1) can be used to supply data. The following example defines a two-column table consisting of three records.

<<H1 ID=COMPSR_FIRST>Hector</H1>
<MARQUEE ID=COMPSR_LAST>Berlioz</MARQUEE>
<DIV ID=COMPSR_BIRTH>1803</DIV>
<H2 ID=COMPSR_FIRST>Modest</H2>
<H3 ID=COMPSR_LAST>Moussorgsky</H3>
<BUTTON ID=COMPSR_BIRTH>1839</BUTTON>
<TEXTAREA ID=COMPSR_FIRST>Franz</TEXTAREA>
<XMP ID=COMPSR_LAST>Liszt</XMP>
<SPAN ID=COMPSR_BIRTH>1811</SPAN>

Observe that the MSHTML DSO disregards the lack of consistency in the elements used. In the example above, the H1, H2, and TEXTAREA elements represent the data for the first name column in the data set; the P, H3, and XMP elements represent the last name column; the DIV, BUTTON, and SPAN elements represent the date of birth column.

Once the data page is defined, use an OBJECT tag on the data bound page to supply the data as follows:

<OBJECT ID=htmlComposer DATA="compdata.htm" HEIGHT=0 WIDTH=0>
</OBJECT>

The DATA attribute points to the data page and can specify a complete or relative URL.

Elements on the page used to present the data can be bound using the data binding extensions.

Click the Show Me button to see how the MSHTML DSO works.

Creating Custom Data Source Objects

While the components described above are implementations of data source objects (DSO) provided with Internet Explorer 4.0 and available through the DSO gallery, the specification is completely open and language independent so that independent software vendors (ISVs) can create their own data providers. For more information on creating a DSO, see the COM Objects as Data Providers document.


Binding HTML Elements to Data

To display the data provided by a data source object (DSO), the page author binds elements on an HTML page to the DSO. Using the data binding extensions or the corresponding data binding properties makes it easy. This section shows how to bind an element to data, the elements that support data binding, and the capabilities of those elements. Capabilities include support for updating the data to which an element is bound and the format in which the data is displayed—HTML or plain text.

Bindable HTML elements fall into two categories—single-valued and tabular consumers. Single-valued consumers bind to a single field of the current record provided by a DSO. Tabular consumers bind to an entire data set and use their contained elements as a template to repeat the data. In Internet Explorer 4.0, the TABLE element is an example of a tabular data consumer, and the procedure for binding it to data is described below.

Binding a Single-Valued Element to Data

The procedure for binding a single-valued element to data is the same regardless of the element. Elements can be bound to data at design time using the DATASRC and DATAFLD attributes or at run time using the dataSrc and dataFld properties exposed by the corresponding objects in the document object model.

Binding a single-valued element to data at design time

To specify a complete binding to a field in a data set, data-consuming elements use the DATASRC and DATAFLD attributes. Given a text box, for example, a page author can bind that element to data as follows:

<INPUT TYPE=TEXTBOX DATASRC=#dsoComposers DATAFLD=compsr_last>

The DATASRC attribute in this example specifies the ID, prefixed by a hash mark (#), of a data source object (DSO) embedded on the page. The hash mark is required. The DATAFLD attribute identifies the field in the data provided by the DSO to which the text box should be bound.

Click the Show Me button to see how it works.

Binding a TABLE to Data

Because the TABLE element is a tabular data consumer, it relies upon the elements that it contains to bind to the individual fields in the data set provided by the DSO. The contained elements serve as a template, and they are repeated once for each record in the data set. The TABLE specifies the DATASRC attribute. The contained elements specify the DATAFLD attribute and inherit the DATASRC from the table. Here's a simple example:

<TABLE DATASRC=#dsoComposer>
    <TR><TD><SPAN DATAFLD=compsr_first></SPAN></TD></TR>
</TABLE>

Click the Show Me button to see how it works.

As with single-valued consumers, a tabular data consumer can be bound to data at run time using the document object model. The procedure for accomplishing this is described below.

Elements that Support Data Binding

The previous sections used a TEXTBOX, a SPAN, and a TABLE element to illustrate how to bind single-valued and tabular consumers to the data provided by a DSO. Many other HTML elements can be bound to data. Some of these elements support updating the data to which they are bound. Changes can be persisted to the back-end data set if the DSO supports update. Other elements support rendering of the data as HTML in addition to the plain text default using the DATAFORMATAS attribute.

The following table presents the single-valued HTML elements that support data binding. Additional columns indicate:

  • If the element supports update.
  • If the element can render its data as HTML.
  • The property to which the data is applied.

Use the drop-down list to filter the elements appropriately.

Element Updatable Renders HTML Bound Property

Read-only elements

Bindable HTML elements that supply read-only functionality include A (anchor), BUTTON, DIV, IMG (image), FRAME, IFRAME, LABEL, MARQUEE, and SPAN.

Additionally, the BUTTON, DIV, LABEL, MARQUEE, and SPAN elements support the usage of the DATAFORMATAS attribute and the corresponding dataFormatAs property to render the data to which they are bound as plain text (default) and as HTML. The data displayed by the element is automatically updated as the record pointer maintained by the DSO moves or the underlying data to which the element is bound changes. Individual descriptions for these elements follow.

A

An anchor element applies the data supplied by a DSO to the HREF attribute; thus, the supplied data should represent a URL. An example of a bound anchor is:

<A DATASRC=#dsoLinks DATAFLD=link_href><SPAN DATASRC=#dsoLinks DATAFLD=link_friendly></SPAN></A>

BUTTON

A BUTTON element renders the data supplied by a DSO on its face. An example of a bound BUTTON is:

<BUTTON DATASRC=#dsoLinks DATAFLD=link_friendly></BUTTON>

Click the Show Me button to see a working example.

DIV

A DIV element is useful for displaying a block of text. An example of a bound DIV is:

<DIV DATASRC=#dsoComposer DATAFLD=compsr_biography></DIV>

IMG

An IMG element applies the data supplied by a DSO to locate, load, and display the image typically pointed to by its SRC attribute. Supplying raw image data through the bound column is not supported.

An example of a bound IMG tag is:

<SPAN DATASRC=#dsoImages DATAFLD=image></SPAN>

Click the Show Me button to see a working example.

FRAME

A FRAME element applies the data supplied by a DSO to its HREF attribute; thus, the bound value should represent a URL. So that the binding occurs successfully, the data source object supplying data to a bound frame should be present in the HEAD section of the HTML file containing the FRAMESET. An example of a bound FRAME is:

<HTML>
<HEAD>
<<!-- Add DSO reference here -->
</HEAD>
<FRAMESET>
    <FRAME DATASRC=#dsoFAQ DATAFLD=frame_question ...>
    <FRAME DATASRC=#dsoFAQ DATAFLD=frame_answer ...>
</FRAMESET>
</HTML>

The code behind the following Show Me button implements a frame-based FAQ. The first frame displays the question; the second frame displays the answer; the third frame contains navigation buttons. The first and second frames are bound to a two-column table. The first column in the table contains relative paths to pages containing questions. The second column contains relative paths to pages containing the answers. Since the DSO is embedded in the HEAD of the outer page containing the FRAMESET, the code behind the navigation buttons drills out of the page in which it resides using the top object and references the DSO by its ID. top returns an object reference to the outermost containing window.

IFRAME

An IFRAME element applies the data supplied by a DSO to its HREF attribute; thus, the data should represent a URL. In contrast to the FRAME case, the DSO can be declared anywhere on the page. An example of a bound IFRAME is:

<IFRAME DATASRC=#DSC1 DATAFLD=iframe_url>

Click the Show Me button to see a working example.

LABEL

Use a LABEL element to describe another bound element on the page. A label applies the data supplied by a DSO to its caption. An example of a bound LABEL is:

<LABEL FOR=somecontrolid DATASRC=#DSC1 DATAFLD=label_col></LABEL>

Since a LABEL is associated with other elements indicated by its FOR attribute, using a bound LABEL within a repeated table can yield unexpected results. If the FOR attribute references another element within the repeated table, the LABEL tag will not be associated with the elements, since there will be multiple elements with the same ID/NAME as a result of the repetition.

MARQUEE

A MARQUEE element uses its bound data to replace the text that appears between its opening and closing tags.

An example of a bound MARQUEE is:

<MARQUEE DATASRC=#dsoComposer DATAFLD=bio DATAFORMATAS=HTML></MARQUEE>

Click the Show Me button to see a working example.

SPAN

Like a DIV, a SPAN is a read-only data consumer. Use a SPAN to display inline text or limited HTML text. If the SPAN is used to display HTML text, that text should not include any HTML block elements. When the current record or the underlying value in the bound column provided by the DSO changes, the SPAN reflects the change. An example of a bound SPAN is:

<SPAN DATASRC=#dsoComposer DATAFLD=compsr_last></SPAN>

Click the Show Me button to see a working example.

Elements that support update

The APPLET, INPUT (with the exception of the button type), SELECT, TEXTAREA, and OBJECT elements support updating the data to which they are bound if the underlying DSO supports update functionality. Descriptions of these individual elements follow.

INPUT

The INPUT element represents a set of HTML intrinsic controls. Each of the types that support data binding is detailed in the following sections.

RADIO

Radio buttons are used to select a single value from a set of alternatives. These can be used to select the value for an enumerated field in a database. One radio button is specified for each of the alternatives using a separate INPUT. The NAME attribute on the INPUT determines the logical grouping of alternatives. One value is bound for all the INPUTs with the same NAME attribute. All members of a group must specify the corresponding DATASRC and DATAFLD attributes.

An example of a bound radio button group is:

<INPUT TYPE=RADIO NAME=cards VALUE=mc
DATASRC=#dsoOrders DATAFLD=cardname>MasterCard
<INPUT TYPE=RADIO NAME=cards VALUE=amex
DATASRC=#dsoOrders DATAFLD=cardname >American Express
<INPUT TYPE=RADIO NAME=cards VALUE=visa
DATASRC=#dsoOrders DATAFLD=cardname >Visa

Click the Show Me button to see a working example.

CHECKBOX

Although check boxes allow a value attribute that is used when submitting an HTML form on a page, IE4/MSHTML uses check boxes as simple Boolean selections. Check boxes generate the Boolean values TRUE or FALSE depending on whether they are checked or not. The binding agent coerces the values to and from the underlying data set. The following coercions are supported based on the type of the bound column.

The following table describes the values that a bound check box expects a DSO to supply for various data types.

Data type | Expected True Value | Expected False Value
String | "True" | "1" | <non-empty string> | "False" | "0" | <zero-length string>
Integer | non-zero | 0
Float | non-zero | 0
Date | invalid | invalid
Currency | non-zero | 0

An example of a bound check box is as follows:

<INPUT TYPE=CHECKBOX DATASRC=#dsoSurvey DATAFLD=us_resident> U.S. Resident

Click the Show Me button to see a working example.

TEXT

The TEXT type is used as a simple text box. The value of the text box can be bound to a field in the data source using the DATASRC and DATAFLD attributes.

An example of a bound text box is:

<INPUT TYPE=TEXT DATASRC=#DSC1 DATAFLD=name>

HIDDEN

The HIDDEN type is used to store information in the page that isn't displayed to the user. The element is populated with data from the current record, but it cannot be modified.

An example of a bound hidden field is:

<INPUT TYPE=HIDDEN DATASRC=#DSC1 DATAFLD=key>

PASSWORD

The PASSWORD type is basically the same as the TEXT type except that the bound text is not displayed to the user. Use this input type with care since the associated data is fully accessible to scripts through the data-binding object model, as well as directly through the element's value.

An example of a bound password is:

<INPUT TYPE=PASSWORD DATASRC=#DSC1 DATAFLD=password>

SELECT

A SELECT element supplies the functionality of a drop-down list (combo box) or a list box. Internet Explorer supports binding to a single selected element; binding to multiple selections is not supported.

The items in a SELECT control are specified using OPTION tags. The document object model defines an options array that corresponds to the collection of OPTION tags for a SELECT. Each OPTION has a corresponding index, text, and value. The SELECT has a selectedIndex property that corresponds to the index of the OPTION currently selected. If no item is selected, the selectedIndex is set to -1. The text attribute of an OPTION corresponds to the text following the OPTION tag and represents the string that is displayed for that OPTION in the SELECT. The VALUE attribute provides the value that is to be returned when the HTML form is submitted. Value is also what is stored into the bound column of the data source.

Initially, the selectedIndex property of a bound SELECT control will be set to the index of the value in the options array corresponding to the field of the data source. If the value is not a member of the options array, the index property is set to -1 and, if the SELECT is a combo, no value is displayed. When a user changes the selected item, the corresponding OPTION value (attribute) is used to update the value of the bound field of the data source. Validation events are fired as with other controls.

An example of a bound SELECT is:

<SELECT DATASRC=#DSC1 DATAFLD=cardname>
<OPTION VALUE=mc>MasterCard
<OPTION VALUE=amex>American Express
<OPTION VALUE=visa>Visa
</SELECT>

Click the Show Me button to see a working example.

TEXTAREA

A TEXTAREA is a multirow text box for data input similar to the INPUT TYPE=text intrinsic. As such it supports the update of the data if the DSO supports the update feature.

An example of a bound TEXTAREA is:

<TEXTAREA DATASRC=#dsoComposer DATAFLD=bio></TEXTAREA>

Click the Show Me button to see a working example.

OBJECT

When DATASRC and DATAFLD are specified on an OBJECT, Internet Explorer 4.0 attempts to bind to the object's default property. The defaultbind attribute specified in an object's type information uniquely identifies the default property. If a default property is not specified in this way, Internet Explorer 4.0 uses the property with DISPID 0.

An example of binding the default value on the object tag is:

<OBJECT ID=oControl1 WIDTH=100 HEIGHT=100
    CLASSID="CLSID:xxxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxxx"
    DATASRC=#DSC1 DATAFLD=controlData>
</OBJECT>

Additionally, Internet Explorer 4.0 supports binding to arbitrary OBJECT properties through the object's contained PARAM tags. Apply the DATASRC and DATAFLD attributes to the PARAM tag. The property is initialized with the data supplied by the DSO.

An example of binding the PARAMs on the object tag is:

<OBJECT ID="oControl1" WIDTH=100 HEIGHT=100
    CLASSID="CLSID:xxxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxxx">
<PARAM NAME="ForeColor" DATASRC=#DSC1 DATAFLD=forecolor>
<PARAM NAME="BackColor" DATASRC=#DSC1 DATAFLD=backcolor>
</OBJECT>

Bindings can be simultaneously applied to both the object's default value as well as its PARAM tags.

APPLET

Internet Explorer 4.0 supports binding to the PARAM tags of an APPLET. For example, the following specifies a binding on the xyz property of the application:

<APPLET CODE=somecode>
    <PARAM NAME="xyz" VALUE="abc" DATASRC="#Ctrl1" DATAFLD="Column1">
    <PARAM NAME="Title" VALUE="BoundApplet">
</APPLET>

Property name resolution

The NAME attribute of the PARAM specifies the basename of the Java methods used to get and set the value of the property. This is termed basename since the method of the Java applet to retrieve the value of the property is get<basename>. Correspondingly, the method to set the value of the Java applet is set<basename>. This naming convention is consistent with the JavaBeans 1.0 specification. The applet used in the previous section is expected to have methods named getxyz and setxyz.

Notifications

Notifications are not fired by the application when property values change. Property changes are only detected when the current record is changed. During this transition, the binding agent interrogates the application and transfers a modified data value, after validation, to the data source. When values are changed directly in the data source, the binding agent is notified by the data source and transfers the value to the application immediately. See the section on data binding events for details about data binding extensions to the event model.

Name space co-mingling

The bound PARAM in the preceding example is the most complicated specification possible. That is, it addresses the case where there is a binding to a property specified by the NAME attribute, and there is a parameter to the application with the same NAME with a corresponding VALUE attribute. This essentially co-mingles two name spaces: the parameter name space for the application and the binding name space, since the NAME attribute is used for both. In such cases, the application ignores the unexpected DATASRC and DATAFLD attributes on the PARAM when fetching a parameter (applications explicitly fetch parameters using the getParameter method), and the binding agent recognizes the attributes and attempts binding using the get and set methods specified above.

The simplest example is one where there is no conflict between the parameter name space and the property name space. An example would be:

<APPLET>
<PARAM NAME="backcolor" DATASRC="#DSC1" DATAFLD="Color">
</APPLET>

Here, the backcolor property only has DATASRC and DATAFLD attributes. No VALUE attribute is specified.


DHTML Object Model Support for Data Binding

In Internet Explorer 4.0, elements are exposed to scripts as objects. The attributes supported by those elements are exposed as properties. Just as a user can perform actions on most elements (clicking a button for example), scripts can call methods of the corresponding object. Scripts can also customize the behavior of elements by handling the events exposed by the corresponding object.

Web authors can achieve dramatic effects on their data bound pages by adding simple scripts that manipulate the properties, methods, and events exposed by the document object model. The document object model supports the following capabilities at run time:

Modifying the Binding of Elements to Data

Binding a Table at Run Time

Dynamically Adding Bound Elements and Data Providers

Dynamically Changing the Way Elements Render Data

Dynamically Controlling the Amount of Displayed Data

Manipulating Data with Active Data Objects (ADO)

This section discusses how to use these features. Because the event model exposed by the document object model for data binding is so extensive, it is treated in a separate section below.

Modifying the Binding of Elements to Data

The DATASRC and DATAFLD attributes, introduced above, allow an author to bind an HTML element to data. The document object model exposes these attributes as the properties dataSrc and dataFld, and their values can be modified at any time through scripts.

Web authors may want to perform the following operations on elements that support data binding:

  • Add a binding to an unbound element
  • Remove a binding from a currently bound element
  • Change the current binding of an element

The following sections assume that the element is not serving as a template element in a repeated table scenario. Dynamic tabular binding is discussed below.

Adding a binding to a single-valued element at run time

Given an element that supports data binding, such as a SPAN or TEXTAREA, adding a binding is as simple as setting the dataSrc and dataFld properties of that element. For example, to bind a span with ID span1 to the first name field in a data set provided by a DSO with id dsoComposer, use the following script:

span1.dataSrc = "#dsoComposer";
span1.dataFld = "compsr_first";

The same binding can be accomplished at design time using the following HTML code:

<SPAN DATASRC="#dsoComposer" DATAFLD="compsr_first"></SPAN>

In both cases compsr_first is the name of an actual field in the data set. The binding will not occur until both properties are set, and any prior value stored by the element will be lost. If the value is required at a later time, for example when the binding is removed, the page author must cache the value prior to binding the element.

Click the Show Me button to see an example.

Removing the binding from a bound element

To remove the binding from a currently bound element, simply set the dataSrc and dataFld properties to the empty string. For example:

span1.dataSrc = "";
span1.dataFld = "";

The previous Show Me button demonstrates this behavior.

Modifying the binding of a single-valued element at run time

Modifying an existing binding is similar to binding an unbound element. Two cases are described:

  • Binding an element to another field within the same data set.
  • Binding an element to another field in another data set.

To bind an element to another field in the same data set, modify the dataFld property. For example, given a SPAN with ID span1 that is currently bound to a composer's first name, the following code binds the SPAN to the composer's last name.

span1.dataFld = "compsr_last";

To bind an element to a field in a different data set:

  • Set the value of the dataSrc property to the DSO that provides the data.
  • Set the value of the dataFld property for the element if the name of the field in the data set provided by the DSO is different than that of previous the DSO.

Binding a Table at Run Time

The section on Binding HTML Elements to Data explained how to bind a table to data at design time. Binding a table at run time requires three steps:

  1. If the table is already bound to a data source, it must be unbound by setting the dataSrc property of the corresponding table object to the empty string.
  2. Modify the bindings of the template elements contained by the table by setting the dataFld property of the corresponding objects.
  3. Bind the table to the appropriate data source by setting the dataSrc property of the corresponding table object.

Note that modifying the bindings of any of the individual elements contained within a table requires that the entire table be unbound and then rebound to the DSO. This is necessary because while the table is bound, changes to elements inside the table are applied to the generated rows. Changes while the table is unbound affect the template. Click the Show Me button to see an example that modifies the binding at run time.

<SCRIPT FOR=cboField EVENT=onchange>
    cDSO = tblComposers.dataSrc; // remember the DSO
    tblComposers.dataSrc = ""; // unbind the table

    // set the binding for the contained element
    spanField.dataFld = this.options(this.selectedIndex).value;

    tblComposers.dataSrc = cDSO; // rebind the table
</SCRIPT>

<TABLE ID=tblComposers DATASRC=#dsoComposers>
    <THEAD><TR STYLE="font-weight:bold">
        <TD>Last Name</TD>
        <TD><SELECT ID=cboField>
            <OPTION VALUE=compsr_first SELECTED>First Name</OPTION>
            <OPTION VALUE=compsr_last>Last Name</OPTION>
            <OPTION VALUE=compsr_birth>Date of Birth</OPTION>
            <OPTION VALUE=compsr_death>Date of Death</OPTION>
            <OPTION VALUE=origin>Origin
           </SELECT>
         </TD>
    </TR></THEAD>
    <TR>
        <TD><SPAN DATAFLD=compsr_Last></SPAN></TD>
        <TD><SPAN ID=spanField DATAFLD=compsr_first></SPAN></TD>
    </TR>
</TABLE>

This example uses the drop-down list to dynamically set the binding of the second column of the table. When a value is selected in the drop-down list, the onchange event handler stores the table's previous binding in a temporary variable. It then unbinds the table by setting its dataSrc property to the empty string. Finally, the code rebinds the table to the DSO by setting the dataSrc property to the previous value.

Dynamically Adding Bound Elements and Data Providers

In addition to modifying the bindings of existing elements on the page, the document object model supports the dynamic addition of both data bound elements and data source objects at run time. By adding these elements at run time, Web authors can reduce the initial download time of their content and can use a single page to display various sets of data to the user.

Click the Show Me button to see an example that dynamically adds a data source object and bound elements to the page.

Dynamically Changing the Way Elements Render Data

The DATAFORMATAS attribute, introduced above, allows an author to change the way an element renders its data. The document object model exposes the dataFormatAs property on elements that support rendering in formats other than text. Click the Show Me button to see how it works.

Dynamically Controlling the Amount of Displayed Data

The DATAPAGESIZE attribute introduced above allows an author to restrict the number of records displayed by a tabular data consumer. The document object model exposes this attribute as the property dataPageSize, and its value can be modified at any time through scripts. In addition, the page author can control the currently viewed page of records displayed by a tabular consumer using the nextPage and previousPage methods.

Click the Show Me button to see how the dataPageSize property and accompanying methods work on a TABLE, a tabular data consumer.

Manipulating Data with Active Data Objects (ADO)

Previous sections have shown how to use HTML elements to bind and display the data provided by a DSO. Independent of the user interface, scripts can access and manipulate the data provided by a DSO in a consistent manner using the ADO recordset object. The recordset object is exposed by all data source objects through the extended recordset property.

Scripting the ADO recordset object, Web authors can add rich functionality to their pages, including:

  • Navigation
  • Insertion, deletion, and update of records

For complete information on ADO, see the accompanying Active Data Objects documentation.

Accessing the ADO recordset object from script

Given a reference to a data source object, accessing the ADO recordset is easy. The following code sample assumes that dsoComposer is a valid DSO.

var oRecordSet = dsoComposer.recordset;

When using a case-sensitive scripting language such as JScript, observe that the recordset property is completely lowercase.

Navigating through a data set

Data binding in Internet Explorer 4.0 uses the notion of a current record to indicate the record in a data set to be displayed by single-valued consumers. When a data set is first loaded, the first record is typically identified as the current record. The current record is affected by any filter or sort order applied to the data. Single-valued consumers always display the current record.

To change the current record and hence the data displayed by single-valued consumers, Web authors can provide users with a set of navigation buttons like the ones shown below.

The code behind these buttons calls the MoveFirst, MovePrevious, MoveNext, and MoveLast methods on the ADO recordset, respectively.

<INPUT ID=cmdNavFirst TYPE=BUTTON VALUE="<<"
    onclick="tdcComposers.recordset.MoveFirst()">

<INPUT ID=cmdNavPrev TYPE=BUTTON VALUE=" < "
    onclick="tdcComposers.recordset.MovePrevious();
    if (tdcComposers.recordset.BOF)
        tdcComposers.recordset.MoveFirst();">

<INPUT ID=cmdNavNext TYPE=BUTTON VALUE=" > "
    onclick="tdcComposers.recordset.MoveNext();
        if (tdcComposers.recordset.EOF)
            tdcComposers.recordset.MoveLast();">

<INPUT ID=cmdNavLast TYPE=BUTTON VALUE=">>"
    onclick="tdcComposers.recordset.MoveLast()">

Using the recordNumber property

If a page displays both single-valued and tabular data consumers on the page, the Web author can add functionality so that when the user clicks a row in the table, the current record and single-valued consumers are set to display the selected row. Likewise, when the user clicks navigation buttons on the page, the table can be synchronized to indicate the currently selected record. Click the Show Me button to see how it works.

The script behind the example uses the recordNumber property available on all repeated elements within a data bound table. This includes both bound and unbound elements. The property returns the number of the record displayed by the table row. In the example, when the user clicks any element within a table row, the click-handling code sets the AbsolutePosition property of the ADO recordset to the value of that element's recordNumber property.

In turn, if the user clicks a navigation button, the appropriate Move method is called on the ADO recordset. Then the highlighted row in the table is updated by searching for the table row with the recordNumber that corresponds to the value of the AbsolutePosition property on the ADO recordset. Once found, the background color of the table row is set to yellow.

Adding, deleting, and modifying records in a data set

To support the addition and deletion of records from a recordset, the ADO recordset object supports both AddNew and Delete methods. When AddNew is called from a script, the DSO adds a new record to the locally cached data set. When Delete is called, the current record is removed from the local data cache.

Bound elements are immediately updated to reflect the addition, removal, and modification of records through scripts. If the current record is removed, single-valued elements are updated to display the next record in the data set. If the last record in the data set is deleted, the previous record is displayed. Tabular data consumers are updated to no longer display the deleted record.

It is important to distinguish between operations that are performed on the local data cache and those that affect the back-end data set. While the TDC, for example, supports the modification of data in the local cache, it does not support committing those changes to the file from which the data was obtained. In contrast, the Remote Data Service (RDS) does support this feature.

Click the Show Me button to see an example that exercises the ADO object model to insert, delete, and update records in the local data cache.


DHTML Event Model Support for Data Binding

The document object model exposes an extensive set of scriptable events that Web authors can use to customize the behavior of objects on an HTML page. The data binding architecture leverages this model by exposing an additional set of events that are of interest to authors creating data-driven pages. These events fall into three categories:

  • Those that apply to the data source object
  • Those that apply to the bound elements
  • Those that apply to the page

Web authors handle these events to maintain a finer grain of control over the page, especially those that support update. Events occur as the data is loaded and is manipulated by the DSO, as the user interacts with the data, and as the page unloads. The events allow the Web author to monitor changes in the state of the DSO, to perform field and record-level validation, and to execute cleanup processing as the page is unloaded.

The following table provides a quick reference on the events that are relevant to data binding; more detailed descriptions follow. For an overview on how to handle events in the document object model, see Understanding the Event Model.

Event Bubbles Canceleable Applies To

The Bubbles column indicates whether or not the event bubbles up the containment hierarchy. Most data-related events bubble. The onbeforeunload event does not bubble because it fires on the window object, which is at the top of the containment hierarchy.

The Canceleable column indicates whether the default action associated with the event can be canceled. The onbeforeupdate event, for example, can be canceled to allow the author to prevent the field to which a consumer is bound from being updated. The onafterupdate event cannot be canceled because the update has already occurred by the time the event fires. It would not have fired had the author canceled the onbeforeupdate event.

The Applies To column indicates the type of element from which the event originates. Bound elements are elements on the page that consume data from a DSO. DSO is any object or application that conforms to the specification for data source objects.

Events That Apply to the DSO

The DSO sends notifications when the data set has changed, as data becomes available, when the data is completely available, and before and after a record supplied by the DSO is committed to the data cache.

ondatasetchanged

The ondatasetchanged event fires under two circumstances:

  • After a new data set is requested.
  • When the current data set has been altered (for example, filtered or sorted).

When the event occurs, data may not be available, but the recordset can be used to obtain the metadata for the data set. Metadata includes the list of fields and their types. Web authors can create truly dynamic pages using metadata.

The following example code adds the list of fields provided by a DSO to a drop-down list, cboSort. When the user selects an item in the drop-down list, the data is sorted by the selected field.

This code handles the ondatasetchanged event for the DSO name dsoComposers.

<SCRIPT FOR=dsoComposers EVENT=ondatasetchanged>
    FillSortDropDownWithFields(cboSort, this.recordset);
</SCRIPT>

The following code loops through the collection of fields provided by the ADO recordset and adds each field name to the options collection.

<SCRIPT>
// Add specified value/text to the dropdown list
function AddItemToDropDown(oDropDown, cValue, cText)
{
    oOption = document.createElement('OPTION');
    oOption.value = cValue;
    oOption.text = cText;
    oDropDown.add(oOption);
}

// Fill dropdown with field names from the ADO RecordSet
function FillSortDropDownWithFields(oDropDown, oRecordSet)
{
// only fill once or let the caller clear list first
    if (oDropDown.options.length > 0)
        return;

    AddItemToDropDown(oDropDown, "None", "None"); // default
    // add each of the columns in the data set to the drop-down
    for (i = 0; i < oRecordSet.fields.count; i++)
    {
        oField = oRecordSet.fields(i);
        AddItemToDropDown(oDropDown, oField.name, oField.name);
    }
    cboSort.selectedIndex = 0;
}
</SCRIPT>

When the user selects an item from the drop-down list, the following code sets the DSO sort property equal to the appropriate filter or to the empty string if "None" was selected. Note that while the previous code samples work with any DSO, the following code is specific to the Tabular Data Control (TDC).

<SCRIPT FOR=cboSort EVENT=onchange>
    cValue = this.options[this.selectedIndex].value;
    tdcComposers.object.Sort = (cValue == 'None' ? '' : cValue);
    tdcComposers.Reset();
</SCRIPT>

ondataavailable

DSOs typically fire the ondataavailable event when they provide their data asynchronously, indicating that additional records are accessible. Web authors should not rely upon this event to fire but might instead use it to indicate progress to the user. The event may fire zero or more times.

ondatasetcomplete

The ondatasetcomplete event fires when a DSO has cached all its data on the client. The reason property of the event object indicates success (0), abort (1), or failure (2) of the download. A failure might result from an error or from an explicit user action, such as clicking the Stop button. If reason indicates success, all the data is programmatically accessible through the ADO Recordset object.

onreadystatechange

While onreadystatechange is not specific to a DSO, understanding the state of an object can be useful. When this event fires, the event-handling code can retrieve the current value of the readyState property. It is typically safe to access the properties of an object when it reaches a ready state of complete.

<SCRIPT FOR=tdcComposer EVENT=onreadystatechange>
if (this.readyState == 'complete')
{
    // perform some action
}
</SCRIPT>

onrowenter

The onrowenter event fires when the current record pointer has changed, for example, through ADO Recordset navigation. Web authors can use this event to preprocess the data in the current record.

onrowexit

The onrowexit event fires before the current record pointer changes. This might occur for the following reasons:

  • Calling a method on the DSO
  • Deleting the current record
  • Leaving the page

The Web author can perform record-level validation prior to moving to the next record. By returning FALSE from this event handler, the Web author can prevent the user from moving to the next record.

The following code performs a simple validation to ensure that the data indicates that the composer's birthday occurred before his death.

<SCRIPT FOR=dsoComposers EVENT=onrowexit>
if (txtBorn.value > txtDied.value)
{
    alert("Birth date must be less than or equal to deceased dates");
    return false;
}
</SCRIPT>

Events that Apply to Data Consumers

Bound elements fire events that allow page authors to perform field-level validation and to handle errors that occur during an update.

onbeforeupdate and onafterupdate

The onbeforeupdate event fires when the data in an element has been changed and that element is about to lose the focus. An element loses focus when the user tabs to the next or previous field in the tab order, uses the mouse to select a different control, or unloads the page. The events do not fire if the value of a bound control is set programmatically. Should the validation code associated with the event detect invalid data, an author can return FALSE to prevent the user from leaving the field.

The following code performs some basic validation on the value entered into a text box. If the value is nonnumeric or outside a specified range, the user is alerted and prevented from leaving the field.

<SCRIPT FOR=txtBorn EVENT=onbeforeupdate>
    dToday = new Date();
    fRet = ValidateDate(parseInt(this.value), 0, dToday.getFullYear());
    event.cancelBubble = true;
    return fRet;
</SCRIPT>

<SCRIPT>
// perform some basic validation on the date
function ValidateDate(nValue, nMin, nMax)
{
    if (isNaN(nValue))
    {
        alert("Year required");
        return false;
    }

    if (nValue < nMin || nValue > nMax)
    {
        alert("Invalid year");
        return false;
    }
    return true;
}

Both the original and the modified data can be obtained while handling the onbeforeupdate event because, while the control's value has been updated, the data has not been committed to the DSO. Use the ADO recordset supplied by the DSO to get the original value. Use the appropriate control property to obtain the current value as entered by the user. Here's an example that works for any text box.

<SCRIPT FOR=txtBorn EVENT=onbeforeupdate>
    curValue = this.value;
    origValue = dsoComposers.recordset.fields(this.dataFld).value;
</SCRIPT>

If the onbeforeupdate event is not canceled, onafterupdate fires after data is transferred from consumer to data provider.

onerrorupdate

The onerrorupdate event fires when an error occurs while transferring data from the data consumer to the data source object through some user interaction. By canceling this event, any system-provided error dialog boxes are suppressed.

Events That Apply to the Page

In addition to the events specified above for data bound elements and data source controls, the onbeforeunload event allows the Web author to save data changed on the page that has not been committed to the location from which the DSO obtains its data. The following user actions are among those that cause onbeforeunload to fire:

  • Hyperlink navigation
  • Clicking the Forward or Back button
  • Selecting a URL from Favorites
  • Clicking a Submit button
  • Refreshing the page

In addition to these user actions, a script that causes the page to unload will also trigger this event.

window.location.href = "http://www.microsoft.com/ie/ie40";

While the onbeforeunload event is not cancelable, a script writer can return a string from the event through the returnValue property. The string is displayed along with an informative message giving the user the opportunity to cancel the navigation. For example, to warn the user of potential data loss, handle the event as follows:

<SCRIPT FOR=window EVENT=onbeforeunload>
    if (g_fFieldsChanged > 0)
        event.returnValue = "Warning: Modified data has not been saved.";
</SCRIPT>

The g_fFieldsChanged flag used in the example indicates that the page has changed. Page authors can track changes to fields by handling the onafterupdate event:

<SCRIPT FOR=document EVENT=onafterupdate>
    g_fFieldsChanged = g_fFieldsChanged + 1
</SCRIPT>

Putting It All Together with the Data Binding Event Tracker

Click the Show Me button to launch a sample that demonstrates many of the events and concepts discussed in this section.

The sample uses the TDC, so no data will be committed back to the data file. Data can be modified in the local cache, however. By modifying the values within the elements on the page, navigating through the records using the navigation buttons, and changing the filter and sort order through the drop-down lists, the majority of the events will fire. Observe the events and the order in which they occur as they are logged to the TEXTAREA on the right half of the sample page. Clear the event log at any time by clicking the Clear Log button.


Document Object Model

The Dynamic HTML document object model allows authors direct, programmable access to the individual components of their Web documents, from individual elements to containers. This access, combined with the event model, allows the browser to react to user input, execute scripts on the fly, and display the new content without downloading additional documents from a server. The document object model puts sophisticated interactivity within easy reach of the average HTML author.

What Is the Object Model?

The object model is the mechanism that makes Dynamic HTML programmable. It doesn't require that authors learn new HTML tags, and it doesn't involve any new authoring technologies. In fact, the object model builds on functionality that authors have used for creating content for previous browsers. Remember setting the value for a form element in script, or adding mouseover events to links in Internet Explorer 3.0? If so, you've been using a limited form of the object model to access your HTML with script.

What's different in the current object model is that now every HTML element is programmable. This means that every HTML element on the page can have script behind it that can be used to interact with user actions and change the page content dynamically. This event model lets a document react when the user has done something on the page, such as move the mouse over a particular element, press a key, or enter information into a form input. Each event can be linked to a script that tells the browser to modify the content on the fly, without having to go back to the server for a new file. The advantages to this are that authors will be able to create interactive Web sites with fewer pages, and users will not have to wait for new pages to download from Web servers, increasing the speed of their browsing and the performance of the Internet as a whole.

Accessing Elements with Script

Every HTML element is a scriptable object in the object model , with its own set of properties, methods, and events. However, to write script for each element object, the author must know how to get to an element.

The object model is focused around collections of elements, a hierarchy of groupings that the elements fall into. The most important of these collections are the all collection and the children collection. A Dynamic HTML document is a structured arrangement of elements—for instance, in the following example, each element has a scope of influence that depends on where in the document the tags appear.

<HTML>
<BODY>
<DIV>
<P>Some text in a <B>paragraph</B>
<IMG id=image1 src="mygif.gif">
</DIV>
<IMG id=image2 src="mygif.gif">
</BODY>
</HTML>

The DIV element contains (and is the parent of) the P tag and the IMG called image1. Conversely, image1 and the P are children of the DIV. The IMG tag called image2, however, is a child of the BODY element. And all elements are children of the HTML element.

For each element object, there is an all collection that contains all the elements that are beneath that element in the hierarchy, and a children collection that contains only the elements that are direct descendants of that element. In the example above, the B would be in the DIV's all collection, but would not appear in the DIV's children collection. Similarly, the DIV is a member of BODY's children collection, but the P is not.

In addition to these collections for each element, the document itself (represented by the document object) has a number of element and non-element collections. The most important is an all collection that contains all the elements on the Web page. This collection is the primary way to access elements through script. For more information about using collections, see Scripting with Elements and Collections.

Events—Bubbling, Canceling, and Handling

Clicking a button, moving the mouse over part of the Web page, selecting some text on the page—these actions all fire events that a DHTML author can write code to run in response to the event. This particular piece of code is generally known as an event handler because that's what it does, handle events.

Event handling is not particular to Internet Explorer 4.0 or even Internet Explorer 3.x; Netscape Navigator 3.x and Communicator handle events as well. However, in Internet Explorer 4.0, the HTML elements on a Web page that are the source of the events, and the types of events that are generated, have been greatly expanded. Previously, only a small set of HTML elements could generate events: anchors, image maps, form elements, applications, and objects. With the Internet Explorer 4.0 event model, every HTML element on the page can be the source for a full set of mouse and keyboard events.

The following is a set of common events that every HTML element generates in Internet Explorer 4.0.

Mouse event | Generated when the user:
onmouseover | Moves the mouse pointer over (that is, enters) an element.
onmouseout | Moves the mouse off an element.
onmousedown | Presses any of the mouse buttons.
onmouseup | Releases any of the mouse buttons.
onmousemove | Moves the mouse pointer within an element.
onclick | Clicks the left mouse button on an element.
ondblclick Double-clicks the left mouse button on an element.

Keyboard event | Generated when the user:
onkeypress | Presses and releases a key (full down-and-up cycle). However, if a key is held down, multiple onkeypress events are fired.
onkeydown | Presses a key. Only a single event will be fired, even if the key is held down.
onkeyup | Releases a key.

To help authors build code that is compact, simpler, and easier to maintain, Internet Explorer 4.0 introduces a new way to handle events—event bubbling. Windows®, OS/2, OSF Motif, and almost every other GUI platform uses this technique for processing events in their user interfaces. However, event bubbling is new to HTML and provides an efficient model for authors to incorporate event handling in their Web documents.

Previously, if an HTML element generated an event but no event handler was registered for it, the event would just vaporize, never to be seen again. Event bubbling simply passes these unhandled events to the parent element for handling. The event continues up ("bubbles up") the element hierarchy until it is handled, or until it reaches the topmost object, the document object.

Event bubbling is useful because it:

  • Allows multiple common actions to be handled centrally.
  • Reduces the amount of overall code in the Web page.
  • Reduces the number of code changes required to update a document.

The following is a simple example of event bubbling in action.

<html>
<body>
<div id=OuterDiv style="background-color: red" onmouseover="alert(window.event.srcElement.id);">
This is some text
<img id=InnerImg>
</div>
</body>
</html>

On this page, when the user moves the mouse pointer over the text, a dialog box appears with the text "OuterDiv." If the mouse then moves over the image, another dialog box appears with the text "InnerImg".

The interesting thing here is that the onmouseover event for the IMG element was handled even though it does not have an event handler. Why is this? The onmouseover event from the IMG element bubbles up to its parent element, which is the DIV element. DIV does have an event handler registered for the onmouseover event, so it fires and generates the specified dialog window.

Every time an event is fired, a special property on the window object is created. This special property contains the event object. The event object contains context information about the event that just fired, including mouse location, keyboard status, and (most importantly) the source element of the event.

The source element is the element that caused the event to fire, and can be accessed using the srcElement property on the window.event object.

In the example above, the dialog displays the id property of the event's srcElement.

Handling Rollover Effects

An author creates a rollover effect to make part of a page react when the user moves the mouse over it. With Internet Explorer 4.0, the process of creating a rollover effect is greatly simplified.

<html>
<head>
<style>
.Item {
   cursor: hand;
   font-family: verdana;
   font-size: 20;
   font-style: normal;
   background-color: blue;
   color: white
 }
.Highlight {
   cursor: hand;
   font-family: verdana;
   font-size: 20;
   font-style: italic;
   background-color: white;
   color: blue
 }
</style>
</head>
<body>
<span class=Item>Milk</span>
<span class=Item>Cookies</span>
<span class=Item>Eggs</span>
<span class=Item>Ham</span>
<span class=Item>Cheese</span>
<span class=Item>Pasta</span>
<span class=Item>Chicken</span>

<script>
function rollon() {
  if (window.event.srcElement.className == "Item") {
     window.event.srcElement.className = "Highlight";
  }
}

document.onmouseover = rollon;

function rolloff() {
  if (window.event.srcElement.className == "Highlight") {
     window.event.srcElement.className = "Item";
  }
}

document.onmouseout = rolloff;
</script>
</body>
</html>

In this example, seven SPAN elements are initially set to use the class Item. When the mouse moves over any one of those elements, it will be changed to use the class Highlight.

Innovations in Internet Explorer 4.0 enable the following:

  • Events can now be generated from a SPAN element. Previously, an author would have had to wrap each SPAN in an anchor to get the right events.
  • With event bubbling, events can be captured at the document object level. You do not need to create separate event handlers for each element that will participate in the effect. For example, should the author add HTML to the page, these additional elements would participate in the event model without changing a single line of script. Note that the document object is the "super parent" for all elements in the document body.

Canceling Events

All events bubble to their parent element (and recursively all the way up to the document object) unless the event is canceled. To cancel an event, you must set the window.event.cancelBubble property to "true" in the event handler. Note that unless canceled, events will bubble up the hierarchy and be handled by all parent elements registered to the event, even if the event has already been handled.

Canceling event bubbling should not be confused with canceling the default action for the event. Some events (for example, the onclick event on an anchor) have a default action. When an anchor is clicked, its default action is to navigate the current window to the URL specified in the src property. Returning "false" from an event handler, or setting window.event.returnValue to "false", cancels the default action but does not cancel event bubbling unless window.event.cancelBubble is also set. Conversely, canceling an event's bubbling doesn't cancel its default action.

The last example showed how you could use event bubbling to apply a common effect to a set of elements. What if you wanted to exclude an element from that effect? Simply change the line:

<span class=Item>Ham</span>

to

<span class=Item onmouseover="window.event.cancelBubble = true;" onmouseout="window.event.cancelBubble = true;">Ham</span>

Now, no matter how many times you move your mouse over "Ham," it will not change style. This is both the onmouseover and onmouseout events were canceled; they did not bubble through to the document, so the document was never given the opportunity to handle those events for "Ham."

Special Considerations

At any one time, you can have an onmouseover event only on a single object. This means that in the following case:

<DIV id=MyDiv>
<IMG id=MyImg>
</DIV>

If you were to move your mouse over the IMG, the order of events would be as follows:

MyDiv:: onmouseover
MyDiv:: onmouseout
MyImg:: onmouseover

Moving your mouse off the IMG fires the MyDiv::onmouseover event again.

At times, the author might want to detect when the mouse moves outside a DIV to perform some special effect. It is not enough to simply trap the onmouseout event. To make this easier, Internet Explorer 4.0 indicates the source element (fromElement) and target element (toElement) for the onmouseover and onmouseout events. You can use these properties in combination with the contains method to tell when the mouse has moved outside a region.

The following example shows the use of these properties and methods.

<html>
<body id=Body>
<div id=OuterDiv style="width: 100px; height: 50px; background: red"
onmouseover="over();" onmouseout="out();">
<img id=Img1>
<img id=Img2>
<img id=Img3>
</div>
<script>
function over() {
  var s;
  s = "onmouseover: "+window.event.srcElement.id+" from: "+

window.event.fromElement.id+" to: "+window.event.toElement.id;
  alert(s);
}

function out() {
  var s;
  s = "onmouseout: "+window.event.srcElement.id+" from: "+

window.event.fromElement.id+" to: "+window.event.toElement.id;
  alert(s);

  if (!(OuterDiv.contains(window.event.toElement))) {
     alert("Out Now");
  }
}
</script>

</body>
</html>

Technical Topics

Working with Windows, Frames, and Dialogs

Scripting with Elements and Collections

Understanding the Event Model

Cross-Frame Scripting and Security


Working with Windows, Frames, and Dialogs

Microsoft® Internet Explorer creates a window object whenever it opens an HTML document. Because this object is the highest-level object in the object model, you use it to gain access to properties and sub-objects in the object model that you need to dynamically access the document content. The following topics explain how use the window object, create new window objects, and create special types of window objects.

Be sure to review Cross-Frame Scripting and Security for cross-window and frame scripting issues. Security considerations limit the cross-window access from scripts, and reading this section will help you understand what you can and cannot do through scripting.

Using the Window Object

Creating and Using Frames

Creating and Using Modal Dialog Boxes

Showing a Help Window

Using the Window Object

The window object is the root of the object hierarchy. All properties in the object model are either accessed as properties of the window object or as properties of those properties. For example, you access the document through the document property of the window object. Properties that have properties are often called objects or sub-objects, so document is referred to as the document object. For a complete list of properties of the window object, see Properties.

Because the current window object is implied, you do not need to prefix the property with the window keyword. However, many people prefer to use the keyword to ensure that their scripts are as clear and readable as possible. For example:

status = "hello";

is the same as saying:

window.status = "hello";

and both will work when referring to the current window object.

Many of the properties of the window object can be used to carry out simple tasks, such as displaying messages, prompting for input, and loading new documents into the window. For example, you can display a simple modal message box from the current window by using the alert method and change the text in the Internet Explorer status bar by using the status property, as in the following example.

<HTML>
<HEAD><TITLE>A Simple Document</TITLE>
<SCRIPT LANGUAGE="JScript">
function doAlert() {
    window.status = "Page is loaded!";
    alert("Page is loaded!");
}
</SCRIPT>
</HEAD>
<BODY onload="doAlert()">
<P>This is a very short document.
</BODY>
</HTML>

You can use the navigate method or the location object to load a new document into a window. The action is similar to the user clicking a link to the new document, but can be carried out from script. The following example uses the navigate method to load the new document named "sample.htm" after a 60-second timer (using the setTimeout method) elapses.

window.setTimeout("window.navigate('sample.htm')", 60000);

You can also use the location object to navigate within the current document. For example, the following statement jumps to the anchor in the document having the name "sample".

window.location.hash="#sample";

There can be more than one window object at a time. For example, the browser creates one window object for each frame defined within a document. From the scripting perspective, the current window object is always the one that contains the document that contains the script. To access window objects other than the current window object, you precede the property with a window reference. The window.open method returns a reference to this new window that is then used in scripts to access properties and methods of the new window.

The following document uses the method to open a window and load the document "sample.htm" when the user clicks the button.

<HTML>
<HEAD><TITLE>Creating a Window</TITLE>
</HEAD>
<BODY>
<P><BUTTON onclick="window.open('sample.htm')">Open Sample</BUTTON>
</BODY>
</HTML>

The new window is a separate instance of Internet Explorer, and the window object created for it is different than that of the original window. The new window can be referenced from the current window in script by the name "mysample". The following example creates a new window for the "sample.htm" document, then assigns the title of the new window's document to the status bar of the original window.

var new_window = window.open("sample.htm");
if (new_window != null)
    window.status = new_window.document.title;

Once a window creates another, it can manage that window in a variety of ways, from loading new documents in the window with the navigate method or location object to closing the window with the close method. Closing the window unloads the document and closes the separate instance of Internet Explorer.

Because the user can also close the new window at any time, you should always make sure that the window exists before attempting to access it. You can do this by checking the closed property, which is set to true when the window is closed.

You can assign a name to a window when you create it by using the optional second parameter of the open method. The name is useful to use as the target of a link, causing the document specified by the link to be loaded in the window. The following document creates a window named "Sample". The links later in the document use "Sample" as the target name.

<HTML>
<HEAD><TITLE>Linking to Sample</TITLE>
</HEAD>
<BODY onload="window.open('sample.htm','Sample')">
<P>Click the following links to view the documents in the Sample window:
<P><A HREF="abc.htm" TARGET="Sample">All About Abc</A>
<P><A HREF="xyz.htm" TARGET="Sample">Some Words on Xyz</A>
</BODY>
</HTML>

By default, the open method creates a window that has a default width and height and the standard menu, toolbar, and other features of Internet Explorer. You can alter this set of features by using the optional third parameter. This parameter is a string consisting of one or more feature settings, including settings for the position and dimension of the window. For example, the following creates a window that is 200-by-400 pixels, has a status bar, but does not have a toolbar, menu bar, or address field.

window.open("sample.htm",null,
    "height=200,width=400,status=yes,toolbar=no,menubar=no,location=no");

For more information about the window features, see open.

Creating and Using Frames

Frames are a way to organize and structure HTML documents, creating compound views that the user sees within the main window of Internet Explorer. Because each frame is itself a unique window within the main window, you use the window object to access the frame's content.

You create frames by using the IFRAME element or FRAMESET and FRAME elements. Each element creates a frame and loads a specified document. For example, the following document creates two equally sized rectangular frames that fill the main window.

<HTML>
<HEAD><TITLE>Two Equal Frames</TITLE>
</HEAD>
<FRAMESET COLS="50%,*">
<FRAME SRC=x.htm>
<FRAME SRC=y.htm>
</FRAMESET>
</HTML>

In a document within a frame, such as the "x.htm" and "y.htm" documents in the example above, you can use the window object as you would in a document within the main window. This means you can get access to the document and event objects for the frameset document and write script that will run from this frameset document. Note that if you use script, or need to instantiate an OBJECT from this frameset document, you need to define these in the HEAD section. Also note that a BODY element is mutually exclusive from a FRAMESET. Using both in a single document will result in the first one being instantiated and the second one ignored. Many authors try to use a BODY element to set the background color, and then instantiate a FRAMESET. Internet Explorer 4.0 will instantiate the BODY, and ignore the FRAMESET. Move the background color settings to the FRAMESET, and remove the BODY from this document, and the browser will intantiate the FRAMESET as you would expect.

You can also gain access to the window that created the frame (called the parent window) and to the other frames created by the parent by using the parent property and the frames collection. The following JScript example using these to display the URL of the documents in each frame.

for (i=0; i<window.parent.frames.length; i++)
    alert("Frame #" + i + " contains: " + window.parent.frames(i).location);

The frames collection contains window objects for each frame, so you can use the same properties and methods with these objects as you would within the current window. For example, you can gain access to the complete contents of the document in another frame by using frames, as in the following example, to display the title of each document.

for (i=0; i<window.parent.frames.length; i++)
    alert("The title of frame #" + i + " is: " + window.parent.frames(i).document.title);

Note Cross-frame security limits scripting to documents loaded from the same domain. Use the domain property to determine and/or set the domain of a document. See Cross-Frame Scripting and Security for more information on cross frame security and scripting considerations.

The frames collection also works this way for the document object. In this case, the frames collection from the document contains window objects for all frames created by IFRAME elements in a document. Consider the following document.

<HTML>
<HEAD><TITLE>Two Floating Frames</TITLE>
<SCRIPT>
function showFrames() {
    for (i=0; i<window.document.frames.length; i++)
        alert("The title of frame #" + i + " is: " +
            window.document.frames(i).document.title);
}
</SCRIPT>
</HEAD>
<BODY onload="showFrames()">
<IFRAME SRC="x.htm" ALIGN=LEFT></IFRAME> Here's some text to the right of a frame.
<BR CLEAR=LEFT>Here's some text beneath the frame.
<BR>
<IFRAME SRC="y.htm" ALIGN=RIGHT></IFRAME> Here's some text to the left of a frame.
<BR CLEAR=RIGHT>Here's some text beneath the frame.
</BODY>
</HTML>

The document above contains two floating frames, one aligned to the left and the other to the right. Once the document is loaded, the "showFrames" function uses the frames collection to access each frame and display the title of the corresponding document.

Unlike windows created using the open method, you cannot close the window associated with a frame. The frame is "closed" when the window that created it is unloaded. Also, properties that apply to the main window, such as status, have no purpose within a frame. Frames do not have status bars, so attempting to get or set status has no effect for the individual frames, and you should access the parent frameset document to set the status bar.

Notice that accessing the window object associated with a frame is not the same as accessing the FRAME or IFRAME element that created the frame. In particular, you cannot access the attributes of these elements by using the window object. Instead, you must use the object for the element, which you can get from the all collection for the document that contains the frame element. For example, if you want to remove the scroll bars from a frame, you have to set the scrolling property of the IFRAME element as follows:

document.all.tags("IFRAME").item(1).scrolling="no";

For more information about element objects and their properties, see Scripting with Elements and Collections.

Creating and Using Modal Dialog Boxes

A dialog box is a special window that you create by using the showModalDialog method on the window object. Dialog boxes are useful for soliciting input from the user in a way that does not obscure the information in the current window. They are also useful for displaying important information that the user should act upon or acknowledge before proceeding.

The showModalDialog method is similar to the open method in that it takes the URL of an HTML document and displays the document in a new window. One of the main differences, however, is that the dialog box is modal, meaning it does not release the input focus until it is closed. This means the user cannot switch back to the window that created the dialog box until she closes the dialog box. However, this does not prevent the user from switching to other windows or applications.

You typically create dialog boxes in response to user input, such as clicking a button or choosing an item in a menu. The following example calls showModalDialog directly from the onclick attribute of a BUTTON element.

<BUTTON onclick="window.showModalDialog('dialog.htm')">Search</BUTTON>

The method in the example above creates a dialog box having the standard dialog box size and features, and loads the document "dialog.htm" into the new window.

You can load any valid HTML document into a dialog box, but most dialog documents contain one or more controls with which the user supplies input or directs an action. For example, the following document provides a text control for letting the user specify a string to search for and buttons to confirm or cancel the search. Notice that the string is returned to the main window by assigning it to "returnValue".

<HTML>
<HEAD><TITLE>Search For</TITLE>
<SCRIPT LANGUAGE="JScript">
function doOK() {
    window.returnValue = window.document.all.MySearch.value;
    window.close();
}
function doCancel() {
    window.returnValue = "";
    window.close();
}
</SCRIPT>
</HEAD>
<BODY>
<P><B>Search For:</B> <INPUT ID=MySearch TYPE=text>
<CENTER>
<BUTTON onclick="doOK()">OK</BUTTON>&nbsp;
<BUTTON onclick="doCancel()">Cancel</BUTTON>
</CENTER>
</BODY>
</HTML>

When the document above is displayed, the user can type a string into the text control (identified by "MySearch") and click either the OK or Cancel button to carry out an action. Clicking OK calls the "doOK" function, which retrieves the text from the text control and assigns it to the returnValue property of the dialog box. Clicking Cancel calls "doCancel", which assigns an empty string to this property. Both functions then call the close method to close the dialog box and return the input focus to the original window.

The returnValue property on the window object specifies the value to be returned by the showModalDialog method after the dialog box closes. Setting this property is one way a dialog box can return information to the original window. Assuming the document in the previous example is in a file named "search.htm", the following example can use the returned string to carry out a search.

function doSearch() {
    var str = showModalDialog("search.htm");
    if (str == "")
        return;    // user canceled search
    else {
        // search for the string
     }
}

You can pass arguments to a dialog box by using the second parameter of showModalDialog. This parameter accepts any valid type, so an array can be passed just as easily as a discrete type.

   var aCafeArgs = new Array("Tall", "Decaf", "Non-fat", "Mocha");
   var cResult = window.showModalDialog("barista.htm", aCafeArgs);

A dialog box can retrieve the arguments through the dialogArguments property of the window object. Passing arguments is a useful way for the original window to specify the initial values for the controls in the dialog box. For example, consider the dialog document in the search example. By scripting the onload event of the BODY element to call the following function, the dialog can set the initial search string to a value supplied by the original window.

function doInit() {
    if (window.dialogArguments != null)
        window.document.all.MySearch.value = window.dialogArguments;
}
   .
   .
   .
<BODY onload="doInit()">

To set the initial search string to the words "Sample Text", the original window calls showModalDialog as in the following example.

var str = showModalDialog("search.htm", "Sample Text");

A better way to make use of the dialog arguments for this document is to store the search string in a variable within the document of the original window, as in the following example.

var str = "";
function doSearch() {
    str = showModalDialog("search.htm", str);
    if (str == "")
        return;    // user canceled search
    else {
        // search for the string
    }
}

Storing the returned string in the global variable ensures that the previous search string is available whenever the user requests another search. Remember that stored values are discarded when a document is unloaded, so you cannot store the previous string with the dialog document. This also means that the stored string in the original window is discarded when that document is unloaded.

In addition to setting initial values, you can also set the input focus to a specific control in the dialog box by using the focus method. This ensures that when the dialog document is loaded, the user can begin entering input immediately without first moving the focus to an appropriate control. The input focus is typically set in the same function that sets initial values for the dialog box. To set the focus to the text control in the previous example, use the following:

window.document.all.MySearch.focus();

If the original window has more that one value to exchange with the dialog box, it can do this by passing an object to the dialog as an argument. For example, the following dialog document prompts the user with both a "Match Case " check box and a "Search For" string. To receive the user's settings for these, the original window passes an object that the dialog sets when the user presses OK or Cancel.

<HTML>
<HEAD><TITLE>Search For</TITLE>
<SCRIPT LANGUAGE="JScript">
function doInit() {
    if (window.dialogArguments != null) {
        window.document.all.MySearch.value = window.dialogArguments.str;
        window.document.all.MatchCase.checked = window.dialogArguments.caseSensitive;
    }
    window.document.all.MySearch.focus();
    window.returnValue = false;
}
function doOK() {
    window.returnValue = true;
    if (window.dialogArguments != null) {
        window.dialogArguments.str = window.document.all.MySearch.value;
        window.dialogArguments.caseSensitive =
            window.document.all.MatchCase.checked;
    }
    window.close();
}
function doCancel() {
    window.returnValue = false;
    window.close();
}
</SCRIPT>
</HEAD>
<BODY onload="doInit()">
<INPUT ID=MatchCase TYPE=checkbox>&nbsp;<B>Match Case</B>
<P><B>Search For:</B> <INPUT ID=MySearch TYPE=text>
<CENTER>
<BUTTON onclick="doOK()">OK</BUTTON>&nbsp;
<BUTTON onclick="doCancel()">Cancel</BUTTON>
</CENTER>
</BODY>
</HTML>

Be careful! Any document that uses this dialog document needs to properly declare and initialize the object. The following example declares the "myDialog" object and initializes the object before calling showModalDialog.

function myDialog() {
    var str;
    var caseSensitive;
}
function doSearch() {
    myDialog.str = "";
    myDialog.caseSensitive = false;
    if (showModalDialog("search.htm", myDialog)==false)
        return;    // user canceled search
    else {
        // search for the string
    }
}

An alternate way to pass multiple values between the original window and the dialog box is to concatenate those values into a single string, and leave it to the documents to parse the string and extract the values.

The appearance and size of a dialog box can be set from the third parameter of the showModalDialog method. The following example creates a dialog box that uses a default font size of 10 pixels and a dialog width and height of 10 ems.

window.showModalDialog("dialog.htm",null,
    "font-size:10px;dialogWidth:10em;dialogHeight:10em")

As you can see in the example above, the third parameter takes a string, consisting of one or more settings separated by semicolons (;). Each setting consists of a name and a value separated by a colon (:) or equal sign (=). The value depends on the ornament. If it is a number, it takes a units designator, such as "px" or "em".

You use the dialogWidth and dialogHeight names to set the initial width and height of the dialog box. Similarly, you can use dialogLeft and dialogTop to set the initial position of the dialog box relative to the upper-left corner of the desktop (not the parent window). If you don't want to calculate the left and top positions for the dialog box, you can center it in the desktop by using the center keyword.

Although the position, width, and height of a dialog box are typically set by the parent document, you can retrieve and change these settings from within the dialog box itself by using the dialogLeft, dialogTop, dialogWidth, and dialogHeight properties. Changing these settings is important, for example, if you want to expand the content of the dialog box to show additional options that the user can choose from.

You can set the default typeface, font size, weight, and style for text in the dialog box by using the font, font-size, font-weight, and font-style names. These take the same values as the CSS attributes of the same name. The default settings apply only to text in the dialog box that does not already have explicit font settings.

Showing a Help Window

You can show help files in the browser using the showHelp method on the window object. The following example creates a help window that would display an HTML help file. For HTMLHelp, there are no modifying parameters, and only defaults will apply to the new window.

<BUTTON onclick="window.showHelp('helpinfo.htm')">Show Help</BUTTON>

The showHelp method can also be used to display WinHelp files. To display WinHelp files, the first parameter of the method specifies an .hlp file, the second parameter specifies a context identifier, and the third (optional) parameter can be used to specify "popup". The default view for help files is to show the help file in the main browser window. If "popup" is specified for WinHelp files, the help file is displayed in a separate window.


Scripting with Elements and Collections

Every HTML document consists of a combination of HTML tags and their attributes. These elements define the structure of the document and determine how the content is presented. Using the Dynamic HTML object model, you can examine and modify these elements and their modifying attributes. The following topics explain how to access the elements of the document using element collections.

The all Collection and the children Collection

More Collections

Using Collections

Creating new Collections: The tags Method

Accessing Element Properties

Examining the Element Hierarchy

Getting an Element's Position and Dimensions

Scrolling Elements into View

The all Collection and the children Collection

An HTML document is a hierarchical construct of tags that define the contents of the document. The all collection on the document object represents all the elements in the document hierarchy. Each element is represented as a programmable object appearing within the collection in source order. Individual element objects are accessed by index or identifier (unique name). The following document shows how to do this.

<HTML>
<HEAD><TITLE>Elements: Collecting</TITLE>
<SCRIPT LANGUAGE="JScript">
function showElements() {
    var tag_names = "";
    for (i=0; i<document.all.length; i++)
        tag_names = tag_names + document.all(i).tagName + " ";
    alert("This document contains: " + tag_names);
}
</SCRIPT>
</HEAD>
<BODY onload="showElements()">
<H1>Welcome!</H1>
<P>This document is <B>very</B> short.
</BODY>
</HTML>

When this document is loaded, the script (an event handler for the onload event) displays a list of the elements in the document by stepping through the all collection. It displays this message:

This document contains: HTML HEAD TITLE SCRIPT BODY H1 P B

You can see that each HTML element in the document is represented. Notice that the list does not show the end tags for the elements. This is because each element object represents both the start and end tags. Also, the collection does not directly indicate the hierarchy of the elements; that is, you can't tell which elements contain others. The collection lists the elements in the order in which they appear in the HTML source of the document.

In many ways, the all collection is like an array. It contains one or more items each of the same type—in this case, element objects. You access the items by using zero-based index values, or by name or identifier. The first item has index value 0, the second has 1, and so on. You can determine how many items are in the collection by using the length property.

Because each item in the all collection is an element object, you can apply properties and methods to these items. For example, you can use the tagName property to retrieve the HTML tag name of the element as was done in the previous example. Similarly, you can access properties and methods of the respective element by accessing this through the document.all collection.

The all collection always represents the current state of the document and is automatically updated to reflect any changes made to the document. For example, if you retrieve the collection and add or remove document content so that the HTML structure is different, the collection will automatically reflect the new HTML content in source order.

In some cases, the all collection might contain more elements than are actually in the document's file. In particular, the collection always contains the HTML, HEAD, TITLE, and BODY elements even if these are not present in the source. Similarly, the collection always contains a TBODY element for each TABLE regardless of whether TBODY was specified in the HTML source.

The all collection also includes comments (!) and unknown or invalid tags. The purpose is to give you an accurate picture of the content of the document. Unknown or invalid tags are typically misspelled or misplaced tags. Knowing what and where they are gives you an opportunity to replace them with valid tags. The all collection lists unknown and invalid start and end tags separately; it does not attempt to combine these into a single item. The following document displays the message "HTML HEAD TITLE SCRIPT BODY ! P ZZZ> /ZZZ> /B".

<HTML>
<HEAD><TITLE>Elements: Collecting</TITLE>
<SCRIPT LANGUAGE="JScript">
function showElements() {
    var tag_names = "";
    for (i=0; i<document.all.length; i++)
        tag_names = tag_names + document.all(i).tagName + " ";
    alert("This document contains: " + tag_names);
}
</SCRIPT>
</HEAD>
<BODY onload="showElements()">
<!-- A comment -->
<P>This document has an <ZZZ>unknown</ZZZ> and an invalid</B> tag.
</BODY>
</HTML>

In addition to the all collection on the document object, each individual element also exposes an all collection. Remember the hierarchical style of HTML—this helps to think about the all collection for each element. The all collection for an element contains all the elements contained by that element. For example, the all collection for the HTML element would contain everything in the source code except the HTML element (this being the only difference between the all collection for the HTML element and the document.all collection).

Each element also exposes a children collection, which contains only the elements that are direct descendants of the element in the HTML hierarchy. Another way of saying this is that the children collection would contain only those elements whose parentElement property would return that element. The content of the children collection is undefined for overlapping elements.

The following example returns the length and contents of the all and the children collections of the document. Notice that there are only two elements that are children of the HTML tag—HEAD and BODY. The TITLE and SCRIPT elements are children of the HEAD, not of the HTML tag.

<HTML id=theHTML>
<HEAD>
<TITLE> Look at the all and the children collection</TITLE>
<SCRIPT>
function showme() {
alert('all: ' + window.theHTML.all.length);
for (i=0; i < theHTML.all.length;i++)
{
alert(theHTML.all[i].tagName);
}
alert('children: ' + window.theHTML.children.length);
for (i=0; i < theHTML.children.length;i++)
{
alert(theHTML.children[i].tagName);
}
}
</SCRIPT>
</HEAD>
<BODY onload=showme()>
<DIV> Some text in a DIV. This DIV will be in
the all collection of the HTML element</DIV>
</BODY>
</HTML>

More Collections

The object model provides additional collections that you can use to access the elements of the document.

Collection | Applies to | Contains
anchors | document object | A elements having non-empty name property
applets | document | APPLET elements
areas | MAP element | AREA elements in the map
cells | TR element | TD or TH elements in the row
elements | FORM element | BUTTON, INPUT, SELECT, and /or TEXTAREA elements in the form
embeds | document | EMBED elements
filters | all elements | filter objects
forms | document | FORM elements
frames | document and window | window objects defined with FRAME and IFRAME elements
images | document | IMG elements
links | document | A elements having non-empty href properties
options | SELECT element | OPTION elements
rows | TABLE | TR elements in the table
scripts | document | SCRIPT elements
tbodies | TABLE | TBODY elements

Some scriptable collections are not really element collections, but collections of other scriptable objects.
Collection | Applies to | Contains
imports | styleSheet object | @import statements that are defined in a style sheet
styleSheets | document | styleSheet objects— represent instances of LINK and STYLE
filters | element | collection of CSS-defined filter attributes per element object
rules | styleSheet object | collection of style rules—combination of a CSS contextual selector and a style

Like the all collection, these collections are automatically updated as changes are made to the document.

Using Collections

Collections in the object model are similar to an array of variables created in a programming language. You can retrieve an item from the collection by providing an name or identifier for the item, or an ordinal index that specifies the position of the item in the collection. Collections indexes are zero-based, so the first item always has an index of zero. The following JScript example displays the tag name of the P element, the sixth element in the collection.

<HTML>
<HEAD><TITLE>Elements: Retrieving Items</TITLE>
<SCRIPT LANGUAGE="JScript">
function showSixth() {
    var el = document.all(5);
    alert("The sixth element is: " + el.tagName);
}
</SCRIPT>
</HEAD>
<BODY onload="showSixth()">
<P>This is a very simple document.
</BODY>
</HTML>

Because index values for collections are zero-based, the index for the last element in a collection is always one less than the length of the collection. So a quick way to get access to the last element in a collection is to subtract one from its length and use the result as the index value, as in the following example.

var elLast = document.all(document.all.length-1);
alert("The last element in this document is: " + elLast.tagName);

You can also retrieve items from a collection by specifying an identifier. In this case, the element must have a valid identifier, set using the ID= attribute. The following JScript example displays the tag name of the element that has the identifier "MyID".

<HTML>
<HEAD><TITLE>Elements: IDs as Indexes</TITLE>
<SCRIPT LANGUAGE="JScript">
function showElementWithID() {
    var el = document.all("MyID");
    alert("The element having the identifier MyID is: " + el.tagName);
}
</SCRIPT>
</HEAD>
<BODY onload="showElementWithID()">
<P ID="MyID">This is a very simple document.
</BODY>
</HTML>

Elements can also be accessed by name, but it is important to remember that the name attribute primarily applies only to the elements that participate in a form submission. The ID attribute is an identifier that applies to every element.

Be careful! While in theory ID means "unique identifier," in reality the uniqueness is not enforced. If more than one element has the same identifier, the result is a collection of elements with the same ID, rather than an individual element. The subsequent collection can only be accessed ordinally. If no element has the identifier, the result is null.

When using an identifier results in another collection, the elements in the new collection have the same order as they have in the document. To get access to these elements, you can use the item method to apply a zero-based index to the collection, as in the following example.

if (document.all("MyID").length != null)
    alert("The first element that has the identifier MyID: " + document.all("MyID").item(0).tagName);

If you already know that more than one element has the same identifier, you can skip a step and use the optional second parameter of item to retrieve an element without first retrieving the collection. The following JScript example displays the same message as the previous example.

var el = document.all.item("MyID",0);
if (el != null)
    alert("The first element that has the identifier MyID: " + el.tagName);

If you already know that more than one element has the same identifier, you can skip a step and use the optional second parameter of item to retrieve an element without first retrieving the collection. The following JScript example displays the same message as the previous example.

var el = document.all.item("MyID",0);
if (el != null)
    alert("The first element that has the identifier MyID: " + el.tagName);

When using scripting languages such as JScript and VBScript (Visual Basic® Scripting Edition), you can also access elements in collections by using the indexing syntax for that language. JScript offers three ways to index an array: an integer index enclosed in square brackets, an identifier given as a string enclosed in square brackets, and an identifier prefixed with a period. The following JScript statements show how to apply these.

var el = document.all[2];    // is the same as document.all.item(2)
var el = document.all["MyID"];   // is the same as document.all.item("MyID")
var el = document.all.MyID;      // is the same as document.all.item("MyID")

Again, be careful when using identifiers in this way. The collection returns another collection if there is more than one element having the given identifier. Always check the return value before you use it.

You can't use identifiers to access items in an imports collection—the collection consists of imported style sheets rather than HTML elements, so no identifiers are available. Use integer indexes instead. Although you can use names to access items in a frames collection, you should make certain that no two windows have the same name. If you don't, only the first window with the given name will be accessible.

Creating new Collections: The tags Method

The tags method creates a collection of elements that have a given tag name. The method filters an existing collection and creates a new collection of a given tag name. For example, the following JScript code applies the tags method to the all collection to retrieve a new collection containing only the TABLE elements in the document. It then applies a border to each table.

var doc_tables = document.all.tags("TABLE");
for (i=0; i<doc_tables.length; i++)
    doc_tables(i).border = 1;

The method searches for any tag name, even names that are not valid HTML. If it finds one or more elements having that name, it returns the collection. If it can't find an element having that name, it returns an empty collection. Use the length property to determine how many elements the collection contains. The collection is empty if its length is zero.

The tags method preserves the order of the elements as it creates the new collection. This means the first element in the new collection is also the first instance of the tag in the document.

Because the collection returned by the tags method is a subset of the all collection, the ordinal value that you use to access an element is different than you would use to access an element in the all collection. Sometimes it is useful to know both ordinal values. The sourceIndex property for the element returns the ordinal position of the element in the document's all collection.

Accessing Element Properties

Many element properties are named-value pairs that correspond to the HTML attributes of the element and to other values associated with the element. You can get the value of a property to determine how the corresponding attribute is set, and in many cases change the value of this property to dynamically affect the element. This is the key concept behind manipulating dynamic styles and dynamic content. Accessing the properties that let you change styles and content is done by accessing the element object through the collections exposed in the document object model. For example, you can center an H1 element by accessing the H1 element through the all collection on the document and then setting its align property to "center", the same value you would use with the ALIGN= attribute.

var coll = document.all.tags("H1");
if (coll.length>0)
    coll(0).align="center";

Similarly, you can change the image file name for an IMG element by setting its src property.

var coll = document.all.tags("IMG");
if (coll.length>0)
    coll(0).src="newimage.gif";

Most properties have the same name and take the same values as the corresponding attribute. This means most properties take strings, enumerated values, or numeric values. If a property name is different from its corresponding attribute, it is usually fairly close to the attribute name. For example, the className property corresponds to the CLASS= attribute. Name changes are done to avoid conflicts with keywords in common scripting languages, or to make sure that property names don't contain characters that are invalid in common scripting languages.

A few properties represent sub-objects. For example, style corresponds to the STYLE= attribute and represents a sub-object that gives you access to all the CSS attributes that can be applied to the element as an inline style. The style object itself takes properties, which you can set to alter the look and formatting of the element. The following example uses the style object to change the CSS color attribute of all H1 elements to green.

var coll = document.all.tags("H1");
for (i=0; i<coll.length; i++)
    coll[i].style.color = "green";

Some properties do not correspond to element attributes. These properties typically give additional information about the element that isn't available through attributes. For example, the tagName property specifies the HTML tag name of the element, and the sourceIndex property specifies the position of the element in the document's all collection.

Although you can get and set the values of many properties, some properties are "read-only" in that you can get the values but not set or change them. For example, the tagName property is a read-only property—changing the tag name of an element is not permitted.

Sometimes an HTML document will have invalid attributes, or invalid values assigned to attributes. If an invalid value is assigned to an attribute, the corresponding property is always set to its default value. For example, in the following document, "middle" is not a valid value for the ALIGN= attribute, so the document displays the message "left", the default value for the align property.

<HTML>
<HEAD><TITLE>Elements: Using Properties</TITLE>
<SCRIPT LANGUAGE="JScript">
function showAlignment() {
    var coll = document.all.tags("H1");
    for (coll.length>0)
        alert("The alignment for the first heading is " + coll(0).align);
}
</SCRIPT>
</HEAD>
<BODY onload="showAlignment()">
<H1 ALIGN="middle">Welcome!</H1>
<P>This document is <B>very</B> short.
</BODY>
</HTML>

The getAttribute, setAttribute, and removeAttribute methods give you access to the attributes of an element without using properties. You supply an attribute name, and these methods return or set the current value of the attribute, or remove the attribute.

For example, you can get and set the current value of the ALIGN= attribute (rather than retrieve the align property) by using getAttribute and setAttribute as in the following document. The document displays the current value of the attribute ("left"), then changes that value to "center", centering the H1 element.

<HTML>
<HEAD><TITLE>Elements: Using Methods</TITLE>
<SCRIPT LANGUAGE="JScript">
function showAndSetAlignment() {
    alert(document.all.MyHeading.getAttribute("align"));
    document.all.MyHeading.setAttribute("align","center");
}
</SCRIPT>
</HEAD>
<BODY onload="showAndSetAlignment()">
<H1 ID=MyHeading ALIGN="left">Welcome!</H1>
<P>This a short document.
</BODY>
</HTML>

The attribute methods are especially useful when working with unrecognized attributes and invalid values. For example, if an attribute has an invalid value, the getAttribute method retrieves that exact value rather than the default value for the attribute. This means you can use the method to examine what is really in the HTML document and make decisions based on that. The following document uses the methods to repair the alignment of the H1 element ("middle" is not a valid value).

<HTML>
<HEAD><TITLE>Elements: Invalid Values</TITLE>
<SCRIPT LANGUAGE="JScript">
function checkValues() {
    if (document.all.MyHeading.getAttribute("align")=="middle")
        document.all.MyHeading.setAttribute("align","center");
    if (document.all.MyHeading.getAttribute("xyz")!="123")
        document.all.MyHeading.setAttribute("xyz","123");
}
</SCRIPT>
</HEAD>
<BODY onload="checkValues()">
<H1 ID=MyHeading XyZ="123" ALIGN="middle">Welcome!</H1>
<P>This is a short document.
</BODY>
</HTML>

By default, these attribute methods are case insensitive when looking for an unknown attribute. So in the example above, even though "xyz" isn't identical to "XyZ", the methods get and set the attribute anyway. You can force the methods to search for an exact match by setting the optional case-sensitive parameter to true. For example, the following code, if placed in the previous example, displays "Not found" because "xyz" does not match "XyZ".

if (document.all.MyHeading.getAttribute("xyz", true)==null)
    alert("Not found");

If multiple matches are found for a case-sensitive usage of these methods, the actual item returned is not guaranteed to be consistent across platforms.

Examining the Element Hierarchy

The elements of an HTML document form a hierarchy in which some elements contain others. The HTML element, at the top of the hierarchy, contains all other elements in the document. The BODY element, contained by HTML, represents the document. Block elements, such as P, contain text and inline elements, which can themselves contain text and inline elements, and so on.

You can examine this structural hierarchy by using the contains method and the parentElement property. The all collection and the children collection (discussed previously) for each element can also help determine the document structure.

The contains method returns either true or false to indicate whether one element contains another. You apply the method to an element and supply another element as the parameter. For example, the following document displays the message "True!" because the BODY element contains P.

<HTML>
<HEAD><TITLE>Elements: Hierarchy</TITLE>
<SCRIPT LANGUAGE="JScript">
function showContains() {
    var el = document.all.tags("P").item(0);
    if (document.body.contains(el))
        alert("True!");
    else
        alert("False!");
}
</SCRIPT>
</HEAD>
<BODY onload="showContains()">
<P>This is a very simple document.
</BODY>
</HTML>

Note in the example above that the body property of the document object is used to retrieve the BODY object.

The parentElement property always identifies the next element in the hierarchy that contains the element. You can combine contains and parentElement in a more complicated script to determine the hierarchy of the elements document. The following document uses these to determine the hierarchy, then it displays a message that shows the hierarchy.

<HTML>
<HEAD><TITLE>Elements: Hierarchy</TITLE>
<SCRIPT LANGUAGE="JScript">
function showHierarchy() {
    var depth = 0;
    var msg = document.all(0).tagName;
    for (i=1; i<document.all.length; i++) {
        if (document.all(i-1).contains(document.all(i))==true) {
            depth = depth + 1;
        } else {
            var elParent = document.all(i-1).parentElement;
            for ( ; depth>0; depth--) {
                if (elParent.contains(document.all(i))==true)
                    break;
                elParent = elParent.parentElement;
            }
        }
        msg = msg + "\n";
        for (j=1; j<=depth; j++)
            msg = msg + "  ";
        msg = msg + document.all(i).tagName;
    }
    alert("This document contains:\n" + msg);
}
</SCRIPT>
</HEAD>
<BODY onload="showHierarchy()">
<H1>Welcome!</H1>
<P>This document is <B>very</B> short.
</BODY>
</HTML>

Getting an Element's Position and Dimensions

You can determine the location, width, and height of an element by using the offsetLeft, offsetTop, offsetHeight, and offsetWidth properties. These numeric properties specify the physical coordinates and dimensions of the element relative to the element's offset parent. For example, the following document is a simple clock that adjusts the size of its readout to fit the current width and height of the document body.

<HTML>
<HEAD><TITLE>A Simple Clock</TITLE>
<SCRIPT LANGUAGE="JScript">
function startClock() {
    window.setInterval("Clock_Tick()", 1000);
    Clock_Tick();
}

var ratio = 4;
function Clock_Tick()
{
    var s = Date();
    var t = s.substring(11,19);
    var doc_height = document.body.offsetHeight;
    var doc_width = document.body.offsetWidth;

    if ((doc_height*ratio)>doc_width)
        doc_height = doc_width / ratio;
    document.all.MyTime.innerText = t;
    document.all.MyTime.style.fontSize = doc_height;
}
</SCRIPT>
</HEAD>
<BODY onload="startClock()">
<P ID="MyTime">&nbsp;</P>
</BODY>
</HTML>

The offsetLeft and offsetTop property values are relative to the element specified by the offsetParent property for the element. Most of the time the property returns BODY. For example, in the following document, even though the TD element appears to the far right in the document, its position is (0,0) because its offset parent is the TR, not the document body.

<HTML>
<HEAD><TITLE>Elements: Positions</TITLE>
<SCRIPT LANGUAGE="JScript">
function showPosition() {
    var el = document.all.MyID;
    alert("The TD element is at (" + el.offsetLeft + "," + el.offsetTop + ")\n" +
        "The offset parent is " + el.offsetParent.tagName );
}
</SCRIPT>
</HEAD>
<BODY onload="showPosition()">
<P>This document contains a right-aligned table.
<TABLE BORDER=1 ALIGN=right>
<TR><TD ID=MyID>This is a small table
</TABLE>
</BODY>
</HTML>

Scrolling Elements into View

Another useful method is scrollIntoView. This scrolls the element into view within the window, placing it at either the top or bottom of the window. The method is useful for immediately showing the user the result of some action without requiring the user to manually scroll the document to find the result. The following example underlines the content of the fifth paragraph and scrolls it into view at the top of the window.

var coll = document.all.tags("P");
if (coll.length>=5) {
    coll(4).style.textDecoration = "underline";
    coll(4).scrollIntoView(true);
}


Understanding the Event Model

An event is a notification that occurs in response to an action, such as a change in state or as a result of the user clicking the mouse or pressing a key while viewing the document. An event handler is code, typically a function or routine written in a scripting language, that receives control when the corresponding event occurs. The following topics describe events and event handlers and explain how to use them in your documents.

The Life Cycle of an Event

Attaching an Event Handler

More About Event Bubbling

Returning Values and Canceling Default Actions

Event Handler Scoping

Event Object

Keyboard Events

Mouse Events

Focus and Selection Events

Load and Readystate Events

Other Events

The Life Cycle of an Event

An event has a life cycle that begins with the action or condition that initiates the event and ends with the final response to the event by an event handler or Internet Explorer. The life cycle of a typical event has these steps:

  1. The user action or condition associated with the event occurs.
  2. The event object is instantly updated to reflect the conditions of the event.
  3. The event fires. This is the actual notification in response to the event.
  4. The event handler associated with the source element is called. The event handler carries out its actions and returns.
  5. The event bubbles up to the next element in the hierarchy, and the event handler for that element is called. This step repeats until the event bubbles up to the window object or a handler cancels bubbling.
  6. The final default action (if any) is taken, but only if this action has not been canceled by a handler.

For events that bubble, if there is no event handler bound to the source element, the event handler for the next element up the hierarchy is called.

When an event handler carries out its actions, it uses the event object to retrieve information about the event, such as the position of the mouse, the state of the keyboard keys, the element in which the event occurred, and so on.

The following example defines an event handler, named "wasClicked", for the onclick event and associates it with the BODY element. When the user clicks the mouse button anywhere in this document, the event fires and the event handler displays the message "I was clicked", followed by the tag name of the element in which the event occurred.

<HTML>
<BODY onclick="wasClicked()">
<H1>Welcome!</H1>
<P>This is a very <B>short</B> document.
<SCRIPT LANGUAGE="JavaScript">
function wasClicked() {
    alert("I was clicked " + window.event.srcElement.tagName);
}
</SCRIPT>
</BODY>
</HTML>

The srcElement property of the event object specifies the element object in which the event occurred. This is useful for deciding what action the event handler should take in response to the event.

Attaching another event handler, "wasAlsoClicked", to the P element demonstrates the parent-child relationship of document elements.

<HTML>
<BODY onclick="wasClicked()">
<H1>Welcome!</H1>
<P onclick="wasAlsoClicked()">This is a very <B>short</B> document.
<SCRIPT LANGUAGE="JavaScript">
function wasClicked() {
    alert("I was clicked " + window.event.srcElement.tagName);
}
function wasAlsoClicked() {
    alert("You clicked me " + window.event.srcElement.tagName);
}
</SCRIPT>
</BODY>
</HTML>

As in the previous example, if the user clicks in the heading "Welcome!", the message "I was clicked H1" appears. But if the user clicks the word "short", two messages appear: "You clicked me B" followed by "I was clicked B". In the first instance, the click in "Welcome!" fires the onclick event, setting the H1 element as the source element of the event. There is no event handler for this element, so the event bubbles up to its parent element in the hierarchy, BODY, and its event handler, wasClicked, is called.

In the second case, when the user clicks in the word "short", the onclick event fires again. This time the B element is set as the source element. Since there is no event handler for B, the event bubbles up to the P element and its event handler, wasAlsoClicked, is called. But that's not the end of the event. After wasAlsoClicked returns, the event continues to bubble up the hierarchy to the next parent element, BODY, causing wasClicked to be called.

In some cases, you might not want the event to bubble up in the hierarchy. You can stop bubbling by setting the cancelBubble property of the event object to true in any event handler. After the handler returns, the event stops bubbling and comes to an immediate end. Note that this cancellation affects only the current event, not subsequent events. Subsequent events will bubble unless you explicitly cancel them.

Consider the following document. It defines two event handlers, setBodyStyle and setParaStyle, that are called when the user clicks in the document or in the paragraph, respectively. To ensure that only the style for the paragraph changes when the user clicks in the paragraph, the setParaStyle handler uses cancelBubble to prevent the event from bubbling up to BODY.

<HTML>
<BODY onclick="setBodyStyle()">
<H1>Welcome!</H1>
<P onclick="setParaStyle()">This is a very <B>short</B> document.
<SCRIPT LANGUAGE="JavaScript">
function setBodyStyle() { // Set all headings to green
    var coll = document.all.tags("H1");
    for (i=0; i<coll.length; i++)
        coll.item(i).style.color = "green";
}
function setParaStyle() { // Underline the paragraph
    var el = window.event.srcElement;
    while ((el != null) && (el.tagName != "P")) {
        el = el.parentElement;
    }
    if (el != null) el.style.textDecoration = "underline";
    window.event.cancelBubble = true;
}
</SCRIPT>
</BODY>
</HTML>

Notice that the above example does not automatically assume that the source element is P. Because the user might have clicked in the B element, the event handler must check the element before applying the style. In this case, the handler uses the parentElement property to move up the element hierarchy until the P element is found.

Attaching an Event Handler

You must associate an event handler to a specific event and specific element or object in order for the handler to be called when the event fires. You can associate an event handler by using any one of the following, essentially equivalent, methods.

Declare an event handler function and assign a call to that function in the appropriate inline event attribute of an HTML tag. For example, the following defines the JScript function named "flip" and associates it to the IMG element as the event handler for the onmouseover event.

<SCRIPT LANGUAGE="JavaScript">
function flip() {
    // Carry out some work
}
</SCRIPT>
    .
    .
    .
<IMG SRC="sample.gif" onmouseover="flip()">

This example shows an event handler function being bound; however, any expression can be used here to be evaluated each time the event fires. Note that since this is an expression, the parentheses following the function name are required.

Declare event handling code and use the FOR= and EVENT= attributes of the SCRIPT tag to associate the code with the event. The following example also defines JScript code and associates it as the onmouseover event handler for the IMG element having the identifier "MyImage".

<SCRIPT FOR=MyImage EVENT=onmouseover LANGUAGE="JavaScript">
    // Carry out some work
</SCRIPT>
    .
    .
    .
<IMG ID=MyImage SRC="sample.gif">

Declare an event handler function in VBScript and associate it with an event by giving it a name having this form: id_event. The following example defines a VBScript function that handles the IMG element as its onmouseover event handler.

<SCRIPT LANGUAGE="VBScript">
Function MyImage_onmouseover
    ' Carry out some work
End Function
</SCRIPT>
    .
    .
    .
<IMG ID=MyImage SRC="sample.gif">

As a general rule, you should always define and associate your event handlers as early in the document as possible. Depending on the method you use, the handler can begin handling events either while the document is loading or immediately after loading, as shown in the following list.
JScript event handler | When set using an inline event attribute, associates when the element is created.
FOR= and EVENT= event handling code | Associates when the document is fully loaded.
VBScript event handler | Associates when the document and all contained objects and applications have been loaded.

Some events can occur while the document is loading. If you need to handle events at this time, you can use JScript and an inline event attribute to associate the handler when the element is created.

You can associate the same event handler with more than one element in the document. This is useful if you want the same action to occur whenever the given event occurs in any of the elements. Typically, event handlers are written to handle only one type of event, but it is possible to create event handlers that can handle more than one.

You don't have to limit yourself to one event handler for each type of event. If the action you want to occur for a given event in one element is different than for the same event in another element, you can define two event handlers and associate each to its appropriate element. In general, you can define any number of event handlers for the same type of event and associate each with one or more elements in the document.

If you use a combination of handling methods in a document, you can also define more than one event handler for the same event in the same element. For example, you can declare both a JScript and a VBScript event handler and associate them both with the same event and element. If you associate more than one event handler in this way and the handlers are in different languages, all handlers will receive the event, but the order in which they receive the event is not specified.

If you associate two event handlers of the same language to the same event and element, only one handler receives the event. In most cases, this will be the first handler that you bound to the element. But any handler associated using the FOR= and EVENT= attributes always takes precedence over a handler associated using an inline event attribute.

When you associate with an inline attribute, you typically assign to the attribute a call to the event handler function, causing that function to be called when the event fires. But assigning a call to an event handler is not a requirement. You can instead assign any valid script code; this code is executed when the event fires. For example, the following BUTTON element displays the message "Hello World!" when you click it.

<BUTTON onclick="alert('Hello World!')" LANGUAGE="JavaScript">Click Me</BUTTON>

This method is convenient as long as the code is relatively short and uncomplicated. If you use an inline attribute in this way, you should also use the LANGUAGE= attribute to specify the scripting language for the code. If you don't specify the language, either the default language or the most recent language specified is assumed.

Attaching with Event Properties

The inline event attributes of an element are also available as properties. This means you can use the properties to dynamically change the event handling for an element at any time. For example, you can associate a handler to an element that didn't previously have one, or change the existing handler for an element to some other handler. Adding or changing event handlers is a useful way to make sure that the actions taken on an event reflect the current content of the element.

The following JScript example use the event property to associate the event handler, named setHeadStyle, to the H1 element. It assigns a call to the function to the onclick property of the element.

<H1 id=MyHeading>Welcome!</H1>
    .
    .
    .
<SCRIPT LANGUAGE="JavaScript">
function setHeadStyle() {
    window.event.srcElement.style.color = "green";
}

document.all.MyHeading.onclick="setHeadStyle()";
</SCRIPT>

An alternate way to associate the event handler is to assign the function pointer (rather than a function call) to the property as in the following example. VBScript does not support function pointers.

document.all.MyHeading.onclick=setHeadStyle;

Handling Custom Events or Events with Parameters

Using the FOR= and EVENT= attributes to associate events gives you access to custom events fired by embedded objects and to any parameters that an event generates. Unlike standard events that can be bound using attributes or properties, in the case of custom objects these are not available.

You use the FOR= attribute to specify which element or object to handle, assigning it an identifier or the name of an object, application, or control. If there is more than one element or object having the same identifier or name, only the first one is bound to the handler. Names take precedence over identifiers. If you don't specify this attribute, the handler is bound to the window by default. Note that JScript is case sensitive, so you must type the identifier or name exactly as it appears in the corresponding element or object.

You use the EVENT= attribute to specify which event to associate to, assigning it an event name. If the event generates parameters (few predefined events do), you can also specify a list of comma-separated parameter names enclosed in parentheses immediately after the event name. The parameters are untyped. Because JScript is case sensitive, make sure you always spell event names in lowercase letters. Also, if you give a parameter list, VBScript requires that all parameters defined for the event be listed, even if they are not used.

The following JScript example associates the event handling code with the onerror event for the window. This event fires when an error while loading the document is detected. The event generates parameters, so a parameter list is given, and the "lineno" parameter is used in the code.

<SCRIPT FOR=window EVENT="onerror(message, url, lineno)" LANGUAGE="JavaScript">
alert("An error has occurred on line " + lineno);
</SCRIPT>

The following JScript example associates the event handling code with a custom event, named "ondatechange", that the embedded object fires.

<OBJECT ID=myDateObject ... ></OBJECT>
<SCRIPT FOR=myDateObject EVENT="ondatechange()" LANGUAGE="JavaScript">
    // Carries out an action when the date changes
</SCRIPT>

An alternate way to handle custom events and to receive event parameters is to associate VBScript handlers. In this case, you use VBScript's id_event format for the event handler name and provide a parameter list if appropriate. The following VBScript example handles the onerror event and receives its parameters.

<SCRIPT LANGUAGE="VBScript">
Function window_onerror(message, url, lineno)
    alert "An error has occurred on line " & lineno
End Function
</SCRIPT>

Similarly, the following VBScript example handles the custom event, ondatechange, fired by the embedded object.

<OBJECT ID=myDateObject ... ></OBJECT>
<SCRIPT LANGUAGE="VBScript">
Function myDateObject_ondatechange()
    // Carries out an action when the date changes
End Function
</SCRIPT>

More About Event Bubbling

Event bubbling ensures that the event handlers for all elements in which an event occurs have an opportunity to respond to the event. Consider the following example.

<P onclick="doPara()">
Jump to a <B>sample</B> document.
</P>

The user might reasonably expect that clicking the word "sample" will cause the same action, a call to the event handler named "doPara", as clicking any other word in the P element. But if events did not bubble up from the source element, clicking "sample" would cause no action because there is no event handler bound to the B element. Because events do bubble up through the element hierarchy, every event handler on the element's parent hierarchy has a chance to respond, and in this case "doPara" is called when the user clicks "sample".

Unless you keep event bubbling in mind, you might initially be baffled by some results. For example, consider a document that uses onmouseover and onmouseout events to show and hide a collection of paragraphs, but also uses the events inside the list to highlight paragraphs in the collection.

<DIV onmouseover="showPara()" onmouseout="hidePara()">
My Menu
<P STYLE="display:none" onmouseover="highlight()" onmouseout="unhighlight()">Item 1
<P STYLE="display:none" onmouseover="highlight()" onmouseout="unhighlight()">Item 2
</DIV>

In the example above, suppose the user moves the mouse over the words "My Menu", then over the words "Item 1", and finally over the words "Item 2". Here's what happens:

  1. The mouse cursor moves over "My Menu".
  2. The onmouseover event fires for the DIV element, and "showPara" is called.
  3. The mouse cursor moves from "My Menu".
  4. The onmouseout event fires for the DIV element, and "hidePara" is called.
  5. The mouse cursor moves over "Item 1".
  6. The onmouseover event fires for the P element, and "highlight" is called.
  7. The onmouseover event bubbles up to the DIV element, and "showPara" is called with P as the source element.
  8. The mouse cursor moves from "Item 1".
  9. The onmouseout event fires for the P element, and "unhighlight" is called.
  10. The onmouseout event bubbles up to the DIV element, and "hidePara" is called with P as the source element.
  11. The mouse cursor moves over "Item 2".
  12. The onmouseover event fires for the P element, and "unhighlight" is called.
  13. The onmouseover event bubbles up to the DIV element, and "showPara" is called with the second P as the source element.

As you can see, whenever the user moves the mouse over and from a paragraph in the collection, the event handlers for DIV are called. If the handlers were written without taking this into account, the paragraphs might be hidden when they should not be.

In general, whenever you use nested event handlers in this way, you need to carefully consider whether the event handler should carry out an action each time it is called. One way to control the action is to use the cancelBubble property. In the previous example, the "highlight" and "unhighlight" event handlers could set cancelBubble to true to prevent the event from bubbling up to the DIV element. Another way is to check the source element for the event, the srcElement property of the event object, and pick an action that is appropriate to that element.

Returning Values and Canceling Default Actions

Event handlers can return values to the event either by using the return value mechanism defined for the language, such as the return statement for JScript, or by using the returnValue property of the event object.

Return values are useful for controlling the default actions associated with events. For example, clicking the A element causes the browser to load the document specified by the href attribute. You can cancel default actions such as these by returning false from your event handlers.

Not all scripting languages support return values. For these languages, you must use the returnValue property to set a return value. If a language supports return values, you can use either the language-defined method of returning a value or returnValue. If you use both methods, the property always takes precedence.

After all event bubbling is complete, any default action associated with the event is canceled if returnValue is false or, if this property is not set, the return value of the last function is false. Note that some events do not have default actions associated with them and might use the returnValue (or function return value) in other ways.

Canceling a default action is not the same as canceling event bubbling. You can cancel the default action and still allow the event to bubble up through the hierarchy.

Event Handler Scoping

Depending upon whether a script is written inside a FORM container or elsewhere in the document, different scoping rules are applied for executing event handlers and the elements that are available on the window object. The different scenarios are listed below.

When events are fired, a special object reference—the me pointer in VBScript and this in JScript—is set to the current element firing the event.

1) Event handler for a button outside a form

This is the basic case. You can use any of the handling mechanisms described earlier. The only rule is that you cannot access elements within a form block directly on the window object. Instead, you can access them from the document object or the particular form's elements collection.

2) Event handler not inside the FORM block for a button inside a form

If the button has a unique identifier to the entire document, the event handler can be written anywhere within the document. If the event handler is written outside the form block, the same rules apply for accessing elements on the window object as described in 1) above.

3) Event handler inside the FORM block for a button inside the form

If the button's identifier is not unique to the document, the event handler must be written within the form. When writing event handlers behind the form, using either inline attributes or the FOR= and EVENT= attributes (but not the VBScript id_event method) changes the scoping rules of the window object. Events defined this way can access elements behind the form directly from the window object. They can also access elements that are outside the form directly as long as they do not conflict with any of the form's element names.

When using the VBScriptid_event method of handling, only elements that are not within the form's scope can be accessed as properties of the window.

If there is no unique identifier within the form, the first element with the matching identifier is bound to the event handler when using the FOR= and EVENT= attributes of the SCRIPT element or the VBScript id_event mechanism of defining events.

4) Event handler inside the FORM block for a button outside the form

The event handler executes only if the VBScript id_event method of handling is used. Otherwise this code will not execute.

You can write an event handler for multiple elements. This can be done only when the elements are not within the same scope, where scope is defined as being inside the form or not inside the form. For example, if writing an event handler for id=genericButton in the document's scope, and adding a genericButton to the document and another within a form, the same click event is fired in both cases. The me pointer will point to the actual source of the event. These elements do not have to be of the same type for this to work.

If multiple elements have the same identifier and are within the same scope, only the first one fires the event.

Event Object

The event object, on the window object, is accessible to all event handlers and is the language-independent, preferred way for handlers to get and modify information about the event. For example, the following VBScript and JScript examples both use the object to display the tag name of the element in which the event occurred.

<SCRIPT LANGUAGE="VBScript">
Function document_onclick
    alert window.event.srcElement.tagName
End Function
</SCRIPT>

<SCRIPT LANGUAGE="JavaScript">
function doClick() {
    alert(window.event.srcElement.tagName);
}
</SCRIPT>

Note In VBScript, you must use the window keyword with event to avoid a conflict with the VBScript event keyword.

The srcElement property is one of the most important properties on event. Many event handlers use this property to determine an action to take based on the source of the event. For example, the following JScript event handler carries out an action whenever the user clicks any of the H1 elements in the document.

<SCRIPT FOR=document EVENT="onclick()" LANGUAGE="JavaScript">
    if ("H1" == event.srcElement.tagName) {
        // user clicked on a H1
    }
</SCRIPT>

Another important property is cancelBubble, which controls event bubbling for the given event and, if set to true, prevents the event from bubbling up the element hierarchy.

The returnValue property gives an event handler a language-independent way to return a value to the event. For many events, setting the return value to false cancels the default action for that event.

Some properties of the event object have meaning only for certain events. For example, the keyCode property is an integer specifying a standard numeric Unicode keycode for keyboard key events. For other events, this property is set to zero. Other examples are the toElement and fromElement properties, which represent the element that the mouse is going to and coming from for the onmouseover and onmouseout events. For other events, these properties are null.

When a mouse event occurs, such as onclick, the x and y properties specify the horizontal and vertical position of the mouse. If none of the elements containing the source element are positioned, the position of the mouse is relative to the BODY element. If a positioned element contains the source element, the position of the mouse is relative to that element. In addition to mouse position, the button property indicates which mouse buttons are pressed at the time of the event. It is 0 if no buttons are pressed, 1 for the left button, 2 for the right, and 3 for both.

The altKey, ctrlKey, and shiftKey properties are useful for all events. These specify whether the ALT, CTRL, and SHIFT keys were down or up at the time of the event. The property is true if the key was down. The following VBScript example cancels the default action for the A element if the SHIFT key is down when the event occurs.

<SCRIPT FOR=document EVENT="onclick()" LANGUAGE="VBScript">
    If (("A" = window.event.srcElement.tagName) and (window.event.shift)) Then
        event.returnValue = false
    End If
</SCRIPT>

The clientX and clientY properties are integers specifying the coordinates relative to the size of the client area, not including window decorations. The offsetX and offsetY properties are integers specifying container relative positions. These match the offsetTop and offsetLeft properties of the element. Use the offsetParent property to find the container that defines this positioning. The screenX and screenY properties are integers specifying the coordinates relative to the physical screen.

Note that properties such as returnValue and keyCode are read/write properties. This means an event handler can assign a new value to the property, overwriting the original value. The property retains this new value as the event bubbles up the element hierarchy. This makes it easy for an event handler bound at a low level in the hierarchy to modify events that are also handled at a higher level.

The event object gives you detailed information about where in the document an event occurs, so it is easy to write an event handler that can adapt its action based on the source of the event. If you associate the event handler on an element or object that contains all the elements in which the event might occur, event bubbling will ensure that the handler is called whenever the event occurs. This means you don't need to associate the event handler to each element.

Keyboard Events

Keyboard events occur when the user presses or releases a keyboard key. The onkeydown and onkeyup events fire when a key changes state, either being pressed (down) or released (up). These events fire for all keys on the keyboard, including shift state keys such as SHIFT, CTRL, and ALT.

The onkeypress event fires when the user's keyboard input is translated to a character. These occur, for example, when the user presses letter or number keys, or a combination of shift keys and letters and numbers.

When a keyboard event occurs, the keyCode property of the event object contains the Unicode keycode of the corresponding key. The altKey, ctrlKey, and shiftKey properties specify the state of the ALT, CTRL, and SHIFT keys.

You can change which key is associated with the event by either changing the value of the keyCode property or returning an integer value. You can cancel the event by returning zero or false.

The onhelp event is a special keyboard event that occurs when the user presses the help key (F1).

Mouse Events

Mouse events occur when the user moves the mouse or clicks the left button. The onmousemove event fires when the user moves the mouse, and onmouseover and onmouseout fire when the mouse moves in and out of an element. The onmousedown and onmouseup events fire when the left mouse button changes state, either being pressed (down) or released (up). The onclick and ondblclick events fire when the user single-clicks and double-clicks the button.

When a mouse event occurs, the button property of the event object identifies which mouse button (if any) is down. The x and y properties specify the location of the mouse at the time of the event. For the onmouseover and onmouseout events, the toElement and fromElement properties specify the elements the mouse is moving to and from.

Mouse Clicks

The onclick event fires when the user presses and releases the button. The ondblclick event occurs when the elapsed time between two consecutive onclick events is within a system-defined range.

Mouse click events are interspersed with onmousedown and onmouseup events. For example, the onclick event follows an onmouseup event. The ondblclick event occurs at the end of this sequence:
onmousedown
onmouseup
onclick
onmouseup
ondblclick

An onclick event can also occur when the user presses the ENTER key on a focusable element, such as a BUTTON element. In this case, the event fires without a preceding onmouseup event.

You can cancel a mouse click by returning false or setting the returnValue property to false.

Note For mice that have one button, the button is considered the left mouse button.

Moving Between Elements

The onmouseover and onmouseout events fire whenever the mouse cursor moves from one element to another. Consider the following document fragment.

<H1>Move from here</H1>
<P id=myP><B><I>To here</I></B></P>

In the above example, as the mouse moves from the H1 element to the words "To here", it crosses over the boundaries of the P, B, and I elements. However, the event sequence is simplified to the following: onmouseout on the H1 (which bubbles up the hierarchy), and onmouseover on the I element (again bubbling up the hierarchy).

The fromElement and toElement properties on the event object return the element object the mouse is coming from and going to. Through event bubbling, it is possible to determine each boundary that has been crossed by the mouse move.

When moving between elements, the onmouseout event fires first to indicate that the mouse has left the original element. Next the onmousemove event fires, indicating that the mouse has moved. Finally, onmouseover fires to indicate that the mouse has entered the new element.

Focus and Selection Events

The focus and selection events give you detailed information about what actions the user is taking in the document.

The focus events occur on elements such as BUTTON and various types of INPUT that can receive the input focus. For these elements, the onfocus event fires when an element receives the focus, and the onblur event fires when an element loses the focus. An element receives the input focus when the user clicks it with the mouse or navigates to it using the keyboard. These events are useful for knowing when to prepare an element to receive input from the user.

Note that the focus events fire whether moving the input focus between elements in the document or between frames in the window or even applications on the desktop. For example, if a control in the document has the focus and the user switches to another application, the onblur event fires for that control. When the user switches back to the document, the onfocus event fires. It is not possible to cancel the loss of focus.

The selection events occur when the user selects a portion of the document by using the mouse or keyboard. The onselectstart event fires when a selection is first initiated, for example, when the user clicks a character or object in the document. The onselect event fires when the user changes the selection, for example, by moving the mouse over a portion of the document while holding down the mouse button. The default action for the onselectstart event is to move the selection to the given character or object and highlight that selection. You can cancel this default action by returning false.

The ondragstart event fires when the user first begins to drag the selection. The user can drag a selection by holding down the mouse button on the current selection and moving the mouse. The default action for this event is to prepare the selection to be copied to another element. You can cancel this default action by returning false.

Load and Readystate Events

There are three events that signify the current state of the document: onreadystatechange, onload, and onunload.

The onreadystatechange event fires when the document changes from initializing to interactive, and from interactive to loaded. A document is interactive as soon as the user can interact with it by scrolling or clicking on anchors or elements. A document is loaded when all the content has been downloaded.

The onload event fires after the document is loaded and all the elements on the page have been completely downloaded. The onunload event fires immediately prior to the document being unloaded (when navigating to another document).

Specifying code for the onload and onunload events can be done on the body object. However, these events actually occur on the window. Therefore, when handling the onload event using the <SCRIPT FOR= EVENT=> syntax, <SCRIPT FOR=myBody Event=onLoad> will fail. Instead, you must use <SCRIPT FOR=window Event=onLoad>.

Other Events

There are a number of other useful events that you can use in your document. For a complete list, see the Events reference.


Cross-Frame Scripting and Security

With Dynamic HTML, content in different windows and frames can interact in powerful ways by scripting with the object model. However, since it is possible for a browser to simultaneously display unrelated documents in its various windows and frames, certain rules must be enforced to protect data integrity and privacy of information.

This section describes how and why these restrictions apply in the DHTML object model. All rules about script interaction apply equally to windows, dialog boxes, FRAMESETs, FRAMEs, and IFRAMEs.

For most content, only interactions with content from the same domain are allowed. For example, a typical page on http://www.microsoft.com/ can freely script content on any other page on http://www.microsoft.com/ but cannot script to pages that are located on a different Web domain. The DHTML object model uses the document.domain property to enforce this restriction: only pages with identical domain properties are allowed free interaction. The protocol of the URL must also match. For instance, an HTTP page cannot access HTTPS content.

The range of permissible access for a page can be expanded when a script assigns the document.domain property to a suffix of the site name space, up to the second-level domain. For example, a page on http://www.microsoft.com/ can assign the document.domain property—initially "www.microsoft.com"—to be "microsoft.com" to broaden access to include pages in http://home.microsoft.com or any other site, as long as the other pages also set the document.domain property to the identical value. Since only pages from a site whose name ends with "microsoft.com" will permit this domain to be set, it is assured that content from the same provider mutually agrees to interact and is free to do so. Domain suffixes shorter than the second-level domain (such as just "com") are disallowed because they expose beyond a single provider. For international site names such as http://www.microsoft.co.jp/, the second-level domain for widest access would be "microsoft.co.jp" (not "co.jp").

Since it is important to be able to navigate windows or frames to any URL beyond the domain restriction, these types of accesses are always permitted. Only access that attempts to read-out or modify content is restricted. For instance, the window.location might be assigned to cause navigation to occur, but this property cannot be read if the URL is of a different domain. This would allow one page to learn where the user has been browsing, and to allow this is a breach of the user's privacy. Some restrictions that apply to pages of different domains include:
window.location | Property can be set to navigate, but cannot read.
Other location | Functionality is blocked.
document.href | Property can be set to navigate but cannot read.
Other document | Functionality is blocked.
<IFRAME> | src property can be set to navigate but cannot read

Scripts that attempt to access parts of the object model to which they do not have access will be blocked with a "permission denied" error.

While domain security can prevent certain types of content interaction, it is important to understand that this restriction is necessary to ensure security. For example, without domain security, a rogue page could "snoop" on other pages or, using DHTML, manipulate its content.

For more information, see Asynchronous and URL Monikers Overview.


DHTML Accessibility

Writing Accessible Dynamic HTML with Internet Explorer 4.0

Because traditional HTML describes the structure as well as the content of a Web page, it has been easy in the past to create tools that make Web pages largely accessible to people with disabilities. Dynamic HTML gives Web pages many more capabilities, including enhanced support for accessibility. Authors writing interactive Dynamic HTML pages can ensure that their Web pages remain accessible for all people by following a few simple tips.

What Is an Accessible Web Page?

Accessibility problems arise in the interaction between the user and the Web page. The problems involve difficulty either in viewing the content of the page—for example, blindness or low vision—or in providing input to interact with the page—the most common being the inability to maneuver a mouse. Web pages are accessible if they allow alternate methods for both viewing the page and providing input to the page.

The first requirement for accessibility is that the page can be represented nonvisually. Programs called screen readers are used in conjunction with Microsoft® Internet Explorer to represent the page to the user through a sense other than sight, such as sound (voice synthesizer) or touch (Braille). A second requirement for accessibility is that the Web page allows keyboard/alternative-input access to all parts of the page that can be clicked by the mouse.

Internet Explorer, by taking advantage of HTML's structural nature, makes most Web pages accessible automatically. For example, the A tag indicates which areas on the page can be clicked, so Internet Explorer automatically allows the user to tab to any A tag. The A tag also encloses text that Internet Explorer can provide to a screen reader, which can in turn use the text to describe the link to the user.

There are some potential difficulties, however, that can hinder the ability of Internet Explorer to expose a Web page in an accessible manner. Implementing the following tips helps avoid these problems.

Tip#1: Use A tags for all textual areas on the page that respond to a mouse click

Although you can associate a click event with nearly any text element using Dynamic HTML, for accessibility reasons this should be done only on A tags. This allows the keyboard user to navigate to these areas using the keyboard and also gives hints that allow screen readers to know which parts of the Web page are interactive. An additional benefit to using the A tag to denote areas that can be clicked is that the mouse cursor automatically changes to the "hand" cursor when hovering over these areas.

A tags normally navigate to another Web page or bookmark when clicked. To avoid this, set the returnValue property of the window.event object equal to FALSE in the script that runs when the anchor is clicked. This causes the default action (navigating) to be canceled.

To run a specific Visual Basic® Scripting Edition (VBScript) function when an A tag is clicked, use the following syntax:

<A HREF="" ID=anchor1>Click here</A>
<SCRIPT LANGUAGE=vbscript>
function anchor1_onclick

    msgbox "you clicked on anchor1"
    window.event.returnValue=FALSE

end function
</SCRIPT>

Tip #2: Use the LABEL tag to associate text with intrinsic controls

In the HTML 3.2 specification, there was no way for an author to associate text with an intrinsic control such as a radio button or text box. Unlike an A tag, which has an accompanying /A tag and encloses text, the INPUT tag does not have an /INPUT tag. Therefore, screen readers have a difficult time finding exactly what text to use to describe the control to the user. HTML 4.0 introduces the LABEL tag, which allows the author to associate text with another HTML element. This is particularly useful for associating text with intrinsic controls. Whenever an intrinsic control is used on a page, it should be accompanied by a LABEL tag containing its associated text. Doing so provides an additional benefit: clicking the label toggles the value of the associated intrinsic control.

To associate a LABEL tag with a radio button, use the following HTML syntax:

<FORM>
<INPUT TYPE=radio ID=FirstButton NAME=radio1>
  <LABEL FOR=FirstButton>I'm the text for the first radio button</LABEL><BR>
<INPUT TYPE=radio ID=SecondButton NAME=radio1>
  <LABEL FOR=SecondButton>I'm the text for the second radio button</LABEL>
</FORM>

Tip #3: Always assign values for the TITLE attribute of items such as AREA or BGSOUND

The HTML 4.0 TITLE attribute allows the author to specify additional descriptive information about an HTML tag. This capability is particularly important for elements that do not normally have textual information associated with them, such as the AREA tag, which is used to designate a region of an image map, and the BGSOUND tag, which specifies a sound file to play in the background for a Web page. The TITLE attribute should always be used when dealing with these tags. For example:

<BGSOUND SRC="soundfile.mid" TITLE="Sound of falling water">

Tip #4: When using CSS positioning, be sure to specify your coordinates in "em" units

An important part of IE 4.0's Dynamic HTML, CSS positioning allows you to specify exactly where you want an HTML element to appear on the screen. Problems can arise, however, if the user changes the default font size or overrides the font sizes on a Web page. In that case, absolutely positioned elements can increase in size and overlap unless they are created properly. Specifying the position of objects using "em" units helps to solve this problem. Ems are measurement units like inches or pixels, except that they change based upon the default font size. In other words, when the default font size goes up, the value of one em increases as well. Content positioned and sized in ems correctly adjusts for the increased font size.

For example, to specify a <DIV> tag that is absolutely positioned, you can use the following syntax:

<DIV STYLE="position: absolute; left: 10em;top: 12em;height: 5em; width: 5em">Here is some positioned text!</DIV>

Ems tend to be quite large units compared to something like pixels. A good rule of thumb is that 1 em is roughly equivalent to 10 pixels for the standard font size.

Tip #5: Test positioned HTML for accessibility

Here are some test cases for the accessibility of positioned objects. When creating pages that use HTML elements positioned in ems, try changing between the Windows display settings for font size to both "Small Fonts" and "Large Fonts." Also, go to the Accessibility options in the Internet Options dialog and choose "Ignore Font sizes specified on web pages." Then set IE's font size on the View menu to "Largest." A final test is to turn on "High Contrast" mode on the Display tab of the Windows Accessibility options in the Control Panel. Each of these settings should change the font size of elements on your page in ways that are commonly used by people with disabilities.

Tip #6: Use client-side image maps to make pages keyboard navigable

Client-side image maps are more accessible than server-side image maps because the user can tab to each of the defined areas. To further enhance keyboard navigation, add anchors to each of the defined areas in the image map. This way all the user has to do is tab to the desired link and hit ENTER.

Links to Additional Information on Accessibility

The following links provide additional information on accessibility.

  • Microsoft Accessibility Home Page
  • Trace Research and Development Center
  • Web Accessibility Initiative
  • Yuri Rubinsky Insight Foundation


DHTML References

These links provide Web authors with easy access to the set of reference material that will help them create compelling content for the Web.

Document Object Model References

Objects

Properties

Methods

Events

Collections

HTML References

Elements

Character Sets

CSS References

CSS Attributes

Additional References

Color Table

Tips and Tricks


Document Object Model References Document Object Model References *
  * Previous Topic: DHTML References
  * Next Topic: Objects

Document Object Model References

Objects

Properties

Methods

Events

Collections


Objects

The following topics list the set of objects defined by Dynamic HTML. The links take you to the object definitions, which contain the set of members for the object.

Objects
A ACRONYM ADDRESS
all APPLET applets
anchors AREA areas
B BASE BASEFONT
BGSOUND BIG BLOCKQUOTE
BODY BR BUTTON
CAPTION cells CENTER
children CITE CODE
COL COLGROUP COMMENT
DD DEL DFN
DIR DIV DL
document DT elements
EM EMBED embeds
event external FIELDSET
filters FONT FORM
forms FRAME frames
FRAMESET H1 H2
H3 H4 H5
H6 HEAD history
HR HTML I
IFRAME images IMG
INPUT INS KBD
LABEL LEGEND LI
LINK links LISTING
location MAP MARQUEE
MENU META navigator
NEXTID OBJECT OL
OPTION options P
PLAINTEXT plugins PRE
Q rows rules
S SAMP screen
SCRIPT scripts SELECT
selection SMALL SPAN
STRIKE STRONG STYLE
style styleSheet styleSheets
SUB SUP TABLE
TBODY TD TEXTAREA
TextRange TFOOT TH
THEAD TITLE TR
TT U UL
userProfile VAR window
XMP

Input Types
button checkbox file
hidden image password
radio reset submit text

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


A

Description

Designates the start or destination of a hypertext link. The anchor element requires the href or the name property to be specified.

Remarks

Text and/or images can be within an anchor. To represent images that are anchors, a border in the visited or not-visited color is displayed.

Properties

accessKey, className, dataFld, dataSrc, document, hash, host, hostname, href, id, innerHTML, innerText, isTextEdit, lang, language, Methods, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, pathname, port, protocol, recordNumber, rel, rev, search, sourceIndex, style, tabIndex, tagName, target, title, urn

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, ondragstart, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

A


ACRONYM

Description

Indicates an acronym abbreviation.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup,

HTML Element

ACRONYM

See Also

ADDRESS, CITE, DFN, EM, I


ADDRESS

Description

Specifies information such as address, signature, and authorship.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

ADDRESS

See Also

ACRONYM, CITE, DFN, EM, I


APPLET

Description

Places executable content on the page.

Remarks

This element is a block element.

Properties

accessKey, align, altHTML, className, code, codeBase, dataFld, dataSrc, document, height, hspace, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, src, style, tagName, title, vspace, width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, onerrorupdate, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onload, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onreadystatechange, onresize, onrowenter, onrowexit,

HTML Element

APPLET


AREA

Description

Specifies the shape of a "hot spot" in a client-side image MAP.

Properties

alt, className, coords, document, hash, host, hostname, href, id, isTextEdit, lang, language, noHref, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, pathname, port, protocol, search shape, sourceIndex, style, tabIndex, tagName, target, title

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

AREA


B

Description

Specifies that the text should be rendered in bold, where available.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

B

See Also

STRONG


BASE

Description

Specifies the document's base URL.

Remarks

This element is used to ensure that your document is not reviewed out of context.

This element can be used only within the HEAD tag.

Properties

className, document, href, id, isTextEdit, lang, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, tagName, target, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

BASE


BASEFONT

Description

Sets a base font value to be used as the default font when rendering text.

Remarks

This element can be used only within the BODY tag or the HEAD tag. BASEFONT should appear before any displayed text in the BODY of the document.

Properties

className, color, document, face, id, isTextEdit, outerHTML, outerText, parentElement, parentTextEdit, size, sourceIndex, tagName

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

BASEFONT


BGSOUND

Description

Allows you to create pages with background sounds or "sound tracks."

Remarks

This element can be used only within the HEAD tag.

Properties

balance, className, document, id, isTextEdit, loop, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, src, style, tagName, title, volume

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

BGSOUND


BIG

Description

Specifies that the enclosed text should be displayed in a relatively bigger font than the current font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

BIG


BLOCKQUOTE

Description

Sets apart a quotation in text.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

BLOCKQUOTE

See Also

Q


BODY

Description

Specifies the beginning and end of the document body.

Remarks

You can access the BODY element by using the body property on the document object.

Event handlers set using the onblur, onfocus, onload, or onunload property handle these events for the window object. These properties are of the window object but are hosted on the BODY element, since there is no "window" element available.

This element is a block element.

Properties

accessKey, aLink, background, bgColor, bgProperties, bottomMargin, className, clientHeight, clientLeft, clientTop, clientWidth, document, filter, id, innerHTML, innerText, isTextEdit, lang, language, leftMargin, link, noWrap, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, recordNumber, rightMargin, scroll, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tabIndex, tagName, text, title, topMargin, vLink

Methods

click, contains, createTextRange, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeunload, onbeforeupdate, onchange, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, ondragstart, onerrorupdate, onfilterchange, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onrowenter, onrowexit, onselectstart

HTML Element

BODY

"


BR

Description

Inserts a line break.

Properties

className, clear, document, id, isTextEdit, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

HTML Element

BR


BUTTON

Description

Specifies a container for rich HTML that is rendered as a button.

Properties

accessKey, className, dataFld, dataFormatAs, dataSrc, disabled, document, form, id, innerHTML, innerText, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, status, style, tagName, title, type, value

Methods

blur, click, createTextRange, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselectstart

HTML Element

BUTTON


CAPTION

Description

Specifies a caption for a TABLE.

Remarks

This element is a block element.

Properties

align, className, clientHeight, clientLeft, clientTop, clientWidth, document, id, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title, vAlign

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselect, onselectstart

HTML Element

CAPTION


CENTER

Description

Causes subsequent text and images to be centered.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

CENTER


CITE

Description

Indicates a citation. Refers to a book, paper, or other published source material. Text is rendered in italic.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

CITE

See Also

ACRONYM, ADDRESS, DFN, EM, I


CODE

Description

Specifies a code sample.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

CODE

See Also

SAMP


COL

Description

Specifies column-based defaults for the table properties.

Properties

align, className, document, id, isTextEdit, parentElement, parentTextEdit, span, style, tagName, title, vAlign, width

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

COL

See Also

COLGROUP


COLGROUP

Description

Contains a group of columns.

Properties

align, className, document, id, isTextEdit, parentElement, parentTextEdit, span, style, tagName, title, vAlign, width

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

COLGROUP

See Also

COL


COMMENT

Description

Indicates a comment that will not be displayed.

Properties

className, document, id, isTextEdit, lang, parentElement, parentTextEdit, sourceIndex, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

COMMENT


DD

Description

Indicates the definition in a definition list. The definition is usually indented from the definition list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

DD

See Also

DL, DT


DEL

Description

Indicates text that has been deleted from the document.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup

HTML Element

DEL

See Also

INS


DFN

Description

Indicates the defining instance of a term.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

DFN

See Also

ACRONYM, ADDRESS, CITE, I


DIR

Description

Denotes a directory list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

DIR


DIV

Description

Specifies a container that renders HTML.

Remarks

This element is a block element.

Properties

align, className, clientHeight, clientWidth, dataFld, dataFormatAs, dataSrc, document, id, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tagName, title

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselectstart

HTML Element

DIV


DL

Description

Denotes a definition list.

Remarks

This element is a block element.

Properties

className, compact, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

DL

See Also

DD, DT


document

Description

Represents the HTML document in a given browser window.

Remarks

You use the document object to retrieve information about the document, to examine and modify the HTML elements and text within the document, and to process events.

The document object is available at all times. You can retrieve the object by applying the document property to a window or an element object. If used by itself, document represents the document in the current window.

Examples

The following example checks for a document title and displays the title (if not null) in an alert (message) box.

if (document.title!="")
    alert("The title is " + document.title)

The following example shows an event handler function that displays the current position of the mouse (relative to the upper-left corner of the document) in the browser's status window.

<HTML>
<HEAD><TITLE>Report mouse moves</TITLE>
<SCRIPT LANGUAGE="JScript">
function reportMove() {
    window.status = "X=" + window.event.x + " Y=" + window.event.y;
}
</SCRIPT>
<BODY onmousemove="reportMove()">
<H1>Welcome!</H1>
</BODY>
</HTML>

Properties

activeElement, alinkColor, bgColor, body, charset, cookie, defaultCharset, domain, expando, fgColor, lastModified, linkColor, location, parentWindow, readyState, referrer, selection, title, URL, vlinkColor

Collections

all, anchors, applets, children, embeds, forms, frames, images, links, plugins, scripts, styleSheets

Methods

clear, close, createElement, createStyleSheet, elementFromPoint, execCommand, open, queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandSupported, queryCommandText, queryCommandValue, ShowHelp, write, writeln

Events

onafterupdate, onbeforeupdate, onclick, ondblclick, ondragstart, onerrorupdate, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onreadystatechange, onrowenter, onrowexit, onselectstart


DT

Description

Indicates a definition term within a definition list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup onselectstart

HTML Element

DT

See Also

DD, DL


EM

Description

Emphasizes text, usually by rendering it in italic.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup onselectstart

HTML Element

EM

See Also

ACRONYM, ADDRESS, CITE, I


EMBED

Description

Allows you to embed documents of any type. The user needs to have an application that can view the data installed correctly on his or her computer. The EMBED object must appear inside the BODY of the document.

Remarks

This element is a block element.

Properties

accessKey, align, className, document, height, Hidden, id, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, palette, parentElement, parentTextEdit, pluginspage, sourceIndex, src, style, tagName, title, units, width

Methods

blur, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onblur, onfocus

HTML Element

EMBED


event

Description

Represents the state of an event, such as the element in which the event occurred, the state of the keyboard keys, the location of the mouse, and the state of the mouse buttons.

The event object is available only during an event. That is, you can use it in event handlers but not in other code. You retrieve the event object by applying the event keyword to the window object.

Although all event properties are available to all event objects, some properties might not have meaningful values during some events. For example, the fromElement and toElement properties are meaningful only when processing the onmouseover and onmouseout events.

Examples

The following example checks whether a mouse click occurred within a link and prevents the link from being carried out if the SHIFT key is down.

<HTML>
<HEAD><TITLE>Cancels Links</TITLE>
<SCRIPT LANGUAGE="JScript">
function cancelLink() {
    if (window.event.srcElement.tagName == "A" && window.event.shiftKey)
        window.event.returnValue = false;
}
</SCRIPT>
<BODY onclick="cancelLink()">

The following example displays the current mouse position in the browser's status window.

<BODY onmousemove="window.status = 'X=' + window.event.x + ' Y=' + window.event.y">

Note that in VBScript you cannot use the event keyword without applying it to the window keyword or an expression that evaluates to a window.

Properties

altKey, button, cancelBubble, clientX, clientY, ctrlKey, fromElement, keyCode, offsetX, offsetY, reason, returnValue, screenX, screenY, shiftKey, srcElement, srcFilter, toElement, type, x, y

Applies To

window


external

Description

Allows access to an additional object model provided by host applications of the Internet Explorer browser components. In a hosting scenario where it is available, the object model is defined by the application hosting the Internet Explorer components, and the hosting application should be referred to for documentation. For further details on how to implement extensions to the object model, see the SDK documentation on "Reusing the WebBrowser and MSHTML."

Methods

addChannel, isSubscribed

Applies To

window


FIELDSET

Description

Draws a box around the text and other elements it contains. This element is useful for grouping elements in a form and for distinctively marking text in a document.

Properties

accessKey, align, className, clientHeight, clientWidth, document, id, innerHTML, innerText, isTextEdit, lang, language, margin, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, padding, parentElement, parentTextEdit, recordNumber, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tabIndex, tagName, title

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, onchange, ondblclick, ondragstart, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselect, onselectstart

HTML Element

FIELDSET


FONT

Description

Specifies a new font face, size, and color to be used for rendering the enclosed text.

Properties

className, color, document, face, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, size, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

FONT


FORM

Description

Specifies that the contained controls take part in a form.

Remarks

When programming the form, all control-like elements are added to the form as named items.

When the focus is on a control in a form, pressing ESC once causes the value of the control to revert back to the last value, and pressing the key again resets the form. If the focus is on the but not on a particular control, pressing ESC once resets the form.

If one and only one text box is on a form, pressing ENTER fires the onsubmit event. If the form has a Submit button, the button appears with a dark border indicating that pressing ENTER submits the form.

This element is a block element.

Properties

action, className, document, encoding, id, innerHTML, innerText, isTextEdit, lang, language, method, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, target, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, reset, scrollIntoView, setAttribute, submit

Collections

all, children, elements, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onreset, onselectstart, onsubmit

HTML Element

FORM


FRAME

Description

Specifies an individual frame within a FRAMESET.

Remarks

This element is a block element.

Properties

borderColor, className, dataFld, dataSrc, document, frameBorder, height, id, isTextEdit, lang, language, marginHeight, marginWidth, name, noResize, parentElement, parentTextEdit, scrolling, sourceIndex, src, style, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

FRAME

See Also

FRAMESET


FRAMESET

Description

Specifies a frameset, which is used to organize multiple frames and nested framesets.

Remarks

This element is a block element.

Properties

border, borderColor, className, cols, document, frameBorder, frameSpacing, id, isTextEdit, lang, language, parentElement, parentTextEdit, rows, sourceIndex, style, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

Events

onbeforeunload, onload, onresize, onunload

HTML Element

FRAMESET

See Also

FRAME


H1

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H1


H2

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H2


H3

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H3


H4

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H4


H5

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H5


H6

Description

Renders text as a heading style.

Remarks

This element is a block element.

Properties

align, className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

H6


HEAD

Description

Provides an unordered collection of information about the document.

Remarks

HEAD provides information that does not affect the rendering of the document, but might be of use to the browser. The following tags are valid in this element:

  • BASE
  • BASEFONT
  • BGSOUND
  • LINK
  • META
  • NEXTID
  • SCRIPT
  • STYLE
  • TITLE

Properties

className, document, id, isTextEdit, parentElement, sourceIndex, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

HTML Element

HEAD


history

Description

Contains information on the URLs that the client has previously visited.

Property

length

Methods

back, forward, go

Applies To

window


HR

Description

Draws a horizontal rule.

Remarks

This element is a block element.

Properties

align, className, color, document, id, isTextEdit, lang, language, noShade, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, size, sourceIndex, style, tagName, title, width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselectstart

HTML Element

HR


HTML

Description

Identifies the document as containing HTML elements.

Properties

className, document, id, isTextEdit, language, parentElement, sourceIndex, style, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

HTML Element

HTML


I

Description

Specifies that the text should be rendered in italic font, where available.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

I

See Also

ADDRESS, CITE, DFN, EM


IFRAME

Description

Creates inline floating frames.

Remarks

This element is a block element.

The IFrame functions as a document within a document. Consequently, access to the IFrame object is provided through the frames collection. Use the frames collection to read or write to elements contained in an IFrame.

Properties

align, className, dataFld, dataSrc, document, frameBorder, frameSpacing, hspace, id, innerHTML, innerText, isTextEdit, lang, language, marginHeight, marginWidth, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, scrolling, sourceIndex, src, style, tagName, title, vspace

Methods

contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children

Example

The following code returns a reference to the all collection within the IFrame.

document.all.frames["MyIFrame"].document.all

HTML Element

IFRAME


IMG

Description

Embeds an image or a video clip in the document.

Remarks

This element does not fire the onfocus event when it receives the input focus unless it has been associated with a MAP element.

Properties

align, accesKey, alt, border, className, complete, dataFormatAs, dataFld, dataSrc, document, dynsrc, fileCreatedDate, fileModifiedDate, fileSize, fileUpdateDate, filter, href, height, hspace, id, innerHTML, innerText, isMap, isTextEdit, lang, language, loop, lowsrc, mimeTypes, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, protocol, readyState, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, src, start, style, tabIndex, tagName, title, useMap, vspace, width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onabort, onafterupdate, onbeforeupdate, onblur, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, ondragstart, onerror, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onload, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselectstart

HTML Element

IMG

See Also

INPUT


INPUT

Description

Specifies one of these form input controls:
button
checkbox
file
hidden
image
password
radio
reset
submit
text

Collections

all, children, filters

HTML Element

INPUT

See Also

BUTTON, SELECT, TEXTAREA

INPUT type=button

Description

Creates a button control.

Properties

accessKey, className, dataFld, dataFormatAs, dataSrc, disabled, document, form, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, readOnly, recordNumber, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, createTextRange, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

See Also

BUTTON

INPUT type=checkbox

Description

Represents simple Boolean attributes or attributes that can take multiple values at the same time.

Remarks

This element is represented by a number of check box controls, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.

Properties

accessKey, checked, className, dataFld, dataSrc, defaultChecked, disabled, document, form, id, indeterminate, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, recordNumber, size, sourceIndex, status, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

INPUT type=file

Description

Uploads files.

Properties

accessKey, className, defaultValue, disabled, document, form, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, readOnly, recordNumber, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onblur, onchange, onclick, ondblclick, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

INPUT type=hidden

Description

Transmits state information about client/server interaction.

Remarks

This value presents no control to the user, but sends the value of the value property with the submitted form.

Properties

className, dataFld, dataSrc, disabled, document, form, id, isTextEdit, language, name, parentElement, parentTextEdit, sourceIndex, style, tagName, type, value

Methods

contains, getAttribute, removeAttribute, setAttribute

Events

onafterupdate, onbeforeupdate, onerrorupdate

HTML Element

INPUT

INPUT type=image

Description

Represents an image control that you can click, causing the form to be immediately submitted.

Remarks

The x-coordinate is submitted under the name of the control with .x appended, and the y-coordinate is submitted under the name of the control with .y appended. Any value property is ignored. The image itself is specified by the src property, exactly as for the IMG element.

Properties

accessKey align, alt, className, complete, disabled, document, dynsrc, filter, form, height, id, innerHTML, isTextEdit, language, loop, lowsrc, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, readyState, recordNumber, sourceIndex, src, start, style, tabIndex, tagName, title, type width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onabort, onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, onerror, onerrorupdate, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onload, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselect

HTML Element

INPUT

See Also

IMG

INPUT type=password

Description

Similar to the text control, except that text is not displayed as the user enters it.

Properties

accessKey, align, className, dataFld, dataSrc, defaultValue, disabled, document, form, id, isTextEdit, lang, language, maxLength, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, readOnly, size, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onblur, onchange, onclick, ondblclick, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

INPUT type=radio

Description

Used for mutually exclusive sets of values.

Remarks

Each radio-button control in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.

Properties

accessKey, checked, className, dataFld, dataSrc, defaultChecked, disabled, document, form, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, recordNumber, size, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, onerrorupdate, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

INPUT type=reset

Description

Represents a button that, when clicked, resets the form's controls to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.

Properties

accessKey, className, disabled, document, form, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, recordNumber, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

See Also

BUTTON

INPUT type=submit

Description

Represents a button that, when clicked, submits the form.

Remarks

You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a SUBMIT button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data.

Properties

accessKey, className, disabled, document, form, id, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, recordNumber, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

See Also

BUTTON

INPUT type=text

Description

Creates a single-line text-entry control. Use in conjunction with the size and maxLength properties.

Properties

accessKey, align, className, dataFld, dataSrc, defaultValue, disabled, document, form, id, innerHTML, isTextEdit, lang, language, maxLength, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, readOnly, recordNumber, size, sourceIndex, style, tabIndex, tagName, title, type, value

Methods

blur, click, contains, createTextRange, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onselect

HTML Element

INPUT

See Also

TEXTAREA


INS

Description

Indicates text that has been inserted into the document.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup,onselectstart

HTML Element

INS

See Also

DEL


KBD

Description

Renders text in fixed-width font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

KBD


LABEL

Description

Specifies a label for a control-like element.

Remarks

Labels cannot be nested.

If the user clicks the label with the mouse, the onclick event goes to the label, then bubbles to the control specified by the htmlFor property. Pressing the access key for the label is the same as clicking the mouse on the label.

Properties

accessKey, className, document, htmlFor, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

LABEL


LEGEND

Description

Inserts a caption into the box drawn by the FIELDSET element. This element must be the first element in FIELDSET.

Remarks

This element is a block element.

Properties

accessKey, align, className, clientHeight, clientWidth, document, id, innerHTML, innerText, isTextEdit, lang, language, margin offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, padding, parentElement, parentTextEdit, recordNumber, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tabIndex, tagName, title

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onerrorupdate, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselectstart

HTML Element

LEGEND


LI

Description

Denotes one item of a list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title, type, value

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

LI

See Also

OL, UL


LINK

Description

Specifies a typed relationship between the document and some other resource. For example, this element is used to link external style sheets to the document.

Remarks

This element can be used only within the HEAD tag.

Properties

className, disabled, document, href, id, parentElement, readyState, rel, sourceIndex, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

Events

onerror, onload, onreadystatechange

HTML Element

LINK


LISTING

Description

Renders text in fixed-width type.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

LISTING

See Also

XMP


location

Description

Contains information on the current URL.

Remarks

The href property contains the entire URL, and the other properties contain portions of it. Location.href is the default property for the location object. For example, setting location='http://microsoft.com' is equivalent to setting location.href='http://microsoft.com'.

By setting any of the following properties, the browser will initiate an immediate navigation to the newly specified URL.

Properties

hash, host, hostname, href, pathname, port, protocol, search

Methods

assign, reload, replace


MAP

Description

Specifies a collection of hot spots for a client-side image map.

Properties

className, document, filter, id, innerHTML, innerText, isTextEdit, lang, language, name offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, recordNumber, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, removeAttribute, scrollIntoView, setAttribute

Collections

all, areas, children

Events

onafterupdate, onbeforeupdate, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, ondragstart, onerrorupdate, onfilterchange,, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onrowenter, onrowexit, onselectstart

HTML Element

MAP


MARQUEE

Description

Enables you to create a scrolling text marquee.

Remarks

The width of MARQUEE defaults to 100%. When MARQUEE is in a TD that does not specify a width, you should explicitly set the width of MARQUEE. The marquee tries to size according to the TD, and the TD tries to size according to the marquee. Without a specific width, the marquee will collapse to a 1-pixel width, and the contents cannot be viewed.

Properties

accessKey, behavior, bgColor, className, clientHeight, clientWidth, dataFld, dataFormatAs, dataSrc, direction, document, height, hspace, id, innerHTML, innerText, isTextEdit, lang, language, loop, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, scrollAmount, scrollDelay, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tagName, title, trueSpeed, vspace, width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute, start, stop

Collections

all, children, filters

Events

onafterupdate, onblur, onbounce, onclick, ondblclick, ondragstart, onfinish, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselectstart, onstart

HTML Element

MARQUEE


MENU

Description

Specifies that the following block consists of individual items.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

MENU


META

Description

Provides support for client pull.

Remarks

This element can be used only within the HEAD tag.

Properties

charset, className, content, document, httpEquiv, id, isTextEdit, lang, name, parentElement, parentTextEdit, sourceIndex, tagName, title, url

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children

HTML Element

META


navigator

Description

Contains information about the Web browser.

Properties

appCodeName, appMinorVersion, appName, appVersion, browserLanguage, connectionSpeed, cookieEnabled, cpuClass, onLine, platform, systemLanguage, userAgent userLanguage, userProfile

Methods

javaEnabled, taintEnabled

Collections

mimeTypes, plugins

Applies To

window


NEXTID

Description

Serves as a parameter to be read and generated by text editing software to create unique identifiers.

Remarks

This element can be used only within the HEAD tag.

Properties

className, document, id, isTextEdit, language, parentElement, parentTextEdit, sourceIndex, tagName, title

Methods

contains, getAttribute, removeAttribute, setAttribute


OBJECT

Description

Inserts an object onto the HTML page. An object can appear in the HEAD or the BODY of a document.

Possible return values (those generated by Object Model properties) on the OBJECT tag will depend on the implementation of the OBJECT. For example, the readyState property will return null or error if the OBJECT does not implement a readyState property. Object Model properties available for an OBJECT depend on the contents of the OBJECT. See the documentation for the individual object for supported Object Model properties.

Note: the object property for the OBJECT element is a way of reconciling Object Model members that are duplicated by the OBJECT element's implementation and DHTML. For instance, if the OBJECT implements an item method, and DHTML implements an item method, to use the one defined for the OBJECT, document.all.objectID.object.item() would differentiate these methods.

Remarks

This element is a block element.

Properties

accessKey, align, altHTML, classid, className, code, codeBase, codeType, data, dataFld, dataSrc, dataFormatAs, document, height, hspace, id, isTextEdit, lang, language, name, object, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, readyState, sourceIndex, style, tabIndex, tagName, title, type, vspace, width

Methods

blur, click, contains, focus, getAttribute, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondataavailable, ondatasetchanged, ondatasetcomplete, ondblclick, ondragstart, onerror, onerrorupdate, onfilterchange, onfocus, onreadystatechange, onrowenter, onrowexit, onselectstart

HTML Element

OBJECT


OL

Description

Draws lines of text as an ordered list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, start, style, tagName, title, type

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

OL

See Also

LI


OPTION

Description

Denotes one choice in a select list.

Remarks

Although OPTION elements do not appear in the all collection, you can gain access to these elements by applying the options collection to the SELECT element.

Style settings that you apply to the style object for this element are ignored. But style settings that you apply to the containing SELECT element are also applied to this element.

This element is a block element.

Example

The following JScript example displays the text for all options in the first SELECT list in the document.

var el = document.all.tags("SELECT").item(0);
if (el != null) {
    for (i=0; i<el.options.length; i++) {
        alert("Option " + i + " is " + el.options(i).text);
    }
}

Properties

className, document, id, isTextEdit, language, offsetHeight, offsetParent, offsetWidth, parentElement, parentTextEdit, selected, sourceIndex, style, tagName, text, value

Methods

contains, getAttribute, removeAttribute, scrollIntoView, setAttribute

HTML Element

OPTION

See Also

SELECT


P

Description

Denotes a paragraph.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

P


PLAINTEXT

Description

Renders text in fixed-width type without processing tags.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

PLAINTEXT

See Also

XMP


PRE

Description

Renders text in fixed-width type.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

PRE

See Also

XMP


Q

Description

Sets apart a quotation in text.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

Q

See Also

BLOCKQUOTE


S

Description

Renders text in strike-through type.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

S

See Also

STRIKE


SAMP

Description

Specifies a code sample.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

SAMP

See Also

CODE


screen

Description

Contains information about the client's screen and rendering abilities.

Properties

availHeight, availWidth, bufferDepth, colorDepth, height, updateInterval, width

Applies To

window


SCRIPT

Description

Specifies a script for the page that will be interpreted by a script engine.

Remarks

Code within the SCRIPT block that is not contained within a function is executed immediately as the page is loaded. To keep scripts from being displayed on down-level browsers, the SCRIPT block should be nested within a comment block.

This element is a block element.

Properties

className, defer, document, event, htmlFor, id, innerHTML, innerText, isTextEdit, language, parentElement, parentTextEdit, readyState, sourceIndex, src, style, tagName, text, title, type

Methods

contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, setAttribute

Events

onerror, onload, onreadystatechange

HTML Element

SCRIPT


SELECT

Description

Denotes a list box or drop-down list.

Examples

The following JScript example adds a new option to the end of an existing SELECT list.

var oOption = document.createElement("OPTION");
oOption.text="Apples";
oOption.value="5";
document.all.MyList.add(oOption);

Properties

accessKey, className, dataFld, dataSrc, disabled, document, form, id, isTextEdit, lang, language, length, multiple, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, recordNumber, selectedIndex, size, sourceIndex, style, tabIndex, tagName, type, value

Methods

add, blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, item, remove, removeAttribute, scrollIntoView, setAttribute, tags

Collections

all, children, filters, options

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, ondragstart, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselectstart

HTML Element

SELECT

See Also

OPTION


selection

Description

Represents the active selection, a highlighted block of text, and/or other elements in the document upon which a user or a script can carry out some action. You typically use the selection object as input from the user identifying what portion of the document to act on, or as output to the user showing the results of an action.

Remarks

Users and scripts can both create selections. Users create selections by dragging the mouse over a portion of the document. Scripts create them by calling the select method on a text range or similar object. You can retrieve the active selection by applying the selection keyword to the document object. To carry out work on a selection, you can create a text range object from the selection by using the createRange method.

A document can have only one selection at a time. The selection has a type that determines whether it is empty or contains a contiguous block of consecutive text and/or elements. Although an empty selection contains nothing, it is useful for marking a position in the document.

Properties

type

Methods

clear, createRange, empty

Applies To

document


SMALL

Description

Specifies that the enclosed text should be displayed with a relatively smaller font than the current font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

SMALL


SPAN

Description

Specifies an inline text container. This element is especially useful for applying CSS styles.

Properties

className, dataFld, dataFormatAs, dataSrc, document, id, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tagName, title

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onscroll, onselectstart

HTML Element

SPAN


STRIKE

Description

Renders text in strike-through type.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

STRIKE

See Also

S


STRONG

Description

Renders text in bold.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

STRONG

See Also

ACRONYM, ADDRESS, B, CITE


STYLE

Description

Specifies a style sheet for the page.

Remarks

This element should appear in the HEAD section of an HTML document. Internet Explorer 4.0 permits multiple style blocks.

Properties

className, disabled, document, id, isTextEdit, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, readyState, sourceIndex, style, tagName, type

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, scrollIntoView, setAttribute

Events

onerror, onload, onreadystatechange

HTML Element

STYLE


style

Description

Represents the current settings of all possible inline styles for a given element.

Remarks

Inline styles are CSS style assignments that an author applies directly to individual HTML elements using the STYLE= attribute. You use the style object to examine these assignments and either make new assignments or change existing ones.

You can retrieve the style object by applying the style keyword to an element object. You retrieve the current setting for an inline style by applying the corresponding style property to the style object.

The style object does not give access to the style assignments in style sheets. To obtain information about styles in style sheets, you must use the styleSheets collection to gain access to the individual style sheets defined in the document.

Examples

The following example sets the typeface for text in the document body to "Verdana".

document.body.style.fontFamily = "Verdana"

The following example positions the given image at the top of the document.

var i = document.all.tags("IMG");
if (i.length>0) {
    if (i[0].style.position == "absolute")
        i[0].style.top = 0;
}

Properties

background, backgroundAttachment, backgroundColor, backgroundImage, backgroundPosition, backgroundPositionX, backgroundPositionY, backgroundRepeat, border, borderBottom, borderBottomColor, borderBottomStyle, borderBottomWidth, borderColor, borderLeft, borderLeftColor, borderLeftStyle, borderLeftWidth, borderRight, borderRightColor, borderRightStyle, borderRightWidth, borderStyle, borderTop, borderTopColor, borderTopStyle, borderTopWidth, borderWidth, clear, clip, color, cssText, cursor, display, filter, font, fontFamily, fontSize, fontStyle, fontVariant, fontWeight, height, left, letterSpacing, lineHeight, listStyle, listStyleImage, listStylePosition, listStyleType, margin, marginBottom, marginLeft, marginRight, marginTop, overflow, paddingBottom, paddingLeft, paddingRight, paddingTop, pageBreakAfter, pageBreakBefore, pixelHeight, pixelLeft, pixelTop, pixelWidth, posHeight, position, posLeft, posTop, posWidth, styleFloat, textAlign, textDecoration, textDecorationBlink, textDecorationLineThrough, textDecorationNone, textDecorationOverline, textDecorationUnderline, textIndent, textTransform, top, verticalAlign, visibility, width, zIndex

Methods

getAttribute, removeAttribute, setAttribute

Applies To

element object


styleSheet

Description

Represents a single style sheet in the document.

Remarks

You use the object to retrieve information about the style sheet, such as the URL of the source file for the style sheet and the element in the document that owns (defines) the style sheet, and also to modify the style sheet.

You retrieve a style sheet object from the styleSheets collection or from the imports collection. Each item in these collections is a style sheet. A style sheet object is available for a style sheet only if it is included in a document with a STYLE or LINK element, or with an @import statement in a STYLE element.

Properties

disabled, href, id, owningElement, parentStyleSheet, readOnly, type

Methods

addImport, addRule

Collections

imports, rules

Applies To

styleSheets


SUB

Description

Specifies that the enclosed text should be displayed in subscript, using a smaller font than the current font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

SUB

See Also

SUP


SUP

Description

Specifies that the enclosed text should be displayed in superscript and in a smaller font relative to the current font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

SUP

See Also

SUB


TABLE

Description

Specifies that the contained content is organized into a table with rows and columns.

Remarks

Valid tags within a table include:

  • CAPTION
  • COL
  • COLGROUP
  • TBODY
  • TFOOT
  • THEAD
  • TR

This element is a block element. When a document is loading, modifications to a table are restricted until the window.onload event occurs. Read-only access is allowed at any time.

Properties

align, background, bgColor, border, borderColor, borderColorDark, borderColorLight, cellPadding, cellSpacing, className, clientHeight, clientWidth, cols, dataFld, dataPageSize, dataSrc, document, frame, height, id, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, rules, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, style, tagName, title, width

Methods

blur, click, contains, deleteRow, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, insertRow, nextPage, previousPage, refresh, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters, rows

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselectstart

HTML Element

TABLE

See Also

TD, TR


TBODY

Description

Designates rows as the body of the table.

Remarks

This element is exposed for all tables, even if the table did not explicitly define a TBODY element.

This element is a block element.

Properties

align, bgColor, className, document, id, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, sourceIndex, style, tagName, title, vAlign

Methods

click, contains, deleteRow, getAttribute, insertRow, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

TBODY


TD

Description

Specifies a cell in a table.

Remarks

This element is a block element.

Properties

align, background, bgColor, borderColor, borderColorDark, borderColorLight, className, clientHeight, clientWidth, colSpan, document, height, id, isTextEdit, lang, language, noWrap, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, rowSpan, sourceIndex, style, tagName, title, vAlign, width

Methods

blur, click, contains, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselectstart

HTML Element

TD

See Also

TABLE, TH, TR


TEXTAREA

Description

Specifies a multiline text input control.

Remarks

The default font is fixed pitch. You can also set the overflow CSS attribute to "hidden" to remove the scroll bars from the TEXTAREA.

<TEXTAREA STYLE="overflow:hidden" ID=txtComments>
   The patient is in stable condition after suffering an attack of
   the insatiable munchies.
</TEXTAREA>

Properties

accessKey, className, clientHeight, clientWidth, cols, dataFld, dataSrc, disabled, document, form, id, innerText, isTextEdit, lang, language, name, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerText, parentElement, parentTextEdit, readOnly, rows, scrollHeight, scrollLeft, scrollTop, scrollWidth, sourceIndex, status, style, tabIndex, tagName, title, type, value, wrap

Methods

blur, click, contains, createTextRange, focus, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, select, setAttribute

Collections

all, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onchange, onclick, ondblclick, ondragstart, onerrorupdate, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onscroll, onselect, onselectstart

HTML Element

TEXTAREA

See Also

INPUT


TextRange

Description

Represents text in an HTML element.

Remarks

You can use this object to retrieve and modify text in an element, to locate specific strings in the text, and to carry out commands that affect the appearance of the text.

You can retrieve a text range object by applying the createTextRange method to a BODY, BUTTON, or TEXTAREA element or an INPUT element having text type. You can modify the extent of the text range by moving its start and end positions with methods such as move, moveToElementText, and findText. Within the text range, you can retrieve and modify plain text or HTML text. These forms of text are identical except that HTML text includes HTML tags; plain text does not.

This feature might not be available on non-Win32® platforms. See article Q172976 in the Microsoft® Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following JScript example changes the text of a BUTTON element to "Clicked".

var b = document.all.tags("BUTTON");
if (b!=null) {
    var r = b[0].createTextRange();
    if (r != null) {
        r.text = "Clicked";
    }
}

Properties

htmlText, text, boundingHeight, boundingLeft, boundingTop, boundingWidth, offsetLeft, offsetTop

Methods

collapse, compareEndPoints, duplicate, execCommand, expand, findText, getBookmark, inRange, isEqual, move, moveEnd, moveStart, moveToBookmark, moveToElementText, moveToPoint, parentElement, pasteHTML, queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandSupported, queryCommandValue, scrollIntoView, select, setEndPoint

See Also

createTextRange


TFOOT

Description

Designates rows as the table's footer.

Remarks

This element is a block element.

Properties

align, bgColor, className, document, id, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, sourceIndex, style, tagName, title, vAlign

Methods

click, contains, deleteRow, getAttribute, insertRow, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup , onselectstart

HTML Element

TFOOT


TH

Description

Specifies a header column. Header columns are centered within the cell and are bold.

Remarks

This element is a block element.

Properties

align, background, bgColor, borderColor, borderColorDark, borderColorLight, className, colSpan, document, id, isTextEdit, lang, language, noWrap, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, rowSpan, sourceIndex, style, tagName, title, vAlign

Methods

click, contains, getAttribute, removeAttribute, scrollIntoView, setAttribute

Collections

all, children

Events

onclick, ondblclick, ondragstart, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

TH

See Also

TD, TR


THEAD

Description

Designates rows as the table's header.

Remarks

This element is a block element.

Properties

align, bgColor, className, document, id, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, sourceIndex, style, tagName, title, vAlign

Methods

click, contains, deleteRow, getAttribute, insertRow, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

THEAD


TITLE

Description

Identifies the contents of the document in a global context.

Remarks

This element can be used only within the HEAD tag.

This element is a block element.

Properties

className, document, id, isTextEdit, lang parentElement, parentTextEdit, sourceIndex, tagName, text, title

Methods

contains, getAttribute, removeAttribute, setAttribute

Collections

all, children, filters

HTML Element

TITLE


TR

Description

Specifies a row in a table.

Remarks

Within a row, the following tags are valid:

  • TD
  • TH

This element is a block element.

Properties

align, bgColor, borderColor, borderColorDark, borderColorLight, className, document, id, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, parentElement, parentTextEdit, rowIndex, sectionRowIndex, sourceIndex, style, tagName, title, vAlign

Methods

blur, click, contains, deleteCell, focus, getAttribute, insertCell, removeAttribute, scrollIntoView, setAttribute

Collections

all, cells, children, filters

Events

onafterupdate, onbeforeupdate, onblur, onclick, ondblclick, ondragstart, onfilterchange, onfocus, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onresize, onrowenter, onrowexit, onselectstart

HTML Element

TR

See Also

TABLE, TD, TH


TT

Description

Renders text in fixed-width type.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

TT

See Also

XMP


U

Description

Renders text underlined.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

U


UL

Description

Draws lines of text as a bulleted list.

Remarks

This element is a block element.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title, type

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

UL

See Also

LI


userProfile

Description

Provides methods that allow a script to request read access to a user's profile information, and to perform read actions. Note that the request is queued up before the reading or writing action is performed, which simplifies the user's experience because he or she is only prompted for profile release permissions once for a batch of requests.

Example

The following is an example of a script that can be run on the client to read various values from the profile information.

// queue up a request for read access to multiple profile attributes
navigator.userProfile.addReadRequest("vcard.displayname");
navigator.userProfile.addReadRequest("vcard.gender");

// request access to this information
navigator.userProfile.doReadRequest(usage-code, "Acme Corporation");

// now perform read operations to access the information
name = navigator.userProfile.getAttribute("vcard.displayname");
gender = navigator.userProfile.getAttribute("vcard.gender");

// the script can now use the 'name' and 'gender' variables
// to personalize content or to send information back to the server

// this is to support getting back to a clean slate by clearing the
// request queue.
navigator.userProfile.clearRequest();

Methods

addReadRequest, clearRequest, doReadRequest, getAttribute


VAR

Description

Renders text as a small fixed-width font.

Properties

className, document, id, innerHTML, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, insertAdjacentText, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

VAR


window

Description

Represents an open window in the browser.

Remarks

You use the window object to retrieve information about the state of the window and to gain access to the document in the window, to the events that occur in the window, and to features of the browser that affect the window.

Typically, the browser creates one window object when it opens an HTML document. However, if a document defines one or more frames (that is, contains one or more FRAME or IFRAME tags), the browser creates one window object for the original document and one additional window object for each frame. These additional objects are child windows of the original window and can be affected by actions that occur in the original. For example, closing the original window causes all child windows to close. You can also create new windows (and corresponding window objects) by using methods such as open and showModalDialog.

You can apply any window property, method, or collection to any variable or expression that evaluates to a window object, regardless of how that window was created. Additionally, you can access all window properties, methods, and collections in the current window by using the property, method, or collection name directly—that is, without prefixing it with an expression that evaluates to the current window object. However, to help make more readable code and to avoid potential ambiguities, many developers use the window keyword when accessing window properties, methods, and collections for the current window. This keyword always refers to the current window.

Note Window property, method, and collection names are reserved keywords and cannot be used as the names of variables and routines.

The dialogArguments, dialogHeight, dialogLeft, dialogTop, dialogWidth, and returnValue properties are available only for windows created using the showModalDialog method.

Examples

The following example displays an alert (message) box for the current window.

alert("A simple message.")

The following example checks whether the current window contains child windows and, if it does, displays the names of those child windows.

if (window.frames!=null) {
    for (i=0; i<window.frames.length; i++)
        window.alert("Child window "+i+" is named "+window.frames(i).name);
}

The following example shows a simple event handler function for the window's onload event. Note that in the absence of a "window" element, the BODY element hosts the following window object events: onblur, onfocus, onload, and onunload.

<BODY onload="window.status='Page is loaded!'">

Properties

clientInformation, closed, defaultStatus, dialogArguments, dialogHeight, dialogLeft, dialogTop, dialogWidth, document, event, history, length*, location, name, navigator, offscreenBuffering, opener, parent*, returnValue, screen, self, status, top*

*An asterisk indicates properties not applicable to modal dialogs.

Collections

frames*

Methods

alert, blur, clearInterval, clearTimeout, close, confirm, execScript, focus, moveBy, moveTo, navigate, open*, prompt, resizeBy, resizeTo, scroll, scrollBy, scrollTo, setInterval, setTimeout, showHelp, showModalDialog*

*An asterisk indicates properties not applicable to modal dialogs.

Events

onbeforeunload, onblur, onerror, onfocus, onhelp, onload, onresize, onscroll, onunload


XMP

Description

Renders text in fixed-width type used for example text.

Remarks

This tag is no longer recommended. Instead, the PRE or SAMP tag should be used.

This element is a block element.

Properties

className, document, id, innerText, isTextEdit, lang, language, offsetHeight, offsetLeft, offsetParent, offsetTop, offsetWidth, outerHTML, outerText, parentElement, parentTextEdit, sourceIndex, style, tagName, title

Methods

click, contains, getAttribute, insertAdjacentHTML, removeAttribute, scrollIntoView, setAttribute

Collections

all, children, filters

Events

onclick, ondblclick, ondragstart, onfilterchange, onhelp, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselectstart

HTML Element

XMP

See Also

LISTING, PLAINTEXT, PRE, TT


Properties

The following table lists the properties in the DHTML object model. For properties that appear in multiple table cells, roll the mouse over the text to view a ToolTip indicating the objects to which the property applies. Click the text to jump to a full description of that property.

accessKey action activeElement
align align align
align aLink alinkColor
alt altHTML altKey
appCodeName appMinorVersion appName
appVersion availHeight availWidth
background background background
backgroundAttachment backgroundColor backgroundImage
backgroundPosition backgroundPositionX backgroundPositionY
backgroundRepeat balance behavior
bgColor bgColor bgProperties
border border border
borderBottom borderBottomColor borderBottomStyle
borderBottomWidth borderColor borderColor
borderColorDark borderColorLight borderLeft
borderLeftColor borderLeftStyle borderLeftWidth
borderRight borderRightColor borderRightStyle
borderRightWidth borderStyle borderTop
borderTopColor borderTopStyle borderTopWidth
borderWidth bottomMargin boundingHeight
boundingLeft boundingTop boundingWidth
browserLanguage bufferDepth button
cancelBubble caption cellIndex
cellPadding cellSpacing charset
checked classid className
clear clear clientHeight
clientInformation clientLeft clientTop
clientWidth clientX clientY
clip closed code
codeBase codeBase codeType
color color colorDepth
cols cols cols
colSpan compact complete
connectionSpeed content cookie
cookieEnabled coords cpuClass
cssText ctrlKey cursor
data dataFld dataFormatAs
dataPageSize dataSrc defaultCharset
defaultChecked defaultSelected defaultStatus
defaultValue defer defer
dialogArguments dialogHeight dialogLeft
dialogTop dialogWidth direction
disabled disabled display
domain dynsrc encoding
event expando face
fgColor fileCreatedDate fileModifiedDate
fileSize fileUpdatedDate filter
font fontFamily fontSize
fontSmoothingEnabled fontStyle fontVariant
fontWeight form frame
frameBorder frameSpacing fromElement
hash height height
height hidden host
hostname href href
href href hspace
htmlFor htmlFor htmlText
httpEquiv id indeterminate
index innerHTML innerText
isMap isTextEdit keyCode
lang language lastModified
left leftMargin length
letterSpacing lineHeight link
linkColor listStyle listStyleImage
listStylePosition listStyleType location
loop lowsrc map
margin marginBottom marginHeight
marginLeft marginRight marginTop
marginWidth maxLength media
method Methods mimeTypes
multiple name name
noHref noResize noShade
noWrap object offscreenBuffering
offsetHeight offsetLeft offsetParent
offsetTop offsetWidth offsetX
offsetY onLine opener
outerHTML outerText overflow
owningElement padding paddingBottom
paddingLeft paddingRight paddingTop
pageBreakAfter pageBreakBefore palette
parent parentElement parentStyleSheet
parentTextEdit parentWindow pathname
pixelHeight pixelLeft pixelTop
pixelWidth platform plugins
pluginspage port posHeight
position posLeft posTop
posWidth protocol readOnly
readOnly readyState reason
recordNumber recordset referrer
rel returnValue returnValue
rev rightMargin rowIndex
rows rows rowSpan
rules screenX screenY
scroll scrollAmount scrollDelay
scrollHeight scrolling scrollLeft
scrollTop scrollWidth search
sectionRowIndex selected selectedIndex
self shape shiftKey
size size size
sourceIndex span src
src src srcElement
srcFilter start start
status status style
styleFloat systemLanguage tabIndex
tagName target text
text text text
textAlign textDecoration textDecorationBlink
textDecorationLineThrough textDecorationNone textDecorationOverline
textDecorationUnderline textIndent textTransform
tfoot thead title
title toElement top
top topMargin trueSpeed
type type type
type type type
type type type
units updateInterval url
url urn useMap
userAgent userLanguage vAlign
vAlign value value
value verticalAlign visibility
vLink vlinkColor volume
vspace width width
width wrap x
y zIndex

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


accessKey

Description

Specifies an accelerator key that can be applied to several elements, listed below. The ALT key plus a specified access key allows you to set the focus on a particular page.

Syntax

object.accessKey[ = "sAccessKey"]

Parameter | Description
accessKey | Any alphanumeric keyboard key.

Remarks

By default, the accessKey property sets focus to an element. In addition, some controls perform an action after receiving focus. For example, using accessKey on a button fires the onclick event. Whereas using accessKey on a radio button fires the onclick event and toggles the checked property, visibly selecting or deselecting the control.

The following example uses a combination of the LABEL element and the accessKey property to set focus on a text box. The rich text support in the LABEL element makes it possible to underline the designated accessKey.

<LABEL FOR="fp1" ACCESSKEY="1">#<u>1</u>: Press Alt+1 to set focus to textbox</label>
<INPUT TYPE="text" NAME="T1" VALUE=text1 SIZE="20" TABINDEX="1" ID="fp1">

This property has read/write permission and takes a string.

Applies To

A, APPLET, BUTTON, EMBED, FIELDSET, IFRAME, IMG, INPUT, LABEL, OBJECT, SELECT, TABLE, TEXTAREA


action

Description

Specifies the address to be used to carry out the action of the form. If none is specified, the base URL of the document is used.

Syntax

object.action[ = action]

Remarks

The way the data is submitted depends upon the value of the method and encoding properties.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FORM


activeElement

Description

Identifies the element that has the focus.

This read-only property is set when you select a control in the interface or use the focus method.

Syntax

object.activeElement

Applies To

document


align

Description

Specifies how the element is aligned with adjacent text.

Syntax

object.align[ = "string"]

Settings

The value of this read-write property can be one of these strings:

absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

Applies To

APPLET, EMBED, IFRAME, IMG, INPUT type=image, OBJECT


align

Description

Specifies the alignment of the caption or legend.

Syntax

object.align[ = align]

Settings

This read-write property can be set to one of these string values:

bottom | Align bottom-center.
center | Center the caption.
left | Left align.
right | Right align.
top | Align top-center.

Remarks

Difference between a LEGEND tag and a CAPTION tag:

The LEGEND tag is used only within a FIELDSET tag. The contents of the LEGEND tag are displayed by cutting a hole in the top border of the FIELDSET and placing the LEGEND text in that hole.

The CAPTION tag is used only within a TABLE tag. Its contents are displayed centered above the table and do not interact at all with the table border.

Applies To

CAPTION, LEGEND


align

Description

Specifies how the table should be aligned.

Syntax

object.align[ = align]

Settings

This read-write property can be set to one of these string values:

center | Align to the center.
left | Align to the left edge. This is the default value.
right | Align to the right edge.

Applies To

TABLE


align

Description

Displays the element left flush, right flush, or centered relative to the display or table.

Syntax

object.align[ = align]

Settings

This read-write property can be set to one of these string values:

center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

The default is left-aligned for TR and TD. The default is center-aligned for TH.

Applies To

COL, COLGROUP, DIV, H1, H2, H3, H4, H5, H6, HR, P, TBODY, TD, TFOOT, TH, THEAD, TR


aLink

Description

Sets the color for the active link. The color can be one of the color names or values given in Color Table.

Syntax

object.aLink[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

body

See Also

link, vLink


alinkColor

Description

Sets the color for the active link. The color can be one of the color names or values given in Color Table.

Syntax

object.alinkColor[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document

See Also

linkColor, vlinkColor


alt

Description

Indicates optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered.

Syntax

object.alt[ = alt]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

AREA, IMG


altHTML

Description

Indicates an optional HTML script to execute if the OBJECT fails to load.

Syntax

object.altHTML

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

APPLET, OBJECT


altKey

Description

Specifies the state of the ALT key.

Syntax

object.altKey

Settings

This read-only property is TRUE if the key is down, or FALSE otherwise.

Applies To

event


appCodeName

Description

Indicates a string that returns the code name of the browser.

Syntax

object.appCodeName

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


appMinorVersion

Description

Returns the application's minor version value. Internet Explorer 4.0 returns zero.

Syntax

object.appMinorVersion

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


appName

Description

Indicates a string that specifies the name of the browser.

Syntax

object.appName

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


appVersion

Description

Indicates a string that returns the version of the browser.

Syntax

object.appVersion

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


availHeight

Description

Returns the height of the working area of the system's screen, in pixels, excluding the toolbar.

Syntax

object.availHeight

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

screen

See Also

height


availWidth

Description

Returns the width of the working area of the system's screen, in pixels, excluding the toolbar.

Syntax

object.availWidth

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

screen

See Also

width


background

Description

Sets or retrieves the separate background attributes (backgroundColor, backgroundImage, backgroundRepeat, backgroundAttachment, and backgroundPosition) at once.

Syntax

object.style.background[ = background]

Remarks

The property is a shorthand ("composite") property. Separate properties can be used to specify each of the individual properties, but in many cases it is more convenient to set them in one place using this composite property. Possible values here include all of the possible values for each of the individual properties.

For more information on supported colors, see Color Table.

All individual background properties not set by the composite background property will be set to their initial values.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

background


background

Description

Specifies a background picture. The picture is tiled behind the text and graphics on the page.

Syntax

object.background[ = background]

Remarks

This property has read/write permission.

Applies To

BODY


background

Description

Specifies a background picture for a table.

Syntax

object.background[ = background]

Remarks

The picture is tiled behind the text and graphics in the table, table head, or table cell.

This property has read/write permission.

Applies To

TABLE, TD, TH


backgroundAttachment

Description

Sets or retrieves whether the background image scrolls with the content or is fixed.

Syntax

object.style.backgroundAttachment[ = scroll]

Remarks

Possible values include:
fixed | Background image does not scroll with the content.
scroll | Background image scrolls with the content.

The property has read/write permission.

Applies To

HTML Tags | BODY, HTML
Scripting | style

CSS Attribute

background-attachment


backgroundColor

Description

Sets or retrieves the background color of an element.

Syntax

object.style.backgroundColor[ = backgroundColor]

Remarks

For more information on supported colors, see Color Table.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

background-color


backgroundImage

Description

Sets or retrieves the background image of an element.

Syntax

object.style.backgroundImage[ = URL]

Remarks

The URL identifies the image file. When setting a background image, it's a good idea to also set a background color to be used when the image is unavailable. When the image is available, it is overlaid on top of the background color.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

background-image


backgroundPosition

Description

Sets or retrieves the initial position of the background image.

Syntax

object.style.backgroundPosition[ = backgroundPosition]

Remarks

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

background-position


backgroundPositionX

Description

Returns the x-coordinate of the CSS background-position attribute.

Syntax

object.backgroundPositionX[ = backgroundPositionX]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style

CSS Attribute

background-position

See Also

backgroundPositionY


backgroundPositionY

Description

Returns the y-coordinate of the CSS background-position attribute.

Syntax

object.backgroundPositionY[ = backgroundPositionY]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style

CSS Attribute

background-position

See Also

backgroundPositionX


backgroundRepeat

Description

Sets or retrieves whether the image is repeated, if a background image is specified.

Syntax

object.style.backgroundRepeat[ = repeat]

Remarks

Possible values include:
no-repeat | The image is not repeated.
repeat-y | The image is repeated vertically.
repeat-x | The image is repeated horizontally.
repeat | The image is repeated horizontally and vertically.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

background-repeat


balance

Description

Returns the balance value of the background sound. The value determines how the available volume is divided between the left and right speakers.

Syntax

object.balance

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

BGSOUND


behavior

Description

Specifies how the text scrolls in the marquee.

Syntax

object.behavior[ = behavior]

Settings

Possible values include:
alternate | The marquee alternates left and right.
scroll | The marquee is a scrolling marquee in the direction specified by the direction property. The text scrolls off the end and starts over.
slide | The marquee is a scrolling marquee in the direction specified by the direction attribute. The text scrolls to the end and stops.

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

MARQUEE


bgColor

Description

Sets the background color behind the element. The color can be one of the color names or values given in Color Table.

Syntax

object.bgColor[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

MARQUEE, TABLE, TBODY, TD, TFOOT, TH, THEAD, TR

See Also

background


bgColor

Description

Sets the background color of the page. The color can be one of the color names or values given in Color Table.

Syntax

object.bgColor[ = color]

Remarks

JScript supports the entire set of valid property colors both as strings and their numerical equivalents as a string. JScript always returns the property as the numerical equivalent as a string regardless of the format the value was set to.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BODY, document

See Also

background


bgProperties

Description

Sets or retrieves the properties for the background picture. For example, specifies whether the picture is a fixed watermark or scrolls with the page.

Syntax

object.bgProperties[ = bgProperties]

Settings

This read-write property is a string. If set to "fixed", the background picture is fixed and does not scroll with the page. If set to an empty string (""), the background picture scrolls.

Applies To

BODY

See Also

background


border

Description

Sets or retrieves the width, color, and style of a border to be drawn around the element.

Syntax

object.style.border[ = border]

Remarks

The border property is a shorthand (composite) property for setting border width, color, and style for all four sides of an object. If a borderColor is not specified, the text color is used.

All individual border properties not set by the composite border property will be set to their default values. For example, the default value for borderWidth is medium.

Setting border=thin is identical to saying border=thin none; the default value for color picks up the text color if one isn't initially set. So, in addition to setting the border width to thin, it will clear any borderStyle or borderColor that has been previously set.

For more information on supported colors, see Color Table.

Setting a border to zero or omitting the attribute causes no border to be displayed. Supplying the border attribute without a value defaults to a single border.

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border


border

Description

Defines the space between the frames, including the 3-D border.

Syntax

object.border[ = border]

Remarks

The border can be set only on an outermost FRAMESET tag. Setting a border for an inner FRAMESET is ignored, even if a border is not defined on the outermost FRAMESET.

This property has read/write permission.

Applies To

FRAMESET


border

Description

Sets or retrieves the width of the border to be drawn around the element.

Syntax

object.border[ = border]

Remarks

Setting a border to zero or omitting the attribute causes no border to be displayed. Supplying the border attribute without a value defaults to a single border.

This property has read/write permission, meaning you can change as well as retrieve its current value.

Applies To

IMG, TABLE

See Also

borderColor, borderColorDark, borderColorLight, hspace, vspace


borderBottom

Description

Sets or retrieves the color, style, and width of the element's bottom border.

Syntax

object.style.borderBottom[ = borderBottom]

Remarks

The color can be one of the color names or values given in Color Table.

This property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-bottom


borderBottomColor

Description

Sets or retrieves the color of the element's bottom border.

Syntax

object.style.borderBottomColor[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-bottom-color


borderBottomStyle

Description

Sets or retrieves the style of the element's bottom border.

Syntax

object.style.borderBottomStyle[ = borderBottomStyle]

Remarks

Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. The border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-bottom-style


borderBottomWidth

Description

Sets or retrieves the width of the element's bottom border.

Syntax

object.style.borderBottomWidth[ = borderBottomWidth]

Remarks

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-bottom-width


borderColor

Description

Sets or retrieves the element's border color.

Syntax

object.style.borderColor[ = color]

Remarks

Up to four different colors can be specified. If one color is supplied, it is used for all four sides. If two colors are supplied, the first is used for the top and bottom, and the second is used for left and right. If three colors are supplied, they are used for top, right and left, and bottom, respectively. For a list of supported color values, see Color Table.

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IMG, IFRAME, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-color


borderColor

Description

Sets or retrieves the border color and must be used with the borderWidth and borderStyleproperties, except for frames.

Syntax

object.borderColor[ = color]

Remarks

The property has read/write permission.

Applies To

FRAME, FRAMESET, TABLE, TD, TH, TR

See Also

border, borderColorDark, borderColorLight


borderColorDark

Description

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property. The color can be one of the color names or values given in Color Table.

Syntax

object.borderColorDark[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE, TD, TH, TR

See Also

border, borderColor, borderColorLight


borderColorLight

Description

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property. The color can be one of the color names or values given in Color Table.

Syntax

object.borderColorLight[ = borderColorLight]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE, TD, TH, TR

See Also

border, borderColor, borderColorDark


borderLeft

Description

Sets or retrieves the color, style, and width of the left border.

Syntax

object.style.borderLeft[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

This property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-left


borderLeftColor

Description

Sets or retrieves the color of the element's left border.

Syntax

object.style.borderLeftColor[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-left-color


borderLeftStyle

Description

Sets or retrieves the style of the element's left border.

Syntax

object.style.borderLeftStyle[ = borderLeftStyle]

Remarks

Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. The border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-left-style


borderLeftWidth

Description

Sets or retrieves the width of the element's left border.

Syntax

object.style.borderLeftWidth[ = borderLeftWidth]

Remarks

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-left-width


borderRight

Description

Sets or retrieves the color, style, and width of the element's right border.

Syntax

object.style.borderRight[ = borderRight]

Remarks

For more information on supported colors, see Color Table.

This property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-right


borderRightColor

Description

Sets or retrieves the color of the element's right border.

Syntax

object.style.borderRightColor[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-right-color


borderRightStyle

Description

Sets or retrieves the style of the element's right border.

Syntax

object.style.borderRightStyle[ = borderRightStyle]

Remarks

Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. The border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-right-style


borderRightWidth

Description

Sets or retrieves the width of the element's right border.

Syntax

object.style.borderRightWidth[ = borderRightWidth]

Remarks

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-right-width


borderStyle

Description

Sets or retrieves the style of the element's left, right, top, and bottom borders.

Syntax

object.style.borderStyle[ = borderStyle]

Remarks

Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. The border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-style


borderTop

Description

Sets or retrieves the color, style, and width of the element's top border.

Syntax

object.style.borderTop[ = borderTop]

Remarks

For more information on supported colors, see Color Table.

This property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-top


borderTopColor

Description

Sets or retrieves the color of the element's top border.

Syntax

object.style.borderTopColor[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-top-color


borderTopStyle

Description

Sets or retrieves the style of the element's top border.

Syntax

object.style.borderTopStyle[ = borderTopStyle]

Remarks

Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. The border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-top-style


borderTopWidth

Description

Sets or retrieves the width of the element's top border.

Syntax

object.style.borderTopWidth[ = borderTopWidth]

Remarks

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-top-width


borderWidth

Description

Sets or retrieves the width of the left, right, top, and bottom border.

Syntax

object.style.borderWidth[ = borderWidth]

Remarks

Up to four different widths can be specified. If one width is supplied, it is used for all four sides. If two widths are supplied, the first is used for the top and bottom, and the second is used for left and right. If three widths are supplied, they are used for top, right and left, and bottom, respectively.

The property has read/write permission. It is supported on block and replaced elements only.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

border-width


bottomMargin

Description

Specifies the bottom margin for the entire body of the page and overrides the default margin.

Syntax

object.bottomMargin[ = bottomMargin]

Settings

This read-write property takes a string representation of a decimal number. If set to "", the bottom margin will be exactly on the bottom edge.

Applies To

BODY


boundingHeight

Retrieves the height of the rectangle that bounds the TextRange.

Syntax

HTML | n/a
Scripting | iHeight = TextRange.boundingHeight

Remarks

Default Value | Data Type | Access | Inherited
n/a | numeric | n/a

Applies To

HTML Tags | n/a
Scripting | TextRange

Availability

HTML | n/a
Scripting | Internet Explorer 4.0

See Also

boundingLeft, boundingTop, boundingWidth


boundingLeft

Retrieves the left coordinate of the rectangle that bounds the TextRange.

Syntax

HTML | n/a
Scripting | iLeft = TextRange.boundingLeft

Remarks

Default Value | Data Type | Access | Inherited
n/a | numeric | n/a

Applies To

HTML Tags | n/a
Scripting | TextRange

Availability

HTML | n/a
Scripting | Internet Explorer 4.0

See Also

boundingHeight, boundingTop, boundingWidth


boundingTop

Retrieves the top coordinate of the rectangle that bounds the TextRange.

Syntax

HTML | n/a
Scripting | iTop = TextRange.boundingTop

Remarks

Default Value | Data Type | Access | Inherited
n/a | numeric | n/a

Applies To

HTML Tags | n/a
Scripting | TextRange

Availability

HTML | n/a
Scripting | Internet Explorer 4.0

See Also

boundingHeight, boundingLeft, boundingWidth


boundingWidth

Retrieves the width of the rectangle that bounds the TextRange.

Syntax

HTML | n/a
Scripting | iWidth = TextRange.boundingWidth

Remarks

Default Value | Data Type | Access | Inherited
n/a | numeric | n/a

Applies To

HTML Tags | n/a
Scripting | TextRange

Availability

HTML | n/a
Scripting | Internet Explorer 4.0

See Also

boundingHeight, boundingLeft, boundingTop


browserLanguage

Description

Indicates the current browser language. For possible return values, see Language Codes.

Syntax

object.browserLanguage

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


bufferDepth

Description

Specifies an offscreen bitmap buffer.

Syntax

object.bufferDepth[ = bufferDepth]

Settings

This read-write property can have these values:

0
No explicit buffering. The colorDepth property is set to the screen depth.
-1
Perform buffering at the screen depth. colorDepth is set to the screen depth.
1, 4, 8, 15, 16, 24, or 32
Perform buffering using the given bits-per-pixel. colorDepth is also set to this value. The value 15 specifies 16 bits-per-pixel, in which only 15 bits are used in a 5-5-5 layout of RGB values.

Nonsupported values cause bufferDepth to be set to -1.

When bufferDepth is -1 and the user changes system settings that affect the screen depth, the buffer depth is automatically updated to the new depth. This is not the case if you set bufferDepth to a specific value.

Applies To

screen


button

Description

Specifies which mouse button, if any, is pressed.

Syntax

object.button

Settings

This read-only property has one of these values:

0 | No button.
1 | Left button is pressed.
2 | Right button is pressed.
4 | Middle button is pressed.

This property is intended to be used with the onmousedown, onmouseup, and onmousemove events. For other events, it typically is zero regardless of the state of the mouse buttons.

Applies To

event


cancelBubble

Description

Specifies whether the current event should bubble up the hierarchy of event handlers.

Syntax

object.cancelBubble[ = cancelBubble]

Settings

This read-write property takes a Boolean value:

TRUE | Cancels bubbling for this event, preventing the next event handler in the hierarchy from receiving the event.
FALSE | Enables bubbling. This is the default value.

Using this property to cancel bubbling for an event does not affect subsequent events.

Example

The following document fragment cancels bubbling of the onclick event if it occurs in the IMG element when the SHIFT key is down. This prevents the event from bubbling up to the onclick event handler for the document.

<SCRIPT LANGUAGE="JScript">
function checkCancel() {
if (window.event.shiftKey)
    window.event.cancelBubble = true;
}
function showSrc() {
    if (window.event.srcElement.tagName == "IMG")
        alert(window.event.srcElement.src);
}
</SCRIPT>
<BODY onclick="showSrc()">
<IMG onclick="checkCancel()" SRC="sample.gif">

Applies To

event


caption

Description

Points to the CAPTION element in the TABLE. If none exist, it is null.

Syntax

object.caption[ = element]

Return Value

This property has read-only permission.

Remarks

The following example sets the inline style for the CAPTION.

document.all.myTable.caption.style.color = "blue"

Applies To

table


cellIndex

Description

Indicates the element's position in the cells collection of a given row. Collection indexes are in the source order of the HTML document. Note that when a cell spans multiple rows, that cell only appears in the cells collection for the first of the rows that the cell spans.

Syntax

object.cellIndex[ = element]

Return Value

This property has read-only permission.

Applies To

TD

See Also

sectionRowIndex, sourceIndex, rowIndex


cellPadding

Description

Specifies the amount of space between the border of the cell and the content of the cell.

Syntax

object.cellPadding[ = cellPadding]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE

See Also

cellSpacing


cellSpacing

Description

Specifies the amount of space between cells in a table.

Syntax

object.cellSpacing[ = cellSpacing]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE

See Also

cellPadding


charset

Description

Sets or returns the character set of the document.

Syntax

object.charset[ = charset]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document, META


checked

Description

Specifies whether the given check box or radio button is selected.

Syntax

object.checked[ = checked]

Settings

This read-write property takes a Boolean value. It is TRUE if the control is selected, or FALSE otherwise. The default value for this property is FALSE.

Check boxes that are not selected do not return their values when the form is submitted.

Applies To

INPUT

See Also

defaultChecked


classid

Description

Specifies the class identifier for the object.

Syntax

object.classid

Remarks

The format is: classid="clsid:controlspecificclsid "

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT


className

Description

Specifies the class of the given element. The class is typically used to associate a particular style rule in a style sheet with the element.

Syntax

object.className[ = className]

Settings

This read-write property takes any valid string. By default, the property is equal to the string assigned to the CLASS= attribute of the given element, or is an empty string if the attribute is not explicitly assigned.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


clear

Description

Sets or retrieves whether the element allows floating elements on its left and/or right sides so that the next text will display past the floating elements.

Syntax

object.style.clear[ = clear]

Remarks

Possible values include:
all | Element is moved below any floating element.
left | Element is moved below any floating element on the left side.
right | Element is moved below any floating element on the right side.
none | Floating elements are allowed on all sides.

The value of this property lists the sides where floating elements are not accepted.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

clear


clear

Description

Inserts vertical space so that the next text displayed will be below left-aligned or right-aligned floating images.

Syntax

object.clear[ = clear]

Remarks

Possible values include:
all | Element is moved below any floating element.
left | Element is moved below any floating element on the left side.
right | Element is moved below any floating element on the right side.
none | Floating elements are allowed on all sides.

The value of this property lists the sides where floating elements are not accepted.

The property has read/write permission.

Applies To

BR


clientHeight

Description

Returns the height of the element, in pixels. This height does not take into account any margin, border, scroll bar, or padding that might have been applied to the element.

Syntax

object.clientHeight

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, IMG, INPUT, LEGEND, MARQUEE, OBJECT, SPAN, TABLE, TD, TEXTAREA, TR


clientInformation

Description

Returns the navigator object. You use this to retrieve information about the version and name of the browser, as well as whether certain features are enabled.

Syntax

object.clientInformation

Examples

The following JScript example checks whether the user agent name of the browser contains "MSIE". If it does, the browser is Microsoft® Internet Explorer.

if (window.clientInformation.userAgent.indexOf( "MSIE " ) > 0)
    // is Microsoft Internet Explorer

The following JScript example checks whether Java™ applets can be run.

if (window.clientInformation.javaEnabled() == true )
    // Java is enabled, applets can run

Applies To

window


clientLeft

Description

Returns the distance between the offsetLeft and the true left side of the client area, in pixels. The difference between the offsetLeft and clientLeft is the border of the element.

Syntax

object.clientLeft

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, IMG, INPUT, LEGEND, MARQUEE, OBJECT, SPAN, TABLE, TD, TEXTAREA, TR


clientTop

Description

Returns the distance between the offsetTop and the true top of the client area, in pixels. The difference between the offsetTop and the clientTop is the border area of the element.

Syntax

object.clientTop

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, IMG, INPUT, LEGEND, MARQUEE, OBJECT, SPAN, TABLE, TD, TEXTAREA, TR


clientWidth

Description

Returns the width of the element, in pixels. This width does not take into account any margin, border, scroll bar, or padding that might have been applied to the element.

Syntax

object.clientWidth

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, IMG, INPUT, LEGEND, MARQUEE, OBJECT, SPAN, TABLE, TD, TEXTAREA, TR


clientX

Description

Returns the position of the mouse hit relative to the size of the client area of the window. This does not include window decorations or scroll bars.

Syntax

object.clientX

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


clientY

Description

Returns the position of the mouse hit relative to the size of the client area of the window. This does not include window decorations or scroll bars.

Syntax

object.clientY

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


clip

Description

Sets or retrieves which part of the element is visible.

Syntax

object.style.clip[ = clip]

Remarks

This property defines a clipping region shape and size for a positioned element. The clipping region defines the part of the element that is visible. Any part of the element that is outside the clipping region is transparent. Any coordinate can be replaced by the value auto, which causes the clipping rectangle to match the element's opposite side. The default value is to clip to expose the entire element.

Note that the order of the values clip:rect(0 0 50 50) would render the element invisible, as it would set both the top and the right positions of the clipping region to 0. To achieve a 50-by-50 view port, the syntax should be clip:rect(0 50 50 0).

The property has read/write permission.

Applies To

HTML Tags | DIV, FIELDSET, IMG, INPUT, INPUT type=button, MARQUEE, SPAN, TABLE, TEXTAREA
Scripting | style

CSS Attribute

clip


closed

Description

Returns whether the referenced window is closed.

Syntax

object.closed

Settings

This read-only property is TRUE if the window is closed, or FALSE otherwise.

Applies To

window


code

Description

Specifies the name of the file containing the compiled Java class.

Syntax

object.code

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT


codeBase

Description

Specifies a URL referencing where to find the implementation of the object.

Syntax

object.codeBase

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT


codeBase

Description

Specifies the base URL for the application. This is an optional parameter.

Syntax

object.codeBase

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

APPLET, EMBED


codeType

Description

Specifies the Internet media type for the code associated with the object.

Syntax

object.codeType[ = codeType]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

OBJECT


color

Description

Sets or retrieves the color to be used by the font or horizontal rule.

Syntax

object.color[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

BASEFONT, FONT, HR


color

Description

Sets or retrieves the color to be used by the text.

Syntax

object.style.color[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

color


colorDepth

Description

Returns the bits-per-pixel value used for colors on the destination device or buffer. Script programmers use this value when deciding how best to use colors.

Syntax

object.colorDepth

Settings

The value of this read-only property depends on the bufferDepth property. If bufferDepth is 0 or -1, colorDepth is equal to the bits-per-pixel value for the screen or printer. If bufferDepth is nonzero, colorDepth is equal to bufferDepth.

Example

The following JScript example picks foreground and background colors based on the color depth of the screen.

if (screen.colorDepth > 2) {
    document.body.bgColor = "white";
    document.body.color = "blue";
} else {
    document.body.bgColor = "black";
    document.body.color = "white";
}

Applies To

screen


cols

Description

Specifies how many characters wide the text area is.

Syntax

object.cols[ = cols]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TEXTAREA


cols

Description

Specifies the number of columns in the table.

Syntax

object.cols[ = cols]

Remarks

Providing this number can speed up the processing of the table.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE


cols

Description

Specifies a comma-delimited list of frames to create. Each item in the list contains the initial size of the column.

Syntax

object.cols[ = cols]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAMESET


colSpan

Description

Specifies how many columns in the TABLE this cell should span.

Syntax

object.colSpan[ = colSpan]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Remarks

This property can only be changed after the page has been loaded.

Applies To

TD, TH


compact

Description

Specifies that the list should be compacted to remove extra space between list elements.

Syntax

object.compact[ = compact]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

DL


complete

Description

Returns whether the specified element is fully loaded.

Syntax

object.complete

Settings

This read-only property is TRUE if the element is loaded, or FALSE otherwise.

Applies To

IMG


content

Description

Specifies meta-information to be associated with the given name or HTTP response header.

Syntax

object.content[ = content]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

META

See Also

httpEquiv


cookie

Description

Specifies a string value of a cookie, which is a small piece of information stored by the browser.

Cookies are made from the following. (All are optional with the exception of the name=value pair.) Arguments are separated by semicolons.

name=value; | Each cookie is stored in a name=value pair, that is, if the cookie is "foo" and you want to save foo's value as "bar", the cookie would be saved as foo=bar. You can save as many name=value pairs in the cookie as you want, but the cookie is always returned as a string of all the cookies that apply to the page, so the string that is returned has to be parsed to find the values of individual cookies.
Expires=date; | If no expiration is set on a cookie, it will expire when the browser is closed. Setting an expiration date in the future causes the cookie to be saved across browser sessions. Setting an expiration date in the past will delete a cookie. The date should be specified using GMT format.
domain=domainname; | The domain of the cookie can be set, which allows pages on a domain made up of more than one server to share cookie information.
path=path; | Setting a path for the cookie will allow the current document to share cookie information with other pages within the same domain, that is, if the path is set to /foobar, all pages in /foobar and all pages in subfolders of /foobar will be able to access the same cookie information.
secure; | Specifying a cookie as "secure" means that the stored cookie information can be accessed only from a secure environment.

Syntax

object.cookie[ = cookie]

Remarks

Use string methods such as substring, charAt, indexOf, and lastIndexOf to determine the value stored in the cookie.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document


cookieEnabled

Description

Returns whether client-side cookies are enabled in the browser.

Syntax

object.cookieEnabled

Settings

This read-only property is TRUE if cookies are enabled, or FALSE otherwise.

Applies To

navigator


coords

Description

Specifies coordinates that define the hot spot's shape.

Syntax

object.coords[ = coords]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

AREA

See Also

shape


cpuClass

Description

Returns a string of the CPU class (for example, x86, Alpha, Other).

Syntax

object.cpuClass

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


cssText

Description

Sets or returns the persisted representation of the style rule. If a string is returned, it will break out the composite properties into individual attributes.

Syntax

object.cssText[ = cssText]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style


ctrlKey

Description

Returns the state of the CTRL key, a Boolean value.

Syntax

object.ctrlKey

Settings

This read-only property is TRUE if the key is down, or FALSE otherwise.

Applies To

event


cursor

Description

Sets or retrieves the the type of cursor to display for the mouse pointer.

Syntax

object.style.cursor[ = cursor]

Remarks

The following types are defined:

auto | Browser determines the cursor to display based on the current context.
crosshair | Simple cross hair.
default | Platform-dependent default cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating help.
move | Crossed arrows indicating something is to be moved.
*-resize | Arrow indicating edge is to be moved (* may be n, ne, nw, s, se, sw, e, or w).
text | Editable text (usually an I-bar).
wait | Hourglass or watch indicating that the program is busy and the user should wait.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, HTML, I, IFRAME, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

cursor


data

Description

Specifies a URL that references the object's data.

Syntax

object.data

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT

See Also

type


dataFld

Description

Specifies which field of a given data source (as specified by the dataSrc property) to bind to the given element.

Syntax

object.dataFld

Remarks

The property can be set at run time. At design time it can be set through the DATAFLD attribute.

Examples

In the following example, the <OBJECT> with ID="sundae" has its Color property bound to the color column of the data source control. Similarly, the text box displays the flavor.

<TABLE DATASRC="#ice_cream">
    <TR>
        <TD><INPUT TYPE=TEXTBOX DATAFLD=flavor>

<TD><OBJECT ID="sundae" WIDTH=100 HEIGHT=51
            CLASSID="CLSID:FFFFFFF-EEEE-DDDD-CCCC-BBBBBBBBBBBB">
            <PARAM NAME="Color" DATAFLD="color">
            <PARAM NAME="Appearance" VALUE="1">
        </OBJECT>
</TABLE>

In the following example the <SELECT> control is bound to the "card_type" column of the data source control "#order". The value of the field will result in the appropriate option being selected.

<SELECT DATASRC="#order" DATAFLD="card_type">
    <OPTION>Visa
    <OPTION>Mastercard
    <OPTION>American Express
    <OPTION>Diners Club
    <OPTION>Discover
</SELECT>

Applies To

A, APPLET, BODY, BUTTON, DIV, FRAME, IFRAME, IMG, INPUT, LABEL, MARQUEE, OBJECT, SELECT, SPAN, TEXTAREA


dataFormatAs

Description

Specifies how the data supplied to the element should be rendered.

Syntax

object.dataFormatAs

Remarks

The property can be set at run time. At design time it can be set through the dataFormatAs attribute. In Internet Explorer 4.0, the possible values for both the property and the corresponding HTML attribute are TEXT and HTML. TEXT is the default.

Examples

In the following DIV and SPAN examples, the data will be supplied in HTML format. In the TEXTAREA example, the data will be supplied in text format.

<DIV DATAFLD="Column2" DATAFORMATAS="html"></DIV>

<TEXTAREA DATASRC="#customer" DATAFLD="address" DATAFORMATAS="text"
    ROWS=6 COLS=60>
</TEXTAREA>

<SPAN DATASRC="#bank_acct" DATAFLD="balance" DATAFORMATAS="none"></SPAN>

Applies To

BODY, BUTTON, DIV, INPUT type=button, LABEL, MARQUEE, SPAN


dataPageSize

Description

Sets the number of records displayed in a table bound to a data source.

Syntax

object.dataPageSize

Remarks

Use the nextPage and previousPage methods to display the subsequent and previous page of records in the table.

The property can be set at run time. At design time it can be set through the dataPageSize attribute.

Example

In the following example, the intrinsic text box is bound to the customer name of the current row of the data source control with the ID "#customer_source". The row in the table will be repeated 10 times, the value specified by DATAPAGESIZE.

<TABLE DATASRC="#customer_source" DATAPAGESIZE=10>
    <TR>
        <TD><INPUT TYPE=TEXTBOX DATAFLD="customer_name">
</TABLE>

Applies To

TABLE


dataSrc

Description

Specifies the source of the data for databinding.

Syntax

object.dataSrc

Remarks

Both tabular and single-valued data consumers use the dataSrc property to specify a binding. The property takes a string that corresponds to the unique ID of a data source object (DSO) on the page.

When the dataSrc property is used for tabular data binding, it specifies that the entire contents of the table be repeated once for each record from the data set.

The dataSrc property can be inherited by the elements contained in a repeated TABLE. This behavior occurs when an element within a TABLE when that element only specifies a dataFld attribute. To complete the binding, the binding agent interrogates the enclosing TABLE for its data source. This inheritance behavior holds only for single-valued consumers. Tabular data consumers (TABLE) must specify an explicit dataSrc.

The property can be set at run time. At design time it can be set through the corresponding DATASRC attribute.

Example

In the following example, the intrinsic text box is bound to the customer name of the current row of the data source control with the ID "#customer_source", and the contents of the table, in this case <TR>, will be repeated once for each record in the set of tabular data.

<TABLE DATASRC="#customer_source">
    <TR>
        <TD><INPUT TYPE=TEXTBOX DATAFLD="customer_name">
</TABLE>

Applies To

A, APPLET, BODY BUTTON, DIV, FRAME, IFRAME, IMG, INPUT, LABEL, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TEXTAREA


defaultCharset

Description

Sets or returns the default character set of the document.

Syntax

object.defaultCharset[ = defaultCharset]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

META, document


defaultChecked

Description

Determines whether the check box or radio button is selected by default.

Syntax

object.defaultChecked[ = defaultChecked]

Settings

This read-write property is TRUE if the check box or radio button is selected by default, or FALSE otherwise. The default value for this property is TRUE.

The property can be changed programmatically but has no affect on the appearance nor on how forms are submitted.

Applies To

INPUT

See Also

checked


defaultSelected

Description

Determines whether the option is selected by default.

Syntax

object.defaultSelected[ = defaultSelected]

Settings

This read-write property is TRUE if the option is selected by default, or FALSE otherwise. The default value for this property is TRUE.

The property can be changed programmatically but has no affect on the appearance nor on how forms are submitted. It does change the appearance of the selected option if the form is reset.

Applies To

OPTION

See Also

selected


defaultStatus

Description

For a window, reflects the default message displayed in the status bar at the bottom of the window.

Syntax

object.defaultStatus[ = defaultStatus]

Remarks

Do not confuse defaultStatus with status. The status property reflects a priority or transient message in the status bar, such as the message that appears when an onmouseover event occurs over an anchor.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


defaultValue

Description

Specifies the initial contents of a password or text control or the TEXTAREA element.

Syntax

object.defaultValue[ = defaultValue]

Settings

This read-write property takes a string value.

This value can be changed programmatically but has no affect on the appearance nor on how forms are submitted. It does change the initial value of the control when the form is reset.

Applies To

INPUT, TEXTAREA


defer

Description

Indicates to the browser that there is no code in the script that needs to be executed when the page is initially loaded.

Syntax

bDeferred = object.defer

Remarks

Using the attribute at design time can improve the download performance of a page because the browser does not need to parse and execute the script and can continue downloading and parsing the page instead.

Applies To

SCRIPT


defer

Description

Indicates whether the script contains an inline executable function.

Syntax

object.defer

Applies To

SCRIPT


dialogArguments

Description

Returns the variable or array of variables passed into the modal dialog window.

Syntax

object.dialogArguments

Remarks

This property applies only to windows created using the showModalDialog method.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

window


dialogHeight

Description

Returns the height of the dialog window.

Syntax

object.dialogHeight[ = dialogHeight]

Remarks

This property applies only to windows created using the showModalDialog method.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


dialogLeft

Description

Returns the left coordinate of the dialog window.

Syntax

object.dialogLeft[ = dialogLeft]

Remarks

This property applies only to windows created using the showModalDialog method.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


dialogTop

Description

Returns the top coordinate of the dialog window.

Syntax

object.dialogTop[ = dialogTop]

Remarks

This property applies only to windows created using the showModalDialog method.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


dialogWidth

Description

Returns the width of the dialog window.

Syntax

object.dialogWidth[ = dialogWidth]

Remarks

This property applies only to windows created using the showModalDialog method.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


direction

Description

Specifies which direction the text should scroll.

Syntax

object.direction[ = direction]

Settings

This read-write property can be one of these strings:

down | The marquee scrolls down.
left | The marquee scrolls left.
right | The marquee scrolls right.
up | The marquee scrolls up.

The default value is left, which means scrolling to the left from the right.

Applies To

MARQUEE


disabled

Description

Disables a control. The control appears greyed and does not respond to user input.

Syntax

object.disabled[ = disabled]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

APPLET, BUTTON, INPUT, LINK, SELECT, STYLE, TEXTAREA


disabled

Description

Returns FALSE for a style sheet that does not specify a title and that is not currently selected.

Syntax

object.disabled

Remarks

The value of this property can also change per media-dependent style sheets. The application of individual style sheets can be turned on and off dynamically. Note that the value of this property is also controlled by whether titled style sheets are applied.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

styleSheet


display

Sets or retrieves whether an element is rendered.

Syntax

object.style.display[ = display]

Remarks

If this property is set to none, the element is not rendered. If it is set to block, inline, or list-item, the element is rendered. The default is to render the element.

Values for block, inline, and list-item are not supported explicitly but are useful in setting the display property to be on. In contrast to the visibility property, display=none reserves no space for the element on the screen.

Although you can apply the display property to parts of a table (such as a TR or TD element), changing the property has no effect on those parts. However, you can dynamically control the rendering of the entire table by applying the property to the TABLE element.

This property has read/write permission.

Applies To

HTML Tags | BODY, DIV, IFRAME, IMG, INPUT, INPUT type=button, MARQUEE, SELECT, SPAN, TABLE, TEXTAREA
Scripting | style

CSS Attribute

display


domain

Description

Sets or returns the security domain of the document.

Syntax

object.domain[ = domain]

Settings

This read-write property initially returns the host name of the server the page is from. It can be assigned the domain suffix to allow sharing of pages across frames. For example, a page in one frame from home.microsoft.com and a page from www.microsoft.com would initially not be able to communicate with each other. However, by setting the domain property of both pages to the suffix, microsoft.com, both pages would be considered secure and now access is available between the pages.

Applies To

document


dynsrc

Description

Specifies the address of a video clip or VRML world to be displayed in the window. Stands for Dynamic Source.

Syntax

object.dynsrc[ = dynsrc]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IMG


encoding

Description

Specifies the mime encoding for the form. This property corresponds to the HTML ENCTYPE= attribute.

Syntax

object.encoding[ = encoding]

Remarks

The default is "application/x-www-form-urlencoded". Internet Explorer 4.0 also recognizes "multipart/form-data", which with a POST method is required to submit a file upload to the server.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FORM

See Also

action


event

Description

Specifies the event the script is being written for.

Syntax

object.event

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

SCRIPT


expando

Description

Specifies whether arbitrary variables can be created within an object. Default is set to TRUE.

Syntax

object.expando[ = boolean]

Remarks

You can extend the properties on an object by creating arbitrary properties with values. For example, an author scripting in a case-sensitive language such as JScript can easily make the mistake when setting a property value. For instance, if the property value is "borderColor" and the author types the value "bordercolor = 'blue'", they author has just, in fact, created another property on the style object called "bordercolor" with the value 'blue'. If the author queries the value of the property, the value "blue" will be returned. However, the borders for the element will not turn blue.

Setting this property to FALSE on the document object will disallow the creation of arbitrary variables.

Applies To

document


face

Description

Sets the current font's typeface.

Syntax

object.face[ = face]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BASEFONT, FONT

See Also

font


fgColor

Description

Sets or retrieves the foreground (text) color of the document.

Syntax

object.fgColor[ = color]

Settings

This read-write property can be set to any one of the color names or values given in Color Table. The default value for this property is typically black, but depends on the browser.

Applies To

document

See Also

color, text


fileCreatedDate

Description

Returns the date the file was created.

Syntax

object.fileCreatedDate

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

IMG


fileModifiedDate

Description

Returns the date the file was last modified.

Syntax

object.fileModifiedDate

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

IMG


fileSize

Description

Returns the file size.

Syntax

object.fileSize

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

IMG


fileUpdatedDate

Description

Returns the date the file was last updated.

Syntax

object.fileUpdatedDate

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

IMG


filter

Description

Sets or retrieves the filter or collection of filters applied to the element.

Syntax

object.style.filter[ = filter]

Remarks

Internet Explorer 4 supports the following built-in filter types: Visual Filter, Reveal Transition Filter, or Blend Transition Filter. For detailed information, see Creating Multimedia Effects with Visual Filters and Transitions. The filter mechanism is extensible and allows additional filters to be developed and added later.

This read/write property takes a string specifying a filter and its parameters.

Applies To

HTML Tags | BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR
Scripting | style

*An asterisk in the list indicates that a defined height, width, or absolute position is required.

CSS Attribute

filter


font

Description

Sets or retrieves the separate font attributes (fontWeight, fontVariant, fontSize, and fontFamily) for text in the element.

Syntax

object.style.font[ = font]

Remarks

Setting this property also sets the component properties. In this case, the string must be a combination of valid values for the component properties, with no more than one value per property. If the string does not contain a value for a component property, that property remains unchanged.

Example

The following JScript example sets the font to a 12-point, serif typeface with a normal weight and with all letters in small capital letters.

var sVar = document.all.MyParagraph;
sVar.style.font = "normal small-caps 12pt serif";
    .
    .
    .
alert(sVar.font.style);

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font


fontFamily

Description

Sets or retrieves the name of the font used for text in the element.

Syntax

object.style.fontFamily[ = fontFamily]

Remarks

The value is a prioritized list of font family names and/or generic family names. List items are separated by commas to minimize confusion between multiple-word font family names. If the font family name contains white space, it should be quoted with single or double quotation marks.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font-family


fontSize

Description

Sets or retrieves the size of the font used for text in the element.

Syntax

object.style.fontSize[ = fontSize]

Remarks

The default value is medium. Negative values are not allowed. Font sizes are computed based on the font size of the parent element. Therefore, a font size of "10em" means that the size of the "em" is based on the font used by the parent element.

The values for font size are shown below:
absolute-size | A set of keywords that indicate predefined font sizes. Possible keywords include [xx-small | x-small | small | medium | large | x-large | xx-large]. Named font sizes scale according to the user's font setting preferences.
relative-size | A set of keywords that are interpreted as relative to the font size of the parent element. Possible values include [ larger | smaller].
length | An absolute value for the font size.
percentage | A percentage value of the parent element's font size.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font-size


fontSmoothingEnabled

Description

Indicates whether the user has selected the corresponding option through the browser options.

Syntax

object.fontSmoothingEnabled

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

screen


fontStyle

Description

Sets or retrieves whether the font style is italic, normal, or oblique.

Syntax

object.style.fontStyle[ = fontStyle]

Remarks

The settings for the property are italic, normal, or oblique. Internet Explorer 4 displays italic and oblique identically.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font-style


fontVariant

Description

Sets or retrieves the font variation as small-caps for text in the element.

Syntax

object.style.fontVariant[ = fontVariant]

Remarks

This read/write property can be set to either normal or small-caps. The default value is normal. Internet Explorer 4.0 renders small-caps as uppercase letters in a smaller size.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font-variant


fontWeight

Description

Sets or retrieves the weight (boldness) of the text.

Syntax

object.style.fontWeight[ = fontWeight]

Remarks

The key words for fontWeight values are mapped to specific font variations depending on the fonts that are installed on the user's computer. In many cases, the user will not see the difference between different font-weight settings because the system will choose the closest match, which may be the same as the font-weight setting that was previously set on the element.

Setting the font-weight to 400 is equivalent to normal. Setting the font-weight to 700 is equivalent to bold. A font-weight of bolder or lighter is interpreted relative to the parent element's weight. A value of bolder for text whose parent is normal would set the text to bold.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

font-weight


form

Description

Returns a reference to the form the element is embedded on.

Syntax

object.form

Remarks

Returns null if the element is not on a form.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

APPLET, BUTTON, EMBED, FORM, INPUT, OBJECT, OPTION, SELECT, TEXTAREA


frame

Description

Controls the appearance of the border frame around the table.

Syntax

object.frame[ = frame]

Settings

Possible values include;
above | Displays a border on the top side of the border frame.
below | Displays a border on the bottom side of the table frame.
border | Displays a border on all sides of the table frame.
box | Displays a border on all sides of the table frame.
hsides | Displays a border on the top and bottom sides of the table frame.
lhs | Displays a border on the left side of the table frame.
rhs | Displays a border on the right side of the table frame.
void | Removes all outside table borders.
vsides | Displays a border on the left and right sides of the table frame.

Remarks

The default value for this property is void, that is, display no borders.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TABLE

See Also

rules


frameBorder

Description

Specifies whether or not to display a border for the frame.

Syntax

object.frameBorder[ = frameBorder]

Remarks

Valid values are 0 and 1, with 0 specifying no border and 1 specifying an inset border. In addition, "Yes" and "No" are supported corresponding to 1 and 0, respectively. Invalid settings default to turning on borders.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAME, FRAMESET, IFRAME


frameSpacing

Description

Creates additional space between the frames, in pixels.

Syntax

object.frameSpacing[ = frameSpacing]

Remarks

The amount defined for frameSpacing does not include the width of the frame border. Frame spacing can be set on one or more FRAMESET elements and applies to the contained FRAMESET elements unless the contained FRAMESET defines a different frame spacing.

The default spacing is 2 pixels.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAMESET, IFRAME


fromElement

Description

Specifies the element being moved from the onmouseover and onmouseout events.

Syntax

object.fromElement

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


hash

Description

Sets or returns the subsection of the href property that follows the # symbol.

Syntax

object.hash[ = hash]

Remarks

If there is no hash, this property returns an empty string.

This property is useful for moving to a bookmark within a document. Assigning an invalid value does not cause an error.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, location


height

Description

Returns the vertical resolution of the screen, in pixels.

Syntax

object.height

Remarks

This property has read-only permission.

Applies To

screen


height

Description

Sets or retrieves the height of the element.

Syntax

object.style.height[ = height]

Remarks

The value of this read/write property is a string consisting of a floating-point number and a units designator, as described for cascading style sheets.

To carry out operations on the numeric value of this property, use pixelHeight or posHeight.

Percentage values are based on the width of the parent element. When scripting the height property, use either the pixelHeight or posHeight property for numeric manipulation of a height value.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

HTML Tags | APPLET, DIV, EMBED, FIELDSET, HR, IFRAME, IMG, INPUT, INPUT type=button, MARQUEE, OBJECT, SPAN, TABLE, TEXTAREA
Scripting | style

CSS Attribute

height


height

Description

Sets or retrieves the height of the element.

Syntax

object.height

Remarks

Percentage values are based on the width of the parent element. When scripting the height property, use either the pixelHeight or posHeight property for numeric manipulation of a height value.

This property specifies the calculated height of the element, in pixels. For table rows and table cells, this property has a range of 0 to 32750 pixels.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

The scripting property is read/write for the IMG element, but read-only for other elements.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

EMBED, FRAME, IMG, MARQUEE, OBJECT, TABLE

See Also

width


hidden

Description

Forces the embedded element to be invisible.

Syntax

object.Hidden[ = Hidden]

Remarks

This property has read-write permissions.

Applies To

EMBED


host

Description

Sets or retrieves the hostname:port part of the location or URL.

Syntax

object.host[ = host]

Settings

This read-write property is the concatenation of the hostname and port properties, separated by a colon. When the port property is null, the host property is the same as the hostname property.

You can set the host property at any time, although it is safer to set the href property to change a location. If the host that you specify cannot be found, you will get an error.

Applies To

A, AREA, location


hostname

Description

Specifies the host name part of the location or URL.

Syntax

object.hostname[ = hostname]

Remarks

If no host name is available, this property returns an empty string.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, location


href

Description

Returns a string specifying the URL of the linked style sheet, if the style sheet is a LINK. If the style sheet is a STYLE, the property returns NULL.

Syntax

object.href[ = href]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

styleSheet


href

Description

Specifies the destination URL or anchor point.

Syntax

object.href[ = href]

Remarks

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's identification attribute.

When specifying an anchor, everything between the <A HREF..> and the A becomes a clickable link to that address.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, IMG LINK


href

Description

Specifies the baseline URL that relative links will be based on.

Syntax

object.href[ = href]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BASE


href

Description

Returns the entire URL as a string.

Syntax

object.HREF[ = href]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

location

See Also

navigate method


hspace

Description

Specifies the horizontal margin for the element.

Syntax

object.hspace[ = hspace]

Remarks

This property is similar to border, except the margins are not painted with color when the element is a link.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IFRAME, IMG, MARQUEE

See Also

border, vspace


htmlFor

Description

Specifies which element is being bound to the event script. This property corresponds to the HTML FOR= attribute.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Syntax

object.htmlFor

Applies To

SCRIPT


htmlFor

Description

Specifies which control-like element to assign the given label element to. This property corresponds to the HTML FOR= attribute.

Syntax

object.htmlFor[ = htmlFor]

Remarks

This property references the identifier of another element.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

LABEL


htmlText

Description

Returns the HTML source as a valid HTML fragment.

Syntax

object.htmlText

Remarks

This property corresponds to the fragment portion of the CF_HTML clipboard format.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

This feature may not be available on non-Win32® platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


httpEquiv

Description

Binds the content of the element to an HTTP response header.

Syntax

object.http-Equiv[ = http-Equiv]

Remarks

If omitted, the name property should be used to identify the meta-information. The httpEquiv property is not case sensitive.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

META

See Also

content


id

Description

Returns a string identifying the object.

Syntax

object.id

Remarks

To be used in scripts, the identifier can be any alphanumeric string that begins with a letter. Valid special characters include the underbar, "_".

The id should be unique throughout the scope of the current document. If a document contains more than one object with the same identifier, the objects are exposed as a collection that can only be referenced by ordinal position.

This property has read-only permission.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP, styleSheet


indeterminate

Description

Changes the user interface of a check box to have a dimmed background to represent an indeterminate state. When indeterminate is set, the check box will appear checked, but dimmed. The value of indeterminate is independent of the values for the checked and the status properties.

Syntax

object.indeterminate[ = indeterminate]

Settings

This read-write property is TRUE if the check box is dimmed, or FALSE otherwise. The default value for this property is FALSE.

This property does not remove whether the element is checked and is different than disabling the control. A check box in the indeterminate state can still receive the focus. When the user clicks an indeterminate button, the indeterminate state is turned off and the check box is appropriately checked or unchecked.

Applies To

INPUT


index

Description

Returns the ordinal position of the option in the list box.

Syntax

object.index

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OPTION


innerHTML

Description

Sets or retrieves the HTML between the start and end tags of the current element.

Syntax

object.innerHTML[ = innerHTML]

Settings

This read-write property takes a string containing a valid combination of text and HTML tags, except for <html>, <head>, and <title> tags.

When setting this property, the given string completely replaces the existing content of the element. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.

Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.

Applies To

A, ACRONYM, ADDRESS, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, I, IFRAME, IMG, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PRE, Q, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TH, TT, U, UL, VAR

See Also

insertAdjacentHTML method


innerText

Description

Sets or retrieves the text between the start and end tags of the current element.

Syntax

object.innerText[ = innerText]

Settings

This read-write property can be any valid string. When setting this property, the given string completely replaces the existing content of the element, except for <html>, <head>, and <title> tags.

Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.

Applies To

A, ACRONYM, ADDRESS, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, I, IFRAME, IMG, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TD, TEXTAREA, TH, TITLE, TT, U, UL, VAR, XMP

See Also

insertAdjacentText method


isMap

Description

Identifies the picture as a server-side image map.

Syntax

object.isMap[ = isMap]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IMG


isTextEdit

Description

Specifies whether a text range object can be created using the given element.

Syntax

object.isTextEdit

Settings

The value of this read-only property is TRUE if a text range can be created, or FALSE otherwise.

Only the BODY, BUTTON, and TEXTAREA elements and an INPUT element having text type can be used to create a text range object.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


keyCode

Description

Specifies the Unicode key code associated with the key that caused the event. This property is intended to be used with the onkeydown, onkeyup, and onkeypress events.

Syntax

object.keyCode[ = keyCode]

Settings

This read-write property can be set to a Unicode key code. It is zero if no key caused the event.

Applies To

event


lang

Description

Specifies the language to use. The specifier is an ISO standard language abbreviation.

Syntax

object.lang[ = lang]

Remarks

The parser can use this property to determine how to display language-specific choices for quotations, numbers, and so on.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


language

Description

Specifies the language that the current script is written in. JScript is the default for this attribute.

Syntax

object.language

Settings

This read-only property can refer to any scripting language. Internet Explorer 4.0 ships with a JScript (JavaScript-compatible) and VBScript scripting engine. Keywords for accessing these scripting languages include the following:

javascript | Specifies that the script is written in JavaScript.
Jscript | Specifies the language as JavaScript.
vbs | Specifies the language as VBScript.
vbscript | Specifies that the script is written in VBScript.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


lastModified

Description

Contains the last-modified date of the page (if the page supplies one).

Syntax

object.lastModified

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

document


left

Description

Sets or retrieves the position of the element relative to the left edge of the document.

Syntax

object.style.left[ = left]

Remarks

The value of this read/write property is a string consisting of a floating-point number and a units designator, as described for cascading style sheets.

For more information about how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

left

See Also

pixelLeft, posLeft


leftMargin

Description

Specifies the left margin for the entire body of the page and overrides the default margin.

Syntax

object.leftMargin[ = leftMargin]

Settings

This read-write property is a string. If set to "", the left margin will be exactly on the left edge.

Applies To

BODY

See Also

topMargin


length

Description

Returns the number of elements in a collection. The window.length property returns the number of frames contained in a window.

Syntax

object.length

Remarks

This property is read-write on the areas and options collections and <SELECT> object, specifically for image maps and select boxes, respectively. This allows you to change the length of the collection as necessary.

In all other cases, this property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

all, anchors, applets, areas, embeds, forms, frames, history, images, imports, links, plugins, scripts, SELECT, styleSheets, window

See Also

options collection


letterSpacing

Description

Sets or retrieves the amount of additional space between letters in the element.

Syntax

object.letterSpacing[ = letterSpacing]

Remarks

The attribute will add the appropriate letter spacing after each character. If you do not want the end of a word to be affected by the spacing, you need to place the last character outside the closing element tag. Letter spacing can be influenced by justification. Negative values are permitted.

This property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

letter-spacing


lineHeight

Description

Sets or retrieves the distance between lines in a paragraph.

Syntax

object.style.lineHeight[ = lineHeight]

Remarks

Line height is the distance between the descender of the font to the top of the internal leading of the font. A negative line height is allowed to achieve various shadowing effects.

If there is more than one element on a formatted line, the maximum line height applies. Negative values are not allowed.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

line-height


link

Description

Sets or retrieves the color of the document links.

Syntax

object.style.link[ = color]

Remarks

The color can be one of the color names or values given in Color Table.

This is the color used when the link has not been visited, is not actively being navigated, and does not have a mouse positioned over it. Setting the hover pseudo-class is often used in conjunction with setting specific styles for the other states of a link: active, visited, and hover.

The property has read/write permission.

Applies To

body

See Also

aLink, vLink


linkColor

Description

Returns the color of the document links. The color can be one of the color names or values given in Color Table.

Syntax

object.linkColor[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document

See Also

alinkColor, vlinkColor


listStyle

Description

Sets or retrieves these three properties at once: listStyleType, listStyleImage, and listStylePosition.

Syntax

object.style.listStyle[ = listStyle]

Remarks

This shorthand property can specify both a URL and a list-style-type, which will be used if the URL is not found.

The property has read/write permission.

Applies To

HTML Tags | LI, OL, UL
Scripting | style

CSS Attribute

list-style


listStyleImage

Description

Sets or retrieves which image to use as a list-item marker.

Syntax

object.style.listStyleImage[ = listStyleImage]

Remarks

When the image is available, it will replace the marker set with the listStyleType marker. The default value for this property is none.

The property has read/write permission.

Applies To

HTML Tags | LI, OL, UL
Scripting | style

CSS Attribute

list-style-image


listStylePosition

Description

Sets or retrieves how the list-item marker is drawn with regard to the element's content.

Syntax

object.style.listStylePosition[ = listStylePosition]

Remarks

This property is applicable only on elements with a display value of list-item.

The property has read/write permission.

Applies To

HTML Tags | LI, OL, UL
Scripting | style

CSS Attribute

list-style-position


listStyleType

Description

Sets or returns the type of predefined line-item marker.

Syntax

object.style.listStyleType[ = listStyleType]

Remarks

This property determines the appearance of the list-item marker if listStyleImage is none or if the image pointed to by the URL cannot be displayed. The default value is disc.

The property has read/write permission.

Applies To

HTML Tags | LI, OL, UL
Scripting | style

CSS Attribute

list-style-type


location

Description

Returns information on the current URL. The href property contains the entire URL, and the other properties contain portions of it. The full list of properties includes hash, host, hostname, href, pathname, port, protocol, and search.

Syntax

object.location[ = location]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document


loop

Description

Specifies how many times a sound or video will loop when activated. If applied to a marquee, it specifies how many times the content of the marquee should loop. If n=-1 or infinite, it will loop continuously.

Syntax

object.loop[ = loop]

Remarks

Following are descriptions on how loop works for some boundary cases.

<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BGSOUND, IMG, MARQUEE


lowsrc

Description

Specifies a lower resolution image to display.

Syntax

object.lowsrc[ = lowsrc]

Remarks

Setting the src attribute in code has the side effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, if you're going to alter the lowsrc property, you need to do so before setting the src property. If the URL in the src property references an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IMG


map

Description

Sets or returns the element representing the image map.

Syntax

object.map[ = map]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IMG


margin

Description

Retrieves the width of the left and right margins and the height of the top and bottom margins.

Syntax

object.style.margin

Remarks

The property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

margin


marginBottom

Description

Retrieves the height of the bottom margin for the element.

Syntax

object.style.marginBottom

Remarks

Negative margins are supported except for top and bottom margins on inline elements.

The property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

margin-bottom


marginHeight

Description

Sets the top and bottom margins to the appropriate height before displaying the text in a frame.

Syntax

object.marginHeight[ = marginHeight]

Remarks

The value for the margin height is in pixels. Margins cannot be less than 1 nor so large that the text cannot be displayed.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAME, IFRAME

See Also

marginWidth


marginLeft

Description

Retrieves the width of the left margin for the element.

Syntax

object.style.marginLeft

Remarks

Negative margins are supported except for top and bottom margins on inline elements.

This property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

margin-left


marginRight

Description

Retrieves the width of the right margin for the element.

Syntax

object.style.marginRight

Remarks

The property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TEXTAREA, TD, TH, TR, UL, XMP
Scripting | style

CSS Attribute

margin-right


marginTop

Description

Retrieves the height of the top margin for the element.

Syntax

object.style.marginTop

Remarks

Negative margins are supported except for top and bottom margins on inline elements.

The property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TD, TEXTAREA, TH, TR, UL, XMP
Scripting | style

CSS Attribute

margin-top


marginWidth

Description

Sets or retrieves the amount the left and right margin should be set to before displaying the text in a frame.

Syntax

object.marginWidth[ = marginWidth]

Remarks

The value for margin width is in pixels. Margins cannot be less than 1 nor so large that the text cannot be displayed.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAME, IFRAME

See Also

marginHeight


maxLength

Description

Indicates the maximum number of characters that can be entered into a text control. This limits the user entry, not programmatic assignments to the value property.

Syntax

object.maxLength[ = maxLength]

Remarks

This value can be larger than the size of the text box. When this occurs, the text box should scroll accordingly as the user types. The default is no limit.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

INPUT

See Also

size


media

Description

Sets the media type through the STYLE and LINK elements.

Syntax

object.media[ = media]

Parameter | Description
MEDIA | Designed for rendering on these media. Default value is ALL.
SCREEN - Output is intended for nonpaged computer screens.
PRINT - Output is intended for paged, opaque material and for documents on screen viewed in print preview mode.
ALL - Applies to all devices.

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

LINK, STYLE


method

Description

Indicates how the form data should be sent to the server—either as GET or POST, which are the only legal values.

Syntax

object.method[ = method]

Settings

Possible values include;
get | Append the arguments to the action URL and open it as if it were an anchor.
post | Send the data through an HTTP post transaction.

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FORM

See Also

action


Methods

Description

Specifies information about the functions that the user can perform on an object.

Syntax

object.Methods[ = Methods]

Remarks

These methods are more accurately given by the HTTP protocol when it is used, but it might, for reasons similar as for the title property, be useful to include the information in advance in the link. The HTML user agent can chose a different rendering as a function of the methods allowed; for example, something that is searchable might get a different icon.

The value of the property is a comma-separated list of HTTP methods supported by the object for public use.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A


mimeTypes

Description

Returns an empty collection for Internet Explorer 4.0. This property exists for compatibility with other browsers.

Syntax

object.mimeTypes

Remarks

This property has read-only permission.

Applies To

navigator


multiple

Description

Indicates that multiple items in the list can be selected.

Syntax

object.multiple[ = multiple]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

SELECT


name

Description

Specifies the name of a window or the frame so it can be targeted from links in other documents.

Syntax

object.name[ = sName]

Settings

This read/write property takes either a window name or frame name, or one of these special values:

window_name | A string that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

Remarks

An exception to the rule, the window keyword must be used to access the name property.

Examples

The following code shows the name property being assigned to the window object.

window.name="MyWindow";

The name property on the window frequently comes from the FRAME definition.

parent.frames[0].name="Left";

The NAME attribute for a window can only be persisted in HTML when defined in a frame within a frameset.

<FRAMESET>
   <FRAME NAME="Left" SRC="blank.htm">
</FRAMESET>

The name property can be assigned using the window open method.

window.open("file.htm","Frame1");

Applies To

FRAME, IFRAME, window


name

Description

Specifies the name of the control, bookmark, or application.

Syntax

object.name[ = name]

Remarks

The name is used to bind the value of the control when submitting a form. The name is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not cause the name in the programming model to change in the collection of elements, but does change the name used for submitting elements.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, APPLET, BUTTON, FORM, IMG, INPUT, LINK, MAP, META, OBJECT, SELECT, TEXTAREA


noHref

Description

Indicates that clicks in this region should cause no action.

Syntax

object.noHref[ = noHref]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

AREA


noResize

Description

Specifies whether the user can resize the frame.

Syntax

object.noResize[ = noResize]

Settings

This read-write property takes a Boolean value:

TRUE | Frame size is fixed. User cannot resize it.
FALSE | Frame is resizable. This is the default value for the property.

By default, all frames are resizable.

Applies To

FRAME, IFRAME


noShade

Description

Draws the horizontal rule without 3-D shading.

Syntax

object.noShade[ = noShade]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

HR


noWrap

Description

Prevents the browser from automatically performing word wrap.

Syntax

object.noWrap[ = noWrap]

Remarks

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BODY, DD, DIV, DT, TD, TH


object

Description

References the contained object. For instance, if the control's object model uses a conflicting name space, preceding the control's property with object resolves the conflict.

Syntax

object.object

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT


offscreenBuffering

Description

Specifies whether to use offscreen buffering. When the document is first loaded the value is a string, "auto", which allows Internet Explorer 4.0 to decide when offscreen buffering is used.

Syntax

object.offscreenBuffering[ = Boolean]

Settings

This read-write property can be set to TRUE to enable offscreen buffering, and FALSE to disable it. The return type of the property, once it has been set, is a Boolean value.

Applies To

window


offsetHeight

Description

Returns the height of the element, in pixels, relative to the parent coordinate system.

Syntax

object.offsetHeight

Remarks

Using a combination of offset* properties, you can determine the location, width, and height of an element by using the offsetLeft, offsetTop, offsetHeight, and offsetWidth properties. These numeric properties specify the physical coordinates and dimensions of the element relative to the element's offset parent. For example, the following document is a simple clock that adjusts the size of its readout to fit the current width and height of the document body.

<HTML>
<HEAD><TITLE>A Simple Clock</TITLE>
<SCRIPT LANGUAGE="JScript">
function startClock() {
    window.setInterval("Clock_Tick()", 1000);
    Clock_Tick();
}

var ratio = 4;
function Clock_Tick()
{
    var s = Date();
    var t = s.substring(11,19);
    var doc_height = document.body.offsetHeight;
    var doc_width = document.body.offsetWidth;

    if ((doc_height*ratio)>doc_width)
        doc_height = doc_width / ratio;
    document.all.MyTime.innerText = t;
    document.all.MyTime.style.fontSize = doc_height;
}
</SCRIPT>
<BODY onload="startClock()">
<P ID="MyTime">&nbsp;</P>
</BODY>
</HTML>

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


offsetLeft

Description

Returns the calculated left position, in pixels, based on the window.

Syntax

object.offsetLeft

Remarks

Using a combination of offset* properties, you can determine the location, width, and height of an element by using the offsetLeft, offsetTop, offsetHeight, and offsetWidth properties. These numeric properties specify the physical coordinates and dimensions of the element relative to the element's offset parent. For example, the following document is a simple clock that adjusts the size of its readout to fit the current width and height of the document body.

<HTML>
<HEAD><TITLE>A Simple Clock</TITLE>
<SCRIPT LANGUAGE="JScript">
function startClock() {
    window.setInterval("Clock_Tick()", 1000);
    Clock_Tick();
}

var ratio = 4;
function Clock_Tick()
{
    var s = Date();
    var t = s.substring(11,19);
    var doc_height = document.body.offsetHeight;
    var doc_width = document.body.offsetWidth;

    if ((doc_height*ratio)>doc_width)
        doc_height = doc_width / ratio;
    document.all.MyTime.innerText = t;
    document.all.MyTime.style.fontSize = doc_height;
}
</SCRIPT>
<BODY onload="startClock()">
<P ID="MyTime">&nbsp;</P>
</BODY>
</HTML>

This property has read-only permission.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TextRange, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


offsetParent

Description

Returns a reference to the container element that defines the top and left offsets for the object.

Syntax

object.offsetParent

Remarks

The offsetLeft and offsetTop property values are relative to the element specified by the offsetParent property for the element. Most of the time the property returns BODY. For example, in the following document, even though the TD element appears to the far right in the document, its position is (0,0) because its offset parent is TR, not the document body.

<HTML>
<HEAD><TITLE>Elements: Positions</TITLE></HEAD>
<SCRIPT LANGUAGE="JScript">
function showPosition() {
    var el = document.all.MyID;
    alert("The TD element is at (" + el.offsetLeft + "," + el.offsetTop + ")\n" +
     "The offset parent is " + el.offsetParent.tagName );
}
</SCRIPT>
<BODY onload="showPosition()">
<P>This document contains a right-aligned table.
<TABLE BORDER=1 ALIGN=right>
<TR><TD ID=MyID>This is a small table
</TABLE>
</BODY>
</HTML>

This property has read-only permission.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


offsetTop

Description

Returns the calculated top position of the element in the element's parent coordinates.

Syntax

object.offsetTop

Remarks

Using a combination of offset* properties, you can determine the location, width, and height of an element by using the offsetLeft, offsetTop, offsetHeight, and offsetWidth properties. These numeric properties specify the physical coordinates and dimensions of the element relative to the element's offset parent. For example, the following document is a simple clock that adjusts the size of its readout to fit the current width and height of the document body.

<HTML>
<HEAD><TITLE>A Simple Clock</TITLE>
<SCRIPT LANGUAGE="JScript">
function startClock() {
    window.setInterval("Clock_Tick()", 1000);
    Clock_Tick();
}

var ratio = 4;
function Clock_Tick()
{
    var s = Date();
    var t = s.substring(11,19);
    var doc_height = document.body.offsetHeight;
    var doc_width = document.body.offsetWidth;

    if ((doc_height*ratio)>doc_width)
        doc_height = doc_width / ratio;
    document.all.MyTime.innerText = t;
    document.all.MyTime.style.fontSize = doc_height;
}
</SCRIPT>
<BODY onload="startClock()">
<P ID="MyTime">&nbsp;</P>
</BODY>
</HTML>

This property has read-only permission.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TextRange, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


offsetWidth

Description

Returns the width of the element relative to the document's top-left corner.

Syntax

object.offsetWidth

Remarks

Using a combination of offset* properties, you can determine the location, width, and height of an element by using the offsetLeft, offsetTop, offsetHeight, and offsetWidth properties. These numeric properties specify the physical coordinates and dimensions of the element relative to the element's offset parent. For example, the following document is a simple clock that adjusts the size of its readout to fit the current width and height of the document body.

<HTML>
<HEAD><TITLE>A Simple Clock</TITLE>
<SCRIPT LANGUAGE="JScript">
function startClock() {
    window.setInterval("Clock_Tick()", 1000);
    Clock_Tick();
}

var ratio = 4;
function Clock_Tick()
{
    var s = Date();
    var t = s.substring(11,19);
    var doc_height = document.body.offsetHeight;
    var doc_width = document.body.offsetWidth;

    if ((doc_height*ratio)>doc_width)
        doc_height = doc_width / ratio;
    document.all.MyTime.innerText = t;
    document.all.MyTime.style.fontSize = doc_height;
}
</SCRIPT>
<BODY onload="startClock()">
<P ID="MyTime">&nbsp;</P>
</BODY>
</HTML>

This property has read-only permission, meaning you can retrieve its current value, but not change it.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


offsetX

Description

Returns container relative positions. These match the offsetLeft and offsetTop properties of the element. Use offsetParent to find the container element that defines this coordinate system.

Syntax

object.offsetX

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


offsetY

Description

Returns container relative positions. These match the offsetLeft and offsetTop properties of the element. Use offsetParent to find the container element that defines this coordinate system.

Syntax

object.offsetY

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


onLine

Description

Indicates whether or not the system is in global offline mode.

Syntax

object.onLine

Remarks

True indicates the system is in global online mode. False indicates the system is in global offline mode. This property has read-only permission, meaning you can retrieve its current value, but not change it.

The user can modify the global offline state by selecting the Work Offline item from the Internet Explorer 4.0 File menu. This property does not indicate whether or not the system is physically connected to the network.

Applies To

navigator


opener

Description

Returns a reference to the window that created the current window.

Syntax

object.opener[ = opener]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

window


outerHTML

Description

Sets or retrieves the current element and its content in HTML.

Syntax

object.outerHTML[ = outerHTML]

Settings

This read-write property can be any valid string containing a combination of text and HTML tags, except for <html>, <head>, and <title> tags.

When setting this property, the given string completely replaces the element, including its start and end tags. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.

Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BGSOUND, BIG, BLOCKQUOTE, BR, BUTTON, CENTER, CITE, CODE, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP

See Also

insertAdjacentHTML method


outerText

Description

Sets or retrieves the text of the current element.

Syntax

object.outerText[ = outerText]

Settings

This read-write property can be any valid string. When setting this property, the given string completely replaces the original text in the element, except for <html>, <head>, and <title> tags.

Note You cannot set this property while the document is loading. Wait for the onload event before attempting to set it. If a tag is dynamically created using TextRange, innerHTML, or outerHTML, you can only use JScript to create new events to handle the newly formed tags. VBScript is not supported.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BGSOUND, BIG, BLOCKQUOTE, BR, BUTTON, CENTER, CITE, CODE, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP

See Also

insertAdjacentText method


overflow

Description

Sets or retrieves what should be done when the element's content exceeds the height and/or width of the element.

Syntax

object.style.overflow[ = overflow]

Remarks

This property applies to positioned elements. By default, overflowing content is visible. This means the element does not observe its specified height and width. If the attribute is set to scroll, the content is clipped to the height and width specified on the element, and the overflowing content is accessible through scroll bars. If the attribute is set to hidden, the content of the element is clipped to the height and width of the element, and no scroll bars appear to access the hidden content.

For the TEXTAREA element, only the hidden value is valid. Setting the overflow to hidden on a TEXTAREA element hides its scroll bars.

The scripting property has read/write permission.

Applies To

HTML Tags | DIV, FIELDSET, SPAN, TEXTAREA
Scripting | style

CSS Attribute

overflow


owningElement

Description

Returns the element that is next in the HTML hierarchy. This will usually contain the STYLE or LINK element that defined the style sheet.

Syntax

object.owningElement

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

styleSheet


padding

Description

Sets or retrieves paddingTop, paddingBottom, paddingLeft, and paddingRight in one style sheet rule.

Syntax

object.style.padding[ = padding]

Remarks

Padding describes how much space to insert between the element and its margin, or if there is a border, between the element and its border.

This is a composite property. Up to four values can be specified. The order is top, right, bottom, left. If there is only one value, it applies to all sides; if there are two or three, the missing values are taken from the opposite side. Negative values are not allowed.

The property has read/write permission.

Applies To

HTML Tags | BODY, CAPTION, DIV, IFRAME, MARQUEE, TABLE, TD, TEXTAREA, TR
Scripting | style

CSS Attribute

padding


paddingBottom

Description

Sets or retrieves the height of the padding at the bottom of the element.

Syntax

object.style.paddingBottom[ = paddingBottom]

Remarks

The property has read/write permission.

Applies To

HTML Tags | BODY, CAPTION, DIV, IFRAME, MARQUEE, TABLE, TD, TEXTAREA, TR
Scripting | style

CSS Attribute

padding-bottom


paddingLeft

Description

Sets or retrieves the width of the padding at the left edge of the element.

Syntax

object.style.paddingLeft[ = paddingLeft]

Remarks

This property has read/write permission.

Applies To

HTML Tags | BODY, CAPTION, DIV, IFRAME, MARQUEE, TABLE, TD, TEXTAREA, TR
Scripting | style

CSS Attribute

padding-left


paddingRight

Description

Sets or retrieves the width of the padding at the right edge of the element.

Syntax

object.style.paddingRight[ = paddingRight]

Remarks

This property has read/write permission.

Applies To

HTML Tags | BODY, CAPTION, DIV, IFRAME, MARQUEE, TABLE, TD, TEXTAREA, TR
Scripting | style

CSS Attribute

padding-right


paddingTop

Description

Sets or retrieves the height of the padding at the top of the element.

Syntax

object.style.paddingTop[ = paddingTop]

Remarks

This property has read/write permission.

Applies To

HTML Tags | BODY, CAPTION, DIV, IFRAME, MARQUEE, TABLE, TD, TEXTAREA, TR
Scripting | style

CSS Attribute

padding-top


pageBreakAfter

Description

Sets or retrieves whether a page break occurs after the element and on which page (left or right) the subsequent content should resume.

Syntax

object.style.pageBreakAfter[ = pageBreakAfter]

Remarks

This property applies when printing the document.

The values are defined as follows:
auto | Insert a page break after the element only if necessary.
always | Always insert a page break after the element.
left | Insert one or two page breaks after the element until a blank left page is reached.
right | Insert one or two page breaks after the element until a blank right page is reached.

If there are conflicts between this property and the page-break-before value on the previous element (as formatted on the canvas), the value that results in the largest number of page breaks will be used.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, UL, XMP
Scripting | style

CSS Attribute

page-break-after


pageBreakBefore

Description

Sets or retrieves whether a page break occurs before the element and on which page (left or right) the subsequent content should resume.

Syntax

object.style.pageBreakBefore[ = pageBreakBefore]

Remarks

This property applies when printing the document.

The values are defined as follows:
auto | Insert a page break before the element only if necessary.
always | Always insert a page break before the element.
left | Insert one or two page breaks before the element until a blank left page is reached.
right | Insert one or two page breaks before the element until a blank right page is reached.

If there are conflicts between this property and the page-break-after value on the next element (as formatted on the canvas), the value that results in the largest number of page breaks will be used.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, UL, XMP
Scripting | style

CSS Attribute

page-break-before


palette

Description

Specifies the palette used for the embedded document.

Syntax

object.palette

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

EMBED


parent

Description

Returns the parent object in the object hierarchy.

Syntax

object.parent

Remarks

For a document, the parent is the containing window. For a window defined using FRAME, the parent is the window that contains the corresponding FRAMESET definition.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

window


parentElement

Description

Returns the parent element in the element hierarchy.

Syntax

object.parentElement

Remarks

The topmost element returns NULL as its parent.

This is a read-only property.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


parentStyleSheet

Description

Returns the style sheet that was used for importing style sheets. If a style sheet is at the top level (that is, it's a LINK or STYLE), parentStyleSheet returns NULL.

Syntax

object.parentStyleSheet

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

styleSheet


parentTextEdit

Description

Returns the next element in the hierarchy that can be used to create a text range that contains the original element.

Syntax

object.parentTextEdit

Settings

This read-only property is an element object if the parent exists. Otherwise, it is null.

Example

The following example retrieves the parent element (if needed), creates the text range, moves to the original element, and selects the first word in the element.

<SCRIPT LANGUAGE="JScript">
function selectWord() {
    var el = window.event.srcElement ;
    if (!el.isTextEdit)
        el = window.event.srcElement.parentTextEdit;
    if (el != null) {
        var rng = el.createTextRange();
        rng.moveToElementText(window.event.srcElement);
        rng.collapse();
        rng.expand("word");
        rng.select();
    }
}
</SCRIPT>

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


parentWindow

Description

Returns the window object for the document.

Syntax

object.parentWindow

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

document


pathname

Description

Specifies the file or object path.

Syntax

object.pathname[ = pathname]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, location


pixelHeight

Description

Sets or retrieves the height of the element, in pixels. Unlike the height property, this property's value is an integer, not a string, and is always interpreted in pixels.

Syntax

object.pixelHeight[ = pixelHeight]

Settings

This read-write property can be any integer value. Setting this property changes the value of the height without changing the units designator.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

style

CSS Attribute

height

See Also

posHeight


pixelLeft

Description

Sets or retrieves the left position of the element, in pixels. Unlike the left property, this property's value is an integer, not a string, and is always interpreted in pixels.

Syntax

object.pixelLeft[ = pixelLeft]

Settings

This read-write property can be any integer value. Setting this property changes the value of the left position without changing the units designator.

Remarks

This property reflects the value of the CSS left attribute for positioned items. This property always returns zero for nonpositioned items since left does not mean anything unless the object is positioned. Use the offsetLeft property to calculate actual positions within the document area.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

style

CSS Attribute

left

See Also

posLeft


pixelTop

Description

Sets or retrieves the top position of the element, in pixels. Unlike the top property, this property's value is an integer, not a string, and is always interpreted in pixels.

Syntax

object.pixelTop[ = pixelTop]

Settings

This read-write property can be any integer value. Setting this property changes the value of the top position without changing the units designator.

Remarks

This property reflects the value of the CSS top attribute for positioned items. This property always returns zero for nonpositioned items since top does not mean anything unless the object is positioned. Use the offsetTop property to calculate actual positions within the document area.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

style

CSS Attribute

top

See Also

posTop


pixelWidth

Description

Sets or retrieves the width of the element, in pixels. Unlike the width property, this property's value is an integer, not a string, and is always interpreted in pixels.

Syntax

object.pixelWidth[ = pixelWidth]

Settings

This read-write property can be any integer value. Setting this property changes the value of the height without changing the units designator.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

style

CSS Attribute

width

See Also

posWidth


platform

Description

Indicates the platform that the browser is running on (for example, Win32®, Win16, WinCE, and so on).

Syntax

object.platform

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


plugins

Description

Returns an empty collection for Internet Explorer 4.0. This property exists for compatibility with other browsers.

Syntax

object.plugins

Remarks

This property has read-only permission.

Applies To

navigator


pluginspage

Description

Specifies the plug-ins supporting this embedded document.

Syntax

object.pluginspage

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

EMBED


port

Description

Specifies the port number in a URL.

Syntax

object.port[ = port]

Remarks

If no port is specified, an empty string is returned.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, location


posHeight

Description

Sets and retrieves the height of the element in the units specified by the CSS height attribute. Unlike the height property, this property's value is a floating-point number, not a string.

Syntax

object.posHeight[ = posHeight]

Settings

This read-write property takes any valid floating-point number. Setting this property changes the value of the height but leaves the units designator for the property unchanged.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Example

The following JScript example increases the height of the first IMG element by 10 units.

document.all.tags("IMG").item(0).style.posHeight += 10;

Applies To

style

CSS Attribute

height

See Also

pixelHeight


position

Description

Retrieves the type of positioning used for the element.

Syntax

object.style.position

Remarks

The default is static, which means there is no special positioning, and the element obeys the layout rules of HTML.

An absolutely positioned element is always relative to either the next positioned parent or, if there isn't one, the BODY by default. Values for left and top are relative to the upper-left corner of the next positioned element in the hierarchy. Be sure to note the Applies To listings for elements that can be relatively and absolutely positioned.

See Positioning for an overview on how to use dynamic positioning.

The property has read-only permission.

Applies To

HTML Tags

For position:absolute

APPLET, DIV, EMBED, FIELDSET, HR, IFRAME, IMG, INPUT, INPUT type=button, OBJECT, MARQUEE, SELECT, SPAN, TABLE, TEXTAREA

For position:relative

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP

Scripting style

CSS Attribute

position


posLeft

Description

Sets and retrieves the left position of the element in the units specified by the CSS left attribute. Unlike the left property, this property's value is a floating-point number, not a string.

Syntax

object.posLeft[ = posLeft]

Settings

This read-write property takes any valid floating-point number. Setting this property changes the value of the left position but leaves the units designator for the property unchanged.

Remarks

This property reflects the value of the CSS left attribute for positioned items. This property always returns zero for nonpositioned items since left does not mean anything unless the object is positioned. Use the offsetLeft property to calculate actual positions within the document area.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Example

The following JScript example moves the first IMG element to the left by 10 units.

document.all.tags("IMG").item(0).style.posLeft -= 10;

Applies To

style

CSS Attribute

left

See Also

pixelLeft


posTop

Description

Sets and retrieves the top position of the element in the units specified by the CSS top attribute. Unlike the top property, this property's value is a floating-point number, not a string.

Syntax

object.posTop[ = posTop]

Settings

This read-write property takes any valid floating-point number. Setting this property changes the value of the top position but leaves the units designator for the property unchanged.

Remarks

This property reflects the value of the CSS top attribute for positioned items. This property always returns zero for nonpositioned items since top does not mean anything unless the object is positioned. Use the offsetTop property to calculate actual positions within the document area.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Example

The following JScript example moves the first IMG element up by 10 units.

document.all.tags("IMG").item(0).style.posTop -= 10;

Applies To

style

CSS Attribute

top

See Also

pixelTop


posWidth

Description

Sets and retrieves the width of the element in the units specified by the CSS width attribute. Unlike the width property, this property's value is a floating-point number, not a string.

Syntax

object.posWidth[ = posWidth]

Settings

This read-write property takes any valid floating-point number. Setting this property changes the value of the width but leaves the units designator for the property unchanged.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Example

The following JScript example increases the width of the first IMG element by 10 units.

document.all.tags("IMG").item(0).style.posWidth -= 10;

Applies To

style

CSS Attribute

width

See Also

pixelWidth


protocol

Description

Specifies the initial substring up to and including the first colon, which indicates the URL's access method.

Syntax

object.protocol[ = protocol]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, IMG, location


readOnly

Description

Indicates whether the style sheet can be modified. If a style sheet is obtained through a LINK or an Import tag, the style sheet cannot be modified. The default value is FALSE (cannot be modified).

Syntax

object.readOnly

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

styleSheet


readOnly

Description

Causes the element's contents to be read-only, meaning that the user cannot enter or edit text in the control.

Syntax

object.readOnly[ = readOnly]

Remarks

This is different than disabled. Read-only still allows the element to receive the focus, while disabled does not.

The default value for this property is FALSE.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

INPUT (text and password types only), TEXTAREA


readyState

Description

Specifies the current state of an object being downloaded.

Syntax

object.readyState

Settings

Possible values include:
uninitialized | The object is not initialized with data.
loading | The object is currently loading its data.
interactive | The object can be interacted with even though it is not fully loaded.
complete | The control is completely loaded.

Remarks

Each object can independently determine which of the four states it exposes.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

IMG, LINK, OBJECT, SCRIPT, STYLE, document

See Also

onreadystatechange


reason

Description

Indicates the disposition of data transfer for a data source object.

Syntax

object.reason

Settings

This read-only property is an integer value specifying the reason for completion. It can be one of these values:

0 | Data transmitted successfully.
1 | Data transfer aborted.
2 | Data transfer in error.

Applies To

event


recordNumber

Description

Specifies the ordinal record from the data set that generated the element. Applies to a bound, repeated table.

Syntax

object.recordNumber

Remarks

This property can be used in conjunction with the ADO recordset available from every data source object through the object's recordset property.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BGSOUND, BIG, BLOCKQUOTE, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, Hidden


recordset

Description

Returns the recordset if the object is a data provider.

Syntax

object.recordset

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

OBJECT


referrer

Description

Specifies the URL of the previous location.

Syntax

object.referrer

Remarks

This is only true when the current page has been reached through a link from the previous page. Otherwise, document.referrer will return empty; it will also return empty when the link is from a secure site.

For example, if PageA.htm has a link to PageB.htm, and the user clicks the link on PageA.htm to go to PageB.htm, the document.referrer on PageB.htm will return "PageA.htm". However, if the user is on PageA.htm and types PageB.htm into the address line, or uses Open in the File menu to get to PageB.htm, the document.referrer will return empty.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

document


rel

Description

Specifies the relationship(s) described by the hypertext link from the anchor to the target.

Syntax

object.rel[ = rel]

Remarks

The value is a comma-separated list of relationship values. Values and their semantics will be registered by the HTML registration authority. The default relationship, if none other is given, is void. The rel property is used only when the href property is present.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, LINK


returnValue

Description

Specifies the return value from the modal dialog window.

This property applies only to windows created using the showModalDialog method.

Syntax

object.returnValue[ = Variant]

Applies To

window


returnValue

Description

Specifies the return value from the event.

Syntax

object.returnValue[ = Boolean]

Settings

This read-write property can be either TRUE or FALSE. Setting it to FALSE cancels the default action of the source element of the event.

The value of this property takes precedence over values returned by the function, such as through a return statement.

Applies To

event


rev

Description

Same as the rel property, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor can have both rel and rev properties.

Syntax

object.rev[ = rev]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, LINK


rightMargin

Description

Specifies the right margin for the entire body of the page, and overrides the default margin.

Syntax

object.rightMargin[ = rightMargin]

Settings

This read-write property takes a string value. If set to an empty string (""), the right margin will be exactly on the right edge.

Applies To

BODY


rowIndex

Description

Indicates the element's position in the rows collection that is for the TABLE. This is different from sectionRowIndex, which indicates the element's position in the TBODY, THEAD, or TFOOT rows collection. These sections are mutually exclusive, so the TR is always contained in one of these sections, as well as the TABLE. Collection indexes are in source order of the HTML document.

Syntax

object.rowIndex[ = element]

Return Value

This property has read-only permission.

Applies To

TR

See Also

sectionRowIndex, sourceIndex, cellIndex


rows

Description

Specifies the number of rows tall the text area control should be.

Syntax

object.rows[ = rows]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TEXTAREA


rows

Description

Specifies a comma-delimited list of frames to create. Each item in the list contains the initial size of the row.

Syntax

object.rows[ = rows]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAMESET


rowSpan

Description

Specifies how many rows in a TABLE this cell should span. This property can only be changed after the page has been loaded.

Syntax

object.rowSpan[ = rowSpan]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

TD, TH


rules

Description

Specifies which dividing lines are displayed (inner borders).

Syntax

object.rules[ = rules]

Settings

This read-write property takes one of these string values:

all | Displays a border on all rows and columns.
cols | Displays borders between all table columns.
groups | Displays horizontal borders between all table groups. Groups are specified by the THEAD, TBODY, TFOOT, and COLGROUP elements.
none | Removes all interior table borders.
rows | Displays horizontal borders between all table rows.

The property is not set by default.

Applies To

TABLE, stylesheet

See Also

frame


screenX

Description

Returns coordinates relative to the physical screen size.

Syntax

object.screenX

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


screenY

Description

Returns coordinates relative to the physical screen size.

Syntax

object.screenY

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


scroll

Description

Turns the scroll bars on or off.

Syntax

object.scroll[ = scroll]

Settings

This read-write property can be one of the following strings:

yes | Turns on the scroll bars. This is the default value.
no | Turns off the scroll bars.

Applies To

BODY


scrollAmount

Description

Specifies the number of pixels the text scrolls between each subsequent drawing of the MARQUEE.

Syntax

object.scrollAmount[ = scrollAmount]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

MARQUEE


scrollDelay

Description

Specifies the speed of the MARQUEE scroll, in milliseconds.

Syntax

object.scrollDelay[ = scrollDelay]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

MARQUEE


scrollHeight

Description

Returns the element's scrolling height, in pixels. This is the distance between the top and bottom edges of the element's visible content. The physical height of the content, including the nonvisible content, can be obtained with the offsetHeight property.

Syntax

object.scrollHeight

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Setting

This read-only property is always a nonnegative integer.

Applies To

BODY, BUTTON, DIV, FIELDSET, FRAME, IFRAME, IMG, MARQUEE, SPAN, TEXTAREA

See Also

scrollLeft, scrollTop, scrollWidth


scrolling

Description

Specifies that the frame can be scrolled.

Syntax

object.scrolling[ = scrolling]

Settings

Possible values include;
auto | The browser determines if the scroll bars are necessary.
no | The frame cannot be scrolled.
yes | The frame can be scrolled.

Remarks

The scroll bars default to "auto" if this attribute is omitted.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

FRAME, IFRAME


scrollLeft

Description

Sets or retrieves the distance, in pixels, between the left edge of the element and the leftmost portion of the element that is currently visible in the window. This is equal to the horizontal distance that the content of the element has been scrolled.

Syntax

object.scrollLeft[ = scrollLeft]

Settings

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollWidth if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not support scroll bars. For these elements, setting the property has no effect.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

BODY, BUTTON, DIV, FIELDSET, FRAME, IFRAME, IMG, MARQUEE, SPAN, TEXTAREA

See Also

scrollHeight, scrollTop, scrollWidth


scrollTop

Description

Sets or retrieves the distance, in pixels, between the top of the element and the topmost portion of the content that is currently visible in the window. This is equal to the vertical distance that the content of the element has been scrolled.

Syntax

object.scrollTop[ = scrollTop]

Settings

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollHeight if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not have scroll bars. For these elements, setting the property has no effect.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

BODY, BUTTON, DIV, FIELDSET, FRAME, IFRAME, IMG, MARQUEE, SPAN, TEXTAREA

See Also

scrollHeight, scrollLeft, scrollWidth


scrollWidth

Description

Returns the element's scrolling width, in pixels. This is the distance between the left and right edges of the element's visible content.

Syntax

object.scrollWidth

Settings

This read-only property is always a nonnegative integer.

Remarks

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

BODY, BUTTON, DIV, FIELDSET, FRAME, IFRAME, IMG, MARQUEE, SPAN, TEXTAREA

See Also

scrollHeight, scrollLeft, scrollTop, width


search

Description

Indicates the substring of the href property that follows the ? symbol. This is the query string or form data.

Syntax

object.search[ = search]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, location


sectionRowIndex

Description

Indicates the element's position in the TBODY, THEAD, or TFOOT rows collection. These sections are mutually exclusive, so the TR is always contained in one of these sections, as well as the TABLE. The rowIndex property indicates the element's position in the rows collection for the TABLE. Collection indexes are in source order of the HTML document.

Syntax

object.sectionRowIndex[ = element]

Return Value

This property has read-only permission.

Applies To

TR

See Also

sectionRowIndex, sourceIndex, cellIndex


selected

Description

Indicates that this item is the default. If not present, the first item is selected by default.

Syntax

object.selected[ = selected]

Remarks

This property is used to determine whether a value is submitted with the form. If the value of the control matches the default value, the control's value is not submitted. The value is only submitted when the control's value does not match the default value. Therefore, changing this value changes the rule for whether the value is submitted with the form.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

OPTION

See Also

defaultSelected


selectedIndex

Description

Sets or retrieves an integer specifying the index of the selected option in a select object.

Syntax

object.selectedIndex[ = selectedIndex]

Remarks

Options in a select object are indexed in the order in which they are defined, starting with an index of zero. You can set the selectedIndex property at any time. The display of the select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value.

In general, this property is more useful for select objects that are created without the multiple attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the select object.

The selected property of the select object's options array is more useful for select objects that are created with the MULTIPLE attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

SELECT


self

Description

Refers to the current window. The property provides a way to explicitly refer to the current window or frame.

Syntax

object.self

Remarks

Use the self property to disambiguate a window property from a form of the same name. You can also use the self property to make your code more readable.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

window


shape

Description

Specifies the type of shape used in the image map.

Syntax

object.shape[ = shape]

Settings

This read-write property takes a string specifying a shape. Each shape causes the coords attribute to take a different set of values.

circ | Circle. Takes three coordinates: centerx, centery, and radius.
circle | Circle. Takes three coordinates: centerx, centery, and radius.
poly | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.
polygon | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.
rect | Rectangle. Takes four coordinates: x1, y1, x2, and y2.
rectangle | Rectangle. Takes four coordinates: x1, y1, x2, and y2.

Applies To

AREA

See Also

coords


shiftKey

Description

Specifies the state of the SHIFT key, a Boolean value.

Syntax

object.shiftKey

Settings

This read-only property is TRUE if the SHIFT key is down, and FALSE if the key is up.

Applies To

event


size

Description

Specifies font size.

Syntax

object.size[ = size]

Settings

This read-write property takes an integer value in the range 1 through 7, with 7 representing the largest font.

Applies To

BASEFONT, FONT


size

Description

Sets the height of the HR element, in pixels.

Syntax

object.size[ = size]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

HR


size

Description

Specifies the size of the control.

Syntax

object.size[ = size]

Remarks

For the INPUT element, the size is in characters and represents the width of the text box. For the SELECT element, when the size is specified, it represents a list box with the specified number of rows.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

INPUT, SELECT

See Also

maxLength


sourceIndex

Description

Returns the ordinal position of the element in the source order as it appears in the all collection.

Syntax

object.sourceIndex

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


span

Description

Specifies how many columns are in the group.

Syntax

object.span[ = span]

Remarks

This property should be ignored if the COLGROUP element contains one or more COL elements. The span property provides a more convenient way of grouping columns without the need to specify COL elements.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

COL, COLGROUP


src

Description

Specifies the URL of a sound to be played.

Syntax

object.src[ = src]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

BGSOUND


src

Description

Specifies an external file that contains the source code.

Syntax

object.src

Remarks

A script can contain an external reference as well as code within the block. The code specified by src precedes the code contained within the document.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

SCRIPT


src

Description

Specifies a URL to be loaded by the object.

Syntax

object.src[ = src]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

APPLET, EMBED, FRAME, IFRAME, IMG, INPUT type=img


srcElement

Description

Specifies the element that fired the event.

Syntax

object.srcElement

Settings

This read-only property is an element object.

Applies To

event


srcFilter

Description

Specifies the filter object that caused the onfilterchange event to fire.

Syntax

object.srcFilter

Remarks

This is a read-only property.

Applies To

event


start

Description

Specifies the starting number for a list.

Syntax

object.start[ = start]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

OL


start

Description

Specifies when a video clip file should start playing.

Syntax

object.start[ = start]

Settings

This read-write property can be one of the following strings:

fileopen | The video starts as soon as it is finished loading.
mouseover | The video starts when the mouse goes over the animation.

Applies To

IMG


status

Description

Sets or retrieves the message in the status bar at the bottom of the window.

Syntax

object.status[ = status]

Settings

The value of this read-write property can be any valid string.

Do not confuse status with defaultStatus. The defaultStatus property reflects the default message displayed in the status bar.

Applies To

window


status

Description

Sets or retrieves the current value of a check box or radio button. This property is an alias for the value property for check boxes and radio buttons.

Syntax

object.status[ = status]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

INPUT


style

Description

Specifies an inline style sheet for the tag.

Syntax

object.style[ = style]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


styleFloat

Description

Sets or retrieves the CSS float attribute, which specifies whether the element floats, causing text to flow around it.

Syntax

object.styleFloat[ = styleFloat]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style

CSS Attribute

float


systemLanguage

Description

Indicates the default language that the system is running. For possible return values, see Language Codes.

Syntax

object.systemLanguage

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


tabIndex

Description

Sets the tab index for the object.

Syntax

object.tabIndex[ = tabIndex]

Remarks

Tab selection order is determined by the value of tabIndex as follows:

  • All elements with tabIndex > 0 are selected in increasing tab index order, or in source order for duplicate tab index values.
  • All elements with tabIndex = 0, or without tabIndex set, are selected next, in source order if more than one.
  • Elements with tabIndex = -1 are omitted from tabbing order.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, APPLET, AREA, BODY, BUTTON, DIV, EMBED, HR, IFRAME, IMG, INPUT, MARQUEE, OBJECT, SELECT, TABLE, TEXTAREA


tagName

Description

Returns the tag for the current element.

Syntax

object.tagName

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


target

Description

Specifies the window or frame at which to target the contents.

Syntax

object.target[ = target]

Remarks

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

Special Target Values
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A, AREA, BASE, FORM


text

Description

Sets or retrieves the text contained within the range.

Syntax

object.text[ = text]

Remarks

The text is formatted within the current context of the document. This property cannot be set while the document is loading. Wait for the onload event before attempting to setting this property.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


text

Description

Sets or retrieves the text (foreground) color for the document body.

Syntax

object.text[ = color]

Settings

This read-write property can be set to any one of the color names or values given in Color Table.

Applies To

BODY


text

Description

Retrieves the textual content of the block element as a string.

Syntax

object.text

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

SCRIPT, TITLE


text

Description

Sets or retrieves the text string specified by the OPTION tag.

Syntax

object.text[ = text]

Remarks

Assigning a value to the text property changes the text property internally but does not cause the listed value to change. Submitting the form submits the internally stored value, not the one displayed.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

OPTION


textAlign

Description

Sets or retrieves whether text is left-aligned, right-aligned, centered, or justified.

Syntax

object.style.textAlign[ = textAlign]

Remarks

Values are left, right, center, or justify. Full justification is new to Internet Explorer 4.0 and sets contents aligned at both right and left margins.

The property has read/write permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP
Scripting | style

CSS Attribute

text-align


textDecoration

Description

Sets or retrieves whether the text in the element has blink, line-through, overline, or underline decorations.

Syntax

object.style.textDecoration[ = textDecoration]

Remarks

Internet Explorer 4.0 supports the keyword blink but does not render the blink effect.

If the element has no text (for example, the IMG element in HTML) or is an empty element (for example, "<EM> </EM>"), this property has no effect.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

text-decoration


textDecorationBlink

Description

Specifies whether the text in the element has the blink decoration.

Syntax

object.textDecorationBlink[ = textDecorationBlink]

Remarks

Although you can set this style property, it has no effect on the text in the element. Blinking text is not implemented.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style

CSS Attribute

text-decoration


textDecorationLineThrough

Description

Specifies whether the text in the element has the line-through decoration.

Syntax

object.textDecorationLineThrough[ = textDecorationLineThrough]

Settings

This read-write property can be set to TRUE to apply the line-through decoration, or FALSE to prevent it.

Applies To

style

CSS Attribute

text-decoration


textDecorationNone

Description

Specifies whether the text in the element has any decoration.

Syntax

object.textDecorationNone[ = textDecorationNone]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

style

CSS Attribute

text-decoration


textDecorationOverline

Description

Specifies whether the text has the overline decoration.

Syntax

object.textDecorationOverline[ = textDecorationOverline]

Settings

This read-write property can be set to TRUE to apply the overline, or FALSE to prevent it.

Applies To

style

CSS Attribute

text-decoration


textDecorationUnderline

Description

Specifies whether the text has the underline decoration.

Syntax

object.textDecorationUnderline[ = textDecorationUnderline]

Settings

This read-write property can be set to TRUE to apply the underline, or FALSE to prevent it.

Applies To

style

CSS Attribute

text-decoration


textIndent

Description

Retrieves the indentation of the text in the element.

Syntax

object.style.textIndent

Remarks

The property can be negative. An indent is not inserted in the middle of an element that was broken by another element (such as BR in HTML).

The property has read-only permission.

Applies To

HTML Tags | BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP
Scripting | style

CSS Attribute

text-indent


textTransform

Description

Retrieves the rendering of the text.

Syntax

object.style.textTransform

Remarks

This read-only property can have one of these string values:
capitalize | Transforms the first character of each word to uppercase.
uppercase | Transforms all the characters to uppercase characters.
lowercase | Transforms all the characters to lowercase characters.

Applies To

HTML Tags | A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

text-transform


thead

Description

Points to the THEAD element in the TABLE. If none exist, it is null.

Syntax

object.thead[ = element]

Return Value

This property has read-only permission.

Remarks

The following example sets the inline style for the THEAD.

document.all.myTable.thead.style.color = "blue"

Applies To

table


tfoot

Description

Points to the TFOOT element in the TABLE. If none exist, it is null.

Syntax

object.tfoot[ = element]

Return Value

This property has read-only permission.

Remarks

The following example sets the inline style for the TFOOT.

document.all.myTable.tfoot.style.color = "blue"

Applies To

table


title

Description

Sets or retrieves the title of the style sheet. The title is a string that is a grouping mechanism for style sheets.

Syntax

object.title[ = title]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

LINK


title

Description

Specifies advisory information for the element.

Remarks

Internet Explorer 4.0 renders the title as a ToolTip when the user hovers the mouse over the element.

This property has read-write permissions and takes a string.

Syntax

object.title[ = "sMyString"]

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


toElement

Description

Specifies the element being moved to for the onmouseover and onmouseout events.

Syntax

object.toElement

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


top

Description

Sets or retrieves the position of the element relative to the top of the document.

Syntax

object.style.top[ = top]

Remarks

This read/write property is a string consisting of a number and a units designator, as described for cascading style sheets.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

top

See Also

pixelTop, posTop


top

Description

Specifies the topmost ancestor window, which is its own parent.

Syntax

object.top

Remarks

This property has read-only permission.

Applies To

window


topMargin

Description

Specifies the margin for the top of the page, and overrides the default margin.

Syntax

object.topMargin[ = topMargin]

Settings

This read-write property is a string. If set to "", the margin will be exactly on the top edge.

Applies To

BODY

See Also

leftMargin


trueSpeed

Description

Specifies whether the position of the marquee is calculated using the scrollDelay, scrollAmount, and the actual time elapsed from the last clock tick.

Syntax

object.trueSpeed

Settings

This read-only property is a Boolean value:

TRUE | The marquee advances the pixel value of scrollAmount per the number of milliseconds set for scrollDelay. For example, the marquee advances 10 pixels for every 6 milliseconds (ms) if scrollDelay is 6 and scrollAmount is 10.
FALSE | The marquee computes movement based on 60ms ticks of the clock. This means every scrollDelay value under 60 is essentially ignored, and the marquee advances the amount of scrollAmount each 60ms. For example, if scrollDelay is 6 and scrollAmount is 10, the marquee advances 10 pixels every 60ms.

By default, this property is FALSE for compatibility with Internet Explorer 3.0.

Applies To

MARQUEE


type

Description

Changes the style of the list.

Syntax

object.type[ = type]

Settings

This read-write property can be one of these string values:

1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

Applies To

LI, OL, UL


type

Description

Returns the type of selection.

Syntax

object.type

Settings

This read-only property can be one of these string values:

None | No selection/insertion point.
Text | The selection is a text selection.
Control | The selection type is a control selection.

Applies To

selection


type

Description

Specifies the CSS language in which the style sheet is written.

Syntax

object.type

Settings

This read-only property can be any string, including an empty string. Valid style sheets for Internet Explorer 4.0 are set to "text/css".

Applies To

STYLE


type

Description

Specifies the visual appearance and default behavior of the button.

Syntax

object.type

Settings

This read-only property can be one of these strings:

button | Creates a Command button. This is the default value for this property.
reset | Creates a Reset button. If in a form, this button resets the fields in the form to their initial values.
submit | Creates a Submit button. If in a form, this button submits the form.

A Submit button has the same default behavior as the button created using the submit type with the INPUT element. When the input focus is in a control in the form (other than another button), the Submit button receives a bold border, and the user can "click" the button by pressing the ENTER key. If the Submit button has a name property, the button contributes a name/value pair to the submitted data.

When the Submit and Reset buttons are in the document (rather than in a form), the Submit button receives a bold border if the focus is in the document but not in another button, and the user can press ENTER to click the Submit button.

Applies To

BUTTON


type

Description

Returns the event name or scripting language as a string for the event object and script object, respectively.

Syntax

object.type

Remarks

Events are returned without the "on" prefix. For example, the "onclick" event is returned as "click".

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


type

Description

Specifies the mime type of the object. This is used to retrieve a class identifier for the object when no CLASSID= attribute is given.

Syntax

object.type[ = type]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

OBJECT

See Also

data


type

Description

Specifies the CSS language the style sheet is written in.

Syntax

object.type

Settings

This read-only property can be any string, including an empty string. Style sheets having any type other than "text/css" are not supported for Internet Explorer 4.0.

Applies To

styleSheet


type

Description

Specifies the type of intrinsic control represented by the given element object.

Syntax

object.type

Settings

This read-only property is a string specifying the control type. The possible values depend on the element as listed in the following table.
Element | Possible Value | Description
INPUT | button | Used to create a button control.
checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box controls, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No control is presented to the user, but the value of the value property is sent with the submitted form.
image | An image control that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are submitted with the form as two name/value pairs. The x-coordinate is submitted under the name of the control with .x appended, and the y-coordinate is submitted under the name of the control with .y appended. Any value property is ignored. The image itself is specified by the src property, exactly as for the IMG element.
password | Similar to the text control, except that text is not displayed as the user enters it.
radio | Used for mutually exclusive sets of values. Each radio-button control in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | Reset is a button that when clicked resets the form's controls to their specified initial values. The label to be displayed on the button can be specified just as for the Submit button.
submit | Submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application specific. If a Submit button is clicked in order to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data.
text | Used for a single-line text-entry control. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Used to specify a multiple-select list box.
select-one | Used to specify a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry controls. Use in conjunction with the size and maxLength properties.

Applies To

INPUT, SELECT, TEXTAREA


type

Description

Specifies the language that the current script is written in.

Syntax

object.type

Settings

This read-only property can be any string, including an empty string.

Remarks

This read-only property can refer to any scripting language. Internet Explorer 4.0 ships with a JScript (JavaScript-compatible) and VBScript scripting engine. Keywords for accessing these scripting languages include the following:

javascript | Specifies that the script is written in JavaScript.
Jscript | Specifies the language as JScript.
vbs | Specifies the language as VBScript.
vbscript | Specifies that the script is written in VBScript.

Remarks

To avoid conflict, the type should match the language type specified in the language property.

Applies To

SCRIPT


units

Description

Defines the units for the height and width of the EMBED element. Possible units include pixels and ems.

Syntax

object.units[ = units ]

Settings

This read-write property can be set to an integer value specifying the number of milliseconds between updates to the screen. A value of zero (0) disables the update interval.

Applies To

EMBED


updateInterval

Description

Sets or retrieves the update interval for the screen.

Syntax

object.updateInterval[ = msec ]

Settings

This read-write property can be set to an integer value specifying the number of milliseconds between updates to the screen. A value of zero (0) disables the update interval.

Use this property judiciously—a value too small or too large will adversely affect the page rendering response.

Remarks

The interval causes invalidations to the window to be buffered and then drawn in msec milliseconds intervals. The purpose is to limit excessive invalidations that reduce the overall painting performance, which can happen if there is an overabundance of flipbook-style animations occurring at once.

Applies To

screen


url

Description

Indicates the URL for the current document.

Syntax

object.url[ = URL]

Remarks

This property is an alias for the location.href property on the window.

This property has read-write permissions.

Applies To

document


url

Description

If a URL is specified, reloads the URL after the time specified by the CONTENT= attribute of the META element has elapsed.

Syntax

object.url[ = url]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

META


urn

Description

Specifies a uniform resource name (URN) for a target document.

Syntax

object.urn[ = urn]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

A


useMap

Description

Identifies a URL, often with a bookmark extension (#name), to use as a client-side image map.

Syntax

object.useMap[ = useMap]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

IMG


userAgent

Description

Specifies a string that represents the user-agent header sent in the HTTP protocol from the client to the server.

Syntax

object.userAgent

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


userLanguage

Description

Indicates the current user language. For possible return values, see Language Codes.

Syntax

object.browserLanguage

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

navigator


vAlign

Description

Specifies whether the caption appears at the top or bottom.

Syntax

object.vAlign[ = vAlign]

Settings

This read-write property can be set to one of these strings:

bottom | Places the caption at the bottom of the table.
top | Places the caption at the top of the table. This is the default value for this property.

Applies To

CAPTION


vAlign

Description

Specifies how the text and other content of an element is vertically aligned within the element.

Syntax

object.vAlign[ = vAlign]

Settings

This read-write property can be set to one of these strings:

baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

Applies To

COL, COLGROUP, TBODY, TD, TFOOT, TH, THEAD, TR

See Also

vertical-align


value

Description

Sets or retrieves the value of the object.

Syntax

object.value[ = value]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

SELECT, TEXTAREA


value

Description

Specifies the value of the given control to be submitted to the server as a name/value pair.

Syntax

object.value[ = value]

Settings

This read-write property can be any valid string. The purpose of the string depends on the type of control.

Applies To

INPUT, OPTION


value

Description

Changes the count of ordered lists as they progress.

Syntax

object.value[ = value]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

LI


verticalAlign

Description

Sets or retrieves the vertical positioning of the element.

Syntax

object.style.verticalAlign[ = verticalAlign]

Remarks

The values for verticalAlign are shown below:
sub | Vertically aligns text to subscript.
super | Vertically aligns text to superscript.
top | Vertically aligns contents of element supporting VALIGN to top of element.
middle | Vertically aligns contents of element supporting VALIGN to middle of element.
bottom | Vertically aligns contents of element supporting VALIGN to bottom of element.
baseline | Aligns contents of element supporting VALIGN to baseline.
text-top | Vertically aligns text of element supporting VALIGN to top of element.
text-bottom | Vertically aligns text of element supporting VALIGN to bottom of element.

The property has read/write permission.

Applies To

HTML Tags | CAPTION, COL, IMG, SPAN, TABLE, TBODY, TD, TH, THEAD, TFOOT, TR
Scripting | style

CSS Attribute

vertical-align


visibility

Description

Sets or retrieves whether the content of the element is displayed.

Syntax

object.style.visibility[ = visibility]

Remarks

Unlike display:none, elements that are not visible still reserve the same physical space in the content layout as they would if they were visible. Changing the visibility through scripting is useful for showing and hiding content based on user interaction. Note that for a child element to be visible, the parent element must also be visible. See Dynamic Styles for document style scripting information.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, HTML, I, IFRAME, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

visibility


vLink

Description

Sets or returns the color of links that have already been visited. The color can be one of the color names or values given in Color Table.

Syntax

object.vLink[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

body

See Also

aLink, link


vlinkColor

Description

Sets or returns the color of links that have already been visited. The color can be one of the color names or values given in Color Table.

Syntax

object.vlinkColor[ = color]

Remarks

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

document

See Also

alinkColor, linkColor


volume

Description

Specifies the volume setting for the sound. The higher the setting, the louder the sound.

Syntax

object.volume

Remarks

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

BGSOUND


vspace

Description

Specifies vertical margins for the element.

Syntax

object.vspace[ = vspace]

Remarks

This property is similar to border, except the margins are not painted with color when the element is a link.

This property has read-write permissions, meaning you can change as well as retrieve its current value.

Applies To

APPLET, IFRAME, IMG, MARQUEE

See Also

border, hspace


width

Description

Specifies the horizontal resolution of the screen, in pixels.

Syntax

object.width

Remarks

This property has read-only permission.

Applies To

screen


width

Description

Specifies the calculated width of the element, in pixels.

Syntax

object.width

Remarks

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always retrieves the width in pixels.

This property is read/write for the IMG element, but it is read-only for the other elements.

Applies To

EMBED, FRAME, IMG, MARQUEE, OBJECT, TABLE

See Also

height


width

Description

Sets or retrieves the width of the element.

Syntax

object.style.width[ = width]

Remarks

This read/write property is a string consisting of a floating-point number and a units designator, as described for cascading style sheets.

DIV and SPAN cannot be positioned unless a width is provided. Percentage values are based on the width of the parent element.

When scripting the width property, use either the pixelWidth or posWidth property for numeric manipulation of a width value.

For more information on how to access the dimension and location of elements on the page through the document object model, see Measuring Element Dimension and Location.

Applies To

HTML Tags | APPLET, DIV, EMBED, FIELDSET, HR, IFRAME, IMG, INPUT, INPUT type=button, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TEXTAREA
Scripting | style

CSS Attribute

width


wrap

Description

Specifies how to handle word-wrapping in the element.

Syntax

object.wrap[ = wrap]

Settings

This read-write property can be one of these strings:

off | Word-wrapping is disabled. The lines appear exactly as the user types them. This is the default value for this property.
physical | The text is displayed and submitted word-wrapped.
virtual | The text is displayed and submitted using word-wrapping.

Applies To

TEXTAREA


x

Description

Returns the position of the mouse hit relative to the element in the parent hierarchy that is positioned using the CSS positioning attribute. If no element in the hierarchy has been positioned, the BODY element is the default.

Syntax

object.x

Remarks

If the mouse is outside the window when the event is called, this property returns -1.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


y

Description

Returns the position of the mouse hit relative to the element in the parent hierarchy that is positioned using the CSS positioning attribute. If no element in the hierarchy has been positioned, the BODY element is the default.

Syntax

object.y

Remarks

If the mouse is outside the window at the time the event fires, this property returns -1.

This property has read-only permission, meaning you can retrieve its current value, but not change it.

Applies To

event


zIndex

Description

Sets or retrieves the stacking order of positioned elements.

Syntax

object.style.zIndex[ = zIndex]

Remarks

By default (auto), the stacking order is bottom-to-top in the order that the z-indexed elements appear in the HTML source. Positive z-index values are positioned above a negative (or lesser value) z-index. Two elements with the same z-index are stacked according to source order.

The property has read/write permission.

Applies To

HTML Tags | A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP
Scripting | style

CSS Attribute

z-index


Language Codes

Description

The following table lists all the possible language codes used to specify various system settings.
af Afrikaans | sq Albanian
ar-sa Arabic(Saudi Arabia) | ar-iq Arabic(Iraq)
ar-eg Arabic(Egypt) | ar-ly Arabic(Libya)
ar-dz Arabic(Algeria) | ar-ma Arabic(Morocco)
ar-tn Arabic(Tunisia) | ar-om Arabic(Oman)
ar-ye Arabic(Yemen) | ar-sy Arabic(Syria)
ar-jo Arabic(Jordan) | ar-lb Arabic(Lebanon)
ar-kw Arabic(Kuwait) | ar-ae Arabic(U.A.E.)
ar-bh Arabic(Bahrain) | ar-qa Arabic(Qatar)
eu Basque | bg Bulgarian
be Belarusian | ca Catalan
zh-tw Chinese(Taiwan Region) | zh-cn Chinese(PRC)
zh-hk Chinese(Hong Kong SAR, PRC) | zh-sg Chinese(Singapore)
hr Croatian | cs Czech
da Danish | nl Dutch(Standard)
nl-be Dutch(Belgian) | en English
en-us English(United States) | en-gb English(British)
en-au English(Australian) | en-ca English(Canadian)
en-nz English(New Zealand) | en-ie English(Ireland)
en-za English(South Africa) | en-jm English(Jamaica)
en English(Caribbean) | en-bz English(Belize)
en-tt English(Trinidad) | et Estonian
fo Faeroese | fa Farsi
fi Finnish | fr French(Standard)
fr-be French(Belgian) | fr-ca French(Canadian)
fr-ch French(Swiss) | fr-lu French(Luxembourg)
gd Gaelic(Scots) | gd-ie Gaelic(Irish)
de German(Standard) | de-ch German(Swiss)
de-at German(Austrian) | de-lu German(Luxembourg)
de-li German(Liechtenstein) | el Greek
he Hebrew | hi Hindi
hu Hungarian | is Icelandic
in Indonesian | it Italian(Standard)
it-ch Italian(Swiss) | ja Japanese
ko Korean | ko Korean(Johab)
lv Latvian | lt Lithuanian
mk Macedonian | ms Malaysian
mt Maltese | no Norwegian(Bokmal)
no Norwegian(Nynorsk) | pl Polish
pt-br Portuguese(Brazilian) | pt Portuguese(Standard)
rm Rhaeto-Romanic | ro Romanian
ro-mo Romanian(Moldavia) | ru Russian
ru-mo Russian(Moldavia) | sz Sami(Lappish)
sr Serbian(Cyrillic) | sr Serbian(Latin)
sk Slovak | sl Slovenian
sb Sorbian | es Spanish(Spain - Traditional Sort)
es-mx Spanish(Mexican) | es Spanish(Spain - Modern Sort)
es-gt Spanish(Guatemala) | es-cr Spanish(Costa Rica)
es-pa Spanish(Panama) | es-do Spanish(Dominican Republic)
es-ve Spanish(Venezuela) | es-co Spanish(Colombia)
es-pe Spanish(Peru) | es-ar Spanish(Argentina)
es-ec Spanish(Ecuador) | es-cl Spanish(Chile)
es-uy Spanish(Uruguay) | es-py Spanish(Paraguay)
es-bo Spanish(Bolivia) | es-sv Spanish(El Salvador)
es-hn Spanish(Honduras) | es-ni Spanish(Nicaragua)
es-pr Spanish(Puerto Rico) | sx Sutu
sv Swedish | sv-fi Swedish(Finland)
th Thai | ts Tsonga
tn Tswana | tr Turkish
uk Ukrainian | ur Urdu
ve Venda | vi Vietnamese
xh Xhosa | ji Yiddish
zu Zulu


Methods

add addChannel addImport
addReadRequest addRule alert
assign back blur
clear clear clearInterval
clearRequest clearTimeout click
close close collapse
compareEndPoints confirm contains
createCaption createElement createRange
createStyleSheet createTextRange createTHead
createTFoot deleteCaption deleteCell
deleteRow deleteTFoot deleteTHead
doReadRequest duplicate elementFromPoint
empty execCommand execScript
expand findText focus
forward getAttribute getAttribute
getBookmark go inRange
insertAdjacentHTML insertAdjacentText insertCell
insertRow isEqual isSubscribed
item javaEnabled move
moveBy moveEnd moveStart
moveTo moveToBookmark moveToElementText
moveToPoint navigate nextPage
open open parentElement
pasteHTML previousPage prompt
queryCommandEnabled queryCommandIndeterm queryCommandState
queryCommandSupported queryCommandValue refresh
reload remove removeAttribute
replace reset resizeBy
resizeTo scroll scrollBy
scrollTo scrollIntoView select
select setAttribute setEndPoint
setInterval setTimeout showHelp
showModalDialog start stop
submit tags taintEnabled
write writeln zOrder

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


add

Description

Adds an element to the collection.

Before you can add an element to a collection, you must create it first by using the createElement method.

Syntax

object.add(element [, index])

Parameter | Description
element | Element object to add.
index | Optional. Number specifying the position within the collection to place the element. If no value is given, the method places the element at the end of the collection.

Return Value

No return value.

Remarks

For the areas object, this method can only be used on the object after the page has been loaded. If the method is applied "inline," a run-time error will occur.

Applies To

areas, options

See Also

remove


addChannel

Description

Presents a dialog box allowing the user to add the channel specified or change its usage if it is already installed.

Syntax

object.addChannel(urlToCDF)

Parameter | Description
urlToCDF | Required. Specifies the URL of a Channel Definition Format (CDF) file to be installed.

Remarks

Important Note: This function is only intended for use by publishers shipping Active Channels that are pre-installed with Internet Explorer 4.0. It is included in this documentation for completeness.

Applies To

external


addImport

Description

Adds a style sheet to the imports collection for the given style sheet.

Syntax

integer = stylesheet.addImport(url [, index])

Parameter | Description
url | String specifying the location of the source file for the style sheet.
index | Optional. Integer specifying the requested position of the style sheet in the collection. If this value is not given, the style sheet is added to the end of the collection.

Return Value

Returns an integer index value specifying the position of the imported style sheet in the imports collection.

Remarks

The index is a zero-based index value.

Applies To

styleSheet


addReadRequest

Description

Adds an entry to the read-requests queue.

Syntax

navigator.userProfile.addReadRequest(attributeName [, isRequired], success)

Parameter | Description
attributeName | One of the standard vCard names; otherwise, the request is ignored and nothing is added to the read-requests queue.
isRequired | Optional. Currently, Internet Explorer ignores this parameter.
success | Returns TRUE if the request has been added to the queue successfully, or FALSE otherwise. This could mean that either the attribute name was not recognized or the attribute had already appeared in the request queue.

Applies To

userProfile


addRule

Description

Creates a new style rule for the styleSheet object and returns the index into the Rules collection. Rules can be added to a disabled styleSheet, but they will not apply to the document unless the styleSheet has been enabled.

Syntax

integer = object.addRule(selector, style [, index])

Parameter | Description
selector | String specifying the selector for the new rule. Single contextual selectors are valid. For example, "DIV P B" is a valid contextual selector.
style | String specifying the style assignments for this style rule. This style takes the same form as an inline style specification. For example, "color:blue" is a valid style parameter.
index | Integer that specifies where in the Rules collection to add the new style rule. This is an optional parameter. If an index is not provided, the rule will be added to the end of the Rules collection by default.

Return Value

The return value is reserved; do not use.

Remarks

The following example adds a rule to the beginning of the Rules collection for all text in BOLD that appears in a <DIV> <P> tag to be set to the color blue.

var new_rule;
new_rule = styleSheets[0].addRule("DIV P B", "color:blue", 0);

Remarks

NOTE: When manipulating stylesheets through the Object Model, you will not be able to addRule() where the style is "position" to an element which doesn't already have positioning set for it. You can, however, add a rule to the object to make it "position:absolute" if the object has already been set to "position:relative" (and vice versa).

Applies To

styleSheet


alert

Description

Displays an Alert dialog box with a message and an OK button.

Syntax

object.alert([message])

Parameter | Description
message | Optional. (String) String to display.

Return Value

No return value.

Remarks

The title bar of the Alert dialog box cannot be changed.

Applies To

window


assign

Description

Sets the current location to url. This method loads the given document specified by url if it exists.

Syntax

object.assign(url)

Parameter | Description
url | String specifying the URL of the document to assign.

Return Value

No return value.

Applies To

location


back

Description

Loads the previous URL in the History list.

Syntax

object.back( )

Return Value

No return value.

Remarks

This method performs the same action as a user choosing the Back button in the browser. The back method is the same as history.go(-1). Trying to go past the beginning of the history does not generate an error. Instead, you are left at the current page.

Applies To

history

See Also

forward, go


blur

Description

Causes an object to lose focus and fires the onblur event.

Syntax

object.blur( )

Return Value

No return value.

Applies To

A, APPLET, AREA, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, FRAME, FRAMESET, HR, IFRAME, IMG, INPUT, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TD, TEXTAREA, TR, window


clear

Description

Clears the contents of the selection.

Syntax

object.clear( )

Return Value

No return value.

Applies To

selection


clear

Description

Clears the current document.

Syntax

object.clear( )

Return Value

No return value.

Applies To

document


clearInterval

Description

Cancels the interval previously started using the setInterval method.

Syntax

object.clearInterval(intervalID)

Parameter | Description
intervalID | Integer specifying which interval to cancel. This value must have been previously returned by the setInterval method.

Return Value

No return value.

Applies To

window


clearRequest

Description

Clears the compound request, cleaning the slate for building a new request for profile access.

Syntax

navigator.userProfile.clearRequest

Return Value

No return value.

Applies To

userProfile


clearTimeout

Description

Cancels a time-out that was set with the setTimeout method.

Syntax

object.clearTimeout(timeoutID)

Parameter | Description
timeoutID | (Long) Time-out setting that was returned by a previous call to the setTimeout method.

Return Value

No return value.

Applies To

window


click

Description

Simulates a click by causing the onclick event to fire.

Syntax

object.click( )

Return Value

No return value.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP


close

Description

Closes the current browser window.

Syntax

object.close( )

Return Value

No return value.

Applies To

window


close

Description

Closes an output stream and forces data sent to layout to display.

Syntax

object.close( )

Return Value

No return value.

Applies To

document


collapse

Description

Moves the insertion point to the beginning or the end of the current range.

Syntax

object.collapse([start])

Parameter | Description
start | Optional. (Boolean) False moves the insertion point to the end of the text range. True (default) moves the insertion point to the beginning of the text range.

Return Value

No return value.

Remarks

This feature might not be available on non-Win32® platforms. See article Q172976 in the Microsoft® Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange

See Also

expand


compareEndPoints

Description

Compares the two end points and returns -1, 0, or 1 for less than, equal to, or greater than, respectively.

Syntax

object.compareEndPoints(type, range)

Parameter | Description
type String that describes the end point to compare. Can be one of these values:
StartToEnd
StartToStart
EndToStart
EndToEnd
range | Text range object specifying the range from which the source end point is to be taken.

Return Value

Returns the result of the comparison.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


confirm

Description

Displays a Confirm dialog box with the specified message, and OK and Cancel buttons.

Syntax

object.confirm([message])

Parameter | Description
message | Optional. (String) String to display.

Return Value

Returns TRUE if the user chooses OK, or FALSE if the user chooses Cancel.

Remarks

You have no control over the dialog box title.

Applies To

window


contains

Description

Checks whether the given element is contained within the current element.

Syntax

Boolean = object.contains(element)

Parameter | Description
element | Element object specifying the element to check.

Return Value

Returns TRUE if the element is contained, or FALSE otherwise.

Applies To

A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP


createCaption

Description

Creates an empty CAPTION element in the TABLE. If a CAPTION already exists, createCaption() returns the existing element, otherwise, it returns a pointer to the element created.

Syntax

object.createCaption()

Return Value

Returns the CAPTION element object. If the method fails, it returns null.

Remarks

The following example creates a caption,

myCaption = document.all.myTable.createCaption()

Applies To

table

See Also

createTFoot, createTHead, deleteTHead, deleteTFoot, deleteCaption


createElement

Description

Creates an instance of the element object for the specified tag. Only new IMG and OPTION elements can be created. Before they can be used, new objects must be explicitly added to their respective collections.

Syntax

element = object.createElement(tag)

Parameter | Description
tag | (String) Tag specifier.

Return Value

Returns an element object.

Applies To

document

See Also

add


createRange

Description

Creates a text range object from the current selection.

Syntax

object.createRange( )

Applies To

selection


createStyleSheet

Description

Creates a style sheet for the document.

Syntax

object.createStyleSheet(url, index)

Parameter | Description
url | Optional string that indicates how the style sheet is to be added to the document. If a file name is specified for the URL, the style information will be added as a link object. If the URL contains style information, this information will be added to the style object.
index | Optional integer indicating where the new style sheet is inserted in the styleSheets collection. The default is to insert the new style at the end of the collection.

Return Value

Returns a styleSheet object.

Example

To create a link to a style sheet

document.createStyleSheet('styles.css');

To add style sheet to the style object

document.createStyleSheet(document.body.style.backgroundColor='blue');

Applies To

document


createTextRange

Description

Creates a text range object for the given object. You use a text range to examine and modify the text within an object.

Syntax

TextRange = object.createTextRange( )

Return Value

Returns a text range object if successful, or NULL otherwise.

Examples

The following JScript example creates a text range for the document, then uses the range to display all text and HTML tags in the document.

var rng = document.body.createTextRange( );
if (rng!=null) {
    alert(rng.htmlText);
}

The following JScript example creates a text range for the first BUTTON element in the document, then uses the text range to change the text in the button.

var coll = document.all.tags("BUTTON");
if (coll!=null && coll.length>0) {
    var rng = coll[0].createTextRange();
    rng.text = "Clicked";
}

Applies To

BODY, BUTTON, INPUT (text type only), TEXTAREA

See Also

TextRange


createTHead

Description

Creates an empty THEAD element in the TABLE. If a THEAD already exists, createTHead returns the existing element, otherwise, it returns a pointer to the element created.

Syntax

object.createTHead()

Return Value

Returns the THead element object. If the method fails, it returns null.

Remarks

The following example creates a THEAD,

myTHead = document.all.myTable.createTHead()

Applies To

table

See Also

createTFoot, createCaption, deleteTHead, deleteTFoot, deleteCaption


createTFoot

Description

Creates an empty TFOOT element in the TABLE. If a TFOOT already exists for the TABLE, createTFoot returns the existing element, otherwise, it returns a pointer to the element created.

Syntax

object.createTFoot()

Return Value

Returns the THead element object. If the method fails, it returns null.

Remarks

The following example creates a TFOOT,

myTFoot = document.all.myTable.createTFoot()

Applies To

table

See Also

createTHead, createCaption, deleteTHead, deleteTFoot, deleteCaption


deleteCaption

Description

Deletes the Caption element and its contents from the TABLE.

Syntax

object.deleteCaption()

Return Value

No return value.

Remarks

The following example deletes the caption,

document.all.myTable.deleteCaption()

Applies To

table

See Also

createTFoot, createTHead, createCaption, deleteTFoot, deleteTHead


deleteCell

Description

Deletes the specified cell (TD) in the table row and removes the cell from the cells collection. You can specify a cellIndex for the cell to be deleted from the TD, or without a cellIndex, the last cell in the cells collection will be deleted.

Syntax

object.deleteCell(index)

Return Value

No return value. Index specifies which element in the cells collection to remove.

Remarks

The following example deletes the last cell in the first row of the table

document.all.myTable.rows[0].deleteCell()

Applies To

TR

See Also

insertCell, deleteRow


deleteRow

Description

Deletes the specified row (TR) in the table and removes the row from the rows collection. Deleting a row from a TFOOT, TBODY, or THEAD also removes the row from the rows collection for the TABLE. Deleting a row in the TABLE, removes a row from the rows collection for the TBODY. However, when specifying the index for the row to be deleted, you must specify the sectionRowIndex if the row is being deleted from a TBODY, TFOOT or THEAD. You must specify the rowIndex if the row is being deleted from the TABLE.

Syntax

object.deleteRow(index)

Return Value

No return value Index specifies which element in the rows collection to remove.

Remarks

The following example deletes the specified row (TR) in the table,

myNewRow = document.all.myTable.deleteRow()

Applies To

table, TBODY, TFOOT, THEAD

See Also

rows, rowIndex, sectionRowIndex, insertRow


deleteTFoot

Description

Deletes the TFOOT element and its contents from the TABLE.

Syntax

object.deleteTFoot()

Return Value

No return value.

Remarks

The following example deletes the TFOOT element,

document.all.myTable.deleteTFoot()

Applies To

table

See Also

createTFoot, createTHead, createCaption, deleteTHead, deleteCaption


deleteTHead

Description

Deletes the THEAD element and its contents from the TABLE.

Syntax

object.deleteTHead()

Return Value

No return values.

Remarks

The following example deletes the THEAD element,

document.all.myTable.deleteTHead()

Applies To

table

See Also

createTFoot, createTHead, createCaption, deleteTFoot, deleteCaption


doReadRequest

Description

Performs the compound request accumulated in the read-requests queue. If the site does not already have read access, the user will be prompted with a list of attributes requested and can choose to allow or deny access.

Syntax

navigator.userProfile.doReadRequest(usageCode [, friendlyName [, domain [, path [, expiration]]]])

Parameter | Description
usageCode | Notification for the user of the type of access requested. This usage code should be one of the 13 codes (listed below) defined by the Internet Privacy Working Group (IPWG).
friendlyName | Optional. "Friendly name" of the party requesting access to private information. For security reasons, it is not enough for the user agent to display this friendly name to the end user. In addition to this friendly name, it is essential to display the URL that originates the script requesting profile access. If this script originates from a secure connection (for example, SSL), the SSL certificate can also be used to reliably identify the party requesting access.
domain and path | Optional. Which pages the user's choice will apply to in the future, in addition to the current one; the specification follows the cookie standard (RFC-2109 http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html).
expiration | Optional. How long the site is requesting access to these attributes. This is currently ignored by Internet Explorer.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

The following table defines the usage codes.
Usage code values | Meaning
0 | Used for system administration.
1 | Used for research and/or product development.
2 | Used for completion and support of current transaction.
3 | Used to customize the content and design of a site.
4 | Used to improve the content of site including advertisements.
5 | Used for notifying visitors about updates to the site.
6 | Used for contacting visitors for marketing of services or products.
7 | Used for linking other collected information.
8 | Used by site for other purposes.
9 | Disclosed to others for customization or improvement of the content and design of the site.
10 | Disclosed to others, who may contact you, for marketing of services and/or products.
11 | Disclosed to others, who may contact you, for marketing of services and/or products, but you will have the opportunity to ask a site not to do this.
12 | Disclosed to others for any other purpose.

Applies To

userProfile


duplicate

Description

Returns a duplicate of the range.

Syntax

TextRange = object.duplicate( )

Return Value

Returns TextRange.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


elementFromPoint

Description

Returns the element for the specified x and y coordinates.

Syntax

element = object.elementFromPoint(x, y)

Parameter | Description
x | (Integer) X-offset, in pixels.
y | (Integer) Y-offset, in pixels.

Return Value

Returns an element object.

Remarks

Coordinates are supplied in window coordinates (0,0 is the top-left corner of the window). For elementFromPoint to exhibit expected behavior, the object or element located at position (x, y) must support and respond to mouse events. MouseEventsEnabled must be 1.

Applies To

document


empty

Description

Deselects the current selection, sets the selection type to "none", and sets the item property to null.

Syntax

object.empty( )

Return Value

No return value.

Applies To

selection


execCommand

Description

Executes a command over the given selection or text range.

Syntax

Boolean = object.execCommand(sCommand [, bUserInterface [, vValue]])

Parameter | Description
sCommand | String specifying the command to execute. Can be any valid command identifier.
bUserInterface | Optional. Boolean value specifying whether to display a user interface if the command supports one. Can be TRUE or FALSE. If not given, defaults to FALSE.
vValue | Optional. Variant specifying a string, number, or other value to assign. Possible values depend on command.

Return Value

Returns TRUE if the command is successful, or FALSE otherwise.

Remarks

Wait to invoke the execCommand method until after the page has loaded.

Applies To

document, TextRange

See Also

queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandSupported, queryCommandValue


execScript

Description

Executes the script defined for the expression parameter in the language parameter. The language defaults to JScript.

Syntax

object.execScript(expression , language)

Parameter | Description
expression | String specifying the code to be executed.
language | String specifying the language in which the code is executed.

Return Value

No return value.

Applies To

window


expand

Description

Expands the range so that partial units are completely contained.

Syntax

Boolean = object.expand(unit)

Parameter Description
unit Units to move in the range. Can be one of the following:
character | Expands a character.
word | Expands a word. A word is a collection of characters terminated by a space or other white-space character.
sentence | Expands a sentence. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit | Expands to enclose the entire range.

Return Value

Returns TRUE if it successfully expands the range, or FALSE otherwise.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following example creates a range from the current selection, then uses expand to ensure that any word partially enclosed by the range becomes entirely enclosed in the range.

var rng = document.selection.createRange();
rng.expand("word");

Applies To

TextRange

See Also

collapse


findText

Description

Searches for text in the document. Positions the start and end points of the range to encompass the search string.

Syntax

bFound = object.findText(sText [, iSearchScope] [, iFlags])

Parameter | Description
sText | String specifying the text to find.
iSearchScope | Optional. An integer indicating the direction to search from the starting point of the range. A positive integer indicates a forward search; a negative integer indicates a backward search.
iFlags Optional. A combination of one or more of the following flags indicating the type of search:
2 | match whole words only.
4 | match case.

Return Value

Returns true if the search text is found, or false otherwise.

Remarks

A range has two distinct states: degenerate and non-degenerate. Analogous to a text editor, a degenerate range is like a text editor caret (insertion point); it does not actually select any characters. Instead it specifies a point between two characters. A degenerate range’s endpoints are effectively next to each other. On the other hand, a non-degenerate range is like a text editor selection. A certain amount of text is selected, and the end points of the range are not next to each other.

The degenerate state of the range has a significant impact on the behavior of the findText method. The value passed for the iSearchScope parameter controls the part of the document, relative to the range, that is searched. If the range is degenerate, either a large positive or a large negative number can be passed to indicate the direction of the search. If the range is non-degenerate, passing 0 will cause only the text selected by the range to be searched. Passing a large positive number will cause the text to the right of the start of the range to be searched. Passing a large negative number will cause the text to the left of the end of the range to be searched. For all intensive purposes, a large positive and a large negative number are 9999999 and -9999999, respectively. Passing anything else for iSearchScope may not be compatible with future versions of Internet Explorer.

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following example creates a Text Range over the body of the document and searches for text with various flag combinations. The results are indicated in the code comments.

<HTML>
<BODY>
Leonardo da Vinci was one of the great masters of the High Renaissance,
especially in painting, sculpture, architecture, engineering, and science.
</BODY>
</HTML>

<SCRIPT>
   var oRange = document.body.createTextRange();
   var sBookMark = oRange.getBookmark(); // record the current position in a bookmark
   oRange.findText('leo');               // true. case insensitive and partial word match.
   oRange.moveToBookmark(sBookMark);	 // reset the range using the bookmark
   oRange.findText('engineer', 0, 2);    // false. matches whole words only.
   oRange.moveToBookmark(sBookMark);
   oRange.findText('high', 0, 4);        // false. case sensitive.
   oRange.moveToBookmark(sBookMark);
   oRange.findText('Leonardo', 0, 6);    // true. case sensitive and matches whole words.

   // the degenerate case
   oRange.moveToBookmark(sBookMark);
   oRange.collapse();                    // make the range degenerate
   oRange.findText('Leonardo', 0, 6);    // false. must specify large character count in this case
   oRange.findText('Leonardo');          // true. no third parameter passed, so no count needed
   oRange.findText('Leonardo', 1000000000, 6);    // true. a large count covers the range.
</SCRIPT>

Applies To

TextRange


focus

Description

Causes a control to receive the focus and executes the code specified by onfocus.

Syntax

object.focus( )

Return Value

No return value.

Applies To

A, APPLET, AREA, BODY, BUTTON, CAPTION, DIV, EMBED, FIELDSET, FRAME, FRAMESET, HR, IFRAME, IMG, INPUT, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TD, TEXTAREA, TR, window


forward

Description

Loads the next URL in the History list.

Syntax

object.forward( )

Return Value

No return value.

Remarks

This method performs the same action as a user choosing the Forward button in the browser. The forward method is the same as history.go(1). Trying to go past the end of the history does not generate an error. Instead, you are left at the current page.

Applies To

history

See Also

back, go


getAttribute

Description

Retrieves the value of the given attribute.

Syntax

variant = object.getAttribute(attrName [, iFlags])

Parameter | Description
attrName | String specifying the name of the attribute.
iFlags | Optional. A combination of the following flags: 1 indicates that a case-sensitive search should be used to locate the attribute. 2 indicates that the value should be returned as it was specified in the source. 0 (default) indicates that the search should be case-insensitive, and that the returned value may be interpolated.

Return Value

Returns a string, number, or Boolean value as defined by the attribute. If the attribute is not present, this method returns null.

Remarks

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and caseSensitive is FALSE, this method retrieves values only for the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

If iFlags is set to 1, the uppercase and lowercase letters in attrName must match exactly those in the attribute name. If the caseSensitive parameter for the setAttribute method is set to true and this option is set to false (default), a conflict will arise.

Applies To

A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP, style


getAttribute

Description

Returns the value of the named attribute. If read access for this attribute is not already available, this method simply returns the NULL string.

Syntax

navigator.userProfile.getAttribute(attributeName, attributeValue)

Parameter | Description
attributeName | One of the standard vCard names (listed below); otherwise the request is ignored and nothing is returned.
attributeValue | Value stored in the attributeName parameter.

Remarks

The following schema is used for the field names of the user data store. These names are specified when using the getAttribute method on the userProfile object. Please note that the format has changed from vCard_xxx to vCard.xxx and that the older format will no longer be supported.

vCard Names

vCard.Email | vCard.DisplayName | vCard.FirstName
vCard.LastName | vCard.MiddleName | vCard.Cellular
vCard.Gender* | vCard.JobTitle | vCard.Pager
vCard.Company | vCard.Department | vCard.Notes
vCard.Office | vCard.Homepage | vCard.Home.StreetAddress
vCard.Home.City | vCard.Home.State | vCard.Home.Zipcode
vCard.Home.Country | vCard.Home.Phone | vCard.Home.Fax
vCard.Business.StreetAddress | vCard.Business.City | vCard.Business.Phone
vCard.Business.Fax | vCard.Business.URL | vCard.Business.State
vCard.Business.Country | vCard.Business.Zipcode

Note (*) asterisk denotes extensions to the vCard schema, which will be referenced as X- elements as defined in the vCard schema.

Applies To

userProfile


getBookmark

Description

Retrieves a bookmark (opaque string) that can be used with moveToBookmark to return to the same range.

Syntax

string = object.getBookmark( )

Return Value

Returns a string if successful, or null otherwise.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


go

Description

Loads a URL in the History list.

Syntax

object.go(delta | location)

Parameter | Description
delta | location | delta is an integer representing a relative position in the History list. location is a string representing all or part of a URL in the History list.

Return Value

No return value.

Remarks

Trying to go past the beginning or end of the history does not generate an error. Instead, you are left at the current page.

Applies To

history

See Also

back, forward


inRange

Description

Returns whether or not one range (the parameter) is contained within another.

Syntax

bContained = object.inRange(oRange)

Parameter | Description
oRange | Reference to a Text Range.

Return Value

Returns true if the range passed as the method parameter is contained within or is equal to the range upon which the method is called. Returns false otherwise.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following three examples show equal text ranges, a contained range, and a range outside the range upon which inRange is called.

   <HTML>
   <BODY>
   <DIV ID=div1>
   Content for division 1.
   </DIV>
   <DIV ID=div2>
   Content for division 2.
   </DIV>
   </BODY>
   </HTML>

   var oRng1 = document.body.createTextRange();
   var oRng2 = oRng1.duplicate();
   var bInside = oRng1.inRange(oRng2); // returns true; oRng2 is within or equal to oRng1

   oRng1.moveToElementText(div1);
   oRng2.moveToElementText(div2);
   bInside = oRng1.inRange(oRng2); // returns false; oRng2 is outside of oRng1

   var oRng3 = oRng1.duplicate();
   oRng3.findText('division 1');
   bInside = oRng1.inRange(oRng3); // returns false; oRng2 is outside of oRng1
Click the Show Me to see working code.

Applies To

TextRange

See Also

isEqual


insertAdjacentHTML

Description

Inserts the given HTML text into the element at the given place. If the text contains HTML tags, the method parses and formats the text as it inserts.

Syntax

object.insertAdjacentHTML(where, text)

Parameter | Description
where String specifying where to insert the HTML text. Can be one of the following:
BeforeBegin | Inserts the text immediately before the element.
AfterBegin | Inserts the text after the start of the element but before all other content in the element.
BeforeEnd | Inserts the text immediately before the end of the element but after all other content in the element.
AfterEnd | Inserts the text immediately after the end of the element.
text | String specifying the HTML text to insert. The string can be a combination of text and HTML tags. This must be well-formed, valid HTML or this method fails.

Return Value

No return value.

Remarks

You cannot insert text while the document is loading. Wait for the onload event before attempting to call this method.

Applies To

A, ADDRESS, AREA, B, BASEFONT, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, FRAMESET, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TD, TEXTAREA, TH, TR, TT, U, UL, VAR, XMP

See Also

insertAdjacentText,innerHTML, outerHTML


insertAdjacentText

Description

Inserts the given text into the element at the given place. The method inserts the text as plain text.

Syntax

object.insertAdjacentText(where, text)

Parameter | Description
where String specifying where to insert the text. Can be one of the following:
BeforeBegin | Inserts the text immediately before the element.
AfterBegin | Inserts the text after the start of the element but before all other content in the element.
BeforeEnd | Inserts the text immediately before the end of the element but after all other content in the element.
AfterEnd | Inserts the text immediately after the end of the element.
text | String specifying the text to insert.

Return Value

No return value.

Remarks

You cannot insert text while the document is loading. Wait for the onload event before attempting to call this method.

Applies To

A, ADDRESS, AREA, B, BASEFONT, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FONT, FORM, FRAMESET, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, OPTION, P, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TD, TEXTAREA, TH, TR, TT, U, UL, VAR

See Also

insertAdjacentHTML,innerText,outerText


insertCell

Description

Creates a new cell in the table row and adds the cell to the cells collection.

Syntax

object.insertCell(index)

Return Value

Returns the TD element object. If the method fails, it returns null. Index is optional. Default value is "-1" which appends the TD to the end of the cells collection.

Remarks

The following example adds a cell to the end of the TR,

myNewCell = document.all.myTable.rows[0].insertCell()

Applies To

TR

See Also

deleteCell, InsertRow


insertRow

Description

Creates a new row (TR) in the table and adds the row to the rows collection. Inserting a row in a TFOOT, TBODY, or THEAD also adds a row to the rows collection for the TABLE. Inserting a row in the TABLE, adds a row to the rows collection for the TBODY. If specifying an index, the index should be relative to the rows collection for the element which first contains the TR. For example, insertRow for a TBODY would take an index value relative to the rows collection that is on the TBODY, not the TABLE.

Syntax

object.insertRow(index)

Return Value

Returns the TR element object. If the method fails, it returns null. Index is optional. Default value is "-1" which appends the TD to the end of the rows collection.

Remarks

The following example adds a row to the TABLE,

myNewRow = document.all.myTable.insertRow()

Applies To

table, TBODY, TFOOT, THEAD

See Also

rows, rowIndex, sectionRowIndex


isEqual

Description

Returns whether the specified range is equal to the current range.

Syntax

Boolean = object.isEqual(compareRange)

Parameter | Description
compareRange | (TextRange) Range object.

Return Value

Returns TRUE if equal, FALSE otherwise.

Applies To

TextRange

See Also

inRange


isSubscribed

Description

Returns whether the given channel is subscribed to by the client.

Syntax

Boolean = object.isSubscribed(urlToCDF)

Parameter | Description
urlToCDF | Required. Specifies the URL of a Channel Definition Format (CDF) file to be checked for a subscription.

Return Value

Returns true if the channel is subscribed to, or false if no subscription exists for that CDF file.

Remarks

For security purposes, if this method is used in an HTML page that is not in the same secondary domain specified in the urlToCDF, the method will return a scripting error.

Further information is available on Creating Active Channels.

Applies To

external


item

Description

Retrieves an element or a collection from the given collection. The index determines which action to take.

Syntax

element = object.item(index [, subindex])

Parameter | Description
index | Number or string specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
subindex | Optional. Number specifying the position of an element to retrieve. This parameter is used when index is a string. The method uses the string to construct a collection of all elements that have a name or id equal to the string, then retrieves from this collection the element at the position specified by subindex.

Return Value

Returns an element object or a collection of element objects if successful, or null otherwise.

Examples

The following JScript example uses the item method to retrieve each element from the document. In this case, the method parameter is a number, so the elements are retrieved in the order in which they appear in the document.

var coll = document.all;
if (coll!=null) {
    for (i=0; i<coll.length; i++)
        alert(coll.item(i).tagName);
}

The following JScript example uses the item method to retrieve a collection of all elements in the document having "Sample" as an id. It then uses item again to retrieve each element from the "Sample" collection.

var coll = document.all.item("Sample");
If (coll != null) {
    for (i=0; i<coll.length; i++) {
        alert(coll.item(i).tagName);
    }
}

The following JScript example is similar to the previous example, but uses the optional subindex parameter of item to retrieve individual elements.

var coll = document.all.item("Sample")
if (coll!=null) {
    for (i=0; i<coll.length; i++)
        alert(document.all.item("Sample",i).tagName);
}

Applies To

all, anchors, applets, areas, cells, elements, embeds, filters, forms, frames, images, imports, links, options, plugins, rows, scripts, styleSheets


javaEnabled

Description

Returns whether Java is enabled.

Syntax

Boolean = object.javaEnabled( )

Return Value

Returns TRUE if Java is enabled, or FALSE otherwise.

Applies To

navigator


move

Description

Collapses the given text range and moves the empty range by the given number of units.

Syntax

long = object.move(unit [, count])

Parameter | Description
unit String specifying the units to move. Can be one of the following:
character | Moves one or more characters.
word | Moves one or more words. A word is a collection of characters terminated by a space or other white-space character.
sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit | Moves to the start or end of the original range.
count | Optional. Integer specifying the number of units to move. This can be positive or negative. When omitted, defaults to 1.

Return Value

Returns the actual number of units moved.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange

See Also

moveEnd, moveStart


moveBy

Description

Moves the screen position of the window by the specified x and y offsets relative to its current position.

Syntax

object.moveBy(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Applies To

window


moveEnd

Description

Changes the scope of the range by moving the end position of the range.

Syntax

long = object.moveEnd(unit [, count])

Parameter | Description
unit String specifying the units to move. Can be one of the following strings:
character | Moves one or more characters.
word | Moves one or more words. A word is a collection of characters terminated by a space or other white-space character.
sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit | Moves to the start or end of the original range.
count | Optional. Integer specifying the number of units to move. This can be positive or negative. When omitted, defaults to 1.

Return Value

Returns the actual number of units moved.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange

See Also

move, moveStart


moveStart

Description

Changes the scope of the range by moving the start position of the range.

Syntax

long = object.moveStart(unit [, count])

Parameter | Description
unit String specifying the units to move. Can be one of the following strings:
character | Moves one or more characters.
word | Moves one or more words. A word is a collection of characters terminated by a space or other white-space character.
sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
textedit | Moves to the start or end of the original range.
count | Optional. Integer specifying the number of units to move. This can be positive or negative. When omitted, defaults to 1.

Return Value

Returns the actual number of units moved.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange

See Also

move, moveEnd


moveTo

Description

Moves the screen position of the upper-left corner of the window to the specified x and y pixel position.

Syntax

object.moveTo(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Applies To

window


moveToBookmark

Description

Moves to a bookmark. Bookmarks are opaque strings that are created with the getBookmark method.

Syntax

Boolean = object.moveToBookmark( )

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


moveToElementText

Description

Moves the text range so that the start and end positions of the range encompass the text in the given element.

Syntax

object.moveToElementText(element)

Parameter | Description
element | Element object.

Return Value

No return value.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


moveToPoint

Description

Moves the start and end positions of the text range to the given point. The coordinates of the point must be in pixels and be relative to the upper-left corner of the window. The resulting text range is empty, but can be expanded and moved using methods such as expand and moveEnd.

Syntax

object.moveToPoint(x, y)

Parameter | Description
x | Integer specifying the x-coordinate, in pixels.
y | Integer specifying the y-coordinate, in pixels.

Return Value

No return value.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following JScript example moves the text range to the same point as the user clicked the mouse, then expands the range and selects the text within the new range.

<SCRIPT FOR=document EVENT=onclick LANGUAGE="JScript">
var rng = document.body.createTextRange();
rng.moveToPoint(window.event.x, window.event.y);
rng.expand("word");
rng.select();
</SCRIPT>

Applies To

TextRange


navigate

Description

Equivalent to the window.location.href property.

Syntax

object.navigate(URL)

Parameter | Description
URL | (String) URL to be displayed.

Return Value

No return value.

Applies To

window

See Also

href property


nextPage

Description

Allows viewing the next page of records in the data set to which the table is bound.

Syntax

object.nextPage( )

Return Value

No return value.

Remarks

The number of records displayed in the table is determined by the dataPageSize property of the table. The Web author must set the DATAPAGESIZE attribute when designing the page or set the corresponding dataPageSize property at run time for this method to have any effect.

Note The page author does not need to check for boundary conditions.

Applies To

table

See Also

previousPage


open

Description

Opens a new window and loads the document given by URL, or a blank document if a URL is not provided.

Syntax

window = object.open([URL [, name [, features [, replace]]]])

Parameter | Description
URL | String specifying the URL of the document to display. If no URL is specified, a new window with about:blank will be displayed.
name | Optional. String specifying the name of the window. This name is used for TARGET on a FORM or an A.
features Optional. String specifying the window ornaments to display. The following table lists the supported features.
Syntax | Description
fullscreen={ yes | no | 1 | 0 } Specifies whether to display the browser in a full-screen or normal window. Default is no.

Use full-screen mode carefully. Because this mode hides the browser's title bar and menus, you should always provide a button or other visual clue to help the user close the window. ALT+F4 will also close the new window.

channelmode={ yes | no | 1 | 0 } | Specifies whether to display the window in theater mode and show the channel band.
toolbar={ yes | no | 1 | 0 } | Specifies whether to display the browser toolbar, making buttons such as Back, Forward, and Stop available.
location= { yes | no | 1 | 0 } | Specifies whether to display the input field for entering URLs directly into the browser.
directories = { yes | no | 1 | 0 } | Specifies whether to add directory buttons. Default is no.
status={ yes | no | 1 | 0 } | Specifies whether to add a status bar at the bottom of the window. Default is yes.
menubar={ yes | no | 1 | 0} | Specifies whether to display the menu bar. Default is yes.
scrollbars={ yes | no | 1 | 0} | Specifies whether to display horizontal and vertical scroll bars. Default is yes.
resizable={ yes | no | 1 | 0} | Specifies whether to display resize handles at the corners of the window.
width=number | Sets the width of the window, in pixels. Minimum value should be 100.
height=number | Specifies the height of the window, in pixels. Minimum value should be 100.
top=number | Specifies the top position, in pixels. This value is relative to the upper-left corner of the screen.
left=number | Specifies the left position, in pixels. This value is relative to the upper-left corner of the screen.
replace | Optional. A boolean value specifying whether the URL that is loaded into the new page should create a new entry in the window's browsing history or replace the current entry in the browsing history. If true, no new history entry is created.

Return Value

Returns a reference to the new window. Use this reference to script properties and methods on the new window.

Remarks

A name for the new window can be used as a target for a form or an A element. By default, the open() method creates a window that has a default width and height and the standard menu, toolbar, and other features of Internet Explorer. You can alter this set of features by using the features parameter. This parameter is a string consisting of one or more feature settings. The replace parameter controls whether the new window is put into the browser history list.

For example, the following creates a new window that contains Sample.htm. The new window is 200 by 400 pixels, has a status bar, but does not have a toolbar, menu bar, or address field.

window.open("sample.htm",null,
    "height=200,width=400,status=yes,toolbar=no,menubar=no,location=no");

Applies To

window


open

Description

Opens a stream to collect the output of write or writeln methods.

Syntax

document.open(mimeType, replace)

Parameter | Description
mimeType | Currently supports "text/html" only.
replace | Optional. String ("replace") indicating whether you want the new document you are writing to replace the current document in the History list. Otherwise, by default, the document you are creating will not replace the current document in the History list.

Return Value

No return value.

Remarks

The following example replaces the document with the new document.

document.open("text/html", "replace")

Applies To

document

Events

onbeforeunload


parentElement

Description

Retrieves the parent element for the given text range. The parent element is the element that completely encloses the text in the range.

Syntax

element = object.parentElement( )

Return Value

Returns an element object if successful, or null otherwise.

Remarks

If the text range spans text in more than one element, this method returns the smallest element that encloses all the elements. When you insert text into a range that spans multiple elements, the text is placed within the parent element rather than in any of the contained elements.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following JScript example retrieves the parent element for the text range created from the current selection and displays the tag name of the element.

var sel = document.selection;
var rng = sel.createRange();
var el = rng.parentElement();
alert(el.tagName);

Applies To

TextRange


pasteHTML

Description

Pastes HTML text into the given text range. The text completely replaces any previous text and HTML elements in the range.

Syntax

object.pasteHTML(htmlText)

Parameter | Description
htmlText | String specifying the HTML text to paste. The string can contain text and any combination of the HTML tags described in HTML Elements.

Return Value

No return value.

Remarks

Although this method never fails, it might alter the HTML text to make it fit the given text range. For example, attempting to paste a table cell into a text range that does not contain a table might cause the method to insert a TABLE element. For predictable results, you should paste only well-formed HTML text that is appropriate for the given text range.

Note You cannot use this method while the document is loading. Wait until the document is completely downloaded.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following JScript example replaces the current selection with a new paragraph.

var sel = document.selection;
if (sel!=null) {
    var rng = sel.createRange();
    if (rng!=null)
        rng.pasteHTML("<P><B>Selection has been replaced.</B>");
}

Applies To

TextRange


previousPage

Description

Allows viewing the previous page of records in the data set to which the table is bound.

Syntax

object.previousPage

Return Value

No return value.

Remarks

The number of records displayed in the table is determined by the dataPageSize property of the table. The Web author must set the DATAPAGESIZE attribute when designing the page or set the corresponding dataPageSize property at run time for this method to have any effect.

Note The page author does not need to check for boundary conditions.

Applies To

TABLE

See Also

nextPage


prompt

Description

Displays a Prompt dialog box with a message and an input field.

Syntax

object.prompt([message [, inputDefault]])

Parameter | Description
message | Optional. (String) String to display.
inputDefault | Optional. (String) String or integer that represents the default value of the input field.

Return Value

Returns the value that the user types in.

Remarks

If the inputDefault parameter is not supplied, the dialog box displays the value <undefined>. You have no control over the title of the prompt box.

Applies To

window


queryCommandEnabled

Description

Returns whether the command can be successfully executed using ExecCommand now, given the current state of the document.

Syntax

Boolean = object.queryCommandEnabled(command)

Parameter | Description
command | (String) String that specifies the command to query. Can be any valid command identifier.

Return Value

Returns TRUE if the command is enabled, or FALSE otherwise.

Remarks

Note: queryCommandEnabled("delete") on TextRange returns TRUE, while queryCommandEanbled("delete") on Document returns FALSE, but you can still use execCommand("Delete") to delete the selected text.

Applies To

document, TextRange

See Also

execCommand, queryCommandIndeterm, queryCommandState, queryCommandSupported, queryCommandValue


queryCommandIndeterm

Description

Returns whether the specified command is in the indeterminate state.

Syntax

Boolean = object.queryCommandIndeterm(command)

Parameter | Description
command | (String) String that specifies the command to query. Can be any valid command identifier.

Return Value

Returns TRUE if indeterminate, or FALSE otherwise.

Remarks

As an example, given a text range, if some of the characters are bold and others are not, queryCommandIndeterm for bold would return TRUE.

Applies To

document, TextRange

See Also

execCommand, queryCommandEnabled, queryCommandState, queryCommandSupported, queryCommandValue


queryCommandState

Description

Returns the current state of the command.

Syntax

Boolean = object.queryCommandState(command)

Parameter | Description
command | (String) String that specifies the command to query. Can be any valid command identifier.

Return Value

Returns TRUE if the given command has been carried out on the object, FALSE if it has not, and NULL if it is not possible to determine the command state.

Applies To

document, TextRange

See Also

execCommand, queryCommandEnabled, queryCommandIndeterm, queryCommandSupported, queryCommandValue


queryCommandSupported

Description

Returns whether the current command is supported on the current range.

Syntax

Boolean = object.queryCommandSupported(command)

Parameter | Description
command | (String) String that specifies the command to query. Can be any valid command identifier.

Return Value

Returns TRUE if the command is supported, or FALSE otherwise.

Applies To

document, TextRange

See Also

execCommand, queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandValue


queryCommandValue

Description

Returns the current value of the given command. If the command returns a value such as a color rather than a TRUE/FALSE state, this command is used to retrieve the current value of the document or range.

Syntax

string = object.queryCommandValue(command)

Parameter | Description
command | (String) String that specifies the command to query. Can be any valid command identifier.

Return Value

Returns a string representing the command value if the command is supported, or TRUE/FALSE.

Applies To

document, TextRange

See Also

execCommand, queryCommandEnabled, queryCommandIndeterm, queryCommandState, queryCommandSupported


refresh

Description

Refreshes the content of the table.

Syntax

object.refresh( )

Return Value

No return value.

Applies To

TABLE


reload

Description

Reloads the current page.

Syntax

object.reload([bReloadSource] )

Parameter | Description
bReloadSource | Optional. Boolean value specifying whether to reload the page from the cache or server. If TRUE, the page is reloaded from the server. By default, this parameter is FALSE.

Return Value

No return value.

Applies To

location


remove

Description

Removes an element from the collection.

Syntax

object.remove(index)

Parameter | Description
index | Number or string specifying the element to remove. If this parameter is a number, the method removes the element at the given position in the collection, where 0 is the first position, 1 the second, and so on. If this parameter is a string, the method removes all elements having a name or id property equal to the string.

Return Value

No return value.

Remarks

For the areas object, this method can only be used on the object after the page has been loaded. If the method is applied "inline," a run-time error will occur.

Applies To

areas, options

See Also

add


removeAttribute

Description

Removes the given attribute from the element.

Syntax

Boolean = object.removeAttribute(attrName [, caseSensitive])

Parameter | Description
attrName | String specifying the name of the attribute.
caseSensitive | Optional. Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in attrName must match exactly those in the attribute name. By default, this parameter is TRUE. If there are multiple attributes specified with different case sensitivity, the attribute returned might vary across platforms.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and caseSensitive is FALSE, this method removes only the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

Applies To

A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP, style


replace

Description

Replaces the current document by loading the document at the given url. This method also removes the current document from the browser's session history.

Syntax

object.replace(url)

Parameter | Description
url | String specifying the URL to insert into the session history.

Remarks

Replacing a document causes it to no longer be accessible through the history object. Also, the URL is no longer accessible through the user interface navigation methods (Back, Forward, and so on).

Applies To

location


reset

Description

Simulates a mouse click on a reset button for the calling form.

Syntax

object.reset( )

Return Value

No return value.

Applies To

FORM

See Also

INPUT, button, submit


resizeBy

Description

Changes the size of the window outside dimensions by the specified x and y offset relative to its current size.

Syntax

object.resizeBy(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Applies To

window


resizeTo

Description

Sets the size of the window outside dimensions to the specified x and y pixel sizes.

Syntax

object.resizeTo(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Applies To

window


scroll

Description

Causes the window to scroll to the specified x and y offset at the upper-left corner of the window. The preferred method for this is scrollTo; the scroll method is provided for backward compatibility only.

Syntax

object.scroll(x, y)

Parameter | Description
x | (Long) Horizontal position, in pixels.
y | (Long) Vertical offset, in pixels.

Return Value

No return value.

Applies To

window


scrollBy

Description

Causes the window to scroll relative to the current scrolled position by the specified x and y pixel offsets.

Syntax

object.scrollBy(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Remarks

Positive values of x/y scroll further right/down; negative values scroll further left/up. Setting the scroll position beyond the limits results in the extreme valid scroll position in the direction specified.

Applies To

window


scrollIntoView

Description

Causes the object to scroll into view, aligning it at either the top or bottom of the window.

Syntax

object.scrollIntoView([start])

Parameter | Description
start | Optional. Boolean value specifying whether to place the object at the top of the window or at the bottom. If TRUE, the method causes the object to scrolls so that its top is visible at the top of the window. If FALSE, the bottom of the object is visible at the bottom of the window. If no value is given, the object scrolls to the top by default.

Return Value

No return value.

Remarks

The following example causes the element to scroll into view within the window, placing it at either the top or bottom of the window. The method is useful for immediately showing the user the result of some action without requiring the user to manually scroll through the document to find the result. This example underlines the content of the fifth paragraph and scrolls it into view at the top of the window.

var coll = document.all.tags("P");
if (coll.length>=5) {
    coll(4).style.textDecoration = "underline";
    coll(4).scrollIntoView(true);
}

Depending on the size of the given object and the current window, this method might not be able to put the item at the very top or very bottom, but will always position the object as close to the requested position as possible.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, WBR, XMP, TextRange


scrollTo

Description

Scrolls the window to the specified x and y offsets at the upper-left corner of the window.

Syntax

object.scrollTo(x, y)

Parameter | Description
x | (Long) Horizontal scroll offset, in pixels.
y | (Long) Vertical scroll offset, in pixels.

Return Value

No return value.

Applies To

window


select

Description

Highlights the input area of a form element.

Syntax

object.select( )

Return Value

No return value.

Remarks

You can use the select method with the focus method to highlight a field and position the cursor for a user response.

Applies To

INPUT, TEXTAREA

See Also

onselect


select

Description

Makes the active selection equal to the current object.

Syntax

object.select( )

Return Value

No return value.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Applies To

TextRange


setAttribute

Description

Sets the value of the given attribute. If the attribute is not already present, the method adds the attribute to the element and sets the value.

Syntax

object.setAttribute(attrName , value [, caseSensitive])

Parameter | Description
attrName | String specifying the name of the attribute.
value | String, number, or Boolean value to assign to the attribute.
caseSensitive | Optional. Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in attrName must match exactly those in the attribute name. By default, this parameter is TRUE.

Return Value

No return value.

Remarks

Be careful when spelling attribute names. If caseSensitive is TRUE and attrName does not have the same uppercase and lowercase letters as the attribute, this method creates a new attribute.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and caseSensitive is FALSE, this method assigns a value only to the first attribute (the first to be created with this name). All other attributes of the same name are ignored.

Applies To

A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, META, NEXTID, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, WBR, XMP, style


setEndPoint

Description

Sets the end point of one range based on the end point of another. This method takes two parameters: a string that describes the end points to transfer, and a range from which the source end point will be taken.

Syntax

object.setEndPoint(type, range)

Parameter | Description
type String that describes the end point to transfer. Can be one of these values:
StartToEnd
StartToStart
EndToStart
EndToEnd
range | Text range object specifying the range from which the source end point is to be taken.

Return Value

No return value.

Remarks

This feature might not be available on non-Win32 platforms. See article Q172976 in the Microsoft Knowledge Base for the latest information on Internet Explorer cross-platform compatibility.

Example

The following JScript example sets the start point of the current range (r1) to the end point of the second range (r2).

r1.setEndPoint("StartToEnd", r2);

Applies To

TextRange


setInterval

Description

Repeatedly evaluates an expression after a specified number of milliseconds has elapsed.

Syntax

intervalID = object.setInterval(expression, msec [, language])

Parameter | Description
expression | String containing the script code to execute each time the interval elapses.
msec | Integer value or numeric string specifying the length of the interval, in milliseconds.
language | Optional. String specifying the language in which the code is executed.

Return Value

Returns an integer identifier representing the interval. Use this identifier to clear (stop) the interval.

Example

The following example sets a 5-second interval. Each time the interval elapses, the background color of the document changes.

setInterval("changeColor()", 5000);
   .
   .
   .
function changeColor()
{
  if (document.body.bgColor == "#ff0000")   // Check if body bgColor is red by comparing to hexidecimal value
      document.body.bgColor = "blue";
  else
      document.body.bgColor = "red";
}

Applies To

window

See Also

clearInterval


setTimeout

Description

Evaluates an expression after a specified number of milliseconds has elapsed.

Syntax

timeoutID = object.setTimeout(expression, msec [, language])

Parameter | Description
expression | (String) Code to be executed at the specified interval.
msec | (Long) Numeric value or numeric string in millisecond units.
language | Optional. (String) String that specifies the language in which the code is executed.

Return Value

Returns an identifier that is used only to cancel the evaluation with the clearTimeout method.

Applies To

window


showHelp

Description

Displays a Help file. This method can be used with WinHelp or with HTMLHelp.

Syntax

object.showHelp(URL [, arguments])

Parameter | Description
URL | String specifying the URL of the document to display.
contextID | Optional. Identifier of a help context ID in a Help file. Required if displaying an .hlp file.

Return Value

No return value.

Remarks

When implementing this method, a second Help dialog box will appear if the user presses the F1 key or clicks Help from the menu bar. You can prevent the default Help dialog box from appearing by setting window.event.returnValue=false.

The contextID parameter is needed for calling Windows Help files. Without a valid contextID, Help does not load when the URL specifies a Windows Help file.

Applies To

window


showModalDialog

Description

Creates a dialog box and displays in it the HTML document given by URL. The dialog box is a special window that is modal, meaning it retains the input focus until the user closes it.

Syntax

variant = object.showModalDialog(sURL [, vArguments [, sFeatures]])

Parameter | Description
sURL | String specifying the URL of the document to load and display. While an empty string is accepted (""), it should be noted that this is useless since once a modal dialog has been opened, it cannot be accessed by the page that opened it.
vArguments | Optional. Variant specifying the arguments to use when displaying the document. This parameter can be used to pass a value of any type including an array of values. The dialog can extract the values passed by the caller from the dialogArguments property of the window object.
sFeatures Optional. String specifying the window ornaments for the dialog box. It can be a combination of the following values.
Syntax | Description
dialogWidth:number | Sets the width of the dialog window.
dialogHeight:number | Sets the height of the dialog window.
dialogTop:number | Sets the top position of the dialog window relative to the upper-left corner of the desktop.
dialogLeft:number | Sets the left position of the dialog window relative to the upper-left corner of the desktop.
center:{yes | no | 1 | 0 } | Specifies whether to center the dialog window within the desktop. Default is yes.

Return Value

Returns a number, string, or other value. This is equal to the value of the returnValue property as set by the document given by URL.

Remarks

The default font settings should be set in the same way CSS attributes are set; for example, "font:3;font-size:4". To define multiple font values, use multiple font attributes.

When dialogLeft and/or dialogTop is specified, the feature center is overridden, even though the default for center is yes.

Applies To

window


start

Description

Begins scrolling the marquee.

Syntax

object.start( )

Return Value

No return value.

Remarks

The onstart event must be implicitly set.

Applies To

MARQUEE


stop

Description

Stops the marquee scrolling.

Syntax

object.stop( )

Return Value

No return value.

Applies To

MARQUEE


submit

Description

Submits the form and fires the onsubmit event.

Syntax

object.submit( )

Return Value

No return value.

Applies To

FORM

See Also

INPUT, reset


tags

Description

Retrieves a collection of all elements in the given collection that have the given HTML tag name.

Syntax

elements = object.tags(tag)

Parameter | Description
tag | String specifying the name of an HTML tag. It can be the name of any one of the elements listed in Objects.

Return Value

Returns a collection of element objects if successful, or null otherwise.

Remarks

This method returns an empty collection if no elements having the given name are found. Use the length property on the collection to determine the number of elements it contains.

Example

The following JScript example retrieves a collection of all P elements in the document, then applies an underline to each.

var coll = document.all.tags("P");
if (coll!=null) {
    for (i=0; i<coll.length; i++)
    coll[i].style.textDecoration="underline";
}

Applies To

all, anchors, applets, areas, embeds, forms, images, links, plugins, scripts, styleSheets


taintEnabled

Description

Returns whether data tainting is enabled.

Syntax

object.taintEnabled( )

Return Value

Always returns FALSE for Internet Explorer 4.0. Data tainting is not supported.

Applies To

navigator


write

Description

Writes one or more HTML expressions to a document in the specified window.

Syntax

object.write(string)

Parameter | Description
string | String specifying the text and/or HTML tags to write.

Return Value

No return value.

Applies To

document


writeln

Description

Writes one or more HTML expressions to a document in the specified window, followed by a carriage return.

Syntax

object.writeln(string)

Parameter | Description
string | String specifying the text and/or HTML tags to write.

Return Value

No return value.

Remarks

In HTML, the carriage return is ignored unless within preformatted text.

Applies To

document


zOrder

Description

Sets the z-index for positions.

Syntax

object.zOrder([position])

Parameter Description
position (Variant) Can be an integer value specifying the z-order as an absolute value, or one of these string values:
Front | Sends the item to the front of the z-order.
Back | Sends the item to the back of the z-order.

Remarks

If no position is given, the default is Front. This method applies to all positioned elements.

Applies To

APPLET, BUTTON, CAPTION, DIV, EMBED, HR, IMG, INPUT (all types except hidden), MARQUEE, OBJECT, SPAN, TD, TEXTAREA


Events

onabort onafterupdate onbeforeunload onbeforeupdate
onblur onbounce onchange onclick
ondataavailable ondatasetchanged ondatasetcomplete ondblclick
ondragstart onerror onerrorupdate onfilterchange
onfinish onfocus onhelp onkeydown
onkeypress onkeyup onload onmousedown
onmousemove onmouseout onmouseover onmouseup
onreadystatechange onreset onresize onrowenter
onrowexit onscroll onselect onselectstart
onstart onsubmit onunload

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


onabort

Description

Fires when the user aborts the download of the image.

Remarks

An image can be aborted by clicking a link, clicking the Stop button, and so on. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event

Applies To

IMG


onafterupdate

Description

Fires after the transfer of data from the element to the data provider (after a successful onbeforeupdate).

Remarks

This event only fires when the object is databound and an onbeforeupdate event has fired (the element's data has changed). This event cannot be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, IMG, INPUT, MAP, MARQUEE, OBJECT, SELECT, TABLE, TD, TEXTAREA, TR

See Also

onbeforeupdate


onbeforeunload

Description

Fires prior to a page being unloaded.

Remarks

This event gives you a chance to request that the user not leave the page. By returning a string to this event, a dialog box is displayed that gives the user the option to stay on the page. The returned string is displayed in a predefined area to provide the user with the reason.

This event also fires when a document.open is done and when a frameset is created.

Applies To

FRAMESET, window

See Also

onunload


onbeforeupdate

Description

Fires before the transfer of data from the element to the data provider. Fires when an element loses focus or the page is attempting to unload when the value of the element has changed from the value that was in the element at the time it received the focus.

Remarks

This event can be canceled. This allows the programmer to fail the validation and leave the content of the field as well as the cursor intact. All subsequent events are not fired when this event is canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, HR, IMG, INPUT, MAP, OBJECT, SELECT, TABLE, TD, TEXTAREA, TR

See Also

onafterupdate


onblur

Description

Fires when an object, such as a button or check box, loses the input focus.

Remarks

This event is fired even when clicking another control or the background of the page, switching applications, or opening another window within the browser. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event

Applies To

A, APPLET, AREA, BUTTON, DIV, EMBED, HR, IMG, INPUT, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TD, TEXTAREA, TR, window


onbounce

Description

Fires when the behavior property of the MARQUEE element is set to "alternate" and the contents of the marquee reach a side.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

MARQUEE


onchange

Description

Fires when the contents of the object have changed.

Remarks

This event is fired when the contents are committed, not while the value is changing. For example, on a text box, this event is not fired while the user is typing, but rather when the user commits the change by pressing ENTER or leaving the text box focus. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

This code is executed before the code specified by onblur, if the control is also losing the focus.

Applies To

INPUT, SELECT, TEXTAREA

See Also

onkeypress


onclick

Description

Fires when the user presses and releases the left mouse button, or when the user presses keys, such as ENTER and ESC, in a form.

Remarks

The following actions cause an onclick event.

  • Click the left mouse button.
  • Press ENTER when either the submit control or a nonbutton control in the form has focus.
  • Press the ESC key when any control in the form has the focus.
  • Press the SPACEBAR when a checkbox, radio, reset, or submit control has focus or a BUTTON or TEXTAREA element has focus.
  • Press the access key specified by the accessKey property for a checkbox, radio, reset, or submit control or a BUTTON, OPTION, SELECT, or TEXTAREA element.

The default action of an onclick event depends on the object that receives the click. For example, clicking an A element causes the browser to load the document specified by the href property. You can cancel the default behavior by setting the returnValue property of the event object to FALSE.

If the user clicks the left mouse button, the onclick event for an object occurs only if the mouse pointer is over the object and both an onmousedown and an onmouseup event occur in order. For example, if the user presses down in the object but moves the mouse pointer out of the object before releasing, no onclick event occurs.

If the user clicks an object that can receive the input focus but does not already have the focus, the onfocus event occurs for that object before the onclick event. If the user double-clicks the left mouse button in a control, an ondblclick event occurs immediately after the onclick event.

Although the onclick event is available on a large number of HTML tags, its use should be restricted to the <A>, <INPUT>, <AREA>, and <BUTTON> tags. These elements automatically allow keyboard access via the TAB key, making Web pages that use them accessible to keyboard users. For more information, please see the section on Writing Accessible Dynamic HTML.

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Examples

The following JScript example is an onclick event handler for the document. It uses the event object to display the tag name of the element in which the click occurred.

<SCRIPT>
function clickit() {
    alert("Clicked in " + window.event.srcElement.tagName);
}
</SCRIPT>

<BODY onclick="clickit()">

The following VBScript example is an onclick event handler for the document. It uses the event object to determine whether the click occurred in an A element and then cancels the event (and prevents a jump) if the SHIFT key is down.

<SCRIPT LANGUAGE="VBScript">
Function document_onclick()
    If window.event.srcElement.tagName = "A" And window.event.shiftKey Then
        window.event.returnValue = False
    End If
End Function
</SCRIPT>

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document

See Also

click


ondataavailable

Description

Fires periodically as data arrives for data source objects that transmit their data asynchronously. Frequency of firing is dependent upon the data source object.

Remarks

This event fires for objects and applications that are data source objects. There is a qualifier property on the event object; the qualifier will always be set to "" for Internet Explorer 4.0. This event cannot be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

APPLET, IMG, MAP, OBJECT


ondatasetchanged

Description

Fires when the data set exposed by a data source object changes—for example, when a filter operation takes place. Also fires when initial data is available from a data source object.

Remarks

This event fires for objects and applications that are data source objects. There is a qualifier property on the event object; the qualifier will always be set to "" for Internet Explorer 4.0. This event cannot be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

APPLET, IMG, MAP, OBJECT


ondatasetcomplete

Description

Fires to indicate that all data is available from the data source object.

Remarks

This event fires for objects and applications that are data source objects. There is a qualifier property and a reason property on the event object. The qualifier will always be set to "" for Internet Explorer 4.0. This event cannot be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

The reason property is set to indicate the reason for completion and is one of these values:
0 | Data transmitted successfully.
1 | Data transfer aborted.
2 | Data transfer in error.

Applies To

APPLET, IMG, MAP, OBJECT


ondblclick

Description

Fires when the user clicks twice over an object.

Return Value

Returns TRUE or FALSE. Returning FALSE cancels the default action.

Remarks

The ondblclick event occurs when the user clicks twice (presses and releases the left mouse button and then presses and releases it again) over an object. The two clicks must occur within the time limit specified by the system's double-click speed setting. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

The order of events leading to the ondblclick event is:

  1. onmousedown
  2. onmouseup
  3. onclick
  4. onmouseup
  5. ondblclick

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


ondragstart

Description

Fires when the user first starts to drag a selection or selected element.

Remarks

For the INPUT element, the only types supported for this event are file, image, password, and text.

This event can be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, ACRONYM, ADDRESS, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


onerror

Description

Fires when a scripting error occurs (for example, when there are security problems during the loading process or when there is a problem in the code).

Remarks

When programming in VBScript, you can create an event handler that receives event parameters by defining a subroutine having this form:

Sub window_onerror(message, url, line)
    window.event.returnValue=true

The line parameter is an integer specifying the line number at which the error occurred, url is a string specifying the URL of the document containing the error, and the optional message is a message string. Returning true for the event prevents the default error message for Internet Explorer from displaying.

The following example uses JScript.

function errortrap(msg,url,line){
    alert(msg);
    return true;
}
onerror=errortrap;

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

window

See Also

onerror event for other objects


onerror

Description

Fires when an error occurs loading the image or other object.

Remarks

You can suppress error messages that occur when an image fails to load by setting the onerror attribute in the element to "null". This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

IMG, LINK, OBJECT, SCRIPT, STYLE


onerrorupdate

Description

Fires when the onbeforeupdate event handler specified for the element has canceled the data transfer and is fired instead of the onafterupdate event.

Remarks

This event only fires when an onbeforeupdate event has fired (the element's data has changed). This event cannot be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, APPLET, MAP, OBJECT, SELECT, TEXTAREA


onfilterchange

Description

Fires when a visual filter changes state or completes a transition.

Remarks

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR


onfinish

Description

Fires when looping is complete.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

MARQUEE


onfocus

Description

Fires when a control receives the focus. This event also fires for some noncontrol elements such as HR.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

A, APPLET, AREA, BUTTON, DIV, EMBED, HR, IMG, INPUT, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TD, TEXTAREA, TR, window

See Also

focus


onhelp

Description

Fires when the user presses the F1 or Help key on the browser.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document, window


onkeydown

Description

Fires when the user presses a key.

Return Value

Returns a number specifying the keycode of the key that was pressed.

Remarks

The return value can be used to override the keycode value. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

To cancel the keystroke, use the following code in the onkeydown event:

event.returnValue=false;

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


onkeypress

Description

Fires when a user presses a key.

Return Value

Returns a number specifying the Unicode value of the key that was pressed.

Remarks

The return value can be used to override the keycode value. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

To cancel the keystroke, use the following code in the onkeypress event:

event.returnValue=false;

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document

See Also

onchange


onkeyup

Description

Fires when the user releases a key.

Return Value

Returns a number specifying the keycode of the key released.

Remarks

The return value can be used to override the keycode value. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

To cancel the keystroke, use the following code in the onkeyup event:

event.returnValue=false;

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DT, EM, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


onload

Description

Fires immediately after the browser loads the given object.

Remarks

The browser loads applications, embedded objects, and images as soon as it encounters the APPLET, EMBED, and IMG elements during parsing. This means that the onload event for these objects occurs before the browser parses any subsequent elements. To ensure that an event handler receives the onload event for these elements, you must place the SCRIPT element that defines the event handler before the element and use the onload attribute in the element to set the handler.

The onload attribute of the BODY element sets an onload event handler for the window. Setting an onload event handler for the window object by any other means will override the handler set using the onload attribute if the handlers are in the same script language.

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Examples

The following JScript example is an onload event handler for the window.

<SCRIPT FOR=window EVENT=onload LANGUAGE="JScript">
    window.status = "Page is loaded!";
</SCRIPT>

The following JScript example sets an onload event handler for an IMG element. The handler uses the event object to retrieve the URL of the image.

<SCRIPT LANGUAGE="JScript">
function imageLoaded()
{
    window.status = "Image \"" + window.event.srcElement.src + "\" is loaded";
}
</SCRIPT>
<IMG SRC="sample.gif" onload="imageLoaded()">

Applies To

APPLET, EMBED, FRAMESET, IMG, LINK, SCRIPT, STYLE, window


onmousedown

Description

Fires when the user presses a button on a pointer device, such as the mouse.

Remarks

The event ordering for mouse-related events is:

  1. onmousedown
  2. onmouseup
  3. onclick
  4. ondblclick
  5. onmouseup

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document

See Also

ondblclick, onmousemove, onmouseup


onmousemove

Description

Fires when the user moves the mouse.

Remarks

The event ordering for moving the mouse is:

  1. onmouseover
  2. onmousemove
  3. onmouseout

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document

See Also

onmousedown, onmouseup


onmouseout

Description

Fires when the user moves the mouse pointer out of an element.

Remarks

When the user moves the mouse pointer into an element, one onmouseover event occurs, followed by one or more onmousemove events as the user moves the pointer within the element, and finally one onmouseout event when the user moves the pointer out of the element. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Examples

The following JScript example sets the onmouseout event handler for an element having the identifier "para_1". The handler changes the color of the text in the element when the mouse pointer leaves the element.

<SCRIPT FOR=para_1 EVENT=onmouseout LANGUAGE="JScript">
var el = window.event.srcElement;
for ( ; el.id != "para_1"; el = el.parentElement);
el.style.color = "silver";
</SCRIPT>

The following JScript example sets the onmouseout event handler for an IMG element. The handler changes the image source file for the element when the mouse pointer leaves the element.

<IMG SRC="inactive.gif" onmouseover="flipImage('active.gif')" onmouseout="flipImage('inactive.gif')">
    .
    .
    .
<SCRIPT LANGUAGE="JScript">
function flipImage(url)
{
    if (window.event.srcElement.tagName == "IMG" ) {
        window.event.srcElement.src = url;
    }
}
</SCRIPT>

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


onmouseover

Description

Fires when the user moves the mouse pointer into an element. The event occurs when the pointer first enters the element and does not repeat unless the user moves the pointer out of the element and then back into it.

Remarks

When the user moves the mouse pointer into an element, one onmouseover event occurs, followed by one or more onmousemove events as the user moves the pointer within the element, and finally one onmouseout event when the user moves the pointer out of the element. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Examples

The following JScript example sets the onmouseover event handler for an element having the identifier "para_1". The handler changes the color of the text in the element when the mouse pointer enters the element.

<SCRIPT FOR=para_1 EVENT=onmouseover LANGUAGE="JScript">
var el = window.event.srcElement;
for ( ; el.id != "para_1"; el = el.parentElement);
el.style.color = "black";
</SCRIPT>

The following JScript example sets the onmouseover event handler for an IMG element. The handler changes the image source file for the element when the mouse pointer enters the element.

<IMG SRC="inactive.gif" onmouseover="flipImage('active.gif')" onmouseout="flipImage('inactive.gif')">
    .
    .
    .
<SCRIPT LANGUAGE="JScript">
function flipImage(url)
{
    if (window.event.srcElement.tagName == "IMG" ) {
        window.event.srcElement.src = url;
    }
}
</SCRIPT>

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document


onmouseup

Description

Fires when the user releases a mouse button.

Remarks

This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, ADDRESS, APPLET, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MAP, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, document

See Also

ondblclick, onmousedown, onmousemove


onreadystatechange

Description

Fires whenever the ready state for the object has changed.

Remarks

Each object can choose to expose which set of ready states it is exposing. This event should be fired whenever the ready state is changed.

When an element changes to the loaded state, this event fires immediately before the firing of the load event. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

APPLET, EMBED, IMG, LINK, OBJECT, SCRIPT, STYLE, document

See Also

onload, readyState

GE


onreset

Description

Fires when a user resets a form (clicks a Reset button). The onreset event handler executes code when a reset event occurs.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

FORM


onresize

Description

Fires at the beginning of a resize operation.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event. This event will not fire for files with embedded controls.

Applies To

APPLET, BUTTON, CAPTION, DIV, EMBED, FRAMESET, HR, IMG, MARQUEE, SELECT, TABLE, TD, TR, TEXTAREA, window


onrowenter

Description

Fires to indicate that the current row has changed and new data values are available.

Remarks

This event only fires when the object is databound. This event applies only to objects that identify themselves as a data provider. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, HR, IMG, MAP, MARQUEE, OBJECT, SELECT, TABLE, TD, TEXTAREA, TR


onrowexit

Description

Fires just prior to the data source control changing the current row.

Remarks

This event only fires when the object is databound. This event applies only to objects that identify themselves as a data provider. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

APPLET, BODY, BUTTON, CAPTION, DIV, EMBED, HR, IMG, MAP, MARQUEE, OBJECT, SELECT, TABLE, TD, TEXTAREA, TR


onscroll

Description

Fires when the scroll box is repositioned.

Remarks

This notification event fires for the window object and all elements that scroll. This event cannot be canceled and will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

DIV, FIELDSET, IMG, MARQUEE, SPAN, TEXTAREA, window


onselect

Description

Fires when the current selection changes.

Remarks

This event will fire as the mouse moves from character to character during a drag selection. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

INPUT, TEXTAREA

See Also

select


onselectstart

Description

Fires at the beginning of an element selection.

Remarks

This event will fire as the mouse starts the selection of one or more elements. The element at the beginning of the selection fires the event. This event can be canceled. This event will bubble. Events that bubble can be handled on any parent element of the object that fired the event.

Applies To

A, ACRONYM, ADDRESS, AREA, B, BIG, BLOCKQUOTE, BODY, BUTTON, CAPTION, CENTER, CITE, CODE, DD, DEL, DFN, DIR, DIV, DL, DT, EM, FONT, FORM, H1, H2, H3, H4, H5, H6, HR, I, IMG, INPUT, KBD, LABEL, LI, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP

See Also

select


onstart

Description

Fires at the beginning of every loop, and when a bounce cycle begins for alternate behavior.

Remarks

This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

MARQUEE


onsubmit

Description

Fires when a form is about to be submitted.

Return Value

Returns TRUE or FALSE.

Remarks

The onsubmit event default action is to submit the form. This event can be overridden by returning FALSE in the event handler. The purpose of this is to allow the developer to do validation of the data on the client side and prevent invalid data from being submitted to the server. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

FORM


onunload

Description

Fires immediately prior to the page being unloaded.

Remarks

The onunload attribute of the BODY element sets an onunload event handler for the window. This event will not bubble. Events that do not bubble can only be handled on the individual object that fired the event.

Applies To

FRAMESET, window


Collections

all anchors applets areas
cells children elements embeds
filters forms frames images
imports links options plugins
rows rules scripts styleSheets
tbodies


all

Description

Returns an object reference to the collection of elements contained by the object.

Syntax

object.all(index)

Parameter | Description
object | An object that can contain elements such as the document.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

The all collection includes one element object for each valid HTML tag. If a valid tag has a matching end tag, both tags are represented by the same element object.

The collection returned by the document's all property always includes a reference to the HTML, HEAD, TITLE, and BODY objects regardless of whether the tags are present in the document.

If the document contains invalid or unknown tags, the collection includes one element object for each. Unlike valid end tags, unknown end tags are represented by their own element objects. The order of the element objects is the HTML source order. Although the collection indicates the order of tags, it does not indicate hierarchy.

Examples

The following JScript example displays the names of all tags in the document in the order the tags appear in the document.

for(i=0; i<document.all.length; i++) {
    alert(document.all(i).tagName);
}

The following JScript example uses the item method on the all collection to retrieve all element objects for which the name or ID attribute is set to "sample". Depending on how many times the name or ID is defined in the document, the item method may return null, a single element object, or a collection of element objects. The example uses the length property of the collection to determine whether item returned a collection or a single object.

var a = document.all.item("sample");
if (a!=null) {
    if (a.length!=null) {
        for (i=0; i<a.length; i++) {
            alert(a(i).tagName);
        }
    } else
        alert(a.tagName);
}

Property

length

Methods

item, tags

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


anchors

Description

Retrieves a collection of all A elements that have a NAME= and/or ID= attribute. Elements in this collection are in HTML source order.

Syntax

object.anchors(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Example

The following example displays the NAME= attribute of the third anchor defined in the document.

alert(document.anchors(2).name);

Property

length

Methods

item, tags

Applies To

document


applets

Description

Retrieves a collection of all APPLET objects in the document.

Syntax

object.applets(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the object to retrieve. Integer indexes are zero-based, meaning the first object in the collection has index 0. A string index is valid only if the string is a name or identifier of one object in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


areas

Description

Retrieves a collection of the AREA elements defined for the given MAP element.

Syntax

object.areas(index)

Parameter | Description
object | A MAP element.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

Areas may be added to or removed from the collection. If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Property

length

Methods

add, item, remove, tags

Applies To

MAP


cells

Description

Retrieves a collection of all cells in the row of a table. This is a collection of TH and TD elements.

Note When a cell spans multiple rows, that cell appears only in the cells collection for the first of the rows that the cell spans.

Syntax

object.cells(index)

Parameter | Description
object | A TR element.
index | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Example

The following example uses the rows collection on the TABLE and the cells collection to insert a number into each cell of the table.

<HTML>
<SCRIPT LANGUAGE="JScript">
function numberCells() {
    var count=0;
    for (i=0; i < document.all.mytable.rows.length; i++) {
        for (j=0; j < document.all.mytable.rows(i).cells.length; j++) {
            document.all.mytable.rows(i).cells(j).innerText = count;
            count++;
        }
    }
}
</SCRIPT>
<BODY onload="numberCells()">
<TABLE id=mytable border=1>
<TR><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
</TABLE>
</BODY>
</HTML>

Applies To

TR

Property

length

Methods

item, tags


children

Description

Retrieves only the direct descendants of an element. The elements contained in this collection are undefined if the child elements are overlapping tags. Similar to the all collection.

Syntax

object.children(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

The following example illustrates what this collection would return.

<DIV id=divONE>
<IMG src=mygif.gif>
<DIV id=divTWO>
<p>Some text in a paragraph
</DIV>
<BUTTON> The label for the button </BUTTON>
</DIV>

The children collection for divONE would include IMG, DIV, and BUTTON. The children collection for divTWO would include P.

Applies To

A, ACRONYM, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BGSOUND, BIG, BLOCKQUOTE, BODY, BR, BUTTON, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, COMMENT, DD, DEL, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IFRAME, IMG, INPUT, INS, KBD, LABEL, LEGEND, LI, LINK, LISTING, MAP, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, Q, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TITLE, TR, TT, U, UL, VAR, XMP


elements

Description

Retrieves a collection, in source order, of all elements in a given form. This collection can contain any combination of INPUT, SELECT, and TEXTAREA elements.

Syntax

object.elements(index)

Parameter | Description
object | A FORM element.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

FORM


embeds

Description

Retrieves a collection of all EMBED elements on the document.

Syntax

object.embeds(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


filters

Description

Retrieves a collection of filter objects for an element.

Syntax

object.filters(index)

Parameter | Description
object | An element object.
(index) | Optional. An integer specifying the index value of the filter to retrieve. Integer indexes are zero-based, meaning the first filter in the collection has index 0.

Remarks

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Property

length

Methods

item

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR


forms

Description

Retrieves a collection, in source order, of all FORM elements in the document.

Syntax

object.forms(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


frames

Description

Retrieves a collection of all window objects defined by the given document or defined by the document associated with the given window.

Syntax

object.frames(index)

Parameter | Description
object | Either the document or window object.
(index) | Optional. An integer or a string specifying the index value of the window to retrieve. Integer indexes are zero-based, meaning the first window in the collection has index 0. A string index is valid only if the string is the name of one window in the document.

Remarks

If the HTML source document contains a BODY tag, the collection contains one window for each IFRAME element in the document. If the source document contains FRAMESET tags, the collection contains one window for each FRAME tag in the document. In both cases, the order is determined by the HTML source.

This collection contains window objects only and does not provide access to the corresponding FRAME and IFRAME elements. To access these elements, use the all collection for the document containing the elements.

Although you can use names with the item method on this collection, the method never returns a collection. Instead, it always returns the first window having the given name. To ensure that all windows are accessible, you should always make sure that no two windows in a document have the same name.

Examples

The following JScript example displays the URLs of the HTML documents contained in windows created by the IFRAME elements in the document.

var frm = document.frames;
for (i=0; i<frm.length; i++)
    alert(frm(i).location);

The following JScript example displays the names of each window defined by FRAME tags in the parent window of the current document.

var frm = window.parent.frames;
for (i=0; i < frm.length; i++)
    alert(frm(i).name);
}

Property

length

Methods

item

Applies To

document, window


images

Description

Retrieves a collection, in source order, of IMG elements in the document.

Syntax

object.images(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


imports

Description

Retrieves a collection of all the imported style sheets defined for the respective styleSheet object. An imported style sheet is one that is brought into the document using the @import attribute in CSS.

Syntax

object.imports(index)

Parameter | Description
object | A styleSheet object.
(index) | Optional. An integer or a string specifying the index value of the style sheet to retrieve. Integer indexes are zero-based, meaning the first style sheet in the collection has index 0.

Example

The following example displays the URLs of the imported style sheets in the document.

for (i=0; i<document.styleSheets.length; i++) {
    if (document.styleSheets(i).owningElement.tagName == "STYLE") {
        for (j=0; j<document.styleSheets(i).imports.length; j++)
            alert("Imported style sheet " + j + " is at " + document.styleSheets(i).imports(j).href);
    }
}

Property

length

Methods

item

Applies To

styleSheet


links

Description

Retrieves a collection of all A elements that specify the HREF= attribute and all AREA elements in the document.

Syntax

object.links(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

This collection includes A elements that have a NAME= or ID= attribute as long as they also have an HREF= attribute.

Example

The following example displays the HREF= attribute of the third link defined in the document.

alert(document.anchors(2).href);

Property

length

Methods

item, tags

Applies To

document


options

Description

Retrieves a collection of the OPTION elements in a SELECT object.

Syntax

object.options(index)

Parameter | Description
object | A SELECT element.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

To delete an option from a SELECT object, you assign the option a null value. This compresses the array.

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Example

The following example displays the text and values of all OPTION elements in the first SELECT element in the document.

var coll = document.all.tags("SELECT");
if (coll.length>0) {
    for (i=0; i< coll(0).options.length; i++)
        alert("Element " + i + " is " + coll(0).options(i).text + " and has the value " + coll(0).options(i).value);
}

Property

length

Methods

add, item, remove, tags

Applies To

SELECT


plugins

Description

This is an alias for the embeds collection on the document.

Syntax

object.plugins(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is a name or identifier of at least one element in the document.

Remarks

This collection is indexed first by name, then by identifier. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


rows

Description

Retrieves a collection of rows (TR elements) in the table. The scope of this collection is for the THEAD, TBODY, or TFOOT of the table. In addition, there is also a rows collection for the TABLE, which contains all the rows for the entire table. A row that appears in one of the table sections also appears in the rows collection for the TABLE. The TR has two index properties, "rowIndex" and "sectionRowIndex", which indicate where, with respect to the rows collection for the given table section, and where with respect to the rows collection for the table in which the TR appears.

Syntax

object.rows(index)

Parameter | Description
object | A TABLE, TBODY, THEAD, or TFOOT element.
index | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Example

The following example uses the rows and cells collections to insert a number into each cell of the table.

<HTML>
<SCRIPT LANGUAGE="JScript">
function numberCells() {
    var count=0;
    for (i=0; i < document.all.mytable.rows.length; i++) {
        for (j=0; j < document.all.mytable.rows(i).cells.length; j++) {
            document.all.mytable.rows(i).cells(j).innerText = count;
            count++;
        }
    }
}
</SCRIPT>
<BODY onload="numberCells()">
<TABLE id=mytable border=1>
<TR><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH><TH>&nbsp;</TH></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
<TR><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD><TD>&nbsp;</TD></TR>
</TABLE>
</BODY>
</HTML>

Applies To

table, TBODY, TFOOT, THEAD

Property

length

Methods

item, tags


rules

Description

Retrieves a collection of rules that are defined in the style sheet. This collection is always accessible, and can be accessed even if the style sheet is not enabled. Rules are added and removed from the rules collection with add and remove methods on the individual style sheet. A rule that is added to a disabled style sheet will not apply to the document unless the style sheet's disabled property is changed to false.

The rules in this collection are in the source order of the document. Style rules linked in using the "@import" syntax of CSS should be expanded in-place in this collection according to the CSS1 specification.

As rules are added or deleted through the Cascading Style Sheets Object Model, a rule's absolute position in the rules collection might change, but its position relative to other rules will remain the same. The default location to add a new rule (without specifying an index) is at the end of the collection, which is the highest precedence (not accounting for selector specificity, as according to the CSS specification) and is applied to the document last. If an index is supplied, the rule should be inserted before the rule currently in that ordinal position in the collection, or, if the index is larger than the number of rules in the collection, it should be added to the end.

Syntax

object.rules(index)

Parameter | Description
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Property

length

Applies To

styleSheet


scripts

Description

Retrieves a collection of all SCRIPT elements in the document.

Syntax

object.scripts(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid only if the string is an identifier of at least one element in the document.

Remarks

This collection contains all the scripts in the document in source order regardless of the script's location in the document (whether in the HEAD or BODY).

If duplicate identifiers are found, a collection of those items is returned. Collections of duplicates must subsequently be referenced by ordinal position.

Property

length

Methods

item, tags

Applies To

document


styleSheets

Description

Retrieves a collection of styleSheets objects representing the style sheets corresponding to each instance of a LINK or STYLE element in the document. Imported style sheets are contained within a STYLE element and are available through the imports collection.

Syntax

object.styleSheets(index)

Parameter | Description
object | The document object.
(index) | Optional. An integer or a string specifying the index value of the style sheet to retrieve. Integer indexes are zero-based, meaning the first style sheet in the collection has index 0.

Example

The following example displays the titles of the style sheets in the document.

for (i=0; i<document.styleSheets.length; i++) {
    alert("Style sheet " + i + " is titled " + document.styleSheets(i).title);
}

Property

length

Methods

item

Applies To

document


tbodies

Description

Retrieves a collection of all TBODY elements in the table. Elements in this collection are in HTML source order.

Syntax

object.tbodies(index)

Parameter | Description
object | The table object.
index An integer or a string specifying the index value of the element to retrieve. Integer indexes are zero-based, meaning the first element in the collection has index 0. A string index is valid if the string is an identifier of at least one element in the scope of the collection.

This collection can be indexed by name (ID). If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

Example

The following example puts text in the first cell in the first row of the first TBODY element in the TABLE. For each TABLE, an initial TBODY element is synthesized in the HTML tree even if one does not exist in the HTML source.

document.all.mytable.tbodies[0].rows[0].cells[0].innerText="Text for the first table cell";

Applies To

table

Property

length

Methods

item, tags


HTML References HTML References *
  * Previous Topic: tbodies
  * Next Topic: HTML Elements

HTML References

HTML Elements

HTML Character Sets


HTML Elements

<!-- --> !DOCTYPE A ACRONYM ADDRESS APPLET
AREA B BASE BASEFONT BGSOUND BIG
BLOCKQUOTE BODY BR BUTTON CAPTION CENTER
CITE CODE COL COLGROUP COMMENT DD
DEL DFN DIR DIV DL DT
EM EMBED FIELDSET FONT FORM FRAME
FRAMESET HEAD H1 H2 H3 H4
H5 H6 HR HTML I IFRAME
IMG INPUT INS ISINDEX KBD LABEL
LEGEND LI LINK LISTING MAP MARQUEE
MENU META NOBR NOFRAMES NOSCRIPT OBJECT
OL OPTION P PARAM PLAINTEXT PRE
Q S SAMP SCRIPT SELECT SMALL
SPAN STRIKE STRONG STYLE SUB SUP
TABLE TBODY TD TEXTAREA TFOOT
TH THEAD TITLE TR TT U
UL VAR WBR XMP

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


!-- --

Description

Comments are ignored by the HTML parser. Text between the beginning of the comment <!-- and the end tag --> is not displayed in the browser window.

Syntax

<!-- -->

Remarks

Comments can contain other HTML elements. Comments do not nest.

Both the start and end tags are required.

See Also

COMMENT


!DOCTYPE

Description

Specifies the HTML DTD that the document corresponds to.

Syntax

<!DOCTYPE>

Remarks

Different versions can be used depending on the level of compatibility the author wishes to indicate. In the examples below, the first indicates compatibility with the HTML 3.2 DTD; the second indicates a strict adherence to the HTML 4.0 DTD.

Examples

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">


A

Description

Designates the start or destination of a hypertext link. The anchor element requires the HREF= or the NAME= attribute to be specified.

Syntax

<A
 ACCESSKEY=key
CLASS=classname
DATAFLD=colname
DATASRC=#ID
HREF=url
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 METHODS=http-method
NAME=name
REL="stylesheet"
 REV="stylesheet"
 STYLE=css1-properties
TABINDEX=n
TARGET=window_name | _blank | _parent | _self | _top
TITLE=text
URN=urn
event = script
>

Parameter | Description
ACCESSKEY=key | Accelerator for the element. Pressing ALT-key selects this element in the user's browser.
CLASS=classname | Class of the tag being defined. This is used to associate a subclassed style sheet with the tag.
DATAFLD=colname | Column name from the data source object that supplies the bound data.
DATASRC=#ID | ID of the data source object that supplies the data that is bound to this element.
HREF=url | Destination URL or anchor point. If HREF is set to an empty string (""), then hyperlinking will cause the base URL to be opened. For example, if the current file is "http://microsoft.com/home/hello.html", then "http://microsoft.com/home/" will be opened.
ID=value | SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The script is written in JScript.
VBS, VBSCRIPT | The script is written in VBScript.
METHODS=http-method | METHODS attributes of anchors and links provide information about the functions that the user may perform on an object. These are more accurately given by the HTTP protocol when it is used, but it may, for similar reasons as for the TITLE attribute, be useful to include the information in advance in the link. For example, the HTML user agent may choose a different rendering as a function of the methods allowed; for example, something that is searchable may get a different icon.
NAME=name | Name of the anchor.
REL="stylesheet" | Gives the relationship(s) described by the hypertext link from the anchor to the target. The value is a comma-separated list of relationship values. The values and their semantics will be registered by the HTML registration authority. The default relationship if none other is given is void. The REL attribute is only used when the HREF= attribute is present.
REV="stylesheet" | Same as the REL attribute, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor may have both REL and REV attributes.
STYLE=css1-properties | Inline style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object.
TARGET=window_name | _blank | _parent | _self | _top Window or frame at which to target the contents. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a tooltip during the onmouseover event.
event Can be one or more of these events:
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Text and/or images may be within an anchor. To represent images that are anchors, a border in the visited or not visited color is displayed.

Both the start and end tags are required.

Example

<A HREF="http://www.microsoft.com">This is a link to Microsoft.</A>

<A HREF="home.htm">This link points to a file called home.htm in the same directory as this page.</A>

<A TARGET="viewer" HREF="sample.htm">Click here to load the link into "viewer" window.</A>

<A HREF="http://www.microsoft.com"><IMG SRC="images/bullet.gif">This link contains an image</A>

<A HREF="javascript:window.open()">This link opens a new window using the open method in javascript</A>

Scripting Object

A


ACRONYM

Description

Indicates an acronym.

Syntax

<ACRONYM
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Class of the tag being defined. This is used to associate a subclassed style sheet with the tag.
ID=value | SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The script is written in JScript.
VBS, VBSCRIPT | The script is written in VBScript.
STYLE=css1-properties | Inline style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a tooltip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required. This tag does not affect how text appears in the browser.

Example

<ACRONYM>MSN</ACRONYM>

Scripting Object

ACRONYM

See Also

ADDRESS, CITE, DFN, EM, STRONG


ADDRESS

Description

The Address element is used to specify information such as address, signature and authorship.

Syntax

<ADDRESS
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<ADDRESS>This text will be in italic.</ADDRESS>

Scripting Object

ADDRESS

See Also

ACRONYM, CITE, DFN, EM, STRONG


APPLET

Description

Places executable content on the page.

Syntax

<APPLET
 ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 ALT=text
CLASS=classname
CODE=filename
CODEBASE=url
DATAFLD=colname
DATASRC=#ID
HEIGHT=n
HSPACE=n
ID=value
NAME=name
SRC=url
STYLE=css1-properties
TITLE=text
VSPACE=n
WIDTH=n
event = script
>

Parameter | Description
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
ALT=text | Optional text as an alternative to the application if it cannot be executed.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
CODE=filename | The name of the file containing the compiled Java class.
CODEBASE=url | This is an optional parameter that specifies the base URL for the application.
DATAFLD=colname | The column name from the data source object that supplies the bound data. This can only be used on the contained PARAM elements.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
HEIGHT=n | Along with WIDTH=, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
HSPACE=n | Along with VSPACE=, specifies margins for the element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID names must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created and can only be referenced by ordinal position.
NAME=name | Specifies the name of the application.
SRC=url | Specifies a URL for the associated file.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VSPACE=n | Along with HSPACE=, specifies margins for the element.
WIDTH=n | Along with HEIGHT=, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondataavailable ondatasetchanged
ondatasetcomplete ondblclick
onerrorupdate ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onreadystatechange onresize
onrowenter onrowexit

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

APPLET

See Also

EMBED, OBJECT, PARAM


AREA

Description

Specifies the shape of a hyperlink "hot spot" in a client-side image map.

Syntax

<AREA
 ALT=text
CLASS=classname
COORDS=coordinates
HREF=url
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 NOHREF
 SHAPE=CIRC | CIRCLE | POLY | POLYGON | RECT | RECTANGLE
 STYLE=css1-properties
TABINDEX=n
TARGET=window_name | _blank | _parent | _self | _top
TITLE=text
event = script
>

Parameter | Description
ALT=text | Optional text as an alternative to the graphic for rendering in non-graphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COORDS=coordinates | Coordinates that define the hot spot's shape.
HREF=url | Specifies the destination URL or anchor point.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NOHREF | Indicates that clicks in this region should cause no action.
SHAPE=CIRC | CIRCLE | POLY | POLYGON | RECT | RECTANGLE | Specifies the type of shape used in the image map.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object.
TARGET=window_name | _blank | _parent | _self | _top Specifies the window or frame to target the contents at. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed below:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This is an empty element and does not require a closing tag.

Examples

<AREA SHAPE="RECT" COORDS="0, 0, 58, 31" HREF="http://www.microsoft.com/ie/">

<AREA TARGET="viewer" HREF="sample.htm" SHAPE="CIRCLE" COORDS="73, 15, 10">

<AREA SHAPE="RECT" COORDS="58, 0, 88, 31" NOHREF>

Scripting Object

AREA

See Also

MAP, IMG


B

Description

The Bold element specifies that the text should be rendered in boldface, where available. The end tag turns off the bold formatting.

Syntax

<B
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<B>Displayed in a bold typeface.</B>

Scripting Object

B

See Also

STRONG


BASE

Description

Specifies the document's base URL.

Syntax

<BASE
 HREF=url
TARGET=window_name | _blank | _parent | _self | _top
>

Parameter | Description
HREF=url | Specifies the document's reference URL for associating relative URLs with the proper document path.
TARGET=window_name | _blank | _parent | _self | _top Specifies the window or frame to target the contents at. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed below:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.

Remarks

Base is used to ensure that your document's relative links are associated with the proper document path.

This element may only be used within the HEAD tag.

This is an empty element and does not require a closing tag.

Example

<BASE HREF="http://www.sample.com/hello.htm">

Scripting Object

BASE


BASEFONT

Description

Sets a base font value to be used as the default font when rendering text.

Syntax

<BASEFONT
 CLASS=classname
COLOR=color
FACE=font
ID=value
LANG=language
SIZE=n
>

Parameter | Description
CLASS=classname | Class of the tag being defined. This is used to associate a subclassed style sheet with the tag.
COLOR=color | Color to be used by the font or horizontal rule. For a complete list of colors, see the Internet Explorer color table.
FACE=font | Current font typeface.
ID=value | SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
SIZE=n | Font size between 1 and 7 (7 is largest).

Remarks

This is an empty element and does not require a closing tag. This element may be used within the BODY tag or the HEAD tag. BASEFONT should appear before any displayed text in the BODY of the document.

Example

<BASEFONT SIZE=3> This sets the base font size to 3.
<FONT SIZE=+4> Now the font size is 7.
<FONT SIZE=-1> Now the font size is 2.

Scripting Object

BASEFONT


BGSOUND

Description

The BGSOUND tag allows you to create pages with background sounds or "soundtracks."

Syntax

<BGSOUND
 BALANCE=n
CLASS=classname
ID=value
LANG=language
LOOP=n
SRC=url
TITLE=text
VOLUME=n
>

Parameter | Description
BALANCE=n | Determines how the available volume will be divided between the left and right speakers. Valid values for this attribute are in the range of -10,000 to +10,000, with 0 being "Wave Output" center balanced.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LOOP=n | Specifies how many times a sound will loop when activated.
SRC=url | Specifies the URL of a sound to be played.
TITLE=text | Used to provide advisory information.
VOLUME=n | Determines the loudness of a page's background sound. Valid values for this attribute are in the range of -10,000 to 0, with 0 being full "Wave Output" volume.

Remarks

This element may be used within the HEAD tag.

The start tag is required, and the end tag is optional.

Scripting Object

BGSOUND


BIG

Description

Specifies that the enclosed text should be displayed in a relatively bigger font than the current font.

Syntax

<BIG
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<BIG>This text is larger.</BIG>

Scripting Object

BIG


BLOCKQUOTE

Description

Sets apart a long quotation in text.

Syntax

<BLOCKQUOTE
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<P>He said,
<BLOCKQUOTE>"Hi there!"</BLOCKQUOTE>

Scripting Object

BLOCKQUOTE

See Also

Q


BODY

Description

Specifies beginning and end of document body. This element can be used to set the background image, the background color, the link color and the top and left margins of the page. The end tag is required.

Syntax

<BODY
 ALINK=color
BACKGROUND=url
BGCOLOR=color
BGPROPERTIES=FIXED
 BOTTOMMARGIN=pixels
CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
LEFTMARGIN=pixels
LINK=color
RIGHTMARGIN=pixels
SCROLL=YES|NO
 STYLE=css1-properties
TEXT=color
TITLE=string
TOPMARGIN=n
VLINK=color
event = script
>

Parameter | Description
ALINK=color | The color for the active link. For a complete list of colors, look at the Internet Explorer color table.
BACKGROUND=url | Specifies a background picture. The picture is tiled behind the text and graphics on the page.
BGCOLOR=color | Sets the background color of the page. For a complete list of colors, look at the Internet Explorer color table.
BGPROPERTIES= | Specifies a watermark, which is a background picture that does not scroll.
BOTTOMMARGIN= | Specifies the bottom margin for the entire body of the page and overrides the default margin. If set to "0" or "", the bottom margin will be exactly on the bottom edge of the window or frame.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
LEFTMARGIN=pixels | Specifies the left margin for the entire body of the page and overrides the default margin. If set to "0" or "", the left margin will be exactly on the left edge of the window or frame.
LINK=color | The color of shortcuts that have not yet been visited. For a complete list of colors, look at the Internet Explorer color table.
RIGHTMARGIN=pixels | Specifies the right margin for the entire body of the page and overrides the default margin. If set to "0" or "", the right margin will be exactly on the right edge of the window or frame.
SCROLL=YES | NO | Turns on or off the scrollbars. The default is YES.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TEXT=color | Sets the color of text on the page. For a complete list of colors, look at the Internet Explorer color table.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TOPMARGIN=pixels | Specifies the margin for the top of the page and overrides the default margin. If set to "0" or "", the top margin will be exactly on the top edge of the window or frame.
VLINK=color | The color of shortcuts that have already been visited. For a complete list of colors, look at the Internet Explorer color table.
event Can be one or more of these events:
onafterupdate onbeforeunload
onbeforeupdate onclick
ondblclick ondragstart
onhelp onkeydown
onkeypress onkeyup
onload onmousedown
onmousemove onmouseout
onmouseover onmouseup
onrowenter onrowexit
onscroll onselect
onselectstart onunload

Remarks

This element is a block element.

Examples

This is the HTML used to insert the background image of this page.

<BODY BACKGROUND="http://www.microsoft.com/ie/images/watermrk.gif" BGPROPERTIES=FIXED
BGCOLOR=#FFFFFF TEXT=#000000 LINK=#ff6600 VLINK=#330099>

<HTML><BODY>Here's a Web page!</BODY></HTML>

Scripting Object

BODY


BR

Description

Inserts a line break.

Syntax

<BR
 CLASS=classname
CLEAR=ALL |LEFT | RIGHT
 ID=value
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
CLEAR=ALL | LEFT | RIGHT | Inserts vertical space so that the next text displayed will be past left- or right-aligned floating images.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.

Scripting Object

BR

See Also

WBR


BUTTON

Description

Renders an HTML button, displaying the text between the start and end tags as the label within the button.

Syntax

<BUTTON
 ACCESSKEY=string
CLASS=classname
DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
DISABLED
 ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
TYPE=BUTTON | RESET | SUBMIT
 event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=BUTTON | RESET | SUBMIT Defines a button that indicates a default for the ENTER key (with a dark border). The possible values are:
BUTTON | Command button to be used in a script.
RESET | When pressed, this button resets the form's fields to their specified initial values. The label to be displayed on the button may be specified just as for the SUBMIT button.
SUBMIT | Submits the form. The default label is application-specific. If a SUBMIT button is pressed in order to submit the form, and that button has a NAME attribute specified, then that button contributes a name/value pair to the submitted data. Otherwise, a SUBMIT button makes no contribution to the submitted data.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onrowenter
onrowexit onselectstart

Remarks

You should not include the SELECT, BUTTON, INPUT, or A within the BUTTON tag.

This element is a block element.

Both the start and end tags are required.

Scripting Object

BUTTON


CAPTION

Description

Specifies a caption for a TABLE .

Syntax

<CAPTION
 ALIGN=BOTTOM | CENTER | LEFT | RIGHT | TOP
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BOTTOM | TOP
 event = script
>

Parameter | Description
ALIGN= BOTTOM | CENTER | LEFT | RIGHT | TOP Specifies the alignment of the caption.
BOTTOM | Aligns the caption bottom center.
CENTER | Centers the caption.
LEFT | Left aligns the caption.
RIGHT | Right aligns the caption.
TOP | Aligns the caption top center.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BOTTOM | TOP | Specifies whether the caption appears at the top or bottom.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onchange
onclick ondblclick
ondragstart onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onselect onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<TABLE>
<CAPTION VALIGN=BOTTOM>
This caption will appear below the table.
</CAPTION>
<TR>
....
</TR>
</TABLE>

Scripting Object

CAPTION


CENTER

Description

Causes subsequent text and images to be centered. The required end tag returns the alignment to its previous state. This element has the same effect as using the element <DIV ALIGN=CENTER>.

Syntax

<CENTER
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<CENTER>This text appears centered on the page.</CENTER>

Scripting Object

CENTER


CITE

Description

Indicates a citation. Refers to a book, paper, or other published source material. The text for citations is rendered in italics.

Syntax

<CITE
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<CITE>Book Title.</CITE>

Scripting Object

CITE

See Also

ACRONYM, ADDRESS, DFN, EM, STRONG


CODE

Description

Specifies a code sample. The text is rendered in a small font.

By default, the font used is fixed-width. If a font face is specified with the FONT or BASEFONT elements preceding CODE, that font is used instead.

Syntax

<CODE
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<CODE>Here is some text in a small, fixed-width font.</CODE>

Scripting Object

CODE

See Also

SAMP


COL

Description

Used to specify column based defaults for the table properties.

Syntax

<COL
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
ID=value
SPAN=n
STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | MIDDLE | TOP
 WIDTH=n
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
SPAN=n | Specifies how many columns are in the group.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | MIDDLE | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
WIDTH=n | Sets the initial width of the element. This attribute may be initially set in pixels or percentages.

Remarks

This element is a block element.

Example

<TABLE>
<COLGROUP>
<COL ALIGN=RIGHT>
<COL ALIGN=LEFT>
<COLGROUP>
<COL ALIGN=CENTER>
<TBODY>
<TR>
<TD>This is the first column in the group and is right-aligned.</TD>
<TD>This is the second column in the group and is left-aligned.</TD>
<TD>This column is in a new group and is centered.</TD>
</TR>
</TABLE>

Scripting Object

COL

See Also

COLGROUP


COLGROUP

Description

Used as a container for a group of columns.

Syntax

<COLGROUP
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
ID=value
SPAN=n
STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | MIDDLE | TOP
 WIDTH=n
>

Parameter | Description
ALIGN= CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
SPAN=n | Specifies how many columns are in the group.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.
VALIGN=BASELINE | BOTTOM | MIDDLE | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
WIDTH=n | Sets the initial width of the element. This attribute may be initially set in pixels or percentages.

Remarks

End tags are optional.

Example

<TABLE>
<COLGROUP ALIGN=RIGHT>
<COLGROUP SPAN=2 ALIGN=LEFT>
<TBODY>
<TR>
<TD>This column is in the first group and is right-aligned.</TD>
<TD>This column is in the second group and is left-aligned.</TD>
<TD>This column is in the second group and is left-aligned.</TD>
</TR>
</TABLE>

Scripting Object

COLGROUP

See Also

COL


COMMENT

Description

This element is no longer recommended. Indicates a comment that will not be displayed. This element is provided for backward compatibility. When authoring documents, use the <!-- --> comment element for comments instead.

Syntax

<COMMENT
 ID=value
LANG=language
TITLE=text
>

Parameter | Description
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
TITLE= | Used to provide advisory information.

Remarks

Both the start and end tags are required.

Scripting Object

COMMENT

See Also

!-- --


DD

Description

The definition in a definition list. Usually indented from the definition list, and displayed in the right-hand column of a definition list.

Syntax

<DD
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

Example

<DL><DT>Cat<DD>A small domesticated mammal.
<DT>Lizard<DD>A reptile generally found in dry areas.</DL>

Scripting Object

DD

See Also

DL, DT


DEL

Description

Indicates text that has been deleted from the document.

Syntax

<DEL
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<DEL>This text has been revised.</DEL>

Scripting Object

DEL

See Also

INS


DFN

Description

Indicates the defining instance of a term. Formats a term for its first appearance in a document.

Syntax

<DFN
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<DFN>HTML stands for hypertext markup language.</DFN>

Scripting Object

DFN

See Also

ACRONYM, ADDRESS, CITE, STRONG


DIR

Description

Denotes a directory list. The following text is a directory list that consists of individual items, each beginning with an LI element and none containing more than 20 characters.

Syntax

<DIR
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<DIR><LI>Art
<LI>History
<LI>Literature
<LI>Sports
<LI>Entertainment
<LI>Science
</DIR>

Scripting Object

DIR


DIV

Description

The DIV element is used to represent different kinds of containers in a document such as chapter, section, abstract, appendix, etc.

Syntax

<DIV
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text

event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onrowenter
onrowexit onscroll
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<DIV>
This text represents a section.
</DIV>

<DIV ALIGN=CENTER>
This text represents another section, and its text is centered.
</DIV>

Scripting Object

DIV


DL

Description

Denotes a definition list. The text is formatted as a list of terms on the left and their definitions indented below. The DT and DD elements can be used to define the elements within a directory list.

Syntax

<DL
 CLASS=classname
COMPACT
 ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COMPACT | Specifies that the list should be compacted to remove extra space between list elements.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onmousedown onmousemove
onmouseout onmouseover
onmouseup onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<DL>
<DT>Cat
<DD> A small domesticated mammal.
<DT>Lizard
<DD>A reptile generally found in dry areas.
</DL>

Scripting Object

DL

See Also

DD, DT


DT

Description

A definition term within a definition list. The text is a term to be defined, and should be displayed in the left-hand column of a definition list. The corresponding definition should be indicated with the DD element.

Syntax

<DT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

Example

<DL>
<DT>Cat
<DD> A small domesticated mammal.
<DT>Lizard
<DD>A reptile generally found in dry areas.
</DL>

Scripting Object

DT

See Also

DD, DL


EM

Description

Used to emphasize text. Usually renders text in italics.

Syntax

<EM
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<EM>This text is emphasized, often shown in italics.</EM>

Scripting Object

EM

See Also

ACRONYM, ADDRESS, CITE, STRONG


EMBED

Description

Allows you to embed documents of any type. The user needs to have an application which can view the data installed correctly on their machine.

Syntax

<EMBED
 ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 ALT=text
CLASS=classname
CODE=filename
CODEBASE=url
HEIGHT=n
HSPACE=n
ID=value
NAME=name
SRC=url
STYLE=css1-properties
TITLE=text
UNITS=value
VSPACE=n
WIDTH=n

>

Parameter | Description
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
ALT=text | Optional text as an alternative to the application if it cannot be executed.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
CODE=filename | The name of the file containing the compiled Java class.
CODEBASE=url | This is an optional parameter that specifies the base URL for the application.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
HSPACE=n | Along with VSPACE=, specifies margins for the element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID names must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created and can only be referenced by ordinal position.
NAME=name | Specifies the name of the application.
SRC=url | Specifies a URL for the associated file.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
UNITS=value | Defines the units for the height and width of the EMBED element, expressed as pixels (px) or ems (em).
VSPACE=n | Along with HSPACE=, specifies margins for the element.
WIDTH=n | Along with HEIGHT, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

EMBED

See Also

APPLET, OBJECT, PARAM


FIELDSET

Description

The FIELDSET element is similar to the DIV element but is for the specific purpose of grouping related fields. It is a container and it is nestable. It can contain a single LEGEND that must immediately follow the FIELDSET tag. The legend is used to identify the contained set of fields. This is especially useful to speech-based browsers which can then provide users with a way to move from group to group. This element renders as a box around the group and transposes the legend over the upper-left or lower-left portion of the box depending upon the ALIGN= attribute value on the LEGEND element. The legend element must be the first element within the field set. If it is not, the legend text cannot be rendered as part of the FIELDSET border.

Syntax

<FIELDSET
 ALIGN= LEFT | CENTER | RIGHT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
ALIGN=LEFT | CENTER | RIGHT | Displays the element left flush, right flush, or centered, relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID names must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created and can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE= | Specifies an in-line style sheet for the tag.
TITLE= | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onblur onchange
onclick ondblclick
ondragstart onfilterchange
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onscroll
onselect onselectstart

Remarks

Both the start and end tags are required.

Scripting Object

FIELDSET

See Also

CAPTION, LEGEND


FONT

Description

Specifies a new font face, size, and color to be used for rendering the enclosed text.

Syntax

<FONT
 CLASS=classname
COLOR=color
FACE=font
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
SIZE=n
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLOR=color | Set the color to be used by the font or horizontal rule. For a complete list of colors, look at the Internet Explorer color table.
FACE=font | Sets the current font typeface.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
SIZE=n | Specifies font size between 1 and 7 (7 is largest).
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Scripting Object

FONT


FORM

Description

Specifies that the contained controls take part in a form.

Syntax

<FORM
 ACTION=url
CLASS=classname
ENCTYPE=encoding
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
METHOD=GET | POST
 NAME=name
STYLE=css1-properties
TARGET=window_name | _blank | _parent | _self | _top
TITLE=text
event = script
>

Parameter | Description
ACTION=url | Specifies the address to be used to carry out the action of the form. If none is specified, the base URL of the document is used.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ENCTYPE=encoding | Specifies the format of the data being submitted by the form.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
METHOD=GET | POST | Indicates how the form data should be sent to the server; either GET or POST
NAME=name | Specifies the name of the control, bookmark, or application.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TARGET=window_name | _blank | _parent | _self | _top Specifies the window or frame to target the contents at. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed below:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onreset onselectstart
onsubmit

Remarks

When programming the form, all control-like elements are added to the form as named items. In addition, these items are exposed through the Item method on the form.

This element is a block element.

Both the start and end tags are required.

Example

<FORM TARGET="viewer" ACTION="http://www.sample.com/bin/search">
...
</FORM>

Scripting Object

FORM


FRAME

Description

Specifies an individual frame within a FRAMESET .

Syntax

<FRAME
 BORDERCOLOR=color
CLASS=classname
DATAFLD=colname
DATASRC=#ID
FRAMEBORDER=NO | YES | 0 | 1
 HEIGHT=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
MARGINHEIGHT=pixels
MARGINWIDTH=pixels
NAME=window_name | _blank | _parent | _self | _top
NORESIZE=NORESIZE | RESIZE
 SCROLLING=AUTO | NO | YES
 SRC=url
TITLE=text
WIDTH=n
event = script
>

Parameter | Description
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
FRAMEBORDER=NO | YES | 0 | 1 | Specifies whether or not to display a border for the frame.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
MARGINHEIGHT=pixels | Sets the amount of top and bottom margin should be set before displaying the text in a frame.
MARGINWIDTH=pixels | Sets the amount of left and right margin should be set before displaying the text in a frame.
NAME=window_name | _blank | _parent | _self | _top Specifies the window or frame to target the contents at. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed below:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.
NORESIZE | When this attribute is supplied, the frame is not resizable by the user. The default behavior allows the user to resize the frame.
SCROLLING=AUTO | NO | YES | Specifies that the frame can be scrolled. If set to "AUTO," the browser determines whether scrollbars are necessary.
SRC=url | Specifies a URL for the associated file.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
WIDTH=n | Along with HEIGHT, sets the initial size of the element. This attribute may be initially set in pixels or percentages.
event Can be this event:
onreadystatechange

Remarks

This element is a block element.

Example

<FRAME FRAMEBORDER=0 SCROLLING=NO SRC="sample.htm">

Scripting Object

FRAME

See Also

FRAMESET, NOFRAMES


FRAMESET

Description

Sets the number and size of vertical and horizontal frames for a compound document. Use the FRAME element within FRAMESET to define the content and properties of the individual frames. You can also nest FRAMESET elements to create frames within a frame.

Syntax

<FRAMESET
 BORDER=pixels
BORDERCOLOR=color

CLASS=classname
COLS=col-widths
FRAMEBORDER=NO | YES | 0 | 1
FRAMESPACING=spacing
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
ROWS=row-heights
TITLE=text
>

Parameter | Description
BORDER=pixels | Defines the space between the frames in pixels, including the 3D border. For nested FRAMESETS, the border can only be defined for the top-level FRAMESET element.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLS=col-widths | A comma delimited list of frames to create. Each item in the list contains the initial size of the column. You can specify the column dimensions by percentage (%), pixels, or a relative size (*)
FRAMEBORDER=NO | YES | 0 | 1 | Specifies whether or not to display a border for the frame. "YES" or 1 causes a border to be displayed (default). "NO" or 0 displays no border.
FRAMESPACING=spacing | Creates additional space between the frames in pixels.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
ROWS=row-heights | A comma delimited list of frames to create. Each item in the list contains the initial size of the row. You can specify the row dimensions by percentage (%), pixels, or a relative size (*).
TITLE=text | Used to provide advisory information.

Remarks

A frameset organizes multiple frames on the screen. Only frames, nested FRAMESETelements, and the NOFRAMES tag are valid within a frameset.

This element is a block element.

Both the start and end tags are required.

Example

<FRAMESET COLS="25%, 50%, *">
<FRAME SRC="contents.htm">
<FRAME SRC="info.htm">
<FRAME SCROLLING=NO SRC="graphic.htm">
</FRAMESET>

Scripting Object

FRAMESET

See Also

FRAME, NOFRAMES


HEAD

Description

An unordered collection of information that marks the document heading.

Syntax

<HEAD
 CLASS=classname
ID=value
TITLE=text
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.

Remarks

The HEAD provides information that does not effect the rendering of the document, but may be of use to the browser. The HEAD falls before the BODY of the document is specified. The following tags are valid in the HEAD block:

  • BASE
  • LINK
  • TITLE
  • META
  • BASEFONT
  • BGSOUND

The TITLE tag is the only information that is required as part of a HEAD block.

Example

<HEAD>
<TITLE>A Simple Document</TITLE>
</HEAD>

Scripting Object

HEAD


Hn

Description

Renders text in heading style. Use H1 through H6 to specify different sizes and styles of headings. The end tag is required to restore the formatting to normal.

Syntax

<Hn
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
n | Sets the heading level. This is an integer from 1 to 6.
ALIGN= | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<H1>Welcome to Internet Explorer!</H1>

Scripting Objects

H1 H2 H3
H4 H5 H6

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


HR

Description

Draws a horizontal rule.

Syntax

<HR
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
COLOR=color
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
NOSHADE
SIZE=n
STYLE=css1-properties
TITLE=text
WIDTH=n
event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLOR=color | Set the color to be used by the font or horizontal rule. For a complete list of colors, look at the Internet Explorer color table.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NOSHADE | Draws the horizontal rule without 3-D shading.
SIZE=n | Sets the height of the <HR > element in pixels.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
WIDTH=n | Sets the initial width of the element. This attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onbeforeupdate onblur
onclick ondblclick
ondragstart onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onselectstart

Remarks

This element is a block element.

Scripting Object

HR


HTML

Description

This element identifies the document as containing HTML elements. The begin tag typically appears after the !DOCTYPE element. The end tag comes after all HTML elements in the document.

Syntax

<HTML
 TITLE=text
>

Parameter | Description
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
TITLE= | Used to provide advisory information.

Remarks

Example

<HTML>
<BODY>
<P>This is an HTML document.
</BODY>
</HTML>

Scripting Object

HTML


I

Description

The Italic element specifies that the text should be rendered in italic font, where available.

Syntax

<I
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<I>This text will be in italic.</I>

Scripting Object

I

See Also

ADDRESS, CITE, DFN, EM


IFRAME

Description

Used to create in-line floating frames.

Syntax

<IFRAME
 ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 BORDER=pixels
BORDERCOLOR=color
CLASS=classname
DATAFLD=colname
DATASRC=#ID
FRAMEBORDER=NO | YES | 0 | 1
 FRAMESPACING=pixels
HEIGHT=n
HSPACE=pixels
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
MARGINHEIGHT=pixels
MARGINWIDTH=pixels
NAME=window_name | _blank | _parent | _self | _top
 NORESIZE=NORESIZE | RESIZE
 SCROLLING=AUTO | NO | YES
 SRC=url
STYLE=css1-properties
TITLE=text
VSPACE=pixels
WIDTH=n
>

Parameter | Description
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
BORDER=pixels | Specifies the thickness of a border to be drawn around the element. The default is 0.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
FRAMEBORDER=NO | YES | 0 | 1 | Specifies whether or not to display a 3-D border around the frame. "YES" or 1 causes a border to be displayed (default). "NO" or 0 displays no border.
FRAMESPACING=pixels | Creates additional space between the frames.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
HSPACE=pixels | Along with VSPACE, specifies margins for the element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
MARGINHEIGHT=pixels | Sets the amount of top and bottom margin should be set before displaying the text in a frame.
MARGINWIDTH=pixels | Sets the amount of left and right margin should be set before displaying the text in a frame.
NAME=window_name | _blank | _parent | _self | _top Specifies the window or frame to target the contents at. If no frame or window exists that matches the specified target, a new window is opened for the specified link. If no target is specified, the default is "_self" for a link within the same site or "_top" if the site is external. Special target values are listed below:
_blank | Specifies to load the link into a new unnamed window.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the current window.
NORESIZE | When this attribute is supplied, the frame is not resizable by the user. The default behavior allows the user to resize the frame.
SCROLLING=AUTO | NO | YES | Specifies that the frame can be scrolled. If set to "AUTO," the browser determines whether scrollbars are necessary (default).
SRC=url | Specifies a URL for the associated file to be displayed in the frame.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.
VSPACE=pixels | Along with HSPACE, specifies margins for the element.
WIDTH=n | Along with HEIGHT, sets the initial size of the element. This attribute may be initially set in pixels or percentages.

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<IFRAME FRAMEBORDER=0 SCROLLING=NO SRC="sample.htm"></IFRAME>

Scripting Object

IFRAME


IMG

Description

Embeds an image or a video clip in the document.

Syntax

<IMG
 ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 ALT=text
BORDER=n
CLASS=classname
DATAFLD=colname
DATASRC=#ID
DYNSRC=url
HEIGHT=n
HSPACE=n
ID=value
ISMAP
 LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
LOOP=n
LOWSRC=url
NAME=name
SRC=url
STYLE=css1-properties
TITLE=text
USEMAP=url
VSPACE=n
WIDTH=n
event = script
>

Parameter | Description
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the image.
ALT=text | Optional text as an alternative to the graphic for rendering in non-graphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.
BORDER=n | Specifies the thickness of a border to be drawn around the element.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
DYNSRC=url | Specifies the address of a video clip or VRML world to be displayed in the window. Stands for Dynamic Source.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
HSPACE=n | Along with VSPACE, specifies margins for the element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
ISMAP | Identifies the picture as a server-side image map. Image maps allow users to access other documents by clicking different areas in an image. Server-side image maps require a script or other service on the server to process click information. When the user clicks on the image, the server receives the coordinates of the user's click along with the URL of the map. Internet Explorer appends a "?" and a comma-separated pair of x-y coordinates to the HREF attribute in the A element. For further information regarding server-side maps and the content of the map file, check your HTTP server documentation.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
LOOP=n | Specifies how many times a sound or video will loop when activated. Also specifies how many times the marquee should loop.
LOWSRC=url | Specifies a lower resolution image to display.
NAME=name | Specifies the name of the control.
SRC=url | Specifies a URL for the associated file.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
USEMAP=url | Identifies the picture as a client-side image map and specifies a MAP to use for responding to the user's clicks. Use the MAP and AREA elements to create the client-side mapping information.
VSPACE=n | Along with HSPACE, specifies margins for the element.
WIDTH=n | Along with HEIGHT, sets the initial size of the element. This attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onabort onafterupdate
onbeforeupdate onblur
onclick ondblclick
ondragstart onerror
onfocus onhelp
onkeydown onkeypress
onkeyup onload
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onselectstart

Example

<IMG SRC=mygraphic.bmp>

Scripting Object

IMG

See Also

AREA, INPUT, MAP


INPUT

Description

Specifies a form input control.

Syntax

<INPUT
ACCESSKEY=key
ALIGN=LEFT | CENTER | RIGHT
ALT=text
CLASS=classname
DISABLED
DYNSRC=url
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
LOWSRC=url
MAXLENGTH=n
NAME=name
READONLY
SIZE=n
SRC=url
STYLE=css1-properties
TABINDEX=n
TITLE=text
TYPE=BUTTON | CHECKBOX | FILE | HIDDEN | IMAGE | PASSWORD | RADIO | RESET | SUBMIT | TEXT
VALUE=value
event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser. This attribute applies to the BUTTON, CHECKBOX, FILE, PASSWORD, RADIO, RESET, SUBMIT, and TEXT input types.
ALIGN=LEFT | CENTER | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table when TYPE=IMAGE..
ALT=text | When TYPE=IMAGE, optional text as an alternative to the graphic for rendering in non-graphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
DYNSRC=url | Specifies the address of a video clip or VRML world to be displayed in the window. Stands for Dynamic Source. Applies to type=image only.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
LOWSRC=url | Specifies a lower resolution image to display. Applies to type=image only.
MAXLENGTH=n | Indicates the maximum number of characters that can be entered into a text control. This attribute applies to the PASSWORD and TEXT input types.
NAME=name | Specifies the name of the control, bookmark, or application.
READONLY | Causes the element's contents to be read only. The INPUT element can still receive the focus. This attribute applies to the PASSWORD and TEXT input types.
SIZE=n | Specifies the size of the control.
SRC=url | Specifies a URL for the associated file. This attribute applies to the IMAGE type.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object. This attribute applies to the BUTTON, CHECKBOX, FILE, PASSWORD, RADIO, RESET, SUBMIT, and TEXT input types.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=BUTTON | CHECKBOX | FILE | HIDDEN | IMAGE | PASSWORD | RADIO | RESET | SUBMIT | TEXT Specifies the type of intrinsic control. The default is TEXT.
BUTTON | A button on the HTML form.
CHECKBOX | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
FILE | A file upload element that allows the user to supply a file as the input.
HIDDEN | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
IMAGE | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with ".x" appended, and the y-coordinate is submitted under the name of the field with ".y" appended. Any VALUE= attribute is ignored. The image itself is specified by the SRC= attribute, exactly as for the IMG element.
PASSWORD | The same as the TEXT input type, except that text is not displayed as the user enters it.
RADIO | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit VALUE= attribute.
RESET | When pressed, this button resets the form's fields to their specified initial values. The label to be displayed on the button may be specified just as for the SUBMIT button.
SUBMIT | Submits the form. The default label is application-specific. If a SUBMIT button is pressed in order to submit the form, and that button has a NAME attribute specified, then that button contributes a name/value pair to the submitted data. Otherwise, a SUBMIT button makes no contribution to the submitted data.
TEXT | Used for a single-line text-entry field. Use in conjunction with the SIZE= and MAXLENGTH= attributes.
VALUE=value | For textual/numerical controls, specifies the default value of the control. For Boolean controls, specifies the value to be returned when the control is turned on. This attribute applies to the BUTTON, CHECKBOX, HIDDEN, PASSWORD, RADIO, RESET, SUBMIT, and TEXT input types.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onchange
onclick ondblclick
ondragstart onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onselect
onselectstart

Remarks

Objects can be submitted in forms. The NAME is the identifier of the object tag (i.e., <OBJECT NAME=slider CLASSID=...>), and the VALUE is obtained by getting the value of the default property of the control. If any of the following conditions occur, then the object will not become part of the submit string:
Object did not instantiate
Object does not have an identifier
Object does not have a default property to get
Default property cannot be coerced into a string

Example

<FORM ACTION="http://intranet/survey" METHOD=POST>
<P>Name
<BR><INPUT NAME="CONTROL1" TYPE=TEXT VALUE="Your Name">
<P>Password
<BR><INPUT TYPE="PASSWORD" NAME="CONTROL2">
<P>Color
<BR><INPUT TYPE="RADIO" NAME="CONTROL3" VALUE="0" CHECKED>Red
<INPUT TYPE="RADIO" NAME="CONTROL3" VALUE="1">Green
<INPUT TYPE="RADIO" NAME="CONTROL3" VALUE="2">Blue
<P>Comments
<BR><INPUT TYPE="TEXT" NAME="CONTROL4" SIZE="20,5" MAXLENGTH="250">
<P><INPUT NAME="CONTROL5" TYPE=CHECKBOX CHECKED>Send receipt
<P><INPUT TYPE="SUBMIT" VALUE="OK"><INPUT TYPE="RESET" VALUE="Reset">
</FORM>

Scripting Object

INPUT

See Also

TEXT, BUTTON, IMG, TEXTAREA, OBJECT


INS

Description

Indicates text that has been added to the document.

Syntax

<INS
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Class of the tag being defined. This is used to associate a subclassed style sheet with the tag.
ID=value | SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The script is written in JScript.
VBS, VBSCRIPT | The script is written in VBScript.
STYLE=css1-properties | Inline style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a tooltip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup

Remarks

Both the start and end tags are required.

Example

<INS datetime="1997-10-01T12:15:30-05:00">This text has been revised.</INS>

Scripting Object

INS

See Also

DEL


ISINDEX

Description

Causes the browser to prompt the user for a single line of input with a dialog window.

Syntax

<ISINDEX
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
PROMPT=text
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
PROMPT=text | Specifies a text prompt message for the input field.

Remarks

With HTML 4 this element will be deprecated, with INPUT recommended for use instead.


KBD

Description

Indicates text to be entered at the keyboard. Renders text in bold with a fixed-width font.

Syntax

<KBD
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<KBD>The user should enter this text.</KBD>

Scripting Object

KBD


LABEL

Description

Specifies a label for a control-like element. The content between the start and end tags defines the label text.

Syntax

<LABEL
 ACCESSKEY=key
CLASS=classname
DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
FOR=ID
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
FOR=ID | Specifies the ID for the control-like element the label is for. This is optional when the label is wrapped around the control the label applies to.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Labels cannot be nested.

Both the start and end tags are required.

Scripting Object

LABEL


LEGEND

Description

Identifies a contained set of fields defined in the FIELDSET element. The LEGEND element must be the first element within the FIELDSET element.

Syntax

<LEGEND
 ALIGN=BOTTOM | CENTER | LEFT | RIGHT | TOP
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BOTTOM | TOP
 event = script
>

Parameter | Description
ALIGN= BOTTOM | CENTER | LEFT | RIGHT | TOP Specifies the alignment of the legend text.
BOTTOM | Aligns the legend text bottom center.
CENTER | Centers the legend text.
LEFT | Left aligns the legend text.
RIGHT | Right aligns the legend text.
TOP | Aligns the legend text top center.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BOTTOM | TOP | Specifies whether the legend text appears at the top or bottom.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

LEGEND


LI

Description

Denotes one item of a list. This element is used inside a DIR, MENU, OL, or UL block.

Syntax

<LI
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
TYPE=1 | a | A | i | I
 VALUE=value
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=1 | a | A | i | I Changes the style of the list.
1 | List items are numbered.
a | List items are labeled with lowercase letters.
A | List items are labeled with uppercase letters.
i | List items are labeled with lowercase roman numerals.
I | List items are labeled with uppercase roman numerals.
VALUE=value | Changes the count of ordered lists as they progress.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

Example

<DIR> <LI>Art
<LI>History
<LI>Literature
<LI>Sports
<LI>Entertainment
<LI>Science</DIR>

Scripting Object

LI

See Also

DIR, MENU, OL, UL


LINK

Description

Used to specify a typed hyperlink between the document and some other resource.

Syntax

<LINK
 DISABLED
 HREF=url
ID=value
MEDIA=SCREEN | PRINT | ALL
 REL=STYLESHEET
 TITLE=text
TYPE="text/css"
>

Parameter | Description
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
HREF=url | Specifies the destination URL or anchor point.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
MEDIA= SCREEN | PRINT | ALL Describes the output device for the document. A value of "PRINT" does not affect the on-screen layout. Default value is ALL.
SCREEN | Output is intended for non-paged computer screens.
PRINT | Output is intended for paged, opaque material and for documents on screen viewed in print preview mode.
ALL | Applies to all devices.
REL=STYLESHEET | The REL attribute gives the relationship(s) described by the hypertext link from the anchor to the target. Values and their semantics will be registered by the HTML registration authority. The default relationship if none other is given is void. The REL attribute is only used when the HREF= attribute is present.
TITLE=text | Used to provide advisory information.
TYPE="text/css" | Indicates the type of style sheet.

Remarks

This element may only be used within the HEAD tag.

Example

<LINK REL=stylesheet HREF="styles.css" TYPE="text/css">

Scripting Object

LINK


LISTING

Description

This element is no longer recommended and should not be used in new documents. LISTING renders text in fixed-width type. When authoring new documents, use the PRE element.

Syntax

<LISTING
 CLASS=classname
ID=string
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
ALIGN= | Displays the element left flush, right flush, or centered relative to the display or table.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

LISTING

See Also

PRE


MAP

Description

Specifies a collection of hot spots for a client-side image map

Syntax

<MAP
 CLASS=classname
ID=value
LANG=language
NAME=name
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
NAME=name | Specifies the name of the window.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

This example shows a client-side image map having two hot spots and an area that is not hot. These hot spots can be applied to an image by using the name "map1" with the USEMAP= attribute of the IMG element.

Scripting Object

MAP


MARQUEE

Description

Enables you to create a scrolling text marquee.

Syntax

<MARQUEE
 BEHAVIOR=ALTERNATE | SCROLL | SLIDE
 BGCOLOR=color
CLASS=classname
DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
DIRECTION=DOWN | LEFT | RIGHT | UP
 HEIGHT=n
HSPACE=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
LOOP=n
SCROLLAMOUNT=n
SCROLLDELAY=milliseconds
STYLE=css1-properties
TITLE=text
TRUESPEED
 VSPACE=n
WIDTH=n
event = script
>

Parameter | Description
BEHAVIOR=ALTERNATE | SCROLL | SLIDE How the text scrolls in the marquee.
Alternate | The marquee text alternates left and right.
Scroll | The marquee text scrolls in the direction specified in the DIRECTION= attribute. The text scrolls off the end and starts over.
Slide | The marquee text scrolls in the direction specified in the DIRECTION= attribute and stops when it reaches the end.
BGCOLOR=color | Background color behind the element. For a complete list of colors, see the Internet Explorer color table.
CLASS=classname | Class of the tag being defined. This is used to associate a subclassed style sheet with the tag.
DATAFLD=colname | Column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | ID of the data source object that supplies the data that is bound to this element.
DIRECTION=DOWN | LEFT | RIGHT | UP | Which direction the text should scroll.
HEIGHT=n | HEIGHT of the MARQUEE in pixels or as a percentage of the screen height.
HSPACE=n | Along with VSPACE, specifies margins for the element.
ID=value | SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underscore character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The script is written in JScript.
VBS, VBSCRIPT | The script is written in VBScript.
LOOP=n | Number of times the marquee text will loop.
SCROLLAMOUNT=n | Number of pixels the text scrolls between each subsequent drawing of the MARQUEE.
SCROLLDELAY=milliseconds | Speed the MARQUEE scrolls in milliseconds.
STYLE=css1-properties | Inline style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a tooltip during the onmouseover event.
TRUESPEED | When present, this attribute indicates that the exact scroll delay value specified is used to move the marquee text. Without this attribute, all scroll delay values of 59 or less are rounded to 60 milliseconds.
VSPACE=n | Along with HSPACE, specifies margins for the element in pixels.
WIDTH=n | Returns the calculated width of the marquee in window coordinates. In HTML, this attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onafterupdate onblur
onbounce onclick
ondblclick ondragstart
onfinish onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onselectstart onstart

Remarks

Both the start and end tags are required.

Example

<MARQUEE DIRECTION=RIGHT BEHAVIOR=SCROLL SCROLLAMOUNT=10 SCROLLDELAY=200>
This is a scrolling marquee.
</MARQUEE>

Scripting Object

MARQUEE


MENU

Description

Specifies that the following block consists of individual items that begin with the LI element.

Syntax

<MENU
 CLASS=classname
ID=value
LANG=language
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<MENU>
<LI>This is the first item in the menu.
<LI>And this is the second item in the menu.
</MENU>

Scripting Object

MENU


META

Description

Provides information about an HTML document to browsers, search engines, and other applications

Syntax

<META
 CONTENT=description
HTTP-EQUIV=response
NAME=text
TITLE=text
URL=url
>

Parameter | Description
CONTENT=description | Specifies meta-information to be associated with the given name or HTTP response header.
HTTP-EQUIV=response | Used to bind the CONTENT of the element to an HTTP response header. This information is then used based on the application reading the header.
NAME=name | Specifies the name of the control, bookmark, or application.
TITLE=text | Used to provide advisory information.
URL=url | If a URL is specifies, the URL will be loaded after the specified time has elapsed.

Remarks

This element may only be used within the HEAD tag.

The start tag is required, and the end tag is optional.

The value of the CONTENT= attribute depends on the HTTP-EQUIV= attribute. The following lists some of these values.
HTTP-EQUIV CONTENT
REFRESH delay[;url]

The delay is the number of seconds that the browser waits before reloading a document. The optional url specifies the document to reload. If no url is given, the browser reloads the current document.

Content-Type text/html; CHARSET=character-set

The character-set specifies one of the character set aliases listed in HTML Character Sets.

Examples

The following example sets the character set for the document.

<META HTTP-EQUIV="Content-Type"
  CONTENT="text/html; CHARSET=Windows-1251">

The following example causes the browser to reload the document every two seconds.

<META HTTP-EQUIV="REFRESH" CONTENT=2>

The following example causes the browser to load the new document, http://www.sample.com/next.htm, after a five second delay.

<META HTTP-EQUIV="REFRESH" CONTENT="5; URL=http://www.sample.com/next.htm">

The following example causes the server to include the given content in the HTTP response to a GET or HEAD request for the document.

<META HTTP-EQUIV="Expires"
CONTENT="Tue, 04 Dec 1996 21:29:02 GMT">
<meta http-equiv="Keywords" CONTENT="HTML, Reference">
<META HTTP-EQUIV="Reply-to"
content="anybody@microsoft.com">

The HTTP response includes the following header fields.

Expires: Tue, 04 Dec 1996 21:29:02 GMT
Keywords: HTML, Reference
Reply-to: anybody@microsoft.com

Scripting Object

META


NOBR

Description

Renders text without line breaking.

Syntax

<NOBR
 ID=value
STYLE=css1-properties
TITLE=text
>

Parameter | Description
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.

Remarks

The start tag is required, and the end tag is optional.

Example

<NOBR>Here's a line of text I don't want to be broken . . . here's the end of the line.</NOBR>


NOFRAMES

Description

Used to contain HTML for browsers that do not support FRAMESET elements.

Syntax

<NOFRAMES
 ID=value
STYLE=css1-properties
TITLE=text
>

Parameter | Description
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<FRAMESET>
<NOFRAMES>You need Internet Explorer 3.0 to view frames!</NOFRAMES>
</FRAMESET>

See Also

FRAME, FRAMESET


NOSCRIPT

Description

Specifies HTML to be displayed in browsers that do not support scripting.

Syntax

<NOSCRIPT
>

Remarks

This element is a block element.

Both the start and end tags are required.


OBJECT

Description

Inserts an object, such as an image, document, application, or control, into the HTML document. An object can contain any elements ordinarily used within the body of an HTML document, including section headings, paragraphs, lists, forms, and nested objects.

Syntax

<OBJECT
 ACCESSKEY=key
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 CLASS=classname
CLASSID=id
CODE=url
CODEBASE=url
CODETYPE=media-type
DATA=url
DATAFLD=colname
DATASRC=#ID
HEIGHT=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
NAME=name
STYLE=css1-properties
TABINDEX=n
TITLE=text
TYPE=MIME-type
WIDTH=n
event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser.
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
CLASSID=id | Identifies the object implementation. For example, the syntax is CLSID:class-identifier for registered ActiveX controls.
CODE=url | The name of the file containing the compiled Java class.
CODEBASE=url | Specifies a URL referencing where to find the implementation of the object.
CODETYPE=media-type | Specifies the Internet media type for code.
DATA=url | Specifies a URL referencing the object's data.
DATAFLD=colname | The column name from the data source object that supplies the bound data. This attribute can be used on both the OBJECT element and the PARAM elements it contains.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NAME=name | Specifies the name of the control, bookmark, or application.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=MIME-type | Specifies the MIME type for the associated scripting engine; will override any LANGUAGE value.
WIDTH=n | Along with HEIGHT, sets the initial size of the element. This attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onreadystatechange onresize
onrowenter onrowexit
onselectstart

Remarks

Objects can be submitted in forms. See INPUT.

This element is a block element. Both the start and end tags are required.

Scripting Object

OBJECT

See Also

APPLET, EMBED, PARAM


OL

Description

Draws lines of text as an ordered list.

Syntax

<OL
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
START=n
STYLE=css1-properties
TITLE=text
TYPE=1 | a | A | i | I
 event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
START=n | Specifies the starting number for a list.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=1 | a | A | i | I Changes the style of the list.
1 | List items are numbered.
a | List items are labeled with lowercase letters.
A | List items are labeled with uppercase letters.
i | List items are labeled with lowercase roman numerals.
I | List items are labeled with uppercase roman numerals.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<OL>
<LI>This is the first item in the list.
<LI>And this is the second item in the list.
</OL>

<OL START=3>
<LI>This is item number 3.
</OL>

<OL TYPE=A>
<LI>This is item A.
</OL>

Scripting Object

OL

See Also

LI


OPTION

Description

Denotes one choice in a SELECT block.

Syntax

<OPTION
 CLASS=classname
ID=value
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
SELECTED
 VALUE=value
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
SELECTED | Indicates that this item is the default. If not present, the first item is selected by default.
VALUE=value | For textual/numerical controls, specifies the default value of the control. For Boolean controls, specifies the value to be returned when the control is turned on.
event Can be one or more of these events:
ondragstart onselectstart

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

Example

<SELECT NAME="Cars" SIZE="1">
<OPTION VALUE="1">BMW
<OPTION VALUE="2">PORSCHE
<OPTION VALUE="3" SELECTED>MERCEDES
</SELECT>

Scripting Object

OPTION

See Also

SELECT


P

Description

Denotes a paragraph.

Syntax

<P
 ALIGN=CENTER | LEFT | RIGHT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

The start tag is required, and the end tag is optional.

Example

<P>This is a paragraph.</P>

Scripting Object

P


PARAM

Description

Sets the property value for a given object. This element valid within the APPLET, EMBED, and OBJECT elements.

Syntax

<PARAM
 DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
NAME=name
VALUE=value
>

Parameter | Description
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
NAME=name | Specifies the name of the parameter.
VALUE=value | Specifies the property value. The value is passed to the object without change except that any character or numeric character entities are replaced with their corresponding character values.

See Also

APPLET, EMBED, OBJECT


PLAINTEXT

Description

Renders text in fixed-width type without processing tags and disables HTML parsing for the rest of the document. Although a </PLAINTEXT> tag is required, it does not close the container and is rendered on-screen. This element has been deprecated and may not be supported in a consistent manner by all browsers. It is recommended that the PRE element be used instead.

Syntax

<PLAINTEXT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script

>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

PLAINTEXT


PRE

Description

Renders text in fixed-width type.

Syntax

<PRE
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<PRE>Here's some plain text.</PRE>

Scripting Object

PRE


Q

Description

Sets apart a short quotation in text.

Syntax

<Q
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<P>He said,
<Q>"Hi there!"</Q>

Scripting Object

Q

See Also

BLOCKQUOTE


S

Description

Renders text in strikethrough type.

Syntax

<S
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<S>This text has a line through it.</S>

Scripting Object

S

See Also

STRIKE


SAMP

Description

Specifies sample text and renders it in a small font. The required end tag restores the text formatting to normal. By default, the font used is fixed-width. If a font face is specified in a FONT or BASEFONT element preceding SAMP, that font is used instead.

Syntax

<SAMP
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<SAMP>Here is some text in a small fixed-width font.</SAMP>

Scripting Object

SAMP

See Also

CODE


SCRIPT

Description

Specifies a script for the page that will be interpreted by a script engine.

Syntax

<SCRIPT
 CLASS=classname
DEFER
EVENT=eventname
FOR=element
ID=value
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
SRC=url
TITLE=text
TYPE=MIME-type
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DEFER | Indicates the script block contains only functions and no in-line script. Deferring the parsing of scripts until they are needed can improve performance by decreasing the time it takes to load a document.
EVENT=eventname | Specifies the event the script is being written for.
FOR=element | Specifies which element is being bound to the event script. A scripting object or element ID can be specified as the element value.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT. This attribute overrides any TYPE= value.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
SRC=url | Specifies a URL for the associated file.
TITLE=text | Used to provide advisory information.
TYPE=MIME-type | Specifies the MIME type for the associated scripting engine.

Remarks

Code within the SCRIPT block that are not contained within a function are executed immediately as the page is loaded. To keep scripts from being displayed on down-level browsers, the SCRIPT block should be nested within a comment block.

This element is a block element.

Both the start and end tags are required.

Scripting Object

SCRIPT


SELECT

Description

Denotes a list box or dropdown list. The end tag encloses any OPTION elements that may appear within the SELECT element.

Syntax

<SELECT
 ACCESSKEY=key
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 CLASS=classname
DATAFLD=colname
DATASRC=#ID
DISABLED
 ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
MULTIPLE
 NAME=name
SIZE=n
STYLE=css1-properties
TABINDEX=n
event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser.
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
MULTIPLE | Indicates that multiple items in the list can be selected.
NAME=name | Specifies the name of the control, bookmark, or application.
SIZE=n | Specifies the size of the control.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onchange
onclick ondblclick
ondragstart onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onselectstart

Remarks

Both the start and end tags are required.

Example

<SELECT NAME="Cars" SIZE="1">
<OPTION VALUE="1">BMW
<OPTION VALUE="2">PORSCHE
<OPTION VALUE="3" SELECTED>MERCEDES
</SELECT>

Scripting Object

SELECT

See Also

OPTION


SMALL

Description

Specifies that the enclosed text should be displayed with a relatively smaller font than the current font.

Syntax

<SMALL
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<SMALL>This text is smaller.</SMALL>

Scripting Object

SMALL


SPAN

Description

This does not have any structural role or established rendering convention. It allows a user to define their own method of rendering using style sheets.

Syntax

<SPAN
 CLASS=classname
DATAFLD=colname
DATAFORMATAS=HTML | TEXT
 DATASRC=#ID
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATAFORMATAS=HTML | TEXT | Indicates whether bound data is plain text or HTML.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<P>This paragraph contains a single <SPAN STYLE="color: blue">blue</SPAN> word.

Scripting Object

SPAN


STRIKE

Description

Renders text in strikethrough type.

Syntax

<STRIKE
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<STRIKE>This text has a line through it.</STRIKE>

Scripting Object

STRIKE

See Also

S


STRONG

Description

Renders text with a strong emphasis, often shown in boldface.

Syntax

<STRONG
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<STRONG>This text is strongly emphasized, shown as bold.</STRONG>

Scripting Object

STRONG

See Also

ACRONYM, ADDRESS, CITE, EM


STYLE

Description

Specifies the style sheet for the page.

Syntax

<STYLE
 DISABLED
 MEDIA=SCREEN | PRINT | ALL
 TITLE=text
TYPE="text/css"
>

Parameter | Description
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
MEDIA= SCREEN | PRINT | ALL Describes the output device for the document. A value of "PRINT" does not affect the on-screen layout. Default value is ALL.
SCREEN | Output is intended for non-paged computer screens.
PRINT | Output is intended for paged, opaque material and for documents on screen viewed in print preview mode.
ALL | Applies to all devices.
TITLE=text | Used to provide advisory information.
TYPE="text/css" | Indicates the type of style sheet.

Remarks

This element may be used within the BODY tag.

Both the start and end tags are required.

Example

<STYLE>
   BODY {background: white; color: black}
   H1 {font: 8pt Arial bold}
   P {font: 10pt Arial; text-indent: 0.5in}
   A {text-decoration: none; color: blue}
</STYLE>

Scripting Object

STYLE


SUB

Description

The enclosed text should be displayed in subscript, and using a smaller font than the current font.

Syntax

<SUB
 CLASS=classname
ID=value

LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

(X<SUB>1</SUB>,Y<SUB>1</SUB>)

Scripting Object

SUB

See Also

SUP


SUP

Description

The enclosed text should be displayed in SuperScript and in a smaller font relative to the current font.

Syntax

<SUP
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

X<SUP>2</SUP> + Y<SUP>2</SUP>

Scripting Object

SUP

See Also

SUB


TABLE

Description

Used to specify that the contained content is organized into a table with rows and columns. Use the TR, TD, and TH elements in the container to create the rows, columns, and cells.

The optional CAPTION, THEAD, TBODY, TFOOT, COLGROUP, and COL elements can be used to organize a table and apply attributes across columns and groups of columns.

Syntax

<TABLE
 ALIGN=CENTER | LEFT | RIGHT
 BACKGROUND=url
BGCOLOR=color
BORDER=n
BORDERCOLOR=color
BORDERCOLORDARK=color
BORDERCOLORLIGHT=color
CELLPADDING=n
CELLSPACING=n
CLASS=classname
COLS=n
DATAPAGESIZE=n
DATASRC=#ID
FRAME=ABOVE | BELOW | BORDER | BOX | INSIDES | LHS | RHS | VOID | VSIDES
 HEIGHT=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
RULES=ALL | COLS | GROUPS | NONE | ROWS
 STYLE=css1-properties
TITLE=text
WIDTH=n
event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Specifies how the table should be aligned.
BACKGROUND=url | Specifies a background picture for the table. The picture is tiled behind the text and graphics in the table, table head, or table cell.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
BORDER=n | Specifies the thickness of a border to be drawn around the element.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORDARK=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORLIGHT, and must be used with the BORDER attribute.
BORDERCOLORLIGHT=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORDARK, and must be used with the BORDER attribute.
CELLPADDING=n | Specifies the amount of space between the border of the cell and the contents of the cell.
CELLSPACING=n | Specifies the amount of space between cells in a table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLS=n | The number of columns in the table.
DATAPAGESIZE=n | Sets the number of records displayed in a data bound repeated table.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
FRAME= ABOVE | BELOW | BORDER | BOX | INSIDES | LHS | RHS | VOID | VSIDES Specifies which sides of a frame (outside borders) are displayed. The possible values are:
BORDER | Displays a border on all sides of the table frame. This is the default.
VOID | Removes all outside table borders.
ABOVE | Displays a border on the top side of the table frame.
BELOW | Displays a border on the bottom side of the table frame.
HSIDES | Displays a border on the top and bottom sides of the table frame.
LHS | Displays a border on the left-hand side of the table frame.
RHS | Displays a border on the right-hand side of the table frame.
VSIDES | Displays a border on the left and right sides of the table frame.
BOX | Displays a border on all sides of the table frame.
HEIGHT=n | Along with WIDTH, specifies the size at which the element is drawn. This attribute may be initially set in pixels or percentages.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
RULES=ALL | COLS | GROUPS | NONE | ROWS | Specifies which dividing lines are displayed (inside borders).
Specifies which dividing lines (inside borders) are displayed. The possible values are:
NONE | Removes all interior table borders. This is the default.
GROUPS | Displays horizontal borders between all table groups. Groups are specified by the THEAD, TBODY, TFOOT, and COLGROUP elements.
ROWS | Displays horizontal borders between all table rows.
COLS | Displays vertical borders between all table columns.
ALL | Displays a border on all rows and columns.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
WIDTH=n | Along with HEIGHT, sets the initial size of the element. This attribute may be initially set in pixels or percentages.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onrowenter
onrowexit onscroll
onselectstart

Remarks

Valid tags within a table include:

  • TR
  • CAPTION
  • THEAD
  • TBODY
  • TFOOT
  • COLGROUP
  • COL

This element is a block element.

Both the start and end tags are required.

Example

<TABLE BORDER=1 WIDTH=80%>
<THEAD>
<TR>
<TH>Heading 1</TH>
<TH>Heading 2</TH>
</TR>
<TBODY>
<TR>
<TD>Row 1, Column 1 text.</TD>
<TD>Row 1, Column 2 text.</TD>
</TR>
<TR>
<TD>Row 2, Column 1 text.</TD>
<TD>Row 2, Column 2 text.</TD>
</TR>
</TABLE>

Scripting Object

TABLE

See Also

TD, TR


TBODY

Description

Creates multiple sections when rules are needed between groups of table rows. If a table does not have a header or footer (does not have a THEAD or TFOOT element), the TBODY element is optional. The end tag is optional.

You can use the TBODY element more than once in a table. This is useful for dividing lengthy tables into smaller units and for controlling the placement of horizontal rules.

Syntax

<TBODY
 ALIGN=CENTER | LEFT | RIGHT
 BGCOLOR=color
CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is exposed for all tables, even if the table did not explicitly define a TBODY element.

This element is a block element.

The end tags are optional.

Example

<TABLE>
<THEAD>
<TR>
...
</TR>
<TBODY>
<TR>
...
</TR>
</TBODY>
</TABLE>

Scripting Object

TBODY


TD

Description

Specifies a cell in a table. This element is valid only within a row in a table. You must use a TR element before using TD. All attributes are optional.

Syntax

<TD
 ALIGN=CENTER | LEFT | RIGHT
 BACKGROUND=url
BGCOLOR=color
BORDERCOLOR=color
BORDERCOLORDARK=color
BORDERCOLORLIGHT=color
CLASS=classname
COLSPAN=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 NOWRAP
 ROWSPAN=n
STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BACKGROUND=url | Specifies a background picture for the table. The picture is tiled behind the text and graphics in the table, table head, or table cell.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORDARK=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORLIGHT, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORLIGHT=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORDARK, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLSPAN=n | Specifies how many columns in the TABLE this cell should span.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NOWRAP | The NOWRAP attribute is used when you do not want the browser to automatically perform word wrap.
ROWSPAN=n | Specifies how many rows in a TABLE this cell should span.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onrowenter
onrowexit onscroll
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

TD

See Also

TABLE, TH, TR


TEXTAREA

Description

Creates a multiline text entry control in which the user can type and edit text. The end tag is required. Any text between the start tag and end tag is used as the initial value for the control.

Syntax

<TEXTAREA
 ACCESSKEY=key
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP
 CLASS=classname
COLS=n
DATAFLD=colname
DATASRC=#ID
DISABLED
 ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 NAME=name
READONLY
 ROWS=n
STYLE=css1-properties
TABINDEX=n
TITLE=text
WRAP=OFF | PHYSICAL | VIRTUAL
 event = script
>

Parameter | Description
ACCESSKEY=key | Specifies an accelerator for the element. Pressing alt-key selects this element in the user's browser.
ALIGN=ABSBOTTOM | ABSMIDDLE | BASELINE | BOTTOM | LEFT | MIDDLE | RIGHT | TEXTTOP | TOP | Specifies the alignment for the control-like element.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLS=n | Specifies how many characters wide the text area is.
DATAFLD=colname | The column name from the data source object that supplies the bound data.
DATASRC=#ID | Indicates the ID of the data source object that supplies the data that is bound to this element.
DISABLED | Used to disable an element. This attribute prevents an element from receiving the focus, and causes the element to appear "grayed out."
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NAME=name | Specifies the name of the control, bookmark, or application.
READONLY | Causes the element's contents to be read only.
ROWS=n | Specifies the number of rows tall the text area control should be.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TABINDEX=n | Sets the tab order position for the object.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
WRAP=OFF | PHYSICAL | VIRTUAL Specifies how to handle word-wrapping inside the text area.
OFF | Word-wrapping is disabled (default).
PHYSICAL | The text is displayed and submitted word-wrapped
VIRTUAL | The text is displayed word-wrapped, but is submitted as typed.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onchange
onclick ondblclick
ondragstart onfocus
onhelp onkeydown
onkeypress onkeyup
onmousedown onmousemove
onmouseout onmouseover
onmouseup onresize
onrowenter onrowexit
onscroll onstart
onselectstart

Remarks

The default font is fixed pitch.

Both the start and end tags are required.

Scripting Object

TEXTAREA

See Also

INPUT


TFOOT

Description

Defines the table footer. Use TFOOT to duplicate footers when breaking a table across page boundaries, or for static headers when body sections are rendered in a scrolling panel. The end tag is optional.

The table footer is optional; if given, only one footer is allowed. The TFOOT element is valid only within a table; you must use a TABLE element before using this element.

Syntax

<TFOOT
 ALIGN=CENTER | LEFT | RIGHT
 BGCOLOR=color
CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Example

<TABLE>
<TBODY>
<TR>
...
</TR>
<TFOOT>
<TR>
...
</TR>
</TABLE>

Scripting Object

TFOOT


TH

Description

Creates a row or column heading in a table. The element is similar to the TD element but emphasizes the text in the cell to distinguish it from text in TD cells. The end tag is optional.

Syntax

<TH
 ALIGN=CENTER | LEFT | RIGHT
 BACKGROUND=url
BGCOLOR=color
BORDERCOLOR=color
BORDERCOLORDARK=color
BORDERCOLORLIGHT=color
CLASS=classname
COLSPAN=n
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
NOWRAP
 ROWSPAN=n

STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BACKGROUND=url | Specifies a background picture for the table. The picture is tiled behind the text and graphics in the table, table head, or table cell.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORDARK=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORLIGHT, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORLIGHT=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORDARK, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
COLSPAN=n | Specifies how many columns in the TABLE this cell should span.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
NOWRAP | The NOWRAP attribute is used when you do not want the browser to automatically perform word wrap.
ROWSPAN=n | Specifies how many rows in a TABLE this cell should span.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onscroll onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

TH

See Also

TD, TR


THEAD

Description

Defines the table heading. Use THEAD to duplicate headings when breaking tables across page boundaries, or for static headings when body sections are rendered in a scrolling panel. The end tag is optional.

The table heading is optional; if given, only one heading is allowed. The THEAD element is valid only within a table; you must use a TABLE element before using this element.

Syntax

<THEAD
 ALIGN=CENTER | LEFT | RIGHT
 BGCOLOR=color
CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Example

<TABLE>
<THEAD>
<TR>
...
</TR>
<TBODY>
<TR>
...
</TR>
</TABLE>

Scripting Object

THEAD


TITLE

Description

Identifies the contents of the document in a global context.

Syntax

<TITLE
 ID=value
TITLE=string
>

Parameter | Description
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
TITLE= | Used to provide advisory information.

Remarks

This element may only be used within the HEAD tag.

This element is a block element.

Both the start and end tags are required.

Example

<HEAD>
<TITLE>"Welcome To Internet Explorer!"</TITLE>
</HEAD>

Scripting Object

TITLE


TR

Description

Creates a row in a table. The row can contain one or more TD elements.

Syntax

<TR
 ALIGN=CENTER | LEFT | RIGHT
 BGCOLOR=color
BORDERCOLOR=color
BORDERCOLORDARK=color
BORDERCOLORLIGHT=color
CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
 STYLE=css1-properties
TITLE=text
VALIGN=BASELINE | BOTTOM | CENTER | TOP
 event = script
>

Parameter | Description
ALIGN=CENTER | LEFT | RIGHT | Displays the element left flush, right flush, or centered relative to the display or table.
BGCOLOR=color | Sets the background color behind the element. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLOR=color | Sets border color and must be used with the BORDER attribute, except for frames. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORDARK=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORLIGHT, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
BORDERCOLORLIGHT=color | Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of BORDERCOLORDARK, and must be used with the BORDER attribute. For a complete list of colors, look at the Internet Explorer color table.
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
VALIGN=BASELINE | BOTTOM | CENTER | TOP Displays the elements aligned at the top or bottom within the element.
BASELINE | Vertical align to the baseline of the font.
BOTTOM | Vertical align to the bottom of the element.
MIDDLE | Vertical align to the middle of the element.
TOP | Vertical align to the top of the element.
event Can be one or more of these events:
onafterupdate onbeforeupdate
onblur onclick
ondblclick ondragstart
onfocus onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onresize onrowenter
onrowexit onselectstart

Remarks

Within a row, the following tags are valid:

  • TD
  • TH

This element is a block element.

Both the start and end tags are required.

Example

<TABLE>
<TR>
...
</TR>
<TR>
...
</TR>
</TABLE>

Scripting Object

TR

See Also

TABLE, TD, TH


TT

Description

Indicates teletype. Renders text in fixed-width type. The required end tag returns the text formatting to normal.

Syntax

<TT
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<TT>Here's some plain text.</TT>

Scripting Object

TT


U

Description

Renders underlined text. The required end tag restores the text to normal.

Syntax

<U
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

<U>This text is underlined.</U>

Scripting Object

U


UL

Description

Specifies that the following block of text is a bulleted (or unordered) list. Each item begins with a LI tag. The end tag is required.

Syntax

<UL
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
TYPE=1 | a | A | i | I
 event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
TYPE=1 | a | A | i | I Changes the style of the list.
1 | List items are numbered.
a | List items are labeled with lowercase letters.
A | List items are labeled with uppercase letters.
i | List items are labeled with lowercase roman numerals.
I | List items are labeled with uppercase roman numerals.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Example

<UL>
<LI>This is the first bulleted item in the list.
<LI>And this is the second bulleted item in the list.
</UL>

Scripting Object

UL

See Also

LI


VAR

Description

Indicates placeholder text for a variable. Displays text in a small, fixed-width type. The required end tag restores the formatting to normal.

Syntax

<VAR
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

Both the start and end tags are required.

Example

Enter the <VAR>filename</VAR> in the dialog box.

Scripting Object

VAR


WBR

Description

Inserts a soft line break in a block of NOBR text.

Syntax

<WBR
 CLASS=classname

ID=value
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS
STYLE=css1-properties
TITLE=text
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information.

Remarks

The start tag is required, and the end tag is optional.

Example

<NOBR>This line of text will not break, no matter how narrow the window gets.
<WBR>This one, however, will.</NOBR>

See Also

BR


XMP

Description

This tag is no longer recommended. Instead, the PRE or SAMP tags should be used. XMP indicates example text by displaying it in fixed-width type. The required end tag restores the text to normal.

Syntax

<XMP
 CLASS=classname
ID=value
LANG=language
LANGUAGE=JAVASCRIPT | JSCRIPT | VBSCRIPT | VBS

STYLE=css1-properties
TITLE=text
event = script
>

Parameter | Description
CLASS=classname | Specifies the class of the tag being defined. This is used to associate a sub-classed style sheet with the tag.
ID=value | An SGML identifier used as the target for hypertext links or for naming particular elements in associated style sheets. Valid ID values must begin with a letter. The underbar character, "_", may be used in the ID name. The ID should be unique throughout the scope of the document. If more than one object with the same identifier exists in a document, a collection of those named items is created that can only be referenced by ordinal position.
LANG=language | Specifies which language to use in ISO standard language abbreviation form.
LANGUAGE=JAVASCRIPT | JSCRIPT | VBS | VBSCRIPT Specifies the language the current script is written in and invokes the proper scripting engine. The default value is JAVASCRIPT.
JAVASCRIPT, JSCRIPT | The scripting language is written in JavaScript.
VBS, VBSCRIPT | The scripting language is written in VBScript.
STYLE=css1-properties | Specifies an in-line style sheet for the tag.
TITLE=text | Used to provide advisory information. The contents of the title attribute will be displayed in a ToolTip during the onmouseover event.
event Can be one or more of these events:
onclick ondblclick
ondragstart onhelp
onkeydown onkeypress
onkeyup onmousedown
onmousemove onmouseout
onmouseover onmouseup
onselectstart

Remarks

This element is a block element.

Both the start and end tags are required.

Scripting Object

XMP

See Also

LISTING, PLAINTEXT, PRE, TT


HTML Character Sets

Character sets determine how the bytes that represent the text of your HTML document are translated to readable characters. Microsoft® Internet Explorer interprets the bytes in your document according to the applied character set translations. It interprets numeric character references ("&#12345;") as ISO10646 code points, consistent with the Unicode Standard, version 2.0, and independent of the chosen character set. Named entities ("&") are displayed independently of the chosen character set as well. The display of an arbitrary numeric character reference requires the existence of a font that is able to display that particular character on the user's system. Accordingly, the content in the first column of the following tables may not render as expected on all systems.

ISO Latin-1 Character Set

Additional Named Entities for HTML

Character Entities for Special Symbols and BIDI Text

Character Set Recognition


ISO Latin-1 Character Set

The following table contains the complete ISO Latin-1 character set, corresponding to the first 256 entries of the Unicode character repertoire in Internet Explorer 4.0. The table describes each character, its decimal code, and its named entity reference for HTML, and also provides a brief description.
Character | Decimal code | Named entity | Description
--- &#00; --- Unused
--- &#01; --- Unused
--- &#02; --- Unused
--- &#03; --- Unused
--- &#04; --- Unused
--- &#05; --- Unused
--- &#06; --- Unused
--- &#07; --- Unused
--- &#08; --- Unused
--- &#09; --- Horizontal tab
--- &#10; --- Line feed
--- &#11; --- Unused
--- &#12; --- Unused
--- &#13; --- Carriage Return
--- &#14; --- Unused
--- &#15; --- Unused
--- &#16; --- Unused
--- &#17; --- Unused
--- &#18; --- Unused
--- &#19; --- Unused
--- &#20; --- Unused
--- &#21; --- Unused
--- &#22; --- Unused
--- &#23; --- Unused
--- &#24; --- Unused
--- &#25; --- Unused
--- &#26; --- Unused
--- &#27; --- Unused
--- &#28; --- Unused
--- &#29; --- Unused
--- &#30; --- Unused
--- &#31; --- Unused
&#32; --- Space
! &#33; --- Exclamation mark
" &#34; &quot; Quotation mark
# &#35; --- Number sign
$ &#36; --- Dollar sign
% &#37; --- Percent sign
& &#38; &amp; Ampersand
' &#39; --- Apostrophe
( &#40; --- Left parenthesis
) &#41; --- Right parenthesis
* &#42; --- Asterisk
+ &#43; --- Plus sign
, &#44; --- Comma
- &#45; --- Hyphen
. &#46; --- Period (fullstop)
/ &#47; --- Solidus (slash)
0 &#48; --- Digit 0
1 &#49; --- Digit 1
2 &#50; --- Digit 2
3 &#51; --- Digit 3
4 &#52; --- Digit 4
5 &#53; --- Digit 5
6 &#54; --- Digit 6
7 &#55; --- Digit 7
8 &#56; --- Digit 8
9 &#57; --- Digit 9
: &#58; --- Colon
; &#59; --- Semicolon
< &#60; &lt; Less than
= &#61; --- Equals sign
> &#62; &gt; Greater than
? &#63; --- Question mark
@ &#64; --- Commercial at
A &#65; --- Capital A
B &#66; --- Capital B
C &#67; --- Capital C
D &#68; --- Capital D
E &#69; --- Capital E
F &#70; --- Capital F
G &#71; --- Capital G
H &#72; --- Capital H
I &#73; --- Capital I
J &#74; --- Capital J
K &#75; --- Capital K
L &#76; --- Capital L
M &#77; --- Capital M
N &#78; --- Capital N
O &#79; --- Capital O
P &#80; --- Capital P
Q &#81; --- Capital Q
R &#82; --- Capital R
S &#83; --- Capital S
T &#84; --- Capital T
U &#85; --- Capital U
V &#86; --- Capital V
W &#87; --- Capital W
X &#88; --- Capital X
Y &#89; --- Capital Y
Z &#90; --- Capital Z
[ &#91; --- Left square bracket
\ &#92; --- Reverse solidus (backslash)
] &#93; --- Right square bracket
^ &#94; --- Caret
_ &#95; --- Horizontal bar (underscore)
` &#96; --- Acute accent
a &#97; --- Small a
b &#98; --- Small b
c &#99; --- Small c
d &#100; --- Small d
e &#101; --- Small e
f &#102; --- Small f
g &#103; --- Small g
h &#104; --- Small h
i &#105; --- Small i
j &#106; --- Small j
k &#107; --- Small k
l &#108; --- Small l
m &#109; --- Small m
n &#110; --- Small n
o &#111; --- Small o
p &#112; --- Small p
q &#113; --- Small q
r &#114; --- Small r
s &#115; --- Small s
t &#116; --- Small t
u &#117; --- Small u
v &#118; --- Small v
w &#119; --- Small w
x &#120; --- Small x
y &#121; --- Small y
z &#122; --- Small z
{ &#123; --- Left curly brace
| &#124; --- Vertical bar
} &#125; --- Right curly brace
~ &#126; --- Tilde
 &#127; --- Unused
€ &#128; --- Unused
&#160; | &nbsp; | Nonbreaking space
¡ &#161; &iexcl; Inverted exclamation
¢ &#162; &cent; Cent sign
£ &#163; &pound; Pound sterling
¤ &#164; &curren; General currency sign
¥ &#165; &yen; Yen sign
¦ &#166; &brvbar; or &brkbar; Broken vertical bar
§ &#167; &sect; Section sign
¨ &#168; &uml; or &die; Diæresis / Umlaut
© &#169; &copy; Copyright
ª | &#170; | &ordf; | Feminine ordinal
« &#171; &laquo; Left angle quote, guillemot left
¬ &#172; &not Not sign
&#173; | &shy; | Soft hyphen
® &#174; &reg; Registered trademark
¯ &#175; &macr; or &hibar; Macron accent
° &#176; &deg; Degree sign
± &#177; &plusmn; Plus or minus
² | &#178; | &sup2; | Superscript two
³ | &#179; | &sup3; | Superscript three
´ &#180; &acute; Acute accent
µ | &#181; | &micro; | Micro sign
¶ &#182; &para; Paragraph sign
· &#183; &middot; Middle dot
¸ &#184; &cedil; Cedilla
¹ | &#185; | &sup1; | Superscript one
º | &#186; | &ordm; | Masculine ordinal
» &#187; &raquo; Right angle quote, guillemot right
¼ | &#188; | &frac14; | Fraction one-fourth
½ | &#189; | &frac12; | Fraction one-half
¾ | &#190; | &frac34; | Fraction three-fourths
¿ &#191; &iquest; Inverted question mark
À | &#192; | &Agrave; | Capital A, grave accent
Á | &#193; | &Aacute; | Capital A, acute accent
Â | &#194; | &Acirc; | Capital A, circumflex
Ã | &#195; | &Atilde; | Capital A, tilde
Ä | &#196; | &Auml; | Capital A, diæresis / umlaut
Å | &#197; | &Aring; | Capital A, ring
Æ | &#198; | &AElig; | Capital AE ligature
Ç | &#199; | &Ccedil; | Capital C, cedilla
È | &#200; | &Egrave; | Capital E, grave accent
É | &#201; | &Eacute; | Capital E, acute accent
Ê | &#202; | &Ecirc; | Capital E, circumflex
Ë | &#203; | &Euml; | Capital E, diæresis / umlaut
Ì | &#204; | &Igrave; | Capital I, grave accent
Í | &#205; | &Iacute; | Capital I, acute accent
Î | &#206; | &Icirc; | Capital I, circumflex
Ï | &#207; | &Iuml; | Capital I, diæresis / umlaut
Ð | &#208; | &ETH; | Capital Eth, Icelandic
Ñ | &#209; | &Ntilde; | Capital N, tilde
Ò | &#210; | &Ograve; | Capital O, grave accent
Ó | &#211; | &Oacute; | Capital O, acute accent
Ô | &#212; | &Ocirc; | Capital O, circumflex
Õ | &#213; | &Otilde; | Capital O, tilde
Ö | &#214; | &Ouml; | Capital O, diæresis / umlaut
× &#215; &times; Multiply sign
Ø | &#216; | &Oslash; | Capital O, slash
Ù | &#217; | &Ugrave; | Capital U, grave accent
Ú | &#218; | &Uacute; | Capital U, acute accent
Û | &#219; | &Ucirc; | Capital U, circumflex
Ü | &#220; | &Uuml; | Capital U, diæresis / umlaut
Ý | &#221; | &Yacute; | Capital Y, acute accent
Þ | &#222; | &THORN; | Capital Thorn, Icelandic
ß | &#223; | &szlig; | Small sharp s, German sz
à | &#224; | &agrave; | Small a, grave accent
á | &#225; | &aacute; | Small a, acute accent
â | &#226; | &acirc; | Small a, circumflex
ã | &#227; | &atilde; | Small a, tilde
ä | &#228; | &auml; | Small a, diæresis / umlaut
å | &#229; | &aring; | Small a, ring
æ | &#230; | &aelig; | Small ae ligature
ç | &#231; | &ccedil; | Small c, cedilla
è | &#232; | &egrave; | Small e, grave accent
é | &#233; | &eacute; | Small e, acute accent
ê | &#234; | &ecirc; | Small e, circumflex
ë | &#235; | &euml; | Small e, diæresis / umlaut
ì | &#236; | &igrave; | Small i, grave accent
í | &#237; | &iacute; | Small i, acute accent
î | &#238; | &icirc; | Small i, circumflex
ï | &#239; | &iuml; | Small i, diæresis / umlaut
ð | &#240; | &eth; | Small eth, Icelandic
ñ | &#241; | &ntilde; | Small n, tilde
ò | &#242; | &ograve; | Small o, grave accent
ó | &#243; | &oacute; | Small o, acute accent
ô | &#244; | &ocirc; | Small o, circumflex
õ | &#245; | &otilde; | Small o, tilde
ö | &#246; | &ouml; | Small o, diæresis / umlaut
÷ &#247; &divide; Division sign
ø | &#248; | &oslash; | Small o, slash
ù | &#249; | &ugrave; | Small u, grave accent
ú | &#250; | &uacute; | Small u, acute accent
û | &#251; | &ucirc; | Small u, circumflex
ü | &#252; | &uuml; | Small u, diæresis / umlaut
ý | &#253; | &yacute; | Small y, acute accent
þ | &#254; | &thorn; | Small thorn, Icelandic
ÿ | &#255; | &yuml; | Small y, diæresis / umlaut


Additional Named Entities for HTML

The following table contains additional named entities, their numeric character reference, and a description of each.
Character | Named entity | Numeric character reference | Description
Latin Extended-B
ƒ | &fnof | &#402; | latin small f with hook, =function, =florin, U0192 ISOtech
Greek
Α | &Alpha | &#913; | greek capital letter alpha, U0391
Β | &Beta | &#914; | greek capital letter beta, U0392
Γ | &Gamma | &#915; | greek capital letter gamma, U0393 ISOgrk3
Δ | &Delta | &#916; | greek capital letter delta, U0394 ISOgrk3
Ε | &Epsilon | &#917; | greek capital letter epsilon, U0395
Ζ | &Zeta | &#918; | greek capital letter zeta, U0396
Η | &Eta | &#919; | greek capital letter eta, U0397
Θ | &Theta | &#920; | greek capital letter theta, U0398 ISOgrk3
Ι | &Iota | &#921; | greek capital letter iota, U0399
Κ | &Kappa | &#922; | greek capital letter kappa, U039A
Λ | &Lambda | &#923; | greek capital letter lambda, U039B ISOgrk3
Μ | &Mu | &#924; | greek capital letter mu, U039C
Ν | &Nu | &#925; | greek capital letter nu, U039D
Ξ | &Xi | &#926; | greek capital letter xi, U039E ISOgrk3
Ο | &Omicron | &#927; | greek capital letter omicron, U039F
Π | &Pi | &#928; | greek capital letter pi, U03A0 ISOgrk3
Ρ | &Rho | &#929; | greek capital letter rho, U03A1
Σ | &Sigma | &#931; | greek capital letter sigma, U03A3 ISOgrk3
Τ | &Tau | &#932; | greek capital letter tau, U03A4
Υ | &Upsilon | &#933; | greek capital letter upsilon, U03A5 ISOgrk3
Φ | &Phi | &#934; | greek capital letter phi, U03A6 ISOgrk3
Χ | &Chi | &#935; | greek capital letter chi, U03A7
Ψ | &Psi | &#936; | greek capital letter psi, U03A8 ISOgrk3
Ω | &Omega | &#937; | greek capital letter omega, U03A9 ISOgrk3
a | &alpha | &#945; | greek small letter alpha, U03B1 ISOgrk3
b | &beta | &#946; | greek small letter beta, U03B2 ISOgrk3
g | &gamma | &#947; | greek small letter gamma, U03B3 ISOgrk3
d | &delta | &#948; | greek small letter delta, U03B4 ISOgrk3
ε | &epsilon | &#949; | greek small letter epsilon, U03B5 ISOgrk3
ζ | &zeta | &#950; | greek small letter zeta, U03B6 ISOgrk3
η | &eta | &#951; | greek small letter eta, U03B7 ISOgrk3
θ | &theta | &#952; | greek small letter theta, U03B8 ISOgrk3
ι | &iota | &#953; | greek small letter iota, U03B9 ISOgrk3
κ | &kappa | &#954; | greek small letter kappa, U03BA ISOgrk3
λ | &lambda | &#955; | greek small letter lambda, U03BB ISOgrk3
μ | &mu | &#956; | greek small letter mu, U03BC ISOgrk3
ν | &nu | &#957; | greek small letter nu, U03BD ISOgrk3
ξ | &xi | &#958; | greek small letter xi, U03BE ISOgrk3
ο | &omicron | &#959; | greek small letter omicron, U03BF NEW
p | &pi | &#960; | greek small letter pi, U03C0 ISOgrk3
ρ | &rho | &#961; | greek small letter rho, U03C1 ISOgrk3
ς | &sigmaf | &#962; | greek small letter final sigma, U03C2 ISOgrk3
σ | &sigma | &#963; | greek small letter sigma, U03C3 ISOgrk3
τ | &tau | &#964; | greek small letter tau, U03C4 ISOgrk3
υ | &upsilon | &#965; | greek small letter upsilon, U03C5 ISOgrk3
φ | &phi | &#966; | greek small letter phi, U03C6 ISOgrk3
χ | &chi | &#967; | greek small letter chi, U03C7 ISOgrk3
ψ | &psi | &#968; | greek small letter psi, U03C8 ISOgrk3
ω | &omega | &#969; | greek small letter omega, U03C9 ISOgrk3
ϑ | &thetasym | &#977; | greek small letter theta symbol, U03D1 NEW
ϒ | &upsih | &#978; | greek upsilon with hook symbol, U03D2 NEW
ϖ | &piv | &#982; | greek pi symbol, U03D6 ISOgrk3
General Punctuation
• &bull &#8226; bullet, =black small circle, U2022 ISOpub
… &hellip &#8230; horizontal ellipsis, =three dot leader, U2026 ISOpub
′ &prime &#8242; prime, =minutes, =feet, U2032 ISOtech
″ &Prime &#8243; double prime, =seconds, =inches, U2033 ISOtech
‾ &oline &#8254; overline, =spacing overscore, U203E NEW
⁄ &frasl &#8260; fraction slash, U2044 NEW
Letterlike Symbols
℘ &weierp &#8472; script capital P, =power set, =Weierstrass p, U2118 ISOamso
ℑ | &image | &#8465; | blackletter capital I, =imaginary part, U2111 ISOamso
ℜ | &real | &#8476; | blackletter capital R, =real part symbol, U211C ISOamso
™ &trade &#8482; trade mark sign, U2122 ISOnum
ℵ | &alefsym | &#8501; | alef symbol, =first transfinite cardinal, U2135 NEW
Arrows
← &larr &#8592; leftward arrow, U2190 ISOnum
↑ &uarr &#8593; upward arrow, U2191 ISOnum
→ &rarr &#8594; rightward arrow, U2192 ISOnum
↓ &darr &#8595; downward arrow, U2193 ISOnum
↔ &harr &#8596; left right arrow, U2194 ISOamsa
↵ &crarr &#8629; downward arrow with corner leftward, =carriage return, U21B5 NEW
⇐ &lArr &#8656; leftward double arrow, U21D0 ISOtech
⇑ &uArr &#8657; upward double arrow, U21D1 ISOamsa
⇒ &rArr &#8658; rightward double arrow, U21D2 ISOtech
⇓ &dArr &#8659; downward double arrow, U21D3 ISOamsa
⇔ &hArr &#8660; left right double arrow, U21D4 ISOamsa
Mathematical Operators
∀ &forall &#8704; for all, U2200 ISOtech
∂ &part &#8706; partial differential, U2202 ISOtech
∃ &exist &#8707; there exists, U2203 ISOtech
∅ &empty &#8709; empty set, =null set, =diameter, U2205 ISOamso
∇ &nabla &#8711; nabla, =backward difference, U2207 ISOtech
∈ &isin &#8712; element of, U2208 ISOtech
∉ &notin &#8713; not an element of, U2209 ISOtech
∋ &ni &#8715; contains as member, U220B ISOtech
∏ &prod &#8719; n-ary product, =product sign, U220F ISOamsb
∑ &sum &#8722; n-ary sumation, U2211 ISOamsb
− &minus &#8722; minus sign, U2212 ISOtech
∗ &lowast &#8727; asterisk operator, U2217 ISOtech
√ &radic &#8730; square root, =radical sign, U221A ISOtech
∝ &prop &#8733; proportional to, U221D ISOtech
∞ &infin &#8734; infinity, U221E ISOtech
∠ &ang &#8736; angle, U2220 ISOamso
∧ &and &#8869; logical and, =wedge, U2227 ISOtech
∨ &or &#8870; logical or, =vee, U2228 ISOtech
∩ &cap &#8745; intersection, =cap, U2229 ISOtech
∪ &cup &#8746; union, =cup, U222A ISOtech
∫ &int &#8747; integral, U222B ISOtech
∴ &there4 &#8756; therefore, U2234 ISOtech
∼ &sim &#8764; tilde operator, =varies with, =similar to, U223C ISOtech
≅ &cong &#8773; approximately equal to, U2245 ISOtech
≈ &asymp &#8773; almost equal to, =asymptotic to, U2248 ISOamsr
≠ &ne &#8800; not equal to, U2260 ISOtech
≡ &equiv &#8801; identical to, U2261 ISOtech
≤ &le &#8804; less-than or equal to, U2264 ISOtech
≥ &ge &#8805; greater-than or equal to, U2265 ISOtech
⊂ &sub &#8834; subset of, U2282 ISOtech
⊃ &sup &#8835; superset of, U2283 ISOtech
⊄ &nsub &#8836; not a subset of, U2284 ISOamsn
⊆ &sube &#8838; subset of or equal to, U2286 ISOtech
⊇ &supe &#8839; superset of or equal to, U2287 ISOtech
⊕ &oplus &#8853; circled plus, =direct sum, U2295 ISOamsb
⊗ &otimes &#8855; circled times, =vector product, U2297 ISOamsb
⊥ &perp &#8869; up tack, =orthogonal to, =perpendicular, U22A5 ISOtech
⋅ &sdot &#8901; dot operator, U22C5 ISOamsb
Miscellaneous Technical
⌈ &lceil &#8968; left ceiling, =apl upstile, U2308, ISOamsc
⌉ &rceil &#8969; right ceiling, U2309, ISOamsc
⌊ &lfloor &#8970; left floor, =apl downstile, U230A, ISOamsc
⌋ &rfloor &#8971; right floor, U230B, ISOamsc
⟨ &lang &#9001; left-pointing angle bracket, =bra, U2329 ISOtech
⟩ &rang &#9002; right-pointing angle bracket, =ket, U232A ISOtech
Geometric Shapes
◊ &loz &#9674; lozenge, U25CA ISOpub
Miscellaneous Symbols
♠ &spades &#9824; black spade suit, U2660 ISOpub
♣ &clubs &#9827; black club suit, =shamrock, U2663 ISOpub
♥ &hearts &#9829; black heart suit, =valentine, U2665 ISOpub
♦ &diams &#9830; black diamond suit, U2666 ISOpub


Character Entities for Special Symbols and BIDI Text

Using NE | NE | NCR | Using NCR
C0 Controls and Basic Latin
" &quot &#34; quotation mark, =apl quote, U0022 ISOnum
& &amp &#38; ampersand, U0026 ISOnum
< &lt &#60; less-than sign, U003C ISOnum
> &gt &#62; greater-than sign, U003E ISOnum
Latin Extended-A
Œ | &OElig | &#338; | latin capital ligature oe, U0152 ISOlat2
œ | &oelig | &#339; | latin small ligature oe, U0153 ISOlat2
Š | &Scaron | &#352; | latin capital letter s with caron, U0160 ISOlat2
š | &scaron | &#353; | latin small letter s with caron, U0161 ISOlat2
Ÿ | &Yuml | &#376; | latin capital letter y with diaeresis, U0178 ISOlat2
Spacing Modifier Letters
ˆ | &circ | &#710; | modifier letter circumflex accent, U02C6 ISOpub
˜ &tilde &#732; small tilde, U02DC ISOdia
General Punctuation
  &ensp | &#8194; | en space, U2002 ISOpub
  &emsp | &#8195; | em space, U2003 ISOpub
  &thinsp | &#8201; | thin space, U2009 ISOpub
‌ &zwnj &#8204; zero width non-joiner, U200C NEW RFC 2070
‍ &zwj &#8205; zero width joiner, U200D NEW RFC 2070
‎ &lrm &#8206; left-to-right mark, U200E NEW RFC 2070
‏ &rlm &#8207; right-to-left mark, U200F NEW RFC 2070
– &ndash &#8211; en dash, U2013 ISOpub
— &mdash &#8212; em dash, U2014 ISOpub
‘ &lsquo &#8216; left single quotation mark, U2018 ISOnum
’ &rsquo &#8217; right single quotation mark, U2019 ISOnum
‚ &sbquo &#8218; single low-9 quotation mark, U201A NEW
“ &ldquo &#8220; left double quotation mark, U201C ISOnum
” &rdquo &#8221; right double quotation mark, U201D ISOnum
„ &bdquo &#8222; double low-9 quotation mark, U201E NEW
† &dagger &#8224; dagger, U2020 ISOpub
‡ &Dagger &#8225; double dagger, U2021 ISOpub
‰ &permil &#8240; per mille sign, U2030 ISOtech
‹ &lsaquo &#8249; single left-pointing angle quotation mark, U2039 ISO proposed
› &rsaquo &#8250; single right-pointing angle quotation mark, U203A ISO proposed


Character Set Recognition

Internet Explorer uses the character set specified for a document to determine how to translate the bytes in the document into characters on the screen or paper. By default, Internet Explorer uses the character set specified in the HTTP content type returned by the server to determine this translation. If this parameter is not given, Internet Explorer uses the character set specified by the META element in the document. It uses the user's preferences if no META element is given.

You can use the META element to explicitly set the character set for a document. In this case, you set the HTTP-EQUIV= attribute to "Content-Type" and specify a character set identifier in the CONTENT= attribute. For example, the following META element identifies Windows-1251 as the character set for the document.

<META HTTP-EQUIV="Content-Type"
  CONTENT="text/html; CHARSET=Windows-1251">

As long as you place the META element before the BODY element, it affects the whole document, including the TITLE element. For clarity it should appear as the first element after HEAD so that all readers know the encoding before the first displayable is parsed. Note that the META element applies to the document containing it. This means, for example, that a compound document (a document consisting of two or more documents in a set of frames) can use different character sets in different frames.

Windows Codepage # | Display name | Preferred ID on SAVE | Internet Explorer 4 Aliases
1252 Western iso-8859-1
except when 128-159 is used, use "Windows-1252" 		iso8859-1, iso_8859-1, iso-8859-1, ANSI_X3.4-1968, iso-ir-6, ANSI_X3.4-1986, ISO_646, irv:1991, ISO646-US, us, IBM367, cp367, csASCII, latin1, iso_8859-1:1987, iso-ir-100, ibm819, cp819, Windows-1252
20105 | us-ascii | us-acii, ascii
28592 | Central European (ISO) | iso-8859-2 | iso8859-2, iso-8859-2, iso_8859-2, latin2, iso_8859-2:1987, iso-ir-101, l2, csISOLatin2
1250 | Central European (Windows) | Windows-1250 | Windows-1250, x-cp1250
1251 | Cyrillic (Windows) | Windows-1251 | Windows-1251, x-cp1251
1253 | Greek (Windows) | Windows-1253 | Windows-1253
1254 | Turkish (Windows) | Windows-1254 | Windows-1254
932 | Japanese (Shift-JIS) | shift_jis | shift_jis, x-sjis, ms_Kanji, csShiftJIS, x-ms-cp932
51932 | Japanese (EUC) | x-euc-jp | Extended_UNIX_Code_Packed_Format_for_Japanese, csEUCPkdFmtJapanese, x-euc-jp, x-euc
50220 | Japanese (JIS) | iso-2022-jp | csISO2022JP, iso-2022-jp
1257 | Baltic (Windows) | Windows-1257 | windows-1257
950 | Traditional Chinese (BIG5) | big5 | big5, csbig5, x-x-big5
936 | Simplified Chinese (GB2312) | gb2312 | GB_2312-80, iso-ir-58, chinese, csISO58GB231280, csGB2312, gb2312
20866 | Cyrillic (KOI8-R) | koi8-r | csKOI8R, koi8-r
949 | Korean (KSC5601) | ks_c_5601 | ks_c_5601, ks_c_5601-1987, korean, csKSC56011987
1255 (logical) | Hebrew (ISO-logical) | Windows-1255 | iso-8859-8i
1255 (visual) | Hebrew (ISO-Visual) | iso-8859-8 | ISO-8859-8 Visual, ISO-8859-8 , ISO_8859-8, visual
862 | Hebrew (DOS) | dos-862 | dos-862
1256 | Arabic (Windows) | Windows-1256 | Windows-1256
720 | Arabic (DOS) | dos-720 | dos-720
874 | Thai | Windows-874 | Windows-874
1258 | Vietnamese | Windows-1258 | Windows-1258
65001 | Unicode UTF-8 | UTF-8 | UTF-8, unicode-1-1-utf-8, unicode-2-0-utf-8
65000 | Unicode UTF-7 | UNICODE-1-1-UTF-7 | utf-7, UNICODE-1-1-UTF-7, csUnicode11UTF7, utf-7
50225 | Korean (ISO) | ISO-2022-KR | ISO-2022-KR, csISO2022KR
52936 | Simplified Chinese (HZ) | HZ-GB-2312 | HZ-GB-2312
28594 | Baltic (ISO) | iso-8869-4 | ISO_8859-4:1988, iso-ir-110, ISO_8859-4, ISO-8859-4, latin4, l4, csISOLatin4
28585 | Cyrillic (ISO) | iso_8859-5 | ISO_8859-5:1988, iso-ir-144, ISO_8859-5, ISO-8859-5, cyrillic, csISOLatinCyrillic, csISOLatin5
28597 | Greek (ISO) | iso-8859-7 | ISO_8859-7:1987, iso-ir-126, ISO_8859-7, ISO-8859-7, ELOT_928, ECMA-118, greek, greek8, csISOLatinGreek
28599 | Turkish (ISO) | iso-8859-9 | ISO_8859-9:1989, iso-ir-148, ISO_8859-9, ISO-8859-9, latin5, l5, csISOLatin5


CSS Attributes Reference CSS Attributes Reference *
  * Previous Topic: Character Set Recognition
  * Next Topic: CSS Attributes

CSS Attributes Reference

CSS Attributes


CSS Attributes

This section defines the cascading style sheet (CSS) attributes that are supported in Microsoft® Internet Explorer 4.0.

Font and Text Properties | font-family
font-style
font-variant
font-weight
font-size
@font-face
font
letter-spacing
line-height
text-decoration
text-transform
text-align
text-indent
vertical-align
Color and Background Properties | color
background-color
background-image
background-repeat
background-attachment
background-position
background
Layout Properties | margin-top
margin-right
margin-bottom
margin-left
margin
padding-top
padding-right
padding-bottom
padding-left
padding
border-top-width
border-right-width
border-bottom-width
border-left-width
border-width
border-top-color
border-right-color
border-bottom-color
border-left-color
border-color
border-top-style
border-right-style
border-bottom-style
border-left-style
border-style
border-top
border-right
border-bottom
border-left
border
float
clear
Classification Properties | display
list-style-type
list-style-image
list-style-position
list-style
Positioning Properties | clip
height
left
overflow
position
top
visibility
width
z-index
Printing Properties | page-break-before
page-break-after
Filter Properties | filter
Pseudo-Classes and Other Properties | active
hover
@import
!important
cursor
link
visited
Unsupported CSS Attributes | word-spacing
first-letter pseudo
first-line pseudo
white-space


active

Description

Sets the style of anchor (A) elements when the link is engaged or "active".

Remarks

Active means that the user is currently navigating the link. Setting the active pseudo-class is often used in conjunction with setting specific styles for the other states of a link: link, visited, hover. Using pseudo-classes on elements other than the A element has no effect.

Example

Note that the syntax in the following example uses a colon (:) to specify a pseudo-class.

A:active {text-decoration:overline;color:purple}

Applies To

A

See Also

hover, link, visited


background

Description

Sets all background attributes (image, attachment, color, repeat, position) for an element at once.

Syntax

{ background: background-color || background-image || background-repeat || background-attachment || background-position}

Remarks

While separate attributes can be used to specify the individual background properties, it is often more convenient to set them in one place using this composite property.

Individual background properties not set by the composite background property will be set to their default values. For example, the default value for "background-image" is none. Setting "background: white" is identical to saying "background: white none repeat scroll 0% 0%". So, in addition to setting the background color to white, it will clear any background-image, background-repeat, background-attachment, or background-position that has been previously set.

For more information on supported colors, see Color Table.

This property does not inherit, but the parent element's background will display through by default due to the default transparent value.

Examples

The first example below sets the background-color for DIV elements to red and sets all other background properties to their default values. The second example sets the background for the BODY element to show an image. This image will stay fixed as if it were a watermark on a page. Assuming the image is transparent, the color blue will bleed through.

DIV {background: red}

BODY {background: blue url(sample.gif) fixed}

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, TEXTAREA, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP

Scripting Property

background


background-attachment

Description

Determines if the background image is fixed with regard to the content or if it scrolls with the content.

Syntax

{ background-attachment: scroll | fixed}

Remarks

This attribute is not inherited.

Applies To

BODY, HTML

Scripting Property

backgroundAttachment


background-color

Description

Sets the background color of an element.

Syntax

{ background-color: color | transparent}

Remarks

This attribute is not inherited.

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, INPUT type=button, INPUT type=checkbox, INPUT type=file, INPUT type=image, INPUT type=password, INPUT type=radio, INPUT type=reset, INPUT type=submit, INPUT type=text, TEXTAREA, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP

Scripting Property

backgroundColor


background-image

Description

Sets the background image of an element.

Syntax

{ background-image: url | none}

Remarks

This attribute is not inherited.

When setting a background image, one should also set a background color that will be used when the image is unavailable. When the image is available, it is overlaid on top of the background color.

Example

BODY { background-image: url(marble.gif) }
P { background-image: none }

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=image, INPUT type=checkbox, INPUT type=radio, INPUT type=password

Scripting Property

backgroundImage


background-position

Description

Specifies the initial position of the background image for the element.

Syntax

{ background-position: [percentage | length]{1,2} | [top | center | bottom] || [left | center | right]}

Remarks

The attribute has no effect if no background image has been specified for the element.

This attribute is not inherited.

Examples

Sets the background image at these x,y coordinates of the object.

{background-position: 20px 40px}

Positions the background image at the top vertical position and the center horizontal position.

{background-position: top center}

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=image, INPUT type=checkbox, INPUT type=radio, INPUT type=password

Scripting Property

backgroundPosition, backgroundPositionX, backgroundPositionY


background-repeat

Description

Determines how the background image of an element is repeated.

Syntax

{ background-repeat: repeat | repeat-x | repeat-y | no-repeat}

Remarks

The attribute only has an effect if a background image has been specified.

A value of repeat means that the image is repeated both horizontally and vertically. The repeat-x (repeat-y) value makes the image repeat horizontally (vertically), to create a single band of images from one side to the other. With a value of no-repeat, the image is not repeated.

This attribute is not inherited.

Example

In the following example, the image will only be repeated vertically.

BODY {background: red url(pendant.gif);
      background-repeat: repeat-y;}

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=image, INPUT type=checkbox, INPUT type=radio, INPUT type=password

Scripting Property

backgroundRepeat


border

Description

Specifies the border to display around the element. The border property is a shorthand (composite) property for setting border width, color, and style for all four sides of an object. If a border-color is not specified, the text color is used. Supported on block and replaced elements only.

All individual border properties not set by the composite border property will be set to their initial values. For example, the initial value for border-width is medium. Setting border: thin is identical to saying border: thin none; the initial value for color picks up the text color if one isn't initially set. So, in addition to setting the border width to thin, it will clear any border-style or border-color that has been previously set.

Syntax

{ border: border-width || border-style || color}

Remarks

This attribute is not inherited.

Example

Creates a border for all four sides of the object, where all four sides show a 20 pixel blue border with an inset style. Use the individual properties to control the border for individual sides of the object.

{border: 20px inset blue}

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

border

See Also

border-width, border-style, border-color border-right, border-left, border-top, border-bottom


border-bottom

Description

Specifies the bottom border. Values that are not present are set to their initial values. Supported on block and replaced elements only.

For more information on supported colors, see Color Table.

Syntax

{ border-bottom: border-bottom-width || border-style || color}

Remarks

This attribute is not inherited.

Example

In this example, the border will be a solid green line.

{border-bottom: 20px outset green}

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderBottom

See Also

border-bottom-width, border-bottom-style, border-bottom-color, border, border-top


border-bottom-color

Description

Sets the color of an element's bottom border. Supported on block and replaced elements only. See the Color Table for a list of supported color values.

Syntax

{ border-bottom-color: border-color}

Remarks

For more information on supported colors, see Color Table.

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderBottomColor

See Also

border-top-color, border-left-color, border-right-color, border-color


border-bottom-style

Description

Sets the style of an element's bottom border. Supported on block and replaced elements only. Dotted and dashed are treated as solid.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. Border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

Syntax

{ border-bottom-style: none | dotted | dashed | solid | double | groove | ridge | inset | outset }

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderBottomStyle

See Also

border-top-style, border-left-style, border-right-style, border-style


border-bottom-width

Description

Sets the width of an element's bottom border. Supported on block and replaced elements only.

Syntax

{ border-bottom-width: thin | medium | thick | length}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderBottomWidth

See Also

border-top-width, border-left-width, border-right-width, border-width


border-color

Description

Sets the color of the four borders.

"{1,4}" indicates that up to four different colors can be specified. If one color is supplied, it is used for all four sides. If two colors are supplied, the first is used for the top and bottom, and the second is used for left and right. If three colors are supplied, they are used for top, right and left, and bottom, respectively. Supported on block and replaced elements only. See Color Table for a list of supported color values.

Syntax

{ border-color:border-color{1,4}}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderColor

See Also

border-top-color, border-left-color, border-right-color, border-bottom-color


border-left

Description

Sets the left border. Values that are not present are set to their initial values. Supported on block and replaced elements only.

For more information on supported colors, see Color Table.

Syntax

{ border-left: border-left-width || border-left-style || border-left-color}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderLeft

See Also

border-left-width, border-left-color, border-left-style, border-right, border-top, border-bottom


border-left-color

Description

Sets the color of an element's left border. Supported on block and replaced elements only. See Color Table for a list of supported color values.

Syntax

{ border-left-color: border-color}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderLeftColor

See Also

border-right-color, border-top-color, border-bottom-color, border-color


border-left-style

Description

Sets the style of an element's left border. Dotted and dashed are treated as solid. Supported on block and replaced elements only.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. Border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

Syntax

{ border-left-style: none | dotted | dashed | solid | double | groove | ridge | inset | outset }

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderLeftStyle

See Also

border-right-style, border-top-style, border-bottom-style, border-style


border-left-width

Description

Sets the width of an element's left border. Supported on block and replaced elements only.

Syntax

{ border-left-width: thin | medium | thick | length}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderLeftWidth

See Also

border-right-width, border-top-width, border-bottom-width, border-width


border-right

Description

Sets the right border. Values that are not present are set to their initial values. Supported on block and replaced elements only.

For more information on supported colors, see Color Table.

Syntax

{ border-right: border-right-width || border-right-style || border-right-color}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderRight

See Also

border-left, border-top, border-bottom, border


border-right-color

Description

Sets the color of an element's right border. Supported on block and replaced elements only. See Color Table for a list of supported color values.

Syntax

{ border-right-color: border-color}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderRightColor

See Also

border-top-color, border-bottom-color, border-left-color, border-color


border-right-style

Description

Sets the style of an element's right border. Dotted and dashed are treated as solid. Supported on block and replaced elements only.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. Border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

Syntax

{ border-right-style: none | dotted | dashed | solid | double | groove | ridge | inset | outset }

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderRightStyle

See Also

border-left-style, border-top-style, border-bottom-style, border-style


border-right-width

Description

Sets the width of an element's right border. Supported on block and replaced elements only.

Syntax

{ border-right-width: thin | medium | thick | length}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderRightWidth

See Also

border-top-width, border-bottom-width, border-left-width, border-width


border-style

Description

Sets the style of the borders. Dotted and dashed are treated as solid. Supported on block and replaced elements only.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. Border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

Syntax

{ border-style: none | dotted | dashed | solid | double | groove | ridge | inset | outset}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT, TEXTAREA

Scripting Property

borderStyle

See Also

border-width, border-color, border


border-top

Description

Describes the top border. Values that are not present are set to their initial values. Supported on block and replaced elements only.

Syntax

{ border-top: border-top-width || border-top-style || border-top-color}

Remarks

For more information on supported colors, see Color Table.

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderTop

See Also

border-bottom, border-left, border-right


border-top-color

Description

Sets the color of an element's top border. Supported on block and replaced elements only. See Color Table for a list of supported color values.

Syntax

{ border-top-color: border-color}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderTopColor

See Also

border-bottom-color, border-left-color, border-right-color, border-color


border-top-style

Description

Sets the style of an element's top border. Dotted and dashed are treated as solid. Supported on block and replaced elements only.

The border styles are defined as follows:
none | No border is drawn (regardless of any border-width).
solid | Border is a solid line.
double | Border is a double line drawn on top of the background of the element. The sum of the two single lines and the space between equals the border-width value. Border width must be at least 3 pixels wide to draw a double border.
groove | 3-D groove is drawn in colors based on the value.
ridge | 3-D ridge is drawn in colors based on the value.
inset | 3-D inset is drawn in colors based on the value.
outset | 3-D outset is drawn in colors based on the value.

Syntax

{ border-top-style: none | dotted | dashed | solid | double | groove | ridge | inset | outset }

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderTopStyle

See Also

border-bottom-style, border-left-style, border-right-style, border-style


border-top-width

Description

Sets the width of an element's top border. Supported on block and replaced elements only.

Syntax

{ border-top-width: thin | medium | thick | length}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderTopWidth

See Also

border-bottom-width, border-left-width, border-right-width, border-width


border-width

Description

Sets the width of the four borders at the same place in the style sheet.

"{1,4}" indicates that up to four different widths can be specified. If one width is supplied, it is used for all four sides. If two widths are supplied, the first is used for the top and bottom, and the second is used for left and right. If three widths are supplied, they are used for top, right and left, and bottom, respectively. Supported on block and replaced elements only.

Syntax

{ border-width: [thin | medium | thick | length]{1,4}}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

borderWidth

See Also

border-color, border-style, border


clear

Description

Specifies if elements allow floating elements (normally images) to the left or right.

Syntax

{ clear: none | left | right | both}

Remarks

The value of this property lists the sides where floating elements are not accepted. With clear set to left, an element will be moved below any floating element on the left side. With clear set to none, floating elements are allowed on all sides.

This attribute is not inherited.

Example

H1 { clear: left }

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, OPTION, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

clear


clip

Description

Defines a clipping region shape and size for a positioned element.

The clipping region defines the part of the element that is visible. Any part of the element that is outside the clipping region is transparent. Any coordinate can be replaced by the value auto, which causes the clipping rectangle to match the element's opposite side. The default value is to clip to expose the entire element. Note the order of the values: clip:rect(0,0,50,50) would render the element invisible, as it would set both the top and the right positions of the clipping region to 0. To achieve a 50-by-50 view port, the syntax should be clip:rect(0, 50, 50, 0).

Syntax

{ clip: shape | auto }

Syntax

shape:rect (top | right | bottom | left)

Remarks

<top>, <right>, <bottom>, and <left> specify either auto or a length value.

Remarks

This attribute is not inherited.

Applies To

DIV, TEXTAREA, SPAN, INPUT type=button, FIELDSET, IMG, MARQUEE, INPUT, TABLE

Scripting Property

clip


color

Description

Describes the text color of an element, that is, the foreground color.

Syntax

{ color: color}

Remarks

This attribute is inherited.

For more information on supported colors, see Color Table.

Examples

The following examples are different ways to specify red.

EM { color: red }              /* natural language / CNS */
EM { color: #F00 }             /* #RGB */
EM { color: #FF0000 }          /* #RRGGBB */
EM { color: rgb 1.0 0.0 0.0 }  /* float range: 0.0 - 1.0 */

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

color


cursor

Description

Specifies the type of cursor to be displayed for the mouse pointer.

Syntax

{ cursor: auto | crosshair | default | hand | move | e-resize | ne-resize | nw-resize | n-resize | se-resize | sw-resize | s-resize | w-resize | text | wait | help}

Remarks

The following types are defined:

auto
Browser determines the cursor to display based on the current context.
crosshair
Simple cross hair.
default
Platform-dependent default cursor. Usually an arrow.
hand
Hand.
move
Something is to be moved.
*-resize
Edge is to be moved.
text
Editable text. Usually an I-bar.
wait
Cursor to indicate that the program is busy and the user should wait. Usually a watch or hourglass.

This attribute is inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

cursor


display

Description

Indicates whether an element is rendered. If set to none, the element is not rendered. If set to one of the other values, the element is rendered. The default is to render the element.

Note Values for block, inline and list-item are not supported explicitly, but are useful in setting the display property to be on. In contrast to the visibility attribute, display:none reserves no space for the element on the screen.

Syntax

{ display: none | block | inline | list-item}

Remarks

For values other than none, the element will display with its normal display type.

This attribute is not inherited.

Applies To

TABLE, INPUT, TEXTAREA, INPUT type=button, DIV, SPAN, IFRAME, IMG, BODY, MARQUEE, SELECT

Scripting Property

display


filter

Description

Specifies one or more filters applied to an element.

Internet Explorer supports the following built-in filter types: Visual Filter, Reveal Transition Filter, or Blend Transition Filter. For detailed information, see Creating Multimedia Effects with Visual Filters and Transitions. The filter mechanism is extensible and allows additional filters to be developed and added later.

Syntax

{ filter: filtertype1(parameter1, parameter2,...) [filtertype2([parameter1, parameter2)]...}

Remarks

An asterisk in the following applies to list indicates that a defined height, width, or absolute position is required.

Remarks

This attribute is not inherited.

Applies To

BODY, BUTTON, DIV*, IMG, INPUT, MARQUEE, SPAN*, TABLE, TD, TEXTAREA, TFOOT, TH, THEAD, TR


float

Description

Specifies whether the object floats, causing text to flow around it.

Syntax

{ float: left | right | none}

Remarks

With the value none, the element will be displayed where it appears in the text. With a value of left (right), the margin properties will decide the horizontal positioning of the image and the text will flow on the right (left) side of the image. With a value of left or right, the element is treated as block-level (that is, the display property is ignored).

This attribute is not inherited.

Example

The following example demonstrates the float attribute.

<html>
<head>
<title>case for float</title>
</head>
<body>
<p>This is an example of float. "image1" should float to the left and "image2" should float to the right.
<img src=" http://www.microsoft.com/image1.gif" style="float:left">
<img src="http://www.microsoft.com/image2.gif" style="float:right">
<p>
</body>
</html>

Applies To

TABLE, INPUT, TEXTAREA, INPUT type=button, DIV, SPAN, OBJECT, APPLET, EMBED, IFRAMES, MARQUEE, SELECT

Scripting Property

styleFloat


font

Description

Defines the separate font attributes (font-style, font-variant, font-weight, font-size, line-height, and font-family).

Syntax

{ font: [ font-style || font-variant || font-weight ] font-size [ line-height ] font-family}

Remarks

Values that are not present are set to their default values. Font-size and font-family are required.

This attribute is inherited.

Example

The following example sets the font-family to Comic Sans MS and the font-size to 24 point for all SPAN elements within the document.

SPAN {font: 24 'Comic Sans MS'}

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

font


@font-face

Description

Specifies a font to embed into your HTML document.

This feature allows you to use specific fonts that might not be available on your local system. The URL should point to an embedded OpenType file (.eot or .ote format). The file contains compressed font data that is converted to a TrueType font. For more information on the font embedding feature and pointers to a tool for creating .eot files, see Font Embedding.

Syntax

@font-face {font-family: font-family, src url(URL);}

Example

The following example shows how to embed a font in an HTML document by referencing its source from another site.

<html>
<head>
<style>
@font-face {font-family:comic; src:url(http://valid_url/some_font_file.eot);}
</style>
<title>Font embedding using @font-face</title>
</head>
<body>
<p style="font-family:comic;font-size:18pt">This line uses @font-face defined in the above style element section using comic sans ms bold in 18pt.</p>
</body>
</html>


font-family

Description

Specifies the typeface name of the font used for text in the element.

Syntax

{ font-family: [[ family-name | generic-family ] , ]* [ family-name | generic-family ]}

Remarks

The value associated with this attribute is a prioritized list of font family names and/or generic family names. List items are separated by commas to minimize confusion between multiple-word font family names. If the font family name contains white space, it is recommended that it is quoted with single or double quotation marks.

This attribute is inherited.

Example

The following generic families are defined, with an example name in parentheses.

'serif' (Times)
'sans-serif' (Helvetica)
'cursive' (Zapf-Chancery)
'fantasy' (Western)
'monospace' (Courier)

Not knowing which fonts users will have installed on their computers, authors should provide a list of alternatives with a generic font-family at the end of the list. This list can include embedded fonts. See @font-face for more information on embedding fonts.

BODY { font-family: univers, helvetica, sans-serif }
BODY { font-family: 'new century schoolbook', serif }

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, < A HREF="../objects/H4.htm#H4">H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

fontFamily


font-size

Description

Specifies the size of the font to be used when rendering the text displayed by an element.

Syntax

{ font-size: absolute-size | relative-size | length | percentage |}

Remarks

Initial value is medium. Negative values are not allowed.

Font sizes are computed based on the font size of the parent element. Therefore, a font size of "10em" means that the size of the "em" is based on the font used by the parent element.

The values for font size are shown below:
absolute-size | A set of keywords that indicate predefined font sizes. Possible keywords include [xx-small | x-small | small | medium | large | x-large | xx-large]. Named font sizes scale according to the user's font setting preferences.
relative-size | A set of keywords that are interpreted as relative to the font size of the parent element. Possible values include [ larger | smaller].
length | An absolute value for the font size.
percentage | A percentage value of the parent element's font size.

This attribute is inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

fontSize


font-style

Description

Sets the font style. Internet Explorer 4.0 implements italic and oblique identically.

Syntax

{ font-style: normal | italic | oblique}

Remarks

This attribute is inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

fontStyle


font-variant

Description

Sets the font variation to small-caps in the current font family.

Syntax

{ font-variant: normal | small-caps}

Remarks

Internet Explorer 4.0 renders small-caps as uppercase letters in a smaller size.

This attribute is inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

fontVariant


font-weight

Description

Sets the weight (boldness) of the text.

Syntax

{ font-weight: normal | bold | bolder | lighter | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900}

Remarks

The key words for font-weight values are mapped to specific font variations depending on the fonts that are installed on the user's computer. In many cases, the user will not see the difference between different font-weight settings because the system will choose the closest match, which may be the same as the next relative font-weight setting that was previously set on the page. In any case, Internet Explorer 4.0 will always render a bolder font at least the same if not darker than a lighter font.

Setting the font-weight to 400 is equivalent to normal. Setting the font-weight to 700 is the equivalent to bold.

A font-weight of bolder or lighter is interpreted relative to the parent element's weight. A value of bolder for text whose parent is normal would set the text to bold.

Internet Explorer currently supports only normal | bold.

This attribute is inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

fontWeight


height

Description

Specifies the height of a positioned element. Percentage values are based on the width of the parent element.

The height attribute, like all other CSS attributes, specifies a string value. When scripting the height property, use either the pixelHeight or posHeight property for numeric manipulation of a height value.

Syntax

{ height: length | percentage | auto}

Remarks

This attribute is not inherited.

Applies To

TABLE, INPUT, TEXTAREA, INPUT type=button, DIV, SPAN, OBJECT, APPLET, EMBED, IFRAME, IMG, HR, MARQUEE, FIELDSET

Scripting Property

height

See Also

width, top, left, posHeight, pixelHeight


hover

Description

Sets the style of the anchor (A) elements when the user's mouse hovers over the link.

Remarks

Hover means that the user has the mouse positioned over the link and has hesitated. The style will not change if the mouse is simply passed over the link. Setting the hover pseudo-class is often used in conjunction with setting specific styles for the other states of a link: active, link, visited. Note the syntax in the example below uses a colon (:) to specify a pseudo-class.

Example

When a user hovers over a hyperlink contained within a document to which the following style sheet has been applied, the text is displayed in red, is converted to uppercase, and is spaced one centimeter apart.

<style>
a:hover {color:red;text-transform:uppercase;letter-spacing:1cm}
</style>

Applies To

A

See Also

active, link, visited


@import

Description

Specifies a style sheet to import.

Syntax

@import url (URL);

Remarks

This differs from using the LINK element in that the @import statement is used as part of a style sheet definition inside a LINK or a STYLE tag. In the scripting model, this means that the owningElement property of the styleSheet object that represents a style sheet defined through @import will be either a STYLE or a LINK element. The statement should occur at the start of a style sheet, before any declarations. While Internet Explorer 4.0 allows @import statements to be anywhere within the style sheet definition, the rules contained within the @import style sheet will be applied to the document before any other rules defined for the containing style sheet. This can affect expected cascading affects.

Rules in the style sheet override rules in the imported style sheet.

Example

<STYLE type="css/text">
@import url(http://anotherStyleSheet.css)
P {color:blue}
</STYLE>

See Also

link, style, styleSheet, imports


!important

Description

Increases the weight or importance of a particular rule.

Example

The following example illustrates this feature.

<style>
p {color:red!important}
</style>
<p style="color:green">This will be red </p>

In this example, normally the color of the <p> will be green (because inline overrules the rule set in a style tag). But, because of the !important in the style rule, the <p> tag will be red.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text


left

Description

Specifies the position of the element relative to the left of the document.

Syntax

{ left: length | percentage | auto}

Remarks

left is used with the position attribute. This value corresponds to the offsetLeft property of the element, and does not include the border of the parent element (noteworthy for the BODY that draws the border inside the client region). auto is the default position of the element according to the regular HTML layout of the page. Percentage values are based on the parent's position.

This attribute, like all other CSS attributes, specifies a string value. When scripting the left property, use either the pixelLeft or posLeft property for numeric manipulation of a top value.

This attribute is not inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

left

See Also

top, height, width, posLeft, pixelLeft


letter-spacing

Description

Specifies additional space between letters.

Syntax

{ letter-spacing: normal | length}

Remarks

This attribute will add the appropriate letter spacing after each character. If you do not want the end of a word to be affected by the spacing, you need to place the last character outside the closing element tag. Letter spacing can be influenced by justification . The length value indicates an addition to the default space between characters. Negative values are permitted.

This attribute is inherited.

Example

In the following example, the word-spacing between each character in BLOCKQUOTE elements would be increased with '1.0em'.

BLOCKQUOTE { letter-spacing: 1.0em }

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

letterSpacing


line-height

Description

Specifies how far apart the lines in a paragraph are. Line height measures the distance between the descender of the font to the top of the internal leading of the font.

Syntax

{ line-height: normal | number | length | percentage}

Remarks

If there is more than one element on a formatted line, the maximum line height applies. Negative values are not allowed.

This attribute is inherited.

Example

The three rules in this example are identical. If the value is set to normal, the line height is set to the default line height for the element's font.

DIV { line-height: 1.2%; font-size: 10pt }   /* number */
DIV { line-height: 1.2em; font-size: 10pt } /* length */
DIV { line-height: 120%; font-size: 10pt } /* percentage */

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

lineHeight


link

Description

Sets the style of the anchor (A) elements for the link's default (unvisited) state.

Remarks

The link attribute takes effect when the link has not been visited and it is not actively being navigated or has a mouse positioned over it. Setting the hover pseudo-class is often used in conjunction with setting specific styles for the other states of a link: active, visited, and hover. Note the syntax in the example below uses a colon (:) to specify a pseudo-class.

Example

The following example sets unvisited links to red and visited links to blue.

A:link   { color: red }           /* unvisited link */
A:visited  { color: blue }       /* visited links */

Applies To

A

See Also

active, hover, visited


list-style

Description

Sets three properties (list-style-type, list-style-image, and list-style-position) at once.

Syntax

{ list-style: keyword || position || url}

Remarks

A URL can be combined with a list-style-type; if available, the image will replace the marker type.

This attribute is inherited.

Example

In the following example, the "disc" image will be used if the image cannot be found.

UL {list-style: url(http://some_image.gif) disc}

Applies To

LI, OL, UL

Scripting Property

listStyle


list-style-image

Description

Specifies an image to use as a list item marker.

Syntax

{ list-style-image: url | none}

Remarks

When the image is available, it will replace the marker set with the list-style-type marker. The default value is none.

This attribute is inherited.

Applies To

LI, OL, UL

Scripting Property

listStyleImage


list-style-position

Description

Determines how the list item marker is drawn with regard to the content.

Syntax

{ list-style-position: inside | outside}

Remarks

This attribute is applicable only on elements with a display value of list-item. If the value is set to inside, any wrapping text in the list item will wrap directly under the marker. If the value is set to outside, the wrapping text maintains the same left indent as the first line of the list item's text.

This attribute is inherited.

Applies To

LI, OL, UL

Scripting Property

listStylePosition


list-style-type

Description

Specifies a predefined list item marker.

Syntax

{ list-style-type: disc | circle | square | decimal | lower-roman | upper-roman | lower-alpha | upper-alpha | none}

Remarks

Determines the appearance of the list item marker if list-style-image is none or if the image pointed to by the URL cannot be displayed. The default value is disc.

This attribute is inherited.

Applies To

LI, OL, UL

Scripting Property

listStyleType


margin

Description

Sets the margin on all four sides of an object with a single style sheet rule.

Syntax

{ margin: [ length | percentage | auto] {1,4}}

Remarks

This is a composite property. The "{1,4}" means that up to four values can be specified. Specifying one value applies that value to all four sides; specifying two values applies the first value to the top and bottom, and the second value to the left and right. Specifying three values applies the first to the top, the second to the right and left, and the third to the bottom. Negative margins are supported except for top and bottom margins on inline elements. Percentage values refer to the parent element's width.

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, IFRAME, IMG, INPUT, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PLAINTEXT, PRE, SPAN, TABLE, TEXTAREA, TD, TH, TR, UL, XMP

Scripting Property

margin

See Also

margin-bottom, margin-left, margin-right, margin-top


margin-bottom

Description

Specifies the bottom margin for the element. Negative margins are supported except for top and bottom margins on inline elements.

Syntax

{ margin-bottom: [ length | percentage | auto]}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

marginBottom

See Also

margin, margin-left, margin-right, margin-top


margin-left

Description

Specifies the left margin for the element. Negative margins are supported except for top and bottom margins on inline elements.

Syntax

{ margin-left: [ length | percentage | auto]}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

marginLeft

See Also

margin, margin-bottom, margin-right, margin-top


margin-right

Description

Specifies the right margin for the element. Negative margins are supported except for top and bottom margins on inline elements.

Syntax

{ margin-right: [ length | percentage | auto]}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, CAPTION, TEXTAREA, IFRAME, SPAN, IMG, EMBED, OBJECT, INPUT

Scripting Property

marginRight

See Also

margin, margin-bottom, margin-left, margin-top


margin-top

Description

Specifies the top margin for the element. Negative margins are supported except for top and bottom margins on inline elements.

Syntax

{ margin-top: [ length | percentage | auto]}

Remarks

This attribute is not inherited.

Applies To

BLOCKQUOTE, BODY, CAPTION, CENTER, DD, DIR, DIV, DL, DT, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, INPUT, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP, TEXTAREA, IFRAME, SPAN, IMG, OBJECT

Scripting Property

marginTop

See Also

margin, margin-bottom, margin-left, margin-right


overflow

Description

Determines what to do when the element's content exceeds the height and width of the element.

By default, overflowing content is visible. This means the element does not observe its specified height and width. If the attribute is set to scroll, the content is clipped to the height and width specified on the element, and the overflowing content is accessible through scroll bars. If the attribute is set to hidden, the content of the element is clipped to the height and width of the element, and no scroll bars appear to access the hidden content. Applies to positioned elements.

Syntax

{ overflow: scroll | hidden | visible | auto }

Remarks

This attribute is not inherited.

For the TEXTAREA element, only the hidden value is valid. Setting the overflow to hidden on a TEXTAREA element hides its scrollbars.

Example

The following example illustrates this attribute.

<DIV STYLE="position:relative;height:100;width:100;
      top:0;left:0;background-color:green;overflow:scroll">
put enough text in here that will take up more than 100 x 100
pixels worth of space. View this, and you will see that you
will need to use the scroll bars to see the content that won't
fit within a 100 x 100 window.
</DIV>

Applies To

DIV, TEXTAREA, SPAN, FIELDSET

Scripting Property

overflow


padding

Description

Specifies the padding-top, padding-bottom, padding-left, and padding-right in one style sheet rule. Padding describes how much space to insert between the element and its margin, or if there is a border, between the element and its border.

Syntax

{ padding: [ length | percentage ] {1,4}}

Remarks

This is a composite property. The "{1,4}" means that up to four values can be specified. The order is top, right, bottom, left. If there is only one value specified, it applies to all sides; if there are two or three, the missing values are taken from the opposite side. Negative values are not allowed. This property is supported on block and replaced elements only.

This attribute is not inherited.

Applies To

BODY, CAPTION, DIV, FIELDSET, IFRAME, LEGEND, MARQUEE, TABLE, TD, TEXTAREA, TR

Scripting Property

padding


padding-bottom

Description

Sets the bottom padding of an element. Padding values cannot be negative.

Supported on block and replaced elements only.

Syntax

{ padding-bottom: length | percentage}

Remarks

This attribute is not inherited.

Applies To

TABLE, TD, TR, CAPTION, TEXTAREA, IFRAME, BODY, MARQUEE, DIV

Scripting Property

paddingBottom

See Also

padding-top, padding-left, padding-right, padding


padding-left

Description

Sets the left padding of an element. Padding values cannot be negative.

Supported on block and replaced elements only.

Syntax

{ padding-left: length | percentage}

Remarks

This attribute is not inherited.

Applies To

TABLE, TD, TR, CAPTION, TEXTAREA, IFRAME, BODY, MARQUEE, DIV

Scripting Property

paddingLeft

See Also

padding-top, padding-bottom, padding-right, padding


padding-right

Description

Sets the right padding of an element. Padding values cannot be negative.

Supported on block and replaced elements only.

Syntax

{ padding-right: length | percentage}

Remarks

This attribute is not inherited.

Applies To

TABLE, TD, TR, CAPTION, TEXTAREA, IFRAME, BODY, MARQUEE, DIV

Scripting Property

paddingRight

See Also

padding-top, padding-left, padding-bottom, padding


padding-top

Description

Sets the top padding of an element. Padding values cannot be negative.

Supported on block and replaced elements only.

Syntax

{ padding-top: length | percentage}

Remarks

This attribute is not inherited.

Applies To

TABLE, TD, TR, CAPTION, TEXTAREA, IFRAME, BODY, MARQUEE, DIV

Scripting Property

paddingTop

See Also

padding-bottom, padding-left, padding-right, padding


page-break-after

Description

Indicates where to set a page break and on which page (left or right) the subsequent content should resume.

Syntax

{ page-break-after: auto | always | left | right}

Remarks

The values are defined as follows:

auto
Insert a page break after the element only if necessary.
always
Always insert a page break after the element.
left
Insert one or two page breaks after the element until a blank left page is reached.
right
Insert one or two page breaks after the element until a blank right page is reached.

If there are conflicts between page-break-after and the page-break-before value on the previous element (as formatted on the canvas), the value that results in the largest number of page breaks will be used.

This attribute is not inherited.

Example

In the following example, a hard page break is inserted in the document with the BR tag.

<STYLE>
    BR.page { page-break-after: always }
</STYLE>
  ...
<BR CLASS=page>
  ...

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, UL, XMP

Scripting Property

pageBreakAfter


page-break-before

Description

Indicates where to set a page break and on which page (left or right) the subsequent content should resume.

Syntax

{ page-break-before: auto | always | left | right}

Remarks

The values are defined as follows:

auto
Insert a page break before the element only if necessary.
always
Always insert a page break before the element.
left
Insert one or two page breaks before the element until a blank left page is reached.
right
Insert one or two page breaks before the element until a blank right page is reached.

If there are conflicts between this property and the page-break-after value on the next element (as formatted on the canvas), the value that results in the largest number of page breaks will be used.

This attribute is not inherited.

Example

In the following example, a page break is inserted in the document before all H1 elements.

<STYLE>
    H1 { page-break-before: always }
</STYLE>
  ...
<H1 CLASS=chapter>
  ...

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, UL, XMP

Scripting Property

pageBreakBefore


position

Description

Specifies the type of positioning for an element. The initial state is static, which means no special positioning and simply obeys the layout rules of HTML.

Syntax

{ position: absolute | relative | static}

Remarks

An absolutely positioned element is always relative to either the next positioned parent or, if there isn't one, the BODY by default. Values for left and top are relative to the upper-left corner of the next positioned element in the hierarchy.

This attribute is not inherited.

Examples

To place an image at the top left corner of the document, set the attributes to 0.

<IMG SRC="sample.gif" STYLE="position:absolute; left:0; top:0">

Setting an absolute position pulls the element out of the "flow" of the document and positions it irrespective of the layout of surrounding elements. If other elements already occupy the given position, they do not affect the positioned element, nor does the positioned element affect them. Instead, all elements are drawn at the same place, causing the objects to overlap. You can control this overlap by using the z-index attribute.

Setting the CSS position attribute to relative places the element in the natural HTML flow of the document but offsets the position of the element based on the preceding content. For example, placing a piece of text within a paragraph with relative positioning will render the text relative to the text in the paragraph that precedes it.

<p>The superscript in this name<SPAN STYLE="position: relative; top:-3px">xyz</SPAN> is "xyz".

Text and elements that follow a relatively positioned element occupy their own space and do not overlap the natural space for the positioned element. Contrast this with an absolutely positioned element, where subsequent text and elements occupy what would have been the natural space for the positioned element before the positioned element was pulled out of the flow.

See Positioning for an overview on how to use dynamic positioning.

Be sure to note the Applies To listings for elements that can be relatively and absolutely positioned.

Applies To

For position:absolute

TABLE, INPUT, SELECT, TEXTAREA, INPUT type=button, DIV, SPAN, OBJECT, APPLET, EMBED, IFRAME, IMG, HR, MARQUEE, FIELDSET

For position:relative

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

position

See Also

top, left, height, width, z-index


text-align

Description

Describes how text is aligned within the element.

Since this property is inherited, all block-level elements inside the DIV element with CLASS=center will be centered.

Syntax

{ text-align: left | right | center | justify}

Remarks

This attribute is inherited.

Example

The following example centers the text.

DIV.center { text-align: center }

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP

Scripting Property

textAlign


text-decoration

Description

Describes decorations that are added to the text of an element.

Syntax

{ text-decoration: none | [ underline || overline || line-through || blink]}

Remarks

Internet Explorer 4.0 supports the keyword blink, but does not render the blink effect.

If the element has no text (for example, the IMG element in HTML) or is an empty element (for example, <EM> </EM>"), this property has no effect.

This attribute is not inherited.

Example

This example would underline the text of all links in all states of navigation.

A:link, A:visited, A:active, A:hover { text-decoration: underline }

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

textDecoration, textDecorationLineThrough, textDecorationOverline, textDecorationUnderline


text-indent

Description

Specifies the indent that appears before the first formatted line. This property can be negative. An indent is not inserted in the middle of an element that was broken by another (such as BR in HTML).

Syntax

{ text-indent: length | percentage}

Remarks

This attribute is inherited.

Example

This example indents text by 3 ems.

P { text-indent: 3em }

Applies To

BLOCKQUOTE, BODY, CENTER, DD, DIR, DIV, DL, DT, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, TABLE, TD, TH, TR, UL, XMP

Scripting Property

textIndent


text-transform

Description

Changes the rendering of text.

Syntax

{ text-transform: capitalize | uppercase | lowercase | none}

Remarks

The values are defined as follows:
capitalize | Transforms the first character of each word to uppercase.
uppercase | Transforms all the characters to uppercase characters.
lowercase | Transforms all the characters to lowercase characters.

This attribute is inherited.

Example

This example puts H1 elements in uppercase text.

H1 { text-transform: uppercase }

Applies To

A, ADDRESS, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text

Scripting Property

textTransform


top

Description

Specifies the position of the element relative to the top of the document.

Syntax

{ top: length | percentage | auto}

Remarks

Used with the position attribute.

This value corresponds to the offsetTop property of the element, and does not include the border of the parent element (noteworthy for the BODY that draws the border inside the client region). auto is the default position of the element according to the regular HTML layout of the page. Percentage values are based on the parent's position.

This attribute, like all other CSS attributes, specifies a string value. When scripting the top property, use either the pixelTop or posTop property for numeric manipulation of a top value.

This attribute is not inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TEXTAREA, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

top

See Also

width, height, left, posTop, pixelTop


vertical-align

Description

Affects the vertical positioning of the element. The sub value vertically aligns as subscript. The super value vertically aligns as superscript.

Syntax

{ vertical-align: sub | super }

Example

This example aligns the text as subscript.

SPAN.subscript { vertical-align: sub }

Applies To

CAPTION, COL, IMG, SPAN,TBODY, TABLE, TD, TH, THEAD, TFOOT, TR

This attribute is not inherited.

Scripting Property

verticalAlign


visibility

Description

Indicates whether the content of a positioned element is displayed.

Syntax

{ visibility: visible | hidden | inherit}

Remarks

Unlike display:none, elements that are not visible still reserve the same physical space in the content layout as they would if they were visible. Changing the visibility through scripting is useful for showing and hiding content based on a user interaction. Note that for a child element to be visible, the parent element must also be visible. See Dynamic Styles for document style scripting information.

This attribute is not inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, EMBED, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HR, HTML, I, IFRAME, IMG, INPUT, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OBJECT, OL, P, PRE, S, SAMP, SELECT, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TEXTAREA, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, INPUT type=checkbox, INPUT type=radio, INPUT type=image

Scripting Property

visibility

See Also

display


visited

Description

Sets the style of anchor (A) elements for previously visited links.

Remarks

The visited pseudo-class is often used in conjunction with others to define the various states of a link: active, link, and hover.

When the mouse is over a hyperlink to which the visited style has been applied, the hover pseudo-class takes precendence.

Using pseudo-classes on elements other than the A element has no effect.

Example

The following code sets unvisited links to red and visited links to blue. The example below uses a colon (:) to specify a pseudo-class.

A:link   { color: red }           /* unvisited link */
A:visited  { color: blue }       /* visited links */

Applies To

A

See Also

active, hover, link


width

Description

Specifies the width of the element. DIV and SPAN cannot be positioned unless a width is provided. Percentage values are based on the width of the parent element.

Syntax

{ width: length | percentage | auto}

Remarks

The width attribute, like all other CSS attributes, specifies a string value. When scripting the width property, use either the pixelWidth or posWidth property for numeric manipulation of a width value.

This attribute is not inherited.

Applies To

APPLET, DIV, EMBED, FIELDSET, HR, IFRAME, IMG, INPUT, INPUT type=button, MARQUEE, OBJECT, SELECT, SPAN, TABLE, TEXTAREA

Scripting Property

width

See Also

height, left, position, top


z-index

Description

Specifies the stacking order of positioned elements.

Syntax

{ z-index: integer | auto }

Remarks

By default (auto), the stacking order is bottom-to-top in the order that they appear in the HTML source. Positive z-index values are positioned above a negative (or lesser value) z-index. Two elements with the same z-index are stacked according to source order.

This attribute is not inherited.

Applies To

A, ADDRESS, APPLET, B, BIG, BLOCKQUOTE, BODY, CAPTION, CENTER, CITE, CODE, COL, COLGROUP, DD, DFN, DIR, DIV, DL, DT, EM, FIELDSET, FORM, H1, H2, H3, H4, H5, H6, HTML, I, INPUT, INPUT type=button, INPUT type=file, INPUT type=reset, INPUT type=submit, INPUT type=text, TEXTAREA, KBD, LABEL, LEGEND, LI, LISTING, MARQUEE, MENU, OL, P, PLAINTEXT, PRE, S, SAMP, SMALL, SPAN, STRIKE, STRONG, SUB, SUP, TABLE, TBODY, TD, TFOOT, TH, THEAD, TR, TT, U, UL, VAR, XMP

Scripting Property

zIndex

See Also

position


Additional References Additional References *
  * Previous Topic: z-index
  * Next Topic: Color Table

Additional References

Color Table

Tips and Tricks


Color Table

This section lists and displays the colors supported by Microsoft® Internet Explorer 4.0.

You can specify colors in two ways—by using a color name, or by using numbers to denote a red-green-blue (RGB) color value.

In Internet Explorer 4.0, the supported colors appear as follows.

ALICEBLUE
(#F0F8FF) 		ANTIQUEWHITE
(#FAEBD7) 		AQUA
(#00FFFF) 		AQUAMARINE
(#7FFFD4)
AZURE
(#F0FFFF) 		BEIGE
(#F5F5DC) 		BISQUE
(#FFE4C4) 		BLACK
(#000000)
BLANCHEDALMOND
(#FFEBCD) 		BLUE
(#0000FF) 		BLUEVIOLET
(#8A2BE2) 		BROWN
(#A52A2A)
BURLYWOOD
(#DEB887) 		CADETBLUE
(#5F9EA0) 		CHARTREUSE
(#7FFF00) 		CHOCOLATE
(#D2691E)
CORAL
(#FF7F50) 		CORNFLOWER
(#6495ED) 		CORNSILK
(#FFF8DC) 		CRIMSON
(#DC143C)
CYAN
(#00FFFF) 		DARKBLUE
(#00008B) 		DARKCYAN
(#008B8B) 		DARKGOLDENROD
(#B8860B)
DARKGRAY
(#A9A9A9) 		DARKGREEN
(#006400) 		DARKKHAKI
(#BDB76B) 		DARKMAGENTA
(#8B008B)
DARKOLIVEGREEN
(#556B2F) 		DARKORANGE
(#FF8C00) 		DARKORCHID
(#9932CC) 		DARKRED
(#8B0000)
DARKSALMON
(#E9967A) 		DARKSEAGREEN
(#8FBC8B) 		DARKSLATEBLUE
(#483D8B) 		DARKSLATEGRAY
(#2F4F4F)
DARKTURQUOISE
(#00CED1) 		DARKVIOLET
(#9400D3) 		DEEPPINK
(#FF1493) 		DEEPSKYBLUE
(#00BFFF)
DIMGRAY
(#696969) 		DODGERBLUE
(#1E90FF) 		FIREBRICK
(#B22222) 		FLORALWHITE
(#FFFAF0)
FORESTGREEN
(#228B22) 		FUCHIA
(#FF00FF) 		GAINSBORO
(#DCDCDC) 		GHOSTWHITE
(#F8F8FF)
GOLD
(#FFD700) 		GOLDENROD
(#DAA520) 		GRAY
(#808080) 		GREEN
(#008000)
GREENYELLOW
(#ADFF2F) 		HONEYDEW
(#F0FFF0) 		HOTPINK
(#FF69B4) 		INDIANRED
(#CD5C5C)
INDIGO
(#4B0082) 		IVORY
(#FFFFF0) 		KHAKI
(#F0E68C) 		LAVENDER
(#E6E6FA)
LAVENDERBLUSH
(#FFF0F5) 		LAWNGREEN
(#7CFC00) 		LEMONCHIFFON
(#FFFACD) 		LIGHTBLUE
(#ADD8E6)
LIGHTCORAL
(#F08080) 		LIGHTCYAN
(#E0FFFF) 		LIGHTGOLDENRODYELLOW
(#FAFAD2) 		LIGHTGREEN
(#90EE90)
LIGHTGREY
(#D3D3D3) 		LIGHTPINK
(#FFB6C1) 		LIGHTSALMON
(#FFA07A) 		LIGHTSEAGREEN
(#20B2AA)
LIGHTSKYBLUE
(#87CEFA) 		LIGHTSLATEGRAY
(#778899) 		LIGHTSTEELBLUE
(#B0C4DE) 		LIGHTYELLOW
(#FFFFE0)
LIME
(#00FF00) 		LIMEGREEN
(#32CD32) 		LINEN
(#FAF0E6) 		MAGENTA
(#FF00FF)
MAROON
(#800000) 		MEDIUMAQUAMARINE
(#66CDAA) 		MEDIUMBLUE
(#0000CD) 		MEDIUMORCHID
(#BA55D3)
MEDIUMPURPLE
(#9370DB) 		MEDIUMSEAGREEN
(#3CB371) 		MEDIUMSLATEBLUE
(#7B68EE) 		MEDIUMSPRINGGREEN
(#00FA9A)
MEDIUMTURQUOISE
(#48D1CC) 		MEDIUMVIOLETRED
(#C71585) 		MIDNIGHTBLUE
(#191970) 		MINTCREAM
(#F5FFFA)
MISTYROSE
(#FFE4E1) 		MOCCASIN
(#FFE4B5) 		NAVAJOWHITE
(#FFDEAD) 		NAVY
(#000080)
OLDLACE
(#FDF5E6) 		OLIVE
(#808000) 		OLIVEDRAB
(#6B8E23) 		ORANGE
(#FFA500)
ORANGERED
(#FF4500) 		ORCHID
(#DA70D6) 		PALEGOLDENROD
(#EEE8AA) 		PALEGREEN
(#98FB98)
PALETURQUOISE
(#AFEEEE) 		PALEVIOLETRED
(#DB7093) 		PAPAYAWHIP
(#FFEFD5) 		PEACHPUFF
(#FFDAB9)
PERU
(#CD853F) 		PINK
(#FFC0CB) 		PLUM
(#DDA0DD) 		POWDERBLUE
(#B0E0E6)
PURPLE
(#800080) 		RED
(#FF0000) 		ROSYBROWN
(#BC8F8F) 		ROYALBLUE
(#4169E1)
SADDLEBROWN
(#8B4513) 		SALMON
(#FA8072) 		SANDYBROWN
(#F4A460) 		SEAGREEN
(#2E8B57)
SEASHELL
(#FFF5EE) 		SIENNA
(#A0522D) 		SILVER
(#C0C0C0) 		SKYBLUE
(#87CEEB)
SLATEBLUE
(#6A5ACD) 		SLATEGRAY
(#708090) 		SNOW
(#FFFAFA) 		SPRINGGREEN
(#00FF7F)
STEELBLUE
(#4682B4) 		TAN
(#D2B48C) 		TEAL
(#008080) 		THISTLE
(#D8BFD8)
TOMATO
(#FF6347) 		TURQUOISE
(#40E0D0) 		VIOLET
(#EE82EE) 		WHEAT
(#F5DEB3)
WHITE
(#FFFFFF) 		WHITESMOKE
(#F5F5F5) 		YELLOW
(#FFFF00) 		YELLOWGREEN
(#9ACD32)

User-Defined System Colors:

ACTIVEBORDER | ACTIVECAPTION | APPWORKSPACE | BACKGROUND
BUTTONFACE | BUTTONHIGHLIGHT | BUTTONSHADOW | BUTTONTEXT
CAPTIONTEXT | GRAYTEXT | HIGHLIGHT | HIGHLIGHTTEXT
INACTIVEBORDER | INACTIVECAPTION | INACTIVECAPTIONTEXT | INFOBACKGROUND
INFOTEXT | MENU | MENUTEXT | SCROLLBAR
THREEDDARKSHADOW | THREEDFACE | THREEDHIGHLIGHT | THREEDLIGHTSHADOW
THREEDSHADOW | WINDOW | WINDOWFRAME | WINDOWTEXT

Note These color names might not be recognized by other browsers, but the RBG color values should be displayed accurately.

An RGB color value consists of three two-digit hexadecimal numbers, with each number specifying the intensity of the corresponding color. For example, the color value #FF0000 is red because the red number is set to its highest value, FF (255 in the decimal, or base 10, system). Green and blue are set to zero. Similarly, #00FF00 is green and #0000FF is blue. The pound sign (#) is optional. In the following example, the HTML code displays a red horizontal rule.

<HR COLOR="#FF0000">

Although RGB color values theoretically allow for many thousands of colors, the actual number of colors available for your HTML document depends on the color capabilities of the devices the document will be viewed on. Many personal computers can display only 16 colors due to the type of video display adapter they use. Always choose colors carefully and, whenever possible, test your color choices on a variety of computers.


Tips and Tricks

As with any type of programming, writing bug-free, efficient scripts that meet your expectations takes a bit of work. The following sections provide some tips and hints to make that work take less time and go more smoothly.

Checking the Internet Explorer Version Number

Canceling a Button Click

Preventing a Document From Being Cached

Using Objects

Replacing Custom Controls with Dynamic HTML

Checking the Internet Explorer Version Number

Your scripts should always check the version of the client browser so as to degrade gracefully if the browser does not support the new features of Internet Explorer version 4. The easiest way to identify whether the browser is Internet Explorer and determine its version number is to use the following JScript function:

function msieversion()
// return Microsoft Internet Explorer (major) version number, or 0 for others.
// This function works by finding the "MSIE " string and extracting the version number
// following the space, up to the decimal point for the minor version, which is ignored.
{
    var ua = window.navigator.userAgent
    var msie = ua.indexOf ( "MSIE " )
    if ( msie > 0 )        // is Microsoft Internet Explorer; return version number
        return parseInt ( ua.substring ( msie+5, ua.indexOf ( ".", msie ) ) )
    else
        return 0    // is other browser
}

This function runs on the large majority of browsers and returns the major version number for any Microsoft Internet Explorer browser, or zero for all other browsers. Use of this function assures that the script will be compatible with future versions of Internet Explorer.

Scripts should always check version numbers greater than or equal so as to be compatible with future versions. Existing scripts that check for userAgent equal to "MSIE 3" should be changed to check the version correctly so that these scripts will recognize Internet Explorer 4.0 which supports all of the functionality of the previous version.

The following example shows how to correctly check the client browser version.

if ( msieversion() >= 4 )
    document.alert( "This is IE4 or later - safe to use all IE4 features" )
else if ( msieversion() >= 3 )
    document.alert( "This is IE3 - safe to use ActiveX" )
else
    document.alert( "This is not IE" )

Canceling a Button Click

The following HTML example shows a common scripting mistake related to event handling and canceling the default action.

<HTML>
<HEAD><TITLE>Canceling the Default Action</TITLE>
<SCRIPT LANGUAGE="JScript">
function askConfirm() {
    return window.confirm ("Choose OK to follow hyperlink, Cancel to not.")
}
</SCRIPT>

<BODY onload="b3.onclick=askConfirm">
<!-- Try links with different hookups - should be canceled by "Cancel" to confirm dialog. -->

<BR><A NAME=b1 HREF="http://www.microsoft.com" onclick="askConfirm()">1 Without return (won't work)</A>

<BR><A NAME=b2 HREF="http://www.microsoft.com" onclick="return askConfirm()">2 With return (works)</A>

<BR><A NAME=b3 HREF="http://www.microsoft.com">3 Function pointer (works)</A>

</BODY>
</HTML>

The first A element in this example does not work properly. Without the return in the onclick JScript expression, the browser interprets the function expression, throws away the resulting value (this is just a statement consisting of an expression, no assignment, an so on), and leaves the default action unaffected.

The other A elements correctly bind the return value to the event, hence the default action can be canceled when false is returned.

Preventing a Document From Being Cached

You can prevent a document from being cached by adding the following META tag to the document.

<META HTTP-EQUIV="Expires" CONTENT="0">

Preventing the document from being cached ensures that a fresh copy of the document will always be retrieved from the site, even during the user's current session, regardless of how the user has set his browser's caching options. This is useful if the content of the document changes frequently.

Using Objects

Objects are ActiveX controls or other similar components that provide custom capabilities and services for HTML documents. You can add a control to your document by using the OBJECT element, and gain access to the capabilities and services of the control by using its properties and methods from script.

When using objects, be aware that Dynamic HTML extends every object by providing these additional properties:
align BaseHref
classid code
codeBase codeType
data form
height name
object recordset
type width

If a control has properties with these same names, you will not be able to access the properties unless you preface the name with the object property. For example, assume that an ActiveX control is added to the document by using the following.

<OBJECT ID="MyControl" HEIGHT=100 WIDTH=200 CLASSID="clsid: ... ">
</PARAM NAME="width" VALUE="400">
</OBJECT>

In this example, there are two widths: an extended property set within the OBJECT element, and a property belonging to the control that is set using the PARAM element. To access these from script, you use the following code.

alert(MyControl.width);   // this is Dynamic HTML's property; displays "200"
alert(MyControl.object.width);  // this is the object's property; displays "400"

Replacing Custom Controls with Dynamic HTML

Dynamic HTML provides everything you need to generate animated effects without resorting to custom controls. For example, consider the following script, which is a replacement for the Path control.

var tickDuration;
tickDuration = 50;

var activeObjectCount;
var activeObjects;
var itemDeactivated;

var tickGeneration;

activeObjects = new Array();
activeObjectCount = 0;
timerRefcount = 0;
itemDeactivated = false;

tickGeneration = 0;

function initializePath(e) {
 e.waypointX = new Array();
 e.waypointY = new Array();
 e.duration = new Array();

}

function addWaypoint(e, number, x, y, duration) {
 e.waypointX[number] = x;
 e.waypointY[number] = y;
 e.duration[number] = duration;
}

function compact() {
  var i, n, c;

  n = new Array();
  c = 0;
  itemDeactivated = false;
  for (i=0; i<activeObjectCount; i++)  {
     if (activeObjects[i].active == true) {
        n[c] = activeObjects[i];
        c++;
     }
  }

  activeObjects = n;
  activeObjectCount = c;
}

function tick(generation) {

  if (generation < tickGeneration) {
    // alert("Error "+generation);
     return;
  }

  //alert("tick: "+generation);

  if (itemDeactivated)
     compact();

  if (activeObjectCount == 0) {
     return;
  }
  else {
    for (i=0; i<activeObjectCount; i++) {
      moveElement(activeObjects[i]);
    }

    window.setTimeout("tick("+generation+");", tickDuration);
  }
}

function start(e) {
  if (itemDeactivated)
     compact();

  activeObjects[activeObjectCount] = e;
  activeObjectCount++;

  if (activeObjectCount == 1) {
    tickGeneration++;
    tick(tickGeneration);
  }
}

function runWaypoint(e, startPoint, endPoint) {

  var startX, startY, endX, endY, duration;

  if (e.waypointX == null)
    return;

  startX = e.waypointX[startPoint];
  startY = e.waypointY[startPoint];
  endX = e.waypointX[endPoint];
  endY = e.waypointY[endPoint];

  duration = e.duration[endPoint];
  e.ticks = duration / tickDuration;

  e.endPoint = endPoint;
  e.active = true;
  e.currTick = 0;

  e.dx = (endX - startX) / e.ticks;
  e.dy = (endY - startY) / e.ticks;

  e.style.posLeft = startX;
  e.style.posTop = startY;

  start(e);
}

function moveElement(e) {
  e.style.posLeft += e.dx;
  e.style.posTop += e.dy;

  e.currTick++;

  if (e.currTick > e.ticks) {
    e.active = false;
    itemDeactivated = true;
    if (e.onpathcomplete != null) {
       window.pathElement = e;
       e.onpathcomplete()
    }
  }
}

To use this script in your document, do the following:

  1. Load the script by using the src attribute of the SCRIPT element.
  2. Initialize the paths by using the initializePath function.
  3. Set the way points by using the addWaypoint function.
  4. Set the path-complete handlers, using the runWaypoint function.

The following sample document show how this works.

<html>

<body>

<div id=Item1 style="position: absolute; left: 0; top: 0;">Item1</div>
<div id=Item2 style="position: absolute; left: 0; top: 0;">Item2</div>
<div id=Item3 style="position: absolute; left: 0; top: 0;">Item3</div>
<div id=Item4 style="position: absolute; left: 0; top: 0;">Item4</div>
<div id=Item5 style="position: absolute; left: 0; top: 0;">Item5</div>
<div id=Item6 style="position: absolute; left: 0; top: 0;">Item6</div>

<input type=button value="Start" onclick="runWaypoint(Item1, 0, 1); runWaypoint(Item2, 0, 1);">
<div id=Debug>Generation</div>

<script src="htmlpath.js">
</script>

<script>

// need to call initializePath on all objects that will be moved with this mechanism
initializePath(Item1);
initializePath(Item2);
initializePath(Item3);
initializePath(Item4);
initializePath(Item5);
initializePath(Item6);

// the 0th waypoint is the intial position for waypoint #1
// syntax is item, waypoint, endx, endy, duration in msecs
addWaypoint(Item1, 0, 0, 0, 0);
addWaypoint(Item1, 1, 200, 200, 2000);

addWaypoint(Item2, 0, 100, 100, 0);
addWaypoint(Item2, 1, 400, 100, 4000);

addWaypoint(Item3, 0, 400, 400, 0);
addWaypoint(Item3, 1, 200, 100, 1000);

addWaypoint(Item4, 0, 0, 0, 0);
addWaypoint(Item4, 1, 200, 200, 2000);

addWaypoint(Item5, 0, 100, 100, 0);
addWaypoint(Item5, 1, 400, 100, 4000);

addWaypoint(Item6, 0, 400, 400, 0);
addWaypoint(Item6, 1, 200, 100, 1000);

function endfunction() {
  // syntax for runWaypoint is Item, start point, end point
  runWaypoint(Item3, 0, 1);
  runWaypoint(Item4, 0, 1);
  runWaypoint(Item5, 0, 1);
  runWaypoint(Item6, 0, 1);

}

function endfunction2() {
  runWaypoint(Item1, 0, 1);
}

Item1.onpathcomplete = endfunction;
Item6.onpathcomplete = endfunction2;

</script>
</body>
</html>


DHTML Tutorials

Following is a list of articles that walk you, step by step, through the implementation of common Web authoring tasks using Dynamic HTML. Each article ends with a pointer to a sample demonstrating the technique just described, as well as links to related topics. Familiarity with a scripting language, preferrably JScript or VBScript, and its programming concepts is recommended.

How to Fly Text
Make text fly across your page either with the help of a MARQUEE control or by manipulating its position directly through CSS positioning. This article demonstrates both ways of flying text vertically or horizontally on a page.

How to Fly Text in Geometric Patterns
Learn step by step how to fly text diagonally across the page. This article introduces the sophisticated CSS (cascading style sheets) positioning capabilities of Microsoft® Internet Explorer 4.0.

How to Fly Text Through an Oval Path
Fly your text through an oval path with very few lines of code, using the DirectAnimation™ path control. The article describes how simply specifying a target object to be moved causes the path control to move the object around the page over time, in a geometric pattern.

How to Animate a Sequence of Elements
Make your page come alive with animation. The article describes how a series of elements displayed sequentially on a page over a timer or on a mouse click brings life to a slide show presentation.

How to Apply a Transition on an Image
Implement fast and easy visual effects on your pages with the help of transitions. This article teaches you how to apply transitions to an image with simple HTML and very minimal script.

How to Create a Dynamic Table of Contents
Use the power of CSS (cascading style sheets) to create a table of contents that expands and collapses in response to mouse clicks. This article demonstrates how to reassign style sheets on the fly in order to display or hide information on demand.

How to Change Text Color Character by Character
Add some flash to your pages by changing the colors of a group of objects at a set speed. This article models how to use JScript switch statements, timers, CSS (cascading style sheets), and HTML in creating this effect.

How to Manipulate Text Effects in Response to Mouse Events
Animate text using minimal scripting by following the steps presented in this article. The technique described, creating the mouseover highlight, provides an excellent introduction to using CSS (cascading style sheets).


JScript & VBScript Tutorials and References JScript & VBScript Tutorials and References *
  * Previous Topic: DHTML Tutorials
  * Next Topic: Multimedia

JScript & VBScript Tutorials and References

JScript Tutorial

JScript Language Reference

VBScript Tutorial

VBScript Language Reference


Multimedia

DirectAnimation is a set of multimedia controls and scripting methods that animate Web pages and provide integration with Dynamic HTML. DirectAnimation has comprehensive support for media types such as 2-D vector graphics, images and sprites, 3-D geometry, video, and sound.

The DirectAnimation controls provide access to many of the DirectAnimation scripting functions and libraries. These controls allow you to deliver impressive vector graphics, image, and animation content over the Web with little code and short download times.

The DirectAnimation controls consist of the following:

Path Control Move objects around the page over time using splines, geometric primitives, text outlines or shapes that change dynamically over time with control over speed of motion, looping, forward or reverse playback, and bouncing behavior.

Sequencer Control Create complex sequences of action involving ActiveX™ controls, scripts, or dynamic HTML elements.

Sprite Control Add still and animated images to your Web page with control over playback speed, forward or reverse playback, dynamic seeking to different positions in the sprite playback, and user interactivity on a frame-by-frame basis.

Structured Graphics Control Add extremely lightweight vector graphics to your Web page, fully capable of being scaled or rotated in three dimensions, and then easily apply solid colors, patterns, gradient fills or bitmap textures to these graphics.

To see reference documentation for each DirectAnimation control, click here.

DirectAnimation can be accessed in different ways by different user groups. HTML authors can integrate multimedia using the DirectAnimation controls. Web authors can add animations (3-D, movies, sound, etc.) using JScript, VBScript, or Java.

The Microsoft DirectAnimation SDK provides documentation, samples, and tutorials to help users get up and running with DirectAnimation. The Exercises and Templates sections of the samples contain many small, simple scripting examples that perform one animation task and can be cut and pasted. For example, HWorldJS.htm demonstrates basic text animation as a windowless control. Crop.htm demonstrates a cropped animated image that overlays a variation of itself. Clrswtch.htm demonstrates using Visual Basic buttons to color an animation. DanTrapz.htm demonstrates rectangles with time-varying colors that chase each other along a path.


Samples and Tools

Samples

The following samples demonstrate various features of Dynamic HTML.

Dynamic Styles Demonstrates an example of Dynamic Styles. Change text colors, font styles, visibility, and even cursors without refreshing the page!

Dynamic Content Demonstrates an example of Dynamic Content. Stay up-to-the-minute with a DHTML clock. Change the text on the page with the click of a mouse.

Positioning

  • Position Demonstrates 2-D layering of moving images with a mouse.
  • Asteroids You want interactivity? You've got it with a fully functional Dynamic HTML version of Asteroids! This demonstration takes advantage of positioning and JScript to deliver shoot-em-up action.

Centering Demonstrates centering an object within a division on the page.

Resizing

  • Sample1 Demonstrates various samples of resizing capabilities.
  • Sample2 Demonstrates the resizing of div, image, and text.

Image Switches images using preloaded images.

Domain Illustrates accessing a second-tier domain in an IFRAME.

Replacing Custom Controls with Dynamic HTML

  • Path Demonstrates how to replace the path control through the use of scripting.
  • Pop-up Menu Demonstrates how to create a pop-up menu through the use of Dynamic HTML.

DirectAnimation Controls

  • MMAudio Illustrates mixing several .wav files.
  • Structured Graphics Control
    • MMSGX Demonstrates how to use a structured graphic control.
    • Surface Shows how the DirectAnimation DrawingSurface API is used to create a single vector shape with independent internal and external rotations.
  • Path Control
    • Tricycle Shows a sprite control on a path, and allows you to control its behavior.
  • Sprite Control
    • Sprite Demonstrates the ability to add still and animated images on your Web page, with control over frames per second, forward or reverse playback, or dynamic reading of source files.
    • Banner Demonstrates the ability to use the sprite control as a clickless control for a banner-type advertisement.
    • Concentrate Demonstrates the ability to use the sprite control to contain images for this match game.
    • Swapgame Demonstrates the ability to use the sprite control to contain images for puzzle-type games.
  • Sequencer Control
    • Sequencer-JScript Demonstrates how to use the sequence control through JScripting.
    • Sequencer-VBScript Demonstrates how to use the sequence control through VBScripting.

Filters and Transitions

  • Filters
    • Filters Demonstrates the different filters.
  • Transitions
    • Transitions Demonstrates the different transitions.
    • Blend Transition Demonstrates the blend transition.

Tools

Tools for Debugging Scripts

  • Microsoft Script Debugger for Internet Explorer

Wizards for Generating Simple Filters and Transitions Pages

  • Filter Wizards
    • Filters Wizard HTML-based wizard that generates working code for the different filters, based on the parameters entered by the user.
    • Wave Filter Wizard HTML-based wizard that generates working code for the wave filter, based on the parameters entered by the user.
    • Light Filter Wizard HTML-based wizard that generates working code for the light filter, based on the parameters entered by the user.
  • Transitions Wizard
    • Transitions Wizard HTML-based wizard that generates basic code for the different transitions, based on the parameters entered by the user.

CSS Syntax Validation Tool

  • StyleT 2.0 Guide Provides information on the StyleT 2.0 Test Tool. This test tool performs a series of tests to ensure that the syntax of the files matches the CSS Specification. StyleT.htm is available in the \bin directory of the Internet Client SDK installation.

Wizards for Generating Simple DirectAnimation Control Pages

  • Path Wizard HTML-based wizard that generates working code for moving an object around, based on the parameters entered by the user.
  • Graphics HTML-based wizard that generates working code (for the Structured Graphics and Sequencer controls) that produces a rotating text logo, based on the parameters entered by the user.


Cross-Platform Functionality

With Internet Explorer 4.0, content authors can easily create pages that run on all platforms—the 32-bit Windows® platforms, Windows 3.1, Macintosh®, and Unix. In particular, core Dynamic HTML (DHTML) and Active Channel functionality are cross-platform.

The following DHTML features are supported across platforms:

  • Full CSS 1 Core
  • CSS—Positioning
  • DHTML—Dynamic Styles
  • DHTML—Stylesheet Object Model
  • DHTML—Element Collection
  • DHTML—Event Model
  • DHTML—Core Dynamic Content: innerHTML, outerHTML, and associated methods
  • Data Binding
  • HTML 4 support
  • HTML dialogs

The following Active Channel functionality is supported across platforms:

  • General CDF support
  • Subscriptions, notification, offline reading

In addition, several features are available on some platforms, but will degrade gracefully on other platforms:

  • CSS Filters and Transitions. On some platforms, the filters and transitions may degrade to a basic filter or transition effect.
  • Font Download. If a platform does not support font download, the specified font will be substituted by another font already on the computer.
  • User Profile—Object Model. If a platform does not support this feature, it will appear as though the user has disabled it.

Win32 Premium Platforms

In addition to the cross-platform functionality, the versions of Internet Explorer 4.0 for the 32-bit Windows platforms (Windows 95, Windows 98, Windows NT®) support additional premium functionality, including:

  • Multimedia controls
  • DHTML—Extended Dynamic Content: the TextRange, Table object model, and associated methods
  • Data Binding—Remote Data Service
  • XML parser ActiveX control
  • Active Channels: page hit logging
  • Active Channels: display as screen saver
  • Active Channels: display as desktop component

In the future, support for the above features might be added to additional platforms based on customer demand.


Delivering Content to the Web

This section contains information on new ways Web publishers can deliver their content with Internet Explorer 4.0. Several new features using "push" technologies are explained, including Active Channels, Active Desktop items, and Software Update Channels.

Content Delivery Mechanisms

The User Experience

Authoring for New Delivery Mechanisms

CDF Reference

Tools


Content Delivery Mechanisms

The new technology delivered in Microsoft® Internet Explorer version 4.0 integrates HTML items such as Web pages, Java applets, ActiveX™ Controls, images, and floating frames into the user interface. When combined with support for Channel Definition Format (CDF) files, users can customize their desktop environment and have information on the Web automatically delivered directly to their desktop.

Web Site Content Arrives on the Active Desktop

New Ways to Display or Access Web Content

Web Site Content Arrives on the Active Desktop

Today, users don't see a Web site's content unless they intentionally visit that site. However, with the release of Internet Explorer 4.0, Web publishers can now broadcast their content directly to users' desktops on a continuing and increasingly personal basis. Web publishers can transform their Web site into a server that automatically broadcasts content to Active Channels on the desktop, just as a radio station broadcasts to a radio receiver. Active Channels are represented on the user's desktop with a logo button located in the desktop Channel Bar. When adding a channel to their desktop Channel Bar, users can configure channels to notify them of any updates to the channel and optionally have the Web pages automatically downloaded into their local cache for offline reading. Modifying a Web site to support Active Channels involves relatively minor additions to current production processes on existing Web sites, and no additional server software is required. Web content can also be broadcast to Active Desktop items, which allows users to display any HTML content directly on their desktop.

The content authoring options available in Internet Explorer 4.0 are designed to increase the visibility of content and to improve the user experience while viewing that content. Active Channels promote an enhanced user experience through depth, by providing a more personalized content experience than a browser currently offers. Active Desktop items promote the enhanced user experience through breadth, by giving users a way to pull together their favorite summarized Web content into a single desktop space. Therefore, Web publishers will want to author content for both mechanisms to provide maximum exposure of their Web sites. The additional exposure also helps Web publishers maintain an ongoing relationship with their users.

New Ways to Display or Access Web Content

Internet Explorer 4.0 introduces several new mechanisms Web publishers can use to present the content of their Web pages to users:

  • Active Channels
  • Active Desktop Items
  • Software Update Channels
  • HTML-based Web view of folders
  • Site subscriptions

Active Channels

Active Channels are Web sites that are described by a Channel Definition Format (CDF) file. Web sites offering their content as an Active Channel will be required to make a CDF file available on their Web server. The CDF file provides information about the contents of the channel, including titles, abstract descriptions, and images associated with each resource in the channel. In addition to defining the set of resources appearing in the channel, the CDF file also specifies how each item will be used or displayed and when the channel should be updated. Further information on channels and CDF files is available in Creating Active Channels and the CDF Reference for Active Channels.

Active Channel features include:

  • Desktop Channel Bar
  • Category folders
  • Update "gleams" and e-mail notifications
  • Full-screen view
  • Channels Explorer Bar
  • Channel screen savers
  • Page-hit logging

Desktop Channel Bar and category folders

A channel is represented by a branded logo button in the desktop Channel Bar. The desktop Channel Bar contains a list of logo images for all channels currently available on the user's desktop. This allows users to quickly launch the browser into a special full-screen view and load the channel's main HTML page by clicking the desired channel logo.

Desktop Channel Bar

Users can add a channel to their desktop Channel Bar by clicking an "Add Active Channel" button image placed on a publisher's Web page or in the channel guide. Microsoft maintains a list of channels that users can subscribe to or add to their Channel Bar in the channel guide.

In addition to the channel guide, category folders are provided to group together channels with similar topics. When users click an Add button, a dialog box is presented to allow them to add the channel to their Channel Bar and optionally subscribe to the channel.

Channel updates and notification

When adding a channel to the desktop Channel Bar, users select whether they want to just add the Active Channel to the Channel Bar, download the channel hierarchy (the CDF file), or download the hierarchy and all the channel content. If the user selects either the second or third option, Internet Explorer 4.0 monitors the channel for new information and automatically notifies the user that the channel has been updated. A red, asterisk-like "gleam" is placed on a channel logo to indicate an update has occurred. The user can also receive an optional e-mail notification when a channel is updated. To receive e-mail update notifications, users must enable this feature by clicking the Customize button on the Add Channel dialog box when adding the channel, or by changing the channel's properties after it is added.

Full-screen view and Channels Explorer Bar

When the user clicks a logo button in the Desktop Channel Bar, the content from that Web site is immediately displayed in full-screen view. If the user is viewing a subscribed channel (with downloaded content) while offline, the browser opens the most recent update of the channel's resources from the local cache. While full-screen view is active, a status bar and a toolbar with a small set of navigational controls are provided. Internet Explorer full-screen view can be enabled on any browser window by selecting the Full Screen option on the View menu or by clicking the Full Screen icon located in the standard toolbar. By default, a channel launched into full-screen view will also display the Channels Explorer Bar on the left side of the screen. This is an autohiding pane that displays the currently selected channel. Note that the currently selected channel logo is the only one displayed, and all other channel logos are replaced with the channel titles in black-and-white text. Placing the cursor over a nonselected channel causes the channel's logo to be displayed.

Channels Explorer Bar

The Channels Explorer Bar also helps users navigate through a channel's content by acting as a sitemap for the channel. The CDF file hierarchy is exposed through this view, if one exists for the channel. The currently selected channel hierarchy contracts when a user clicks a different channel in the Channels Explorer Bar, and the newly selected channel's hierarchy is expanded. Some channels might not have a hierarchy to display in this pane, in which case the logo is the only item shown.

Screen savers

Web publishers can specify an HTML page in a CDF file to be used as screen saver content. This page is displayed in the Channel Screen Saver included with Internet Explorer 4.0. Each installed channel's screen saver page displays in rotation until the user presses a key or clicks the autohidden Close button in the upper-right corner of the screen. However, the Channel Screen Saver must be enabled by the user before any screen saver content specified in the CDF file will be displayed. If the Channel Screen Saver is not enabled, users are prompted with a dialog box to enable it when subscribing to a channel that contains a screen saver item.

The following is an example of an HTML-based Channel Screen Saver.

HTML-based Channel Screen Saver

By default, moving the mouse doesn't close the screen saver because there may be content or links on the screen saver page that users might want to access. Users can change this behavior by accessing the Screen Saver tab in the Display Properties dialog box and selecting the appropriate option.

Page-hit logging

Internet Explorer 4.0 helps Web publishers better understand the users who visit their sites by providing reliable feedback. When connecting to a Web server to update an Active Channel or Active Desktop item, the page-hit logging feature can be enabled to report the viewing of the channel's pages, including offline browsing. However, Microsoft protects users' privacy with the Profile Assistant. This standards-based feature allows the user to specify exactly what type of demographic information, if any, can be sent back to a Web server.

Note The Profile Assistant can also be used with regular (nonchannel) HTML pages. Page-hit logging only applies to Web content using a CDF file, such as an Active Channel or an Active Desktop Item.

Active Desktop Items

Internet Explorer 4.0 introduces the Active Desktop, which provides you with the ability to include HTML documents and items, such as Java applets or ActiveX Controls, directly on the desktop. This allows users to create a highly customized desktop that contains their favorite updated Web content. Users can add items to the Active Desktop in one of three ways:

  • Clicking an "Add to Active Desktop" button provided on a Web page.
  • Accessing the Web tab in the Display Properties Control Panel, and selecting the "New..." button.
  • Using the right mouse button to drag an HTML icon from the Internet Explorer address or title bar and drop it on the desktop. Once the icon is positioned, select "Create Active Desktop item here" from the context menu.

Because the Active Desktop uses HTML, items can be created using any technique or technology supported by the Internet Explorer browser, including images, Dynamic HTML, ActiveX Controls, Java applets, scripting, and multimedia filters and transitions. This means that Web publishers can leverage what they already know to begin publishing information to the Active Desktop. For more information about desktop items, see Creating Items for the Active Desktop.

Software Update Channels

Software developers can use this new mechanism to automatically deliver their software updates on the Web. Software Update Channels require three major components: a CDF file, an Open Software Description (OSD) file, and a distribution unit. Users subscribing to these channels will receive notifications when the software update is available and can choose to have the software automatically downloaded and installed.

HTML-Based Web View of Folders

The release of Internet Explorer 4.0 extends the original folder views in Windows 95 (Large Icons, Small Icons, List, and Details) with a new HTML-based viewing mode. This mode allows any folder to be represented as a Web page. Therefore, users can create custom HTML files to view file systems containing more graphical and interactive content, such as images and animations, through Java applets, ActiveX Controls, and Dynamic HTML. Web publishers or software developers might want to supply the necessary HTML files in directories created for their products to display important information that is usually presented in a readme file. Viewing a folder as a Web page works on any folder containing an HTML file named Folder.htt and an associated Desktop.ini file. Internet Explorer 4.0 includes Folder.htt templates for some special folders, such as My Computer, Favorites, Control Panel, Printers, and History. Note that the My Computer and Control Panel folders cannot be customized.

To create a Folder.htt file for any directory, bring up the context menu in a directory by clicking the right mouse button and selecting the "Customize this folder..." option. Now select the first option, "Create or edit an HTML document," and follow the steps provided in the wizard. A default Folder.htt file is provided for you to edit. Once this process is completed, the directory is viewed as an HTML page. To disable and re-enable this view at any time, users can toggle the "as Web Page" option in the View menu.

The following illustrates a Web view for Control Panel.

Web view for Control Panel

Site Subscriptions

A site subscription allows users to automatically download the content of any Web site (through site crawling), up to three levels deep, from the specified URL. If the local computer connects to the Internet by modem, the site subscriptions can be configured to automatically dial up and download Web pages without user intervention. Site subscriptions allow users to view the cached information from any Web site when they are offline. Note that Channel Bar logo buttons, Channels Explorer Bar sitemaps, page-hit logging, screen savers, and publisher-recommended update schedules are not available with site subscriptions because they don't have an associated CDF file.

When adding any Web page to the Internet Explorer favorites list, users will be prompted with the following dialog box asking if they want to subscribe to that site.

Add to Favorites Dialog

Web publishers can disable site crawling by Internet Explorer on any Web page by inserting the following line into the HEAD section of the page.

<META NAME="ROBOTS" CONTENT="NOFOLLOW">

To prevent Internet Explorer from crawling any pages on a Web site, a file named Robots.txt should be placed in the root directory of an HTTP server. This file should contain the lines:

User-Agent:MSIECrawler
Disallow:/path/

In this example, path is the name of the path that Internet Explorer should not site crawl. A path of "/" can be used to exclude all pages on the server. Note that "MSIECrawler" can be replaced with "*" to indicate that all automated crawling robots (including Internet Explorer) should be excluded.


The User Experience

The documents in this section describe the Microsoft® Internet Explorer 4.0 user interface elements for these content delivery mechanisms.

Active Channels

Active Desktop Items

Software Update Channels


Active Channels

This document describes how users interact with Active Channels for Microsoft® Internet Explorer 4.0. Details are provided on how users add and remove channels from their desktop, as well as how channel subscriptions are managed.

Introduction to Active Channels

Adding an Active Channel to the Desktop

Removing an Active Channel

Managing an Active Channel Subscription

Introduction to Active Channels

An Active Channel is a Web site described by a Channel Definition Format (CDF) file. The information contained in the CDF includes the hierarchy of the Web pages and resources available for that channel, as well as a schedule recommended by the Web publisher for updating the information in the channel. This document describes the user interface associated with Active Channels, including how users can manage their channels. CDF elements corresponding to a specific feature or user interface element are indicated where applicable. For demonstration purposes, the Internet Client SDK channel is used throughout this document. This channel is available by navigating to Channel Preview with Internet Explorer 4.0 and clicking the Add Active Channel button. Note that some of the images and text shown for this channel are subject to change.

Note Additional information on channels and CDF files is available in Content Delivery Mechanisms, Creating Active Channels, and the CDF Reference for Active Channels.


Adding an Active Channel to the Desktop

Microsoft® Internet Explorer 4.0 includes a special Active Desktop item called the desktop Channel Bar. This item contains the 32W x 80H logos for all channels currently available on the user's computer. The desktop Channel Bar appears on the right side of the desktop by default and is visible only when the Active Desktop is enabled. The user can enable the Active Desktop by right-clicking the desktop and selecting the View as Web Page option from the Active Desktop menu. The desktop Channel Bar is pre-populated with channels and category folders containing groups of channels on related topics. The channel guide appearing in the desktop Channel Bar (shown below) contains a list of Active Channels and is maintained by Microsoft.

Desktop Channel Bar

As the user moves the cursor onto a LOGO image in the desktop Channel Bar, the image is presented as a 3-D button and displays the channel's ABSTRACT description in a ToolTip, if one is specified in the CDF file.

Users can add channels from three sources—a publisher's Web page, the Channel Guide, and preinstalled channels in the desktop Channel Bar. While browsing a Web site or a category in the Channel Guide, the user will encounter a link or image button that can be clicked to add the Active Channel to the desktop Channel Bar and optionally subscribe to the channel. Information on how to place an Add Active Channel logo button is available in the Creating Active Channels documentation.

The Add Active Channel button is shown here.

Add Active Channel button

Invoking the Add Channel Dialog Box

Immediately after users click the Add Active Channel button, the Add Channel dialog box is displayed. This gives users three options for how the channel will be set up on their computer, as follows:

  • Add the channel to the Channel Bar.

    This option simply adds the channel to the desktop Channel Bar. When the user clicks the channel logo, the browser launches into full-screen view and loads the URL specified by the CHANNEL element in the CDF file. Adding a channel with this option is similar to creating a favorite. The user can view the channel while he or she is online, but no content is available for offline viewing, and the content is not updated on the user's computer. Therefore, users are not notified when changes occur on this site.

  • Subscribe to the channel, but only notify the user when updates occur.

    This option updates the channel's CDF file according to a schedule set by the publisher with the SCHEDULE element in the CDF file, unless overridden by the user with a custom schedule. The user is notified that content has been updated by a "gleam" placed over the logo in the desktop Channel Bar and on the icons representing the individual content items. A user can optionally be notified of changes through e-mail. With this option, the channel's navigable hierarchy, or sitemap, is available for offline viewing, if one exists. However, clicking any of the channel's content requires a connection to the Internet because the content wasn't previously downloaded into the cache.

  • Subscribe to the channel, download the content for offline viewing, and notify the user when updates occur.

    A channel with this option set will place the channel's sitemap (if one exists) and the actual content of the channel in the user's cache. Similar to the second option, this type of subscription is updated according to the publisher's schedule unless the user overrides it. Therefore, the user can browse through the entire channel at any time, even when not connected to the Internet, and view the latest information since the last channel update. However, some content may not be available for offline viewing if the publisher has specified the PRECACHE="No" attribute on one or more items.

The Add Active Channel dialog box is shown below.

Add Channel Dialog

Running the Channel Subscription Wizard

If a channel subscription is selected, the user can click the Customize button to run the channel Subscription Wizard. This allows the user to modify the settings for the channel subscription. The first dialog box allows the user to specify whether the entire contents referenced in the CDF file should be downloaded, or just the main channel page. If the user chooses the latter, clicking any item exposed in the sitemap other than the main channel page would require a connection to the Internet, as the resources will not be available in the local cache.

The channel Subscription Wizard content selection is shown below.

Channel Subscription Wizard Content

Next, the user can select how content update notifications will be handled. By default, Internet Explorer uses the visual "gleams" to indicate new content. However, e-mail notification can also be sent to the user when the content is updated.

Channel Subscription Wizard Notifications

The final property set in the channel customization wizard is the update schedule for the CDF file and/or content, depending on the type of subscription selected. The user can select either daily, weekly, monthly, or the publisher's recommended update schedule option. If no recommended schedule exists in the CDF file, the default schedule is "Daily".

Channel Subscription Wizard Schedule

If the user connects to the Internet through a modem, the user must check the "Dial as needed..." box to enable the automatically scheduled updates when the user is offline. Modem users who don't enable the "Dial as needed..." option will receive channel updates only if the update occurs while they are online. Channels can be manually updated at any time by performing one of the following actions:

  • Right-click the channel logo in the desktop Channel Bar and select Update Now.
  • Select the Manage Subscriptions option from the Favorites menu and either right-click the item and select Update Now, or click the Update or Update All button in the toolbar.

Viewing the Active Channel Content

At this point, the user will return to the original Add Channel dialog box presented after the initial Add Active Channel button was clicked. When the user clicks the OK button, the channel subscription is updated, if one exists, and the browser opens the channel in full-screen view, as shown below.

Full-Screen View with Channels Pane

The full-screen view of the browser includes a toolbar at the top of the screen with a smaller set of navigational controls and a status bar. The autohiding Channels Explorer Bar is displayed on the left side of the screen when the channel is initially loaded and whenever the user places the cursor at the left edge of the screen. On screens 1024 x 768 and larger, the Channels Explorer Bar is continuously displayed by default. This behavior can be achieved on smaller screens by clicking the "pin" icon in the right side of the bar. This disables the autohide feature until the pin is clicked again. Note that when viewing a channel in a normal browser window without full-screen view enabled, the Channels Explorer Bar does not autohide.

The ToolTip shown in the following picture is specified in the channel's CDF file using the ABSTRACT element, and it is displayed when the user pauses the mouse over that item.

Notice that the hierarchy of the channel just added is now expanded to show the first level of subchannels and items. Clicking a subchannel further expands the current channel hierarchy displayed in the sitemap to show its contents. The user can select any of these exposed items to navigate to the associated Web page, similar to using the Favorites menu. When the user selects a different channel, the previously selected channel hierarchy contracts in the channel pane, and the newly selected one expands to show any items and subchannels it contains. The Channels Explorer Bar also replaces the previous channel's logo with the title of the channel in plain text, and it now displays the logo of the newly selected channel. The first example below shows the user switching to the News and Technology category folder, and in the second example switching back to the Internet Client SDK channel.

Switching back to the first channel

Although the full-screen view shown above is the default viewing mode for Active Channels, users can navigate through a channel in a normal browser window. To toggle the full-screen view on or off, users can either click the Full Screen button located on the standard button toolbar or select Full Screen on the View menu.

The following illustrates the channel in normal view.

Channel in normal view

Active Channel Screen Savers

Channel publishers can designate Web pages as screen saver pages in CDF files by setting the VALUE="ScreenSaver" attribute on the USAGE element. These pages rotate through the Internet Explorer screen saver with equal display times while the computer is idle. By default, the screen saver page from each channel is shown for 30 seconds before moving on to the next channel.

Active Channel Screen Saver

The user can move the mouse without closing the Channel Screen Saver page. This allows users to navigate to a URL by clicking HTML links displayed on the screen saver page. Web publishers can use the Channel Screen Saver page to provide users with all the latest information because the screen saver is a URL that is downloaded to users' computers on a regular basis. To close the Channel Screen Saver, the user can press any key or click the "x" appearing in the autohide toolbar in the upper-right corner of the screen. This toolbar also allows users to change the screen saver properties as shown below.

Note If the Channel Screen Saver is not enabled when subscribing to a channel containing a screen saver page, users will be asked if they would like to enable it.

Accessing Installed Channels

Now that the channel has been added to the user's computer, a logo image representing a shortcut to the Internet Client SDK channel has been placed just below the channel guide in the desktop Channel Bar, as shown below.

Desktop Channel Bar

When the user clicks the Internet Client SDK logo button, the browser launches the channel's associated URL into the Internet Explorer full-screen view. Channels can also be accessed by clicking the "View Channels" icon in the quick-link launch bar located in the task bar next to the Start button. Clicking this icon opens the browser in full-screen view and loads the most recently viewed channel.

Removing an Active Channel

To remove a channel, the user simply right-clicks an icon or logo image representing the channel and selects Delete from the context menu. Items representing a channel can be found in the following places:

  • The desktop Channel Bar
  • The Channels Explorer Bar
  • The \WINDOWS\Profiles\username\Favorites\Channels folder

This will remove the logo images from the desktop Channel Bar and the Channels Explorer bar, as well as remove the channel's subscription (if any) from the \WINDOWS\Subscriptions folder.

Managing an Active Channel Subscription

Channel subscriptions provide a way for users to automatically receive updated information about a channel. Users can choose to subscribe to just the hierarchy of the channel or to have the content delivered as well. The Subscription tab provides a summary of the channel subscription information and offers the option of unsubscribing from the channel. If the user chooses to unsubscribe, the channel remains in the desktop Channel Bar as a link to the main channel page, but no content is updated in the local cache with a CDF file. This is equivalent to selecting the first option, "Just add to my channel bar," when adding a channel.

To view or modify a channel subscription, hold down the right mouse button on an icon or logo image representing a channel and select Properties from the context menu. Channel icons can be accessed by selecting the "Manage Subscriptions..." option from the Favorites menu, and logos can be accessed from the desktop Channel Bar or Channels Explorer Bar.

The following is an example of subscription properties.

The Receiving tab on the subscription properties allows users to modify the type of subscription (with or without content), e-mail notifications, and login information for the associated Active Channel.

The following is an example of receiving properties.

When channels with full subscriptions are actually updated, the default behavior is to download all content specified in a channel to the local cache, along with designated screen saver files specified in the CDF. The type of content downloaded by default includes the HTML page (or URL) indicated in the ITEM element of the CDF file and any image files it displays. However, users can manage the amount and type of data being sent to their computer by selecting the "Advanced..." button on the Receiving tab. The Advanced Download Options dialog box, shown below, allows users to enable and disable whether images, sounds, video, Java applets, and ActiveX™ Controls used in an HTML page automatically get downloaded to their local cache.

Advanced Download Options

Web publishers can require files to be downloaded as part of the channel by specifying each one in an ITEM element, regardless of the Advanced Download Options settings. If the required resource is not intended to be exposed in the hierarchy displayed in the Channels Explorer Bar, the USAGE element should be included as a child element of the item with its value set to "None".

The Schedule tab allows users to modify the schedule on which the channel's CDF file and content (for full subscriptions) is updated. Besides the publisher's recommended schedule, users can select a standard daily, weekly, or monthly schedule. The "New..." and "Edit..." buttons are provided for creating custom schedules.

The following is an example of schedule properties.

Note Modem users must check the "Dial as needed..." check box to use the publisher's recommended schedule.


Active Desktop Items

Active Desktop™ items are small Web pages or HTML components, such as a Java applet or an ActiveX™ control, that are displayed directly on the desktop. This document describes how users interact with Active Desktop items, including adding an item to the desktop, removing an item, managing an item subscription, and moving or resizing an item. For further explanation of Active Desktop items, see Creating Active Desktop Items.

Adding an Item to the Active Desktop

Managing Active Desktop Item Subscriptions

Moving and Resizing

Enabling and Disabling Desktop Items

Adding an Item to the Active Desktop

Users can customize their desktop by installing Active Desktop items designed for Microsoft® Internet Explorer 4.0. Users add these items by clicking an Add to Active Desktop button on a Web page, or by using the right mouse button to drag an icon in Internet Explorer's address or title bar to the desktop. Users also have the option of manually specifying a URL for an image or floating frame by selecting the Web option tab in the Display Properties Control Panel and clicking the New button. Items added to the desktop manually by the user will have static content unless the user subscribes to that item. An Active Desktop item can be subscribed to by selecting the item in the Web tab of the Display Properties dialog box and then clicking the Properties button followed by the Subscribe button.

Typically, users will encounter a Web page that offers an Active Desktop item related to the Web publisher's content and a button that, when clicked, adds the item to the users' Active Desktop. The button itself is linked to the item's Channel Definition Format (CDF) file. After clicking the button, the user will be presented with a dialog box (shown below) confirming the creation of this item on the Active Desktop. Once confirmed, Internet Explorer downloads the necessary resources and displays the item on the Active Desktop.

Confirmation Dialog Box

Note If the item doesn't appear on the Active Desktop, position the cursor on the desktop and click the right mouse button to bring up the context menu. Under the Active Desktop menu, make sure the View as Web Page option is checked.

Before confirming the addition of the Active Desktop item, users can modify the item's update schedule by clicking the Customize Subscription button. The user should accept the default schedule set up by the desktop item's publisher whenever possible. The dialog box presented to the user is shown below.

Managing Active Desktop Item Subscriptions

When adding an Active Desktop item with a CDF file to the desktop, a subscription for that item is created in the \Windows\Subscriptions folder. The user can easily access the subscription by selecting the Manage Subscriptions option from the Internet Explorer Favorites menu. Right-clicking the mouse on a subscription brings up the context menu for that item, allowing the user to update the item immediately, delete the subscription, or view and modify its properties. Active Desktop item subscription properties can also be accessed by selecting Properties on the menu on the desktop item itself. This menu bar appears when the cursor is placed near the top of the item.

It is important to note that deleting an item's subscription won't remove it from the desktop. To permanently delete an item, users select the Display Properties Control Panel and click the Web tab. From the list of "Items on the Active Desktop," users select the item to be removed and click the Delete button.

Display Properties Control Panel

The "New..." button allows users to manually create a desktop item that points to any valid URL. Additionally, a desktop item can be enabled or disabled by clicking the check box to the left of each item in the list.

Moving and Resizing

The user can move or resize any Active Desktop item. To make this feature easily discoverable, move and resize features have been implemented so they become available as soon as the user moves the mouse over an item. To move an Active Desktop item, the user must position the cursor near the top edge of the item to expose a bar. When the bar appears, the user holds down the mouse button on the bar and moves the mouse to reposition the item on the desktop.

This illustration shows an Active Desktop item.

Active Desktop Item

This illustration shows an Active Desktop item with mouseover focus.

Active Desktop Item with Mouseover Focus

To resize an Active Desktop item, the user positions the mouse cursor over any edge of the rectangular, 2-D HTML layer that contains the item. The cursor then changes to one of the standard directional resize cursors, and the user can drag it to change the size. However, if the desktop item CDF includes one of the CANRESIZE, CANRESIZEX, or CANRESIZEY elements with a value of "No", resizing the item is restricted or disallowed completely. In this case, the resize cursor will only appear for the resize-enabled axis, if one exists.

Enabling and Disabling Desktop Items

Users can disable an Active Desktop item either by unchecking it in the list of desktop items under the Web tab in the Display Properties Control Panel or by clicking the "x" in the bar at the top of the item. This autohide bar appears only when you pause the cursor over the top edge of the item. To reenable an item, users must access the Display Properties Control Panel and click the check box next to the item to be displayed.


Software Update Channels

Software Update Channels provide users with a mechanism for receiving software updates over the Web. If the user chooses, the subscription can be set up to automatically download and install the software when it becomes available. This document describes the user interface associated with Software Update Channels. Further information is available on Creating Software Update Channels and VERSION= (SOFTPKG)
.

Software Channels in the Internet Explorer User Interface

Channels Under the Favorites Menu

Adding a Software Update Channel

Software Channel Update Notification

Software Channels in the Internet Explorer User Interface

The Microsoft® Internet Explorer 4.0 user interface offers two views of the Software Update Channels located in the folder \WINDOWS\Profiles\username\Favorites\Software Updates:

  • The "Software Updates" folder located in the Favorites menu.
  • The "Software Updates" folder in the Favorites Explorer Bar. This view is accessed either by selecting Explorer Bar/Favorites in the View menu, or by clicking the Favorites button in the standard Internet Explorer toolbar.

Channels Under the Favorites Menu

The Favorites menu contains two folders for channel subscriptions: the "Software Updates" folder contains software subscriptions, while the "Channels" folder contains Active Channel subscriptions. Internet Explorer separates software subscriptions from Active Channel subscriptions because the two usually have very different update frequencies.

Many Active Channel subscriptions are set up to receive the latest news stories, business reports, and entertainment information. An Active Channel can send out updates several times a day. Therefore, the user should expect frequent update activity in the "Channels" folder.

On the other hand, a user would not expect to see updated subscriptions in the "Software Updates" folder on a daily basis. Software subscriptions are updated only when a new version of the subscribed software becomes available. With that in mind, users should expect a software channel to update once every few weeks, or even months.

Adding a Software Update Channel

Adding a software channel to the "Software Updates" folder is similar to adding an Active Channel. Users will be presented with an image button or link that references the CDF file for the software channel. Upon clicking the button, users will be presented with the Add Software Update Channel dialog box.

Add Software Channel Dialog Box

At this point, users can choose whether they want to subscribe to the software channel or not. Software Update Channel subscriptions will notify the user whenever the new software is available and, if the user chooses, will also download the software.

Software Channel Update Notification

Internet Explorer uses a "gleam" placed on the channel icon as the basic method for notifying users that a channel subscription contains updated content or software. The icon representing a channel in the "Software Updates" folder will have a red gleam overlaid on it when that channel is updated. Because the Internet Explorer interface provides multiple ways to access software subscriptions, the icon gleam is seen in the "Software Updates" folder, the \WINDOWS\Subscriptions folder, and the Favorites Explorer Bar.

Although the icon gleam is the default notification method for channel updates, the user can choose to be notified by e-mail as well. When a subscription is updated, the user receives e-mail with a short summary describing the update. The user's e-mail address can be specified at subscription time, or it can be specified later by modifying the properties of the software channel's subscription. To access the software channel's properties, hold the right mouse button down on the CDF file and select Properties. The CDF can be accessed by either selecting "Manage Subscriptions..." or the "Software Updates" folder located on the Favorites menu. Note that the context menu used to access the properties of the software channel can also be used for other functions, such as immediately updating or deleting the channel.

In addition to gleams and e-mail notifications, Internet Explorer 4.0 provides the underlying mechanism, using Software Update Channels, for an application to check its own update availability status. When an update is detected, the application can notify the user by presenting a dialog box alert at the time the application is launched.


Authoring for New Delivery Mechanisms

These documents describe how Web publishers can create their own channels or desktop items and provide them to users.

Creating Active Channels

Creating Active Desktop Items

Creating Software Update Channels


Creating Active Channels

This article explains Active Channels™ for Microsoft® Internet Explorer 4.0. Feature descriptions, screen shots, examples, guidelines, and a reference guide are provided to help Web publishers understand how to create their own Active Channels with a Channel Definition Format (CDF) file.

Webcasting

What Is an Active Channel?

Active Channel Types

Active Channel Features

Developing an Active Channel

Optimizing Active Channels over HTTP

Guidelines for Active Channel Logo Images

Using Dynamic HTML with Active Channels

Netcaster CDF Compatibility Notes


Webcasting

Web publishers can now broadcast content to their users on a regular schedule with new "push" and "pull" technologies that are collectively referred to as Webcasting. Users benefit by having the information that is most important to them automatically delivered directly to their desktop without having to go look for it, and also by being notified when the information has been updated. Web publishers benefit through improved feedback from increased exposure, more interactive relationships with their users, and a better understanding of their user base.

Microsoft® Internet Explorer 4.0 supports these new open, standards-based technologies as an "information receiver" client. Web sites can broadcast their content to an information receiver such as Internet Explorer by turning their Web site into an Active Channel. This article describes Active Channels and provides a sample that illustrates how to create one. Consult the CDF Reference for Active Channels for detailed descriptions of the CDF file elements and attributes. Further information on Webcasting is available on Microsoft's Web site, located at http://www.microsoft.com/ie/ie40/press/push.htm.


What Is an Active Channel?

An Active Channel is a Web site that has been enabled for Webcasting to information-receiving programs such as Microsoft® Internet Explorer 4.0. The mechanism that makes this possible in Internet Explorer 4.0 is the Channel Definition Format (CDF) file. The CDF file provides an index of resources available in the channel and a recommended schedule for when the channel should be updated on the user's computer.

A typical CDF file contains a top-level CHANNEL element to define the channel itself, along with ITEM elements to specify the actual contents of the channel. Subsequent occurrences of the CHANNEL element define subchannels and allow publishers to create a hierarchy for the channel. The TITLE and ABSTRACT elements can be used to describe the contents of each item or channel element. Publishers may also want to use the LOGO element to associate an image with each item in the channel, as well as with the channel itself.

Web Publisher's Perspective

Web publishers can give users a better browsing experience by offering their content in a channel. A channel can be created that Webcasts the following items to a browser:

  • Branded icons and logos representing the Active Channel in the desktop Channel Bar.
  • A sitemap describing the content available in the Active Channel.
  • Web pages containing text, images, and ActiveX™ Controls. These pages can have a special use associated with them, such as appearing in a screen saver or Active Desktop item.

A traditional Web site can be viewed as an Active Channel with a minimal amount of work by the Web publisher. These are the required tasks:

  • Create logo images to be displayed in the desktop Channel Bar and Channels Explorer Bar.
  • Create a CDF file listing the resources (logo images, descriptions, and HTML pages) of the channel.
  • Post the CDF file on an HTTP server and place a button linked to the CDF file on the existing Web site. Users who click this button will add the channel to their desktop Channel Bar and select a subscription option for the channel.


Active Channel Types

This section describes basic types of channels that properly use the strengths of the Microsoft® Internet Explorer information delivery architecture within the constraints of bandwidth available in the home or the corporation. Web publishers can create channels to take advantage of the following three key Internet Explorer 4.0 capabilities.

Notification | Internet Explorer 4.0 uses a red "gleam" (resembling an asterisk) to visually flag the logos and icons of channels that have changed since their previous update. Users can choose to have an e-mail message sent to them when a channel is updated.
Sitemap | The Channels Explorer Bar can display a navigable outline of URLs as specified in a channel's CDF file. The exposed hierarchy of the channel helps users efficiently navigate through a channel to find the content they are most interested in.
Offline Content Caching | Internet Explorer 4.0 downloads the set of resources specified in the CDF file to be locally cached. This allows users to browse through the entire content of an active channel even when they are offline. It is important to note that offline content is available only to users accepting the default "download content" option when subscribing to the channel.

Channel Sitemaps and Notifications

Channel Sitemaps and Notifications

These capabilities can, of course, be combined to create different types of end-user channel experiences. It's important to realize, however, that this flexibility also permits authors to define impractical channels (for example, a channel that tries to replicate an extensive Web site to the user's local disk). As a general rule, an Active Channel should fit into one of these categories: news, immersion, or notification. A hybrid channel is also possible.

News Channels

A news channel is used to keep the user up to date on breaking news. This channel periodically Webcasts a hierarchically structured set of news items to the desktop, through the CDF file. The actual content referenced in the CDF file is downloaded into the user's cache and is available for offline use. A news channel uses all three Internet Explorer key capabilities: notification, sitemap, and offline content caching. When developing the content for a news channel, keep the following guidelines in mind:

  • Each news item is a discrete, simple, self-contained page.
    • Each page is dedicated to a single "story."
    • News items don't use frames.
    • The TITLE of the page is the news item's headline.
    • The ABSTRACT of the page summarizes the news item.
  • Each news item page is designed to be small.
    • The page should consist mainly of text and utilize Dynamic HTML layout features.
    • Pages should reuse and/or minimize the use of images, especially large ones.

The CDF file allows Web publishers to hierarchically organize items in a channel into subchannels. The TITLE of each subchannel serves to classify the items contained within the subchannel. By default, subchannels and items in the channel's CDF are displayed in an outline format in the Channels Explorer Bar. In addition to any navigation mechanism authored into the pages themselves, the user can expand and collapse subchannels in the outline and jump to individual news items.

Example: A news publisher, Action News, generates business stories as individual HTML pages.

Today's business stories are:

  • A daily summary of the stock market
    • URL: http://www.action.com/channel/bus/bus001.htm
    • Title: "The Market"
    • Abstract: "Summary of today's market news."
  • An article on the general economy
    • URL: http://www.action.com/channel/bus/bus002.htm
    • Title: "Business nirvana: low inflation, high growth"
    • Abstract: "Best environment for business in 25 years due to convergence of factors."
  • An article on rise in technology issues
    • URL: http://www.action.com/channel/bus/bus003.htm
    • Title: "Tech stocks soar on XYZ Corp. news"
    • Abstract: "XYZ Corp. showed unexpected growth this quarter, dragging up prices through the technology segment."

The pages are primarily textual, sharing a common masthead graphic, as shown here.

Action News Channel Pages

For the purpose of this example, the publisher's channel consists of only these stories organized into a single subchannel called The Market. The publisher could deliver these articles to the desktop by providing the following CDF file:

<?XML VERSION="1.0" ENCODING="UTF-8"?>

<CHANNEL
    HREF="home.htm"
    BASE="http://www.action.com/channel/" >

    <TITLE>Action News</TITLE>
    <ABSTRACT>Description of the Action News Channel</ABSTRACT>
    <LOGO HREF="ActionLogo16x16.gif" STYLE="ICON"/>
    <LOGO HREF="ActionLogo32x80.gif" STYLE="IMAGE"/>

    <SCHEDULE STARTDATE="1997-10-17" STOPDATE="1997-10-17">
        <INTERVALTIME DAY="1"/>
    </SCHEDULE>

    <CHANNEL
        HREF="bus001.htm">
        <TITLE>The Market</TITLE>
        <ABSTRACT>"Summary of today's market news"<ABSTRACT>
        <LOGO HREF="marketLogo.gif" STYLE="ICON"/>

        <ITEM HREF="bus002.htm" LASTMOD="1997-10-17T11:12">
            <TITLE>Business nirvana: low inflation, high growth</TITLE>
            <ABSTRACT>Best environment for business in 25 years due to
                convergence of factors.</ABSTRACT>
            <LOGO HREF="TopStoryLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="bus003.htm" LASTMOD="1997-10-17T11:12">
            <TITLE>Tech stocks soar on XYZ Corp. news </TITLE>
            <ABSTRACT>XYZ Corp. showed unexpected growth this quarter,
                dragging up prices through the technology segment.</ABSTRACT>
            <LOGO HREF="TopStoryLogo.gif" STYLE="ICON"/>
        </ITEM>
    </CHANNEL>
</CHANNEL>

Once subscribed to by the user, Action News would appear within the browser's Channels Explorer Bar as:

Action News Channel

Since none of the stories in the CDF include the PRECACHE="NO" attribute on the ITEM elements, all of the pages will be precached during updating. Therefore, each news page will be available for offline viewing if the user subscribes to the channel and chooses to receive channel content.

Immersion Channels

An immersion channel presents the user with an authored "environment" that provides all navigation (for example, the Channels Explorer Bar is assumed to be hidden). All content is precached so the channel can be used offline. It is important to note that this channel's items and subchannels do not appear in the Channels Explorer Bar. In this case, the CDF file is used exclusively to specify content that needs to be downloaded and to notify the user when the channel has been updated. Downloading channel content helps increase online performance and allows offline use. Similar to the CDF of a news channel, the author specifies a list of items to be updated and a schedule for updating them. However, unlike a news channel, each item in the CDF must include the following child element:

<USAGE VALUE="None"></USAGE>

This element instructs Internet Explorer 4.0 not to display the subchannel or item in the Channels Explorer Bar, but it will download and precache each item. Resources other than HTML pages, such as images and ActiveX™ controls, can also be specified in the CDF to be precached when the channel is updated. Since the channel is designed for offline use, the amount of content specified by the CDF file must be compatible with bandwidth constraints of the target audience.

Example: A maze game immersion channel containing a set of interlinked rooms implemented as HTML pages. On each subsequent update of the CDF file, the publisher dynamically generates a new CDF file that adds new rooms or modifies the existing maze.

Maze Game Immersion Channel

The CDF file to deliver a simple maze game might look something like this:

<?XML VERSION="1.0" ENCODING="UTF-8"?>

<CHANNEL
    HREF="home.htm"
    BASE="http://www.gamer.com/channel/" >

    <TITLE>The Castle</TITLE>
    <ABSTRACT>An always changing maze of rooms for you to explore</ABSTRACT>
    <LOGO HREF="Castle16x16.gif" STYLE="ICON"/>
    <LOGO HREF="Castle32x80.gif" STYLE="IMAGE"/>

    <SCHEDULE STARTDATE="1997-10-17" STOPDATE="1997-10-17">
        <INTERVALTIME DAY="1"/>
    </SCHEDULE>

    <ITEM HREF="room01.htm" LASTMOD="1997-10-17T11:12">
        <USAGE VALUE="None"></USAGE>
    </ITEM>

    <ITEM HREF="room02.htm" LASTMOD="1997-10-17T11:12">
        <USAGE VALUE="None"></USAGE>
    </ITEM>

    <-- a list of additional items -->

    <ITEM HREF="roomNN.htm" LASTMOD="1997-10-17T11:12">
        <USAGE VALUE="None"></USAGE>
    </ITEM>

</CHANNEL>

Maze Game Immersion Channel

Notification Channels

A notification channel informs the user when new information is available within a channel and provides a sitemap (through the CDF file) to the new information without downloading the content itself. The CDF file of a notification channel is similar to a news channel, except that the PRECACHE= attribute of each subchannel and item is explicitly set to "NO". The hierarchy of items and subchannels in the CDF file is displayed in the Channels Explorer Bar, but the content referenced by the outline is available only online. It's important that the publisher sets the user's expectations appropriately, specifically indicating that this type of channel is designed to notify the user of changes to content available online. Like all channels, a "gleam" appears on the channel's logo to inform the user that the channel has been updated.

Example: A corporation wants to create a channel to notify employees about the latest information on their employee services, benefits, company policies, and so on.

Corporate Notification Channel

The following illustrates the notification channel's CDF file. The example includes only the Employee Services subchannel.

<CHANNEL
    HREF="home.htm"
    BASE="http://www.corp.com/channel/"
    PRECACHE="No">

    <TITLE>Corporate Channel</TITLE>
    <ABSTRACT>CorpCo's Corporate Channel</ABSTRACT>
    <LOGO HREF="CorpLogo16x16.gif" STYLE="ICON"/>
    <LOGO HREF="CorpLogo32x80.gif" STYLE="IMAGE"/>

    <SCHEDULE STARTDATE="1997-10-17" STOPDATE="1997-10-17">
        <INTERVALTIME DAY="1"/>
    </SCHEDULE>

    <-- omitted subchannels -->

    <CHANNEL
        HREF="services.htm"
        PRECACHE="NO">

        <TITLE>Employee Services</TITLE>
        <ABSTRACT>Employee services  from CorpCo</ABSTRACT>
        <LOGO HREF="CategoryLogo.gif" STYLE="ICON"/>

        <ITEM HREF="companyStore.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Company Store</TITLE>
            <ABSTRACT> Offerings from the company store </ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="StockServices.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Stock Services</TITLE>
            <ABSTRACT>Buying and selling CorpCo stock</ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="Career.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Career Center</TITLE>
            <ABSTRACT>Job opportunities at CorpCo</ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="Handbook.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Employee Handbook</TITLE>
            <ABSTRACT>Rules and regulations for CorpCo employees</ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="Cafeteria.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Cafeteria Menus</TITLE>
            <ABSTRACT>Today's eats </ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>

        <ITEM HREF="Vacation.htm" PRECACHE= "NO" LASTMOD="1997-10-17T11:12">
            <TITLE>Vacation and Sick Reporting </TITLE>
            <ABSTRACT>Vacation and sick day reporting form </ABSTRACT>
            <LOGO HREF="BulletLogo.gif" STYLE="ICON"/>
        </ITEM>
    </CHANNEL>

    <-- omitted subchannels -->

</CHANNEL>

Hybrid Channels

Hybrid channels combine two or more of the news, immersion, and navigation channel types. When creating a hybrid channel, follow these guidelines:

  • Remember that the total daily download from any channel, including hybrid channels, must take into account bandwidth limitations.
  • Segregate items that can be used offline from those that must be used online into discrete subchannels. Therefore, the subchannels of a hybrid channel should fall into one of the three basic channel types previously discussed. For example, a single hybrid channel that delivers news-style items for offline reading and provides a sitemap to an online site might look like this:

Design Guidelines for Active Channels

To take true advantage of the "push" mechanism available in Internet Explorer 4.0, channels must be as small as possible to minimize download time and provide compelling content and interaction when used offline. When designing your Active Channel, follow these guidelines:

  • Design your channel to conform to one of the Active Channel types previously described in this document. Some channels, of course, might naturally cross the boundaries.
  • Channels intended for offline use (news and immersion channels, for example) should consider the impact of bandwidth limitations. If the target user is a home user dialing over a modem, the average amount of content delivered per update, per channel should be no more than 500K to 1 MB—preferably smaller. Under ideal conditions, a megabyte of content can be downloaded by a 28.8K modem in about six minutes. In practice, however, depending on line and server conditions, downloading 1 MB takes about 10 minutes. The following table shows download connect times for a 28.8K modem for different numbers of channels under different line conditions.

    Number of | 500K | 500K | 1 MB | 1 MB
    channels | (ideal) | (typical) | (ideal) | (typical)
    2 | 6 min. | 10 min. | 12 min. | 20 min.
    4 | 12 min. | 20 min. | 24 min. | 40 min.
    8 | 24 min. | 39 min. | 49 min. | 80 min.
    12 | 36 min. | 59 min. | 73 min. | 120 min.

    Note Sizes represent the average amount of data downloaded per channel.

  • Active Channels should be self-contained. The channel must deliver real value to the user while offline. It is likely that users will become annoyed with an offline channel that constantly forces online connections. This means that links to noncached resources should be minimized or hidden when the user is offline. Scripting can be used on an HTML page to determine when the user is offline and reflow the page accordingly using Dynamic HTML.
  • Channels should be personalized whenever possible. A publisher can provide a personalized channel experience for each user by generating a custom CDF for each user (for example, based on user preferences stored in a cookie). Channels based on personalized CDF files can be more rapidly delivered because content that is not important to the user will not be downloaded. Generating a customized CDF is as easy as offering a personalized home page using server-side scripting.


Active Channel Features

The following sections explain the details of various Active Channel features, as well as what Web publishers need to know to take advantage of them.

  • Scheduled updates and server loads
  • Personalized channels and passwords
  • Password-protected Active Channels
  • Page-hit logging
  • Active Channel screen savers
  • Category folders

Scheduled Updates and Server Loads

Web publishers can create a default schedule in the CDF file that Microsoft® Internet Explorer uses to determine when the channel information on the user's computer should be updated. Specifying a schedule with a range of valid update times can help to effectively manage server loads when Webcasting to Internet Explorer. The actual time Internet Explorer updates the channel is randomly selected from the valid time range for each update. The CDF file specifies the valid time range for updates by including the EARLIESTTIME and LATESTTIME elements as child elements of the SCHEDULE element. The INTERVALTIME element specifies how often, on average, the updates will occur. The following examples illustrate different update schedules for an Active Channel.

Note The shaded areas in the diagrams below represent the range of time during which the actual channel update will occur.

Daily Schedule

The schedule shown below would cause the channel to be updated every day at a random time between 2 A.M. and 6 A.M. Since the publisher didn't specify a start or end date, the schedule takes effect immediately and doesn't expire.

<SCHEDULE>
    <IntervalTime Day="1" />
    <EarliestTime Hour="2" />
    <LatestTime Hour="6" />
</SCHEDULE>

Hourly Schedule

For channels that Webcast extremely time-critical information, a channel may need to be updated many times during the day. The example below shows a channel that is updated four times per day. The actual updates occur sometime after the second hour of each six-hour interval. This schedule is set to expire on December 31, 1999, at which point no further updated information will be downloaded for this channel.

<SCHEDULE STOPDATE="1999-12-31">
    <IntervalTime Hour="6" />
    <EarliestTime Hour="2" />
    <LatestTime Hour="6" />
</SCHEDULE>

Weekly Schedule

A schedule that updates a channel once a week is shown below. Because this weekly schedule started on a Monday, this channel will be updated every Monday sometime between 2 A.M. and 6 A.M. until it reaches the expiration date. This schedule takes effect on Monday, September 29, 1997, and expires on December 31, 1999.

<SCHEDULE StartDate="1997-09-29" STOPDATE="1999-12-31">
    <IntervalTime Day="7" />
    <EarliestTime Hour="2" />
    <LatestTime Hour="6" />
</SCHEDULE>

By default, users accessing the Internet with a dial-up connection need to manually update their channels by either right-clicking on a logo image representing a channel subscription and selecting the Update Now option from the context menu, or by selecting the Update All option from the Favorites menu. Modem users can also configure their subscriptions to automatically dial up their Internet connection on a regular basis without any user intervention. To set up automatic updates over a modem, the user must select the "Dial as needed..." check box in the Schedule tab of the Channel Properties. Once automatic updates are enabled by modem users, the publisher's recommended schedule or a standard schedule (daily, weekly, monthly) can be used. If the "Dial as needed..." feature is not enabled, the channel updating schedule is effectively manual for modem users. Users connected to a network should use the publisher's recommended schedule specified in the CDF file for updating channels.

Personalized Channels

The HTTP cookie standard provides a powerful mechanism for personalizing Web content. The CDF file integrates this standard with Internet Explorer. A Web publisher who wants to create a personalized channel can use regular HTTP cookies to deliver personalized information to users by dynamically generating a custom CDF file based on user preferences. The CDF file thus leverages the existing cookie standard for personalized HTML on the Web and takes it one step further by allowing personalized channels for individual users. Web publishers can create personalized channels for users or groups of users by performing the following tasks:

  1. The first time users visit a channel, present them with a form asking for their preferences, as they relate to the channel.
  2. Store those user preferences on the Web server or within a cookie on the user's computer.
  3. Whenever Internet Explorer 4.0 subsequently requests an updated CDF for that user, the server could either download an existing CDF file or dynamically generate one that matches the user's profile information stored locally in the cookie.

Web publishers using active server pages with Microsoft Internet Information Server (IIS) to dynamically generate personalized CDF files (named with an .asp extension) must insert the following line at the top of the CDF file:

<% Response.ContentType = "application/x-cdf" %>

Note As an alternative for IIS 4.0 site authors, the CDF file can be created with a .cdx extension instead of .asp, and the MIME content type line above can be omitted.

This ensures that the server will return the correct MIME/content type to the browser. Without this line, the browser will not perform the expected actions for CDF files. For example, the CDF file might display as text in the browser window rather than launch the Add Channel dialog box.

Password-Protected Active Channels

Web publishers implementing HTTP authentication in their channels need to make sure Internet Explorer has the user name and password so it can update the channel content without user intervention. To accomplish this, publishers can force Internet Explorer to ask users for this information during the channel subscription setup process by using the LOGIN element in the CDF file. When the channel subscription wizard encounters this element in a CDF file, it will prompt users to enter their user name and password. When the channel setup is complete, the user name and password are stored with the channel's subscription properties. Therefore, subsequent CDF files sent to that user for updating the channel don't require the LOGIN element. Internet Explorer will automatically authenticate HTML pages when using Basic, NTLM, RPA, and HTML forms.

If the authentication process is based on an HTML form, Internet Explorer needs to be able to fill out the form correctly. For the login process to be successful, follow the guidelines just mentioned for the HTTP authentication, and make sure the HTML form complies with these requirements:

  • The form must use the "post" method.
    <FORM METHOD="POST" ACTION="http://www.foo.com/login">
  • The name of the input text box for the user's name must be "username" or "user".
    <INPUT TYPE=TEXT NAME="username" SIZE=20>

    or

    <INPUT TYPE=TEXT NAME="user" SIZE=20>
  • The name of the password field must be "password".
    <INPUT TYPE=PASSWORD NAME="password" SIZE=20>

Note All other elements on the form will be posted with their default values.

Page-Hit Logging

Important Note The page-hit logging feature enables Active Channels to collect the same page-hit information from offline users as they can already collect from online users. This feature can easily be disabled by a home user or a corporate administrator, if desired.

Page-hit logging collects information for Web publishers about activity on their channel pages by logging page hits in the browser, screen saver, and Active Desktop in both offline and online modes. The page-hit engine allows the collection of data for the time and date that the channel pages were loaded into the browser.

Client-side logging

Using the CDF file, publishers can tightly control exactly what page hits are logged. They can also define the maximum time to archive the data. To enable page-hit logging of a channel, the CDF file should contain the LOG element, indicating what items are to be logged, and the LOGTARGET element, indicating where the log file should be sent. Web publishers should use discretion when using the LOG element in the CDF file and select specific items for logging. Be aware that a large number of items marked for logging could potentially create large log files, which could raise bandwidth issues for the user when the log file is uploaded to the LOGTARGET URL. The uploading of the log file back to the server occurs when the CDF file is updated. For more information about the LOG and LOGTARGET elements, including examples, see the CDF Reference for Internet Explorer.

Note Items marked for logging must have an HREF attribute that falls under the URL of the CDF file or the path specified in the LOGTARGET element.

Web publishers receive the page-hit logging files in the directory (URL) specified in the LOGTARGET element, in "Extended Log File Format," as defined by the World Wide Web Consortium (W3C). Every page hit that is logged has two types of records associated with it. The first record is a "header" that contains the URL of the channel item being logged. The records subsequent to the header are details of the page hits. Here is a sample record:

#Fields: s-URI
http://www.foosports.com/news/default.htm
#Fields: c-context c-cache c-date c-time c-duration
N 1 06-02-1997 19:12:37 00:00:04
T 1 06-03-1997 11:38:04 00:00:23

These records indicate that the URL "http://www.foosports.com/news/default.htm" was viewed in normal mode on June 2, 1997, from the cache at 7:12 P.M. for four seconds, and again in full-screen view on June 3 at 11:38 A.M. for 23 seconds. The context value can be "N", "T", "D", or "S" to indicate whether the URL was viewed in a normal browser window, full screen view (Theater View), as an Active Desktop item, or in the Internet Explorer screen saver, respectively. The value for the cache field can be "1" to indicate the URL was retrieved from the local cache or "0" to indicate the URL was retrieved from the site itself. The Web publisher can filter out online or offline records by using the SCOPE= attribute of the LOGTARGET element. The date field shows the date on which the URL was viewed. The time value indicates what time (on the local computer) the URL was viewed, and the duration indicates how long the user viewed the page. The time and duration fields are in HH:MM:SS format, while the date is in MM-DD-YYYY format.

Server-side log file processing

Web publishers that receive page-hit log files can extract and process the data listed above in any way they choose. However, Microsoft provides the following two methods for parsing the information in the log file:

  • A Perl script
  • The ISAPI DLL (IIS users only)

The following Perl script can be used to parse the log file.

require("cgi-lib.pl");
$logfile='log/cdfpost.dat';
$method=$ENV{REQUEST_METHOD};
$clen=$ENV{CONTENT_LENGTH};
print "Content-type: text/html\n\n";
print "<HTML>\n";
&open_logfile;
    &print_env;
&ProcessRawdata;
print "Just to show we got here too <BR>\n";
print "</HTML>\n";
sub ProcessRawdata
{
    &add_logdata;
    close(OUT);
}

sub print_env
{
    print OUT "<!--Request method : ", $method, "\n";
    print OUT "Server : ", $ENV{SERVER_NAME}, "\n";
    print OUT "Script : ", $ENV{SCRIPT_NAME}, "\n";
    print OUT "Client : ", $ENV{REMOTE_ADDR}, "\n";
    print OUT "Content-length : ", $clen, "-->\n";
}

sub open_logfile
{
    if (-e $logfile) {
        open (OUT, ">>$logfile");
    } else {
        open (OUT, ">$logfile");
    }
}

sub add_logdata
{
    open(IN, "-");
    binmode IN;

    while ($clen) {
        print OUT getc(IN);
        $clen=$clen-1;
    };
    print OUT "\n";
}

When running Microsoft Internet Information Server (IIS), you can use the ISAPI DLL to parse the log file. For more information about how to accomplish this, see the Readme file located in the inetsdk\samples\iislog directory. Note that this sample also demonstrates how to decompress encoded posted strings, and the associated CDF file must contain the HTTP-EQUIV element as follows:

<LOGTARGET HREF="http://www.mysite.com/logging/" METHOD="POST">
    <HTTP-EQUIV NAME="encoding-type" VALUE="gzip">
</LOGTARGET>

Additional information is available on how to programmatically access the log file in the page-hit logging API reference.

Active Channel Screen Savers

As part of the CDF file, the publisher may designate a specific URL to be downloaded as content for the Channel Screen Saver. This screen saver supports standard HTML pages, including scripting, images, Java applets, and ActiveX™ Controls. Screen saver content pages can include scripting and Dynamic HTML support to provide a page that dynamically changes the content, style, and position of the HTML elements on the screen. These pages are displayed on the full screen during computer idle times. The Channel Screen Saver cycles through enabled channel screen savers, allocating the same amount of display time to each one (by default, 30 seconds per channel). A channel's screen saver page is automatically included in the rotation when the channel is subscribed to, or subsequently through the Screen Saver Properties dialog box. If a user subscribes to a channel containing a screen saver page and the Channel Screen Saver isn't currently selected, the following dialog box will be displayed.

Screen Saver Confirmation

Publishers can enable a specific URL as a screen saver page by including the USAGE element in a channel's CDF file. In the following example, the HTML page at URL "http://www.foosports.com/screensaver.htm" is defined as the screen saver for the channel in which it occurs.

<ITEM HREF="http://www.foosports.com/screensaver.htm">
    <USAGE VALUE="ScreenSaver"></USAGE>
</ITEM>

Note The screen saver item's USAGE element must be a child of the top-level CHANNEL element. If the USAGE element occurs within a nested CHANNEL element representing a subchannel, the screen saver will be ignored.

Unlike many common screen savers, the user can move the mouse and click objects without immediately dismissing the Internet Explorer screen saver. Clicking a link opens a new browser window and dismisses the screen saver. Pressing a key or clicking on a location that is not an image, link, or object also closes the screen saver. Moving the mouse causes the screen saver toolbar to appear in the upper-right corner of the screen. From this toolbar, the user can close the screen saver or access the screen saver properties.

Active Channel screen saver

Category Folders

The desktop Channel Bar contains some category folders, such as News and Technology, Sports, Business, Entertainment, and Lifestyle and Travel, for grouping channels that have similar types of content. When the user clicks one of these categories, the browser opens a page of all the channels in that category and their associated branded logo images. Selecting one of these channels causes the browser to navigate to the associated channel's main page. The Add Channel dialog box is automatically displayed if the user does not already subscribe to the channel.


Developing an Active Channel

To create an Active Channel on an existing Web site, simply create a CDF file by following these steps:

  1. Design the channel.
  2. Create the logo images.
  3. Create the CDF file.
  4. Post the CDF file.
  5. Offer the new channel to users.

Design the Active Channel

When creating a CDF file, the first step is to determine the structure of the channel. The channel can be designed to represent the structure of an existing Web site, or it can be a subset of a Web site's content with a completely different hierarchy. The structure of the channel is created in the CDF file with the use of the CHANNEL and ITEM elements to represent the subchannel hierarchy and HTML items (content). To prevent users from being overwhelmed with information and images, as well as to provide a uniform "look and feel" among channels, keep the following guidelines in mind:

  • A channel should have no more than eight total subitems in the first level.
  • Web publishers should provide all the images to be used with their channel. Images are needed for the desktop Channel Bar, Channels Explorer Bar, and items in the channel.
  • Design the channel to be one of the recommended Active Channel Types.

Create the Logo Images

There are several places in the user interface where images associated with an Active Channel are displayed:

  • Desktop Channel Bar (32H x 80W)
  • Channel Pane Explorer Bar in the browser (32H x 194W)
  • Icons for items within categories (16H x 16W)

When creating a channel, Web publishers should provide appropriate images for each of these categories, although Microsoft will provide default images wherever necessary. The top-level CHANNEL element should include three LOGO child elements, one for each type of STYLE attribute, as follows:

<CHANNEL HREF="http://www.mysample.com/mainchannel.htm">
    <LOGO HREF="http://www.mysample.com/widelogo.gif" STYLE="IMAGE-WIDE"/>
        <!-- For Channels Explorer Bar -->
    <LOGO HREF="http://www.mysample.com/logo.gif" STYLE="IMAGE"/>
        <!-- For desktop Channel Bar -->
    <LOGO HREF="http://www.mysample.com/icon.gif" STYLE="ICON"/>
        <!-- For category folder -->
    <subitems omitted>
    .
    .
    .
</CHANNEL>

The STYLE="ICON" attribute is included in case the user places an Active Channel in a category folder. When this occurs, the channel will appear in the list of available channels in the Channels Explorer Bar when that channel folder group is selected. All other CHANNEL and ITEM elements in the CDF file should include only one LOGO child element with the STYLE="ICON" attribute. When creating your image files, be sure to make the background color transparent, if applicable. It's also recommended that your image be fairly simple so that it's easy to recognize at the 16H x 16W size. Additional information about image specifications is available in the Guidelines for Active Channel Images.

Create the CDF file

When the channel structure has been designed and the logos have been created, the CDF file can be written. The CDF file must include at least one CHANNEL element and should include the SCHEDULE and LOGO elements. The ITEM element must be used to include any Web pages as part of the channel's content. As the content contained in the channel is added, removed, or modified over time, Web publishers should update the CDF file to reflect the changes. For information about using a channel creation tool, see Microsoft CDF Generator.

The CHANNEL element is used to define the top-level channel itself, along with any subitems nested within that channel. Thus, the occurrence of the <CHANNEL> and </CHANNEL> tags defines the hierarchy of the channel. The LOGO element is used to specify an image file that is displayed in the desktop Channel Bar.

Post the CDF file

After creating the CDF file, it should be posted on the Web site it describes. Typically, the file would be placed in a public folder on the Web site's HTTP server.

Offer the New Channel to Users

Finally, Web publishers need to provide a method for users to install their Active Channel (or Active Desktop item). Users will be able to add channels from three primary sources:

  • A button image placed on a Web page.
  • The Channel Guide.
  • The pre-installed set of channels in the Channel Bar.

Although a simple HREF in an anchor (<A>) element pointing to a CDF file will initiate the channel subscription process, your page should include the Add Active Channel or Add to Active Desktop logo button for consistency and maximum usability. These buttons should have scripts associated with them that, when clicked, perform the proper behavior in any browser. When using the scripts in the following example, clicking the button with Microsoft® Internet Explorer 4.0 displays the Add Channel dialog box by linking to the CDF file. If users without Internet Explorer 4.0 click the button, they will be directed to download the new version.

Note To use the Microsoft Add Active Channel button logo image or the Add to Active Desktop button logo image, you must sign up and accept the terms of the Active Channel Logo Agreement at http://www.microsoft.com/sbnmember/ielogo/default.asp.

Follow these steps to add the logos and scripts to your HTML page.

Step 1. Place these logo image buttons on your Web server.

Add Active Channel

Use this image to allow users to install your Active Channel.

Add to Active Desktop

Use this image to allow users to add your item to their Active Desktop.

Web publishers are encouraged to use these official Internet Explorer button logo images to provide users with a more visible, consistent, and easily recognizable method for adding Active Channels and Active Desktop items.

Step 2. Using Notepad or your favorite HTML editor, open the HTML page that will contain these logos.

Step 3. Copy and paste the following script between the <HEAD> and </HEAD> tags in the HTML page you are editing:

<!-- Begin Put this script into the head of the page -->
<script language="JavaScript">
    function isMsie4orGreater() {
    var ua = window.navigator.userAgent;   var msie = ua.indexOf ( "MSIE " );
    if  (msie > 0)
        {return (parseInt ( ua.substring ( msie+5, ua.indexOf ( ".", msie ) ) ) >=4) &&
        (ua.indexOf("MSIE 4.0b") <0) ;}
    else {return false;}}
</script>
<!-- End   Put this script into the head of the page -->

Step 4. For each individual Add logo included on the HTML page, copy and paste the following lines of HTML:

<a name="uniqueName"
href="http://www.microsoft.com/ie/ie40/download/?/ie/ie40/download/redirect.htm">
<img src="urlOfLogoImage" border=0 width=136 height=20></a>
<script language="JavaScript">
    if ( isMsie4orGreater()) { uniqueName.href ="urlToCDF"; }
</script>

Edit the above script by making the following changes:

  • Replace each occurrence of uniqueName with a unique name for each logo placed on the page. The unique name for each logo must not contain any spaces.
  • Include the actual URL of the button image on your server in place of urlOfLogoImage. This should be one of the GIF files shown in Step 1.
  • Include the actual URL of the CDF file on your server in place of urlToCDF. This can be any URL that returns a CDF file, such as ASP or CGI pages.

Tip Web publishers might also want to use Dynamic HTML to conditionally display or hide content based on whether the user has a subscription to their Active Channel.

The channel guide

Web publishers can include their Active Channels in the Internet Explorer 4.0 channel guide. This acts as a primary resource for users to find channels that match their interests. The channel guide provides users with several channel listings that are separated into the following categories:

  • Business
  • Entertainment
  • Lifestyle and Travel
  • News and Technology
  • Sports

Microsoft Active Channel partners will be listed in the guide with a 32H x 80W GIF logo image. All other channels will be listed in the guide with the channel's title only. When a user places the mouse pointer over the publisher's logo or title, a ToolTip appears with the channel's description. When the user clicks the channel title or logo in the channel guide, a "Preview Page" is displayed. This page is a 365H x 460W-pixel HTML page located on the publisher's server that acts as an advertisement for all of the publisher's Webcasting offerings. The use of Dynamic HTML is strongly encouraged on this page to make the experience more interactive and engaging for the user. Similar to the "Webcasting Offerings Page" described above, the Preview Page should contain the official button and script for each Active Channel or Active Desktop item offered by the Web publisher. The logo image (where applicable), channel description, and Preview Page URL must be provided to Microsoft by the publisher to be placed in the Internet Explorer channel guide. For more information about placing your channel in the Internet Explorer 4.0 channel guide, see the Microsoft SiteBuilder Network Web site at http://www.microsoft.com/sitebuilder, or look in the channel guide itself.

CDF Sample and Explanation

The following sample CDF file shows the syntax used in the CDF, with detailed explanations in the next section. This sample is included in the \samples\channel directory, which is installed in the c:\inetsdk directory by default. To subscribe to the sample channel, follow the instructions provided in the Readme.txt file located in that directory. To subscribe to a channel on a Web page, simply click one of the channel logos in the desktop Channel Bar, or click on the Channel Guide to find a list of additional channels. To subscribe to the Internet Client SDK channel, use Internet Explorer 4.0 to navigate to http://www.microsoft.com/msdn/sdk/inetsdk/help/default.htm, and click the Add Active Channel button. Following is the sample CDF file included in the SDK.

<?XML version="1.0"?>
<CHANNEL HREF="http://www.mysite.com/Channel/homepage.htm"
     BASE="http://www.mysite.com/Channel/">
    <TITLE>Sample "Color" Channel</TITLE>
    <ABSTRACT>The sample color channel contains a red, green, and blue page for viewing.</ABSTRACT>
    <LOGO HREF="logo_big.gif" STYLE="IMAGE-WIDE"/>
    <LOGO HREF="logo_med.gif" STYLE="IMAGE"/>
    <SCHEDULE STARTDATE="1997-09-23">
        <INTERVALTIME DAY="1" />
        <EARLIESTTIME HOUR="2" />
        <LATESTTIME HOUR="6" />
    </SCHEDULE>
       <ITEM HREF="page1.htm">
        <LOGO HREF="red.gif" STYLE="ICON"/>
        <TITLE>The Red Page</TITLE>
        <ABSTRACT>This is the abstract description for the red page.</ABSTRACT>
    </ITEM>
    <ITEM HREF="page2.htm">
        <LOGO HREF="green.gif" STYLE="ICON"/>
         <TITLE>The Green Page</TITLE>
        <ABSTRACT>This is the abstract description for the green page.</ABSTRACT>
       </ITEM>
    <ITEM HREF="page3.htm">
        <LOGO HREF="blue.gif" STYLE="ICON"/>
        <TITLE>The Blue Page</TITLE>
        <ABSTRACT>This is the abstract description for the blue page.</ABSTRACT>
    </ITEM>
    <ITEM HREF="scrnsave.htm">
        <USAGE VALUE="ScreenSaver"></USAGE>
    </ITEM>
</CHANNEL>

The following section lists portions of the CDF example file and then describes the function of the elements and their associated attributes. Where possible, the effect on the user is also indicated.

<CHANNEL HREF="http://www.mysite.com/Channel/homepage.htm"
     BASE="http://www.mysite.com/Channel/">

In this case, the CHANNEL element defines the top-level channel of the hierarchy. Every element that follows until the matching </CHANNEL> element is subordinate to this channel. The HREF attribute defines the Web page to be displayed in the browser when the channel is selected either in the desktop Channel Bar or in the Channels Explorer Bar. The BASE attribute defines the URL of the location where the channel's resources exist. This allows Web publishers to specify other URLs in the CDF file using relative paths.

<TITLE>Sample "Color" Channel</TITLE>
<ABSTRACT>The sample color channel contains a red, green, and blue page for viewing.</ABSTRACT>

The TITLE element defines the text that is associated with this channel in the browser's channel pane. The ABSTRACT element defines a text string that is displayed in a ToolTip when the cursor is placed over the channel.

<LOGO HREF="logo_big.gif" STYLE="IMAGE-WIDE"/>
<LOGO HREF="logo_med.gif" STYLE="IMAGE"/>

The LOGO element marked with the "IMAGE-WIDE" style attribute is displayed in the Channels Explorer Bar, while the "IMAGE" style is shown in the desktop Channel Bar. Clicking this image results in opening the URL specified in the top-level CHANNEL element, or the channel hierarchy is shown, if applicable.

<SCHEDULE STARTDATE="1997-09-23" STOPDATE="1997-11-23">
    <INTERVALTIME DAY="1" />
    <EARLIESTTIME HOUR="2" />
    <LATESTTIME HOUR="6" />
</SCHEDULE>

The SCHEDULE element indicates how often, and during what time range, the channel should be updated. This is designed to help Web sites manage their server traffic. The preceding example is set to update the channel every day between 2 A.M. and 6 A.M. This schedule information is set to expire on November 23, 1997.

<ITEM HREF="page1.htm">
    <LOGO HREF="red.gif" STYLE="ICON"/>
    <TITLE>The Red Page</TITLE>
    <ABSTRACT>This is the abstract description for the red page.</ABSTRACT>
</ITEM>

The ITEM element defines a Web page as a subitem in the sample CDF channel. This item will be displayed in the channel's hierarchy exposed in the Channels Explorer Bar, along with the "ICON" image specified in the LOGO element.

<ITEM HREF="scrnsave.htm">
    <USAGE VALUE="ScreenSaver"></USAGE>
</ITEM>

This occurrence of the ITEM element (along with USAGE) defines the URL of an HTML page to be displayed in the Channel Screen Saver page. The ITEM and USAGE elements can also be used to define an HTML page as an Active Desktop item. These items can contain any valid HTML elements, such as images, ActiveX™ Controls, Java applets, and so on, and can be placed directly on the desktop with Internet Explorer 4.0. For more information on Active Desktop items, review the documentation for Creating Items for the Active Desktop.

</Channel>

This end tag indicates that the definition of the sample CDF channel is complete.


Optimizing Active Channels over HTTP

Web publishers are strongly encouraged to follow the size guidelines discussed in the Design Guidelines for Active Channels section. In addition to considering bandwidth issues, Web publishers should support the following HTTP headers to ensure efficient use of their site by eliminating unnecessary data transfer:

  • Send a "Last-Modified" response header upon HEAD and GET requests. This allows the CDF client to monitor changes to the channel without downloading any resources.
  • Use the LASTMOD= attribute on ITEM elements. This optimization technique prevents Internet Explorer from hitting the server to retrieve the last modified date for each item referenced in the CDF file.
  • Use the "Expires" response header to indicate the lifetime of the resource.
  • Don't send the "Pragma: no-cache" response header unless absolutely necessary.
  • Support the "If-Modified-Since" request header.


Guidelines for Active Channel Logo Images

The guidelines listed in this section are provided to help Web publishers create useful and compelling logos that represent their channel content. When creating images, be aware that the logos are displayed with a fixed 256-color palette, regardless of the monitor's color depth. Therefore, using the Microsoft® Windows® halftone palette is recommended, if possible. The height (H) and width (W) of the images described in these guidelines are assumed to be in pixels.

Active Channel Logos

Microsoft Internet Explorer 4.0 uses different logo sizes for channels displayed on the desktop and channels displayed inside the browser window, as previously discussed. The desktop Channel Bar logo is 32H x 80W, and the Channels Explorer Bar logo is 32H x 194W. When a user resizes the width of the Channels Explorer Bar beyond 194 pixels, the remaining area on the right side of the 32H x 194W logo is filled in with the rightmost top pixel. If only the 32H x 80W image is provided, it is displayed in both places—on the desktop and inside the browser window. When displayed in the browser window Channels Explorer Bar, the remaining area on the right side of the logo is filled in with the same color as the leftmost top pixel. The 32H x 80W logo for the desktop must have a black background, while the logo for the browser should use a colored background. To specify the logos in the CDF file, the following format is used.

For the 32H x 80W logo:

<LOGO HREF="example.gif" STYLE="Image">

For the 32H x 194W logo:

<LOGO HREF="example-wide.gif" STYLE="Image-Wide">

For the 16H x 16W icon images:

<LOGO HREF="example-icon.gif" STYLE="Icon">

Logo Image Descriptions

Desktop Channel Bar Logos

The desktop Channel Bar displays the smaller logo (32H x 80W) for each available channel. To match the visual elements used on the desktop, a black background is required for each logo. All logos in the desktop Channel Bar are shown at the same time. The following illustration shows the hot tracking behavior for when a user moves the mouse over a logo. As the cursor is placed on an image in the desktop Channel Bar, the border around the logo surfaces into a 3-D button, much like other toolbars within Internet Explorer 4.0. This behavior helps make the desktop Channel Bar look like a well-integrated part of the product.

Desktop Channel Bar

Channels Explorer Bar Logos

Inside the Browser window, Internet Explorer 4.0 uses the full-width logo (32H x 194W) in the Channels Explorer Bar. By default, only the channel name is displayed in white text on a black background for each channel. However, when the user moves the mouse over an item, it will hot-track to show the logo for that item. Using a color background for the large logo is recommended. If a user clicks a channel to activate it, that logo remains visible. This allows users to easily determine the current channel because they aren't distracted with logos from other channels.

Channels Explorer Bar

Icons with Visual Clues

When designing your icons, use different images, colors, or shapes to indicate whether an item is a container for other subitems or is actual content. This will help the user discover your channel's content.

Update Gleams

The channel bar provides the user with a 14H x 14W "gleam" to indicate when content has been updated. This gleam is a triangular overlay applied to the upper-left corner of a channel logo. When authoring images for any size, it's important not to place critical text or visual elements in this area, because it will be covered when the gleam is visible. Gleams are also overlaid on any 16H x 16W icon in the channel's hierarchy when that page has been updated. The gleam placed on icons is 7H x 7W.

Guideline Summary for Active Channel Images

Use the following guidelines when authoring Active Channel images:

  • Logos for the desktop must use a predominately black background. The appearance of the channel bar needs to blend into the Active Desktop, which uses a black background. This reduces visual clutter for the user and helps the logos visually tie in to the desktop Channel Bar user interface.
  • When creating the large logo, do not bleed an image on the right. If the user resizes the Channels Explorer Bar, the image will be cropped and the space to the right of the logo will be filled with the upper-right corner pixel color. Design your large logo with this in mind.
  • Provide consistent elements in both large logo sizes. When creating these logos, try to include a visual tie-in so users can recognize the channel in the transition from desktop to browser. When users click your desktop logo, they should be able to easily recognize its larger counterpart inside the browser.
  • Provide consistent elements in icons for pages and folders. Icons for pages and folders should tie in visually with their logo. Try to avoid creating too many icons, because it may be difficult for users to recognize all of them.
  • Be aware of the location of the update gleam. Avoid putting critical text or visual elements in the upper-left corner, because this area will be covered by the gleam for channel updates.


Using Dynamic HTML with Active Channels

A variety of Dynamic HTML features can be used to modify the appearance of a Web page, including changing the text or images that are displayed. As an example, the following steps show how a publisher might use the window.external.isSubscribed method to hide an Add Active Channel logo button if its associated channel is already subscribed.

Assuming the Add Active Channel button was placed on a Web page as previously described, the page would include the following Add Active Channel button:

<a name="channelA"
href="http://www.microsoft.com/ie/ie40/download/?/ie/ie40/download/redirect.htm">
<img src="IEAddChannel.gif" border=0 width=136 height=20></a>
<script language="JavaScript">
    if ( isMsie4orGreater()) { channelA.href ="urlToCDF"; }
</script>

Step 1. Add the ID attribute to the anchor element. The value must be unique.

<a name="channelA" id="idA"
href="http://www.microsoft.com/ie/ie40/download/?/ie/ie40/download/redirect.htm">
<img src="IEAddChannel.gif" border=0 width=136 height=20></a>
<script language="JavaScript">
    if ( isMsie4orGreater()) { channelA.href ="urlToCDF"; }
</script>

Step 2. Include the following script between the page's <HEAD> and </HEAD> tags. Note that the isMsie4orGreater function should already exist in the HEAD section of this page.

<SCRIPT LANGUAGE="JavaScript">
function HideIfSubscribed(elementID, urlToCDF){
if (window.external.isSubscribed(urlToCDF)) {ss.addRule("#"+ elementID,"visibility: hidden");}}

var ss = null;
ss = document.createStyleSheet()
if(isMsie4orGreater()){ //Test if the browser is IE
// For each element you want to conditionally hide, include the following line
// (uniqueID is the unique value for the ID attribute of the element and
// urlToCDF is the URL to the channel's CDF).
HideIfSubscribed("uniqueID","urlToCDF");
}
</SCRIPT>

When using these scripts, remember that the URLs of the channels must include the same protocol and secondary domain name as the page that contains the scripts. Also, any element in Dynamic HTML that has the visibility property can be hidden using the same code.

The following HTML page shows a full example of the scripting shown above.

<HTML>
<HEAD>
<SCRIPT LANGUAGE="JavaScript">
    function isMsie4orGreater() {
        var ua = window.navigator.userAgent;   var msie = ua.indexOf ( "MSIE " );
        if  (msie > 0)
            {return (parseInt ( ua.substring ( msie+5, ua.indexOf ( ".", msie ) ) ) >=4)
            && (ua.indexOf("MSIE 4.0b") <0) ;}
        else    {return false;}}

    function HideIfSubscribed(elementID, urlToCDF){
        if (window.external.isSubscribed(urlToCDF))
        {ss.addRule("#"+ elementID,"visibility: hidden");}}

    var ss = null;
    if(isMsie4orGreater()){ //Test if the browser is IE
        ss = document.createStyleSheet()
        HideIfSubscribed("idA","http://www.mycorp.com/channelA.cdf");
    }
</SCRIPT>
</HEAD>

<BODY>
<a name="channelA" id="idA"
href="http://www.microsoft.com/ie/ie40/download/?/ie/ie40/download/redirect.htm">
<img src="IEAddChannel.gif" border=0 width=136 height=20></a>
<script language="JavaScript">
    if ( isMsie4orGreater()) { channelA.href ="urlToCDF"; }
</script>

</BODY>
</HTML>

If the Web page contains more than one Add Active Channel or Add to Active Desktop logo button, the name and ID attributes must be unique.


Netcaster CDF Compatibility Notes

Due to the similarities between HTML and the Channel Definition Format, other browsers might be able to perform site crawling on a CDF file. This section describes the CDF file compatibility issues related to the release of Netscape Netcaster. For more information about CDF files and the implementation of this standard, see Microsoft's Webcasting White Paper.

Site Crawling a CDF File

Site crawling is the process of a browser proceeding through the following steps:

  1. Retrieve an HTML page.
  2. Store that page locally on a user's computer.
  3. Find the links (anchors) in the HTML page.
  4. Repeat this process from step 1 for each link (anchor) to an HTML page.
  5. Stop the above process when the browser has run out of links to follow or when the process has repeated enough times based on some criteria.
  6. Retrieve the actual content for each link to a non-HTML document, such as an image file or a text file.

Netcaster can use CDF files only toward site crawling and not for full CDF processing. For this to happen, Netcaster must use a CDF file as though it is an HTML page. The key to a browser site crawling CDF files lies in the anchor (A) element, which defines links in HTML.

<A HREF="http://www.microsoft.com/">Visit Microsoft!</A>

This element identifies links for browsers to follow when site crawling. The anchor element can be found inside ITEM and CHANNEL elements of a CDF file. The HREF attributes of these anchor (A) elements identify which HTML pages are displayed when items and channels are selected.

<CHANNEL>
    <A HREF="http://www.microsoft.com/cover.htm"></A>
    <ITEM>
        <A HREF="http://www.microsoft.com/page1.htm"></A>
        <TITLE>Page 1</TITLE>
    </ITEM>
</CHANNEL>

When a browser uses the above CDF section as an HTML page for site crawling, it identifies the links "http://www.microsoft.com/cover.htm" and "http://www.microsoft.com/page1.htm". How the remaining content of the CDF file is used by the browser is less important. Some of it will be rendered, while most of it is ignored. In the majority of circumstances, a CDF file will never be displayed as HTML; it will simply be used for site crawling.

It is important to note that because Netcaster does not take advantage of the BASE attribute in a CDF file, relative URLs will be resolved by Netcaster against the base URL of the CDF file itself rather than the BASE attribute. For this reason, it is suggested that when authoring a CDF file for both Netcaster and Internet Explorer, either omit BASE attributes or make sure their value is the base URL of the CDF file itself. For example, if the CDF http://msn.com/channels/channel2.cdf has any BASE attributes, they should have the value "http://msn.com/channels/".

MIME Types and Extensions

For Netcaster to use a CDF file toward site crawling, it must process the file as an HTML file. To process the CDF file as HTML, one of the following three criteria must be met:

  • A copy of the original CDF file must have the extension "htm" or "html".
  • The HTTP server providing the CDF files must return the MIME (content) type "text/html" to browsers without full CDF support, and "application/x-cdf" to clients with full CDF support.
  • The browser site crawling the CDF files must have the extension or MIME type of CDF files, "cdf" and "application/x-cdf", configured to be opened as HTML by the browser itself.

After one of these criteria has been met, a Netcaster user can subscribe to a channel defined by a CDF file. The user simply proceeds in the usual manner when subscribing to any Web page, except entering the URL of the CDF file.

Netcaster CDF Site Subscriptions

In Netcaster, when a user subscribes to a channel by specifying the URL of a CDF file created through the mentioned methods, the initial page for the channel will not be a normal HTML page. Instead, it will be a CDF file rendered as an HTML page and will probably not appear as desired. To remedy this situation, a channel author can create an intermediate HTML page to represent the channel content along with a reference to the CDF file. This can be achieved using Netscape's LAYER tag. A hidden LAYER tag referencing the new CDF file is inserted into the desired initial HTML as follows:

<LAYER SRC="cdf_file.htm" VISIBILITY=HIDDEN></LAYER>

With this additional work, a user can use the URL of the intermediate HTML page rather than the URL to the CDF file when subscribing to a channel in Netcaster. To enable Netcaster to automatically subscribe to a CDF channel, script can be inserted into the intermediate HTML page as specified in Netscape documentation. This would allow a CDF channel to be subscribed to when a user clicks a button on the intermediate HTML page. The following examples show a CDF file and an intermediate HTML page that could be used with Netcaster.

A CDF file named "cdf_file.cdf":

<?XML VERSION="1.0"?>
<CHANNEL HREF="http://msn.com/default.htm">
    <ABSTRACT>This channel was created using the proposed CDF standard.</ABSTRACT>
    <LOGO HREF="http://msn.com/logo.gif" STYLE="IMAGE" >
    <SCHEDULE> <INTERVALTIME DAY="1" /> </SCHEDULE>
    <!-- the following items are needed for offline use -->
    <ITEM> <A HREF="http://msn.com/page1.html"></A> </ITEM>
    <ITEM> <A HREF="http://msn.com/page2.html"></A> </ITEM>
    <ITEM> <A HREF="http://msn.com/page3.html"></A> </ITEM>
</CHANNEL>

An intermediate Netcaster-compatible HTML page named "channel.htm" is provided below. This page references a copy, named "cdf_file.htm", of the above CDF file.

<HTML>
<BODY>

<LAYER SRC="cdf_file.htm" VISIBILITY=HIDDEN></LAYER>

<SCRIPT language="JavaScript1.2" >

var nc = components["netcaster"];
nc.activate();
var chan = nc.GetChannelObject();
chan.url = "http://msn.com/channel.htm";
chan.name = "My Channel";
chan.desc = "This Channel was created using JavaScript API extensions";
chan.cardURL = "http://msn.com/logo.gif";
function openDialog() { nc.AddChannelObject(chan); }

</SCRIPT>

</BODY>
</HTML>


Creating Active Desktop Items

The Microsoft® Internet Explorer 4.0 Active Desktop™ is capable of hosting any HTML item, such as Web pages, Java applets, ActiveX™ Controls, floating frames, and images. With this technology, users can create a highly customized environment that automatically brings their favorite Web content to the desktop. Web publishers can leverage their existing tools and production processes to enhance their Web content with Dynamic HTML support. The resulting integration of the desktop and the Web benefits users through an enhanced and easier Web experience. Web publishers also benefit from the increased presence in the users' working environment.

For the latest information about Active Desktop items, refer to the list of Frequently Asked Questions (FAQ) in the Internet Client SDK.

Overview: Active Desktop and Active Channels

Publishing Information on the Active Desktop

How the Active Desktop Works

Active Desktop Item Development Guidelines

How to Develop an Active Desktop Item

Overview: Active Desktop and Active Channels

Until now, the primary target for Web-based content has been the browser window. Most Web publishers today are forced to optimize their content to fit into a medium-sized browser window, based on the default window size of the browser. Internet Explorer 4.0 opens new opportunities for content by enabling your content to grow beyond the browser window, in two directions at once. The first direction lets you offer your customers a more focused browsing experience by taking over the entire screen, minimizing most of the "chrome" (toolbars) surrounding your content, and taking full advantage of Dynamic HTML extensions. This helps Web publishers provide a multimedia experience that is more engaging than anything currently possible inside a browser window. This is the idea behind Active Channels.

At the same time, Internet Explorer 4.0 enables your content to grow in a second direction. Now you can augment your content offering by providing your customers a more immediate, condensed experience. This is accomplished with lightweight entry points to top-level summaries and headlines in a small HTML page displayed directly on the user's Active Desktop. This HTML page presents top-level links and lets your customers point and click to open a larger window and absorb the details waiting underneath. This is the idea behind items on the Active Desktop.

For the user, Active Desktop items and Active Channels complement each other to provide different types of information in a useful manner. In a typical situation, users would log onto their computer and immediately see your Active Desktop item (along with several others) on their desktop. The user scans your Active Desktop item to see highlights and news as of the last scheduled update. The user can then click on any link inside the item to see the full story. At this point, the Active Desktop item can launch the user directly into your Active Channel instead of loading the associated URL into a regular browser window. This example illustrates how the Active Desktop item presents the content summary and the Active Channel presents the details.

For the content provider, Active Desktop items and Active Channels are also a great match. This is because the same knowledge and experience you build when authoring an Active Channel also applies to authoring Active Desktop items. Both Active Channels and Active Desktop items use Dynamic HTML to make the most engaging use of their screen area, while at the same time conserving bandwidth. It is important to note that both Active Channels and Active Desktop items require a separate Channel Definition Format (CDF) file to configure their update schedules and presentation requirements.

Active Desktop Features

Because Active Desktop items and Active Channels leverage the same technology, many of the features that apply to Active Channels also apply to Active Desktop items. These features include:

Subscriptions | Icons are placed in the Subscriptions folder to let users manage update schedules and notification attributes.
CDF Support | Subscription icons are based on the information in a CDF file that you author. The CDF file contains special tags to alert Internet Explorer 4.0 that the content is intended for use as an Active Desktop item. Additional CDF elements are available to control how the item is displayed and when it is updated.
Personalized Active Channels and Passwords | Personalized password-based access to a Web publisher's content is available. Since an Active Desktop item is just a tiny Web page, navigating to the content is the same as navigating to a page in a browser window, so you can use a CDF file to support automatic login and password verification.

Publishing Information on the Active Desktop

The following sections describe how Web publishers can create and display content in an Active Desktop item. Examples of Active Desktop item installations are provided at http://www.microsoft.com/ie/ie40/gallery.

Active Desktop items are placed beside existing desktop shortcuts to give users a highly customizable space for creating dynamic links to their favorite Web content. Active Desktop items are typically designed to provide summary information in a small amount of screen space. Most items offer hot spots so the user can click on that area of the item to open a new browser window; the user can then read the full story or browse through the rest of the Web site. The following screen snapshot shows an example of an Active Desktop hosting two Active Desktop items on the right side of the screen, with the standard desktop shortcuts placed on the left edge of the screen.

Active Desktop items

Possible Active Desktop items include:

  • Tickers for sports scores, stock quotes, or weather.
  • Headline lists for news stories or announcements.
  • Pop-up broadcast messages for internal corporate announcements.
  • Notifications for new mail, chat, or public discussion forums.
  • Pictures of sports highlights or breaking news stories. A picture can be configured for daily update; clicking the picture could launch a browser window to preview the related story.

Active Desktop items are completely customizable:

  • By the end user.

    An item can be positioned and resized anywhere on the desktop. The user can also customize schedules for updating each item separately.

  • By the corporation.

    MIS managers can pick and choose a mix of default Active Desktop items for their clients by workgroup or division. Managers can also lock the Active Desktop items to prevent incorrect configuration by end users and filter out undesirable content by implementing a full range of security restrictions. Desktops can be configured for roaming access across workstations, and all settings can be administered remotely.

  • By the publisher.

    Items can consist of any HTML-based content, including Dynamic HTML, ActiveX Controls, Java applets, scripting, frame sets, and so on. Items can be initially configured with a default update schedule so content providers can manage their server traffic. This is accomplished with the use of a Channel Definition Format (CDF) file.

Active Desktop items are an evolution of Internet Explorer 3.0 desktop shortcuts. They can be any size or shape and can display any HTML-based content. Items are dynamic and can be configured to update at regularly scheduled times, so their content is always up to date. As part of the information delivery system in Internet Explorer 4.0, the URL associated with any Active Desktop item is automatically added to the user's Subscriptions folder. This has the following effects:

  • All content is automatically cached offline in the user's cache. This makes content available for browsing when no Internet connection is currently available.
  • Users will be automatically notified whenever the item is changed on the server. Internet Explorer 4.0 provides this service automatically for all subscriptions.
  • Each Active Desktop item can be scheduled individually for updates on the client. For example, users could display a sports ticker that is updated once an hour, a news headline service that is updated once a day, and a comic strip that is updated once a week, all sharing space on the same desktop. Internet Explorer 4.0 automatically refreshes the associated HTML content on the desktop whenever the update occurs.

Site subscription data flow

How the Active Desktop Works

The Active Desktop in Internet Explorer 4.0 is built from two separate layers. The transparent icon layer exposes all the user's existing desktop shortcuts, and the background HTML layer hosts all Active Desktop items. The HTML layer is described by a single, local HTML file called Desktop.htm that is created and edited automatically by Internet Explorer 4.0. This file contains the following:

  • HTML tags that represent each Active Desktop item. Each Active Desktop item consists of a single HTML tag with arbitrary x- and y-positions. Refer to the documentation on Positioning for a description of 2-D positioning and layering with Dynamic HTML. The HTML tag used for an Active Desktop item can be either an image (IMG tag) or a floating frame (IFRAME tag). The tag is generated automatically by Internet Explorer 4.0. The floating frame is the most commonly used approach, because it neatly encapsulates an entire arbitrary HTML document that can contain anything the publisher desires. In either case, there is a single URL that points to the actual content.
  • An ActiveX control that enables moving and resizing of the Active Desktop items and also helps manage the list of items.
  • Any other static HTML that the user wants to have in the background. By default, this is just a reference to the user's chosen wallpaper, which is exposed as the background watermark for the HTML page.

Active Desktop layers

Active Desktop Item Development Guidelines

An item is nothing more than a small, borderless frame that displays a Web page and is embedded on the Active Desktop. The Web page can contain anything that a standard Web page can contain, including ActiveX Controls, Java applets, Dynamic HTML, and so on. The Active Desktop lets the user add and remove the frames at will, as well as adjust their size and position with the mouse.

Users can choose to create an Active Desktop item out of any existing Web page, but the best ones are Web pages that have been specifically designed to be used as Active Desktop items.

When designing an Active Desktop item, there are several guidelines to keep in mind.

  • The item must work offline.

    Since most dial-up users do not have a constant connection to the Internet, an Active Desktop item should display some reasonable content in the absence of a connection. This is of key importance, because the desktop is immediately visible when the user launches the operating system, even before the user has a chance to initiate a dial-up session. An Active Desktop item that displays a blank, gray square or an error message while the user is offline is neither useful nor attractive. For this reason, any necessary data files the item requires should be configured to be cached on the user's computer. This can be particularly tricky for Java applets, because image objects typically sit in separate GIF or JPEG files on the Web server. Fortunately, the Internet Explorer 4.0 subscription feature can be configured to cache any object referenced by an Active Desktop item by including it in the CDF file with the ITEM element.

    In the typical case where an item is built from an HTML document inside a floating frame, Internet Explorer 4.0 subscriptions can be set to automatically download any inline images, sounds, objects, or applets, and also any number of HTML links n levels deep. It is important to note that Java applets cannot be pre-cached if the Java classes are not wrapped together in a CAB, ZIP, or JAR file. If the classes are in separate files, Internet Explorer cannot determine the Java class dependencies and cache appropriately because Java binds classes dynamically.

    Java- and ActiveX-based desktop items should also be authored to give an error or informational message when not connected to the network to prevent an empty gray box from being displayed. Also, to read from the cache when not connected to the network, Java applets should call setUseCaches(TRUE) in their java.net objects. For more information about authoring Java or ActiveX desktop items, review the list of frequently asked questions.

    Active Desktop items can also specify individual subscriptions for any data files or objects it might reference. Please note that Java applets and ActiveX Controls must be signed so they can access content from the offline cache. For more information about signing Java applets or ActiveX Controls, see http://www.microsoft.com/java/ or http://www.microsoft.com/windowsdna/.

  • Avoid using in-place navigation controls.
    Active Desktop items are meant to be lightweight and therefore have no navigation controls available for the user to move backward and forward. By default, clicking a link inside an Active Desktop item creates a new browser window. The intended purpose of an Active Desktop item is to provide quick summary information and an easy browser-launching mechanism if the user wants more information. Therefore, authors shouldn't create in-place navigation controls, and they shouldn't depend on the Back and Forward commands being available to the item. Active Desktop item authors should not make any assumptions about the context in which the item is running. More information about properly handling the context in which an Active Desktop item runs is available in the list of frequently asked questions.

  • Smaller is better.

    An Active Desktop item needs to share the desktop space with any other icons or Active Desktop items the user has selected. Because this space is completely customizable by the user, Active Desktop items should be authored to be as small as possible to display their desired content. This gives Active Desktop users the maximum flexibility to arrange their desktop as they wish. A good benchmark is to make sure that the Active Desktop item takes up no more than one-sixth the area of the screen. By default, Internet Explorer lays out new Active Desktop items on a 3´2 grid. As more items are added to the desktop, they will start to overlap each other. For a desktop at a resolution of 640´480, allowing for reasonable spacing between items, this would translate into a maximum size of no more than 200´200 pixels. This size specification is merely a guideline. Internet Explorer 4.0 does not itself enforce any restrictions on the size of an Active Desktop item.

    Active Desktop item layout

  • Avoid pop-up messages.

    Today it is common for ActiveX Controls, Java applets, and scripting content to notify the user of error messages or warnings by using modal dialog boxes that overlap the browser window. This is fine when the browser window is in the foreground. However, launching a modal dialog box from an Active Desktop item might confuse the user. If an Active Desktop item delivers a pop-up message to the user while the desktop is not in the foreground, the user might not be sure where the message came from or what to do about it. The typical situation to avoid is showing error messages when an Active Desktop item can't connect to the server. In these cases, the item should display some type of status message in the Active Desktop item itself, preferably with a hot spot or link that lets the user get more information and figure out how to proceed.

  • Use the default color palettes.

    A large portion of Internet Explorer 4.0 users have displays that are limited to 256 colors. For these users, Internet Explorer chooses a default palette that is intended to give a broad range of hues across the entire color spectrum. Therefore, when authoring an Active Desktop item, it is important to keep in mind exactly what the image colors will look like on a 256-color display.

  • Include a rating tag in your item.

    Content Advisor is a feature in Internet Explorer that allows parents and supervisors to filter out Web content based on rating labels. This feature is based on the World Wide Web Consortium (W3C) standard for content ratings, known as PICS (http://www.w3.org/PICS External link), or Platform for Internet Content Selection. PICS allows for any rating system to be used and lets the parents or supervisors decide what types of content are acceptable. Web publishers should include a rating tag in their HTML files because someone browsing with the Content Advisor turned on will not be able to see content that is not rated. For more information, see Internet Ratings in the Internet Client SDK.

  • Handle expiration dates.

    Web publishers can define an expiration date for time-sensitive desktop items. This information is specified by the STOPDATE attribute of the SCHEDULE element. For example, a typical desktop item schedule might look like this:

    <Schedule STOPDATE="1998.11.05T08:15-0500">
    <IntervalTime DAY="1" />
    <EarliestTime HOUR="12" />
    <LatestTime HOUR="18" />
</Schedule>

    This schedule shows that on November 5, 1998, Internet Explorer will stop refreshing this desktop item's data from the source URL. The desktop item will remain on the user's desktop, but its content will become stale. A few days before the desktop item expires, Web publishers should replace the content that is pointed to by the desktop item with a notification page. This page should explain to users that the desktop item is no longer valid and that they should either close it or get a new one. The actual desktop item should not be deleted from the HTTP server until after the expiration date to avoid having broken desktop items on users' desktops.

How to Develop an Active Desktop Item

The process for creating an Active Desktop item is very similar to the process for developing a simple channel. In fact, the same steps apply:

  1. Design the Active Desktop item.
  2. Create the CDF file.
  3. Post the CDF file.
  4. Offer the Active Desktop item to users.

Design the Active Desktop Item

An Active Desktop item is just a small Web page. This page gets embedded in the user's Active Desktop as a floating frame inside a single Desktop.htm file that describes the user's HTML wallpaper and all other Active Desktop items.

Note Try implementing Dynamic HTML in your Active Desktop item. It is common for an Active Desktop item to cycle through a set of headlines or summary information. Dynamic HTML makes it possible to achieve this effect without using Java or ActiveX code.

Create the CDF file

Creating a CDF file is very similar to creating a CDF file for an Active Channel. The primary rule is that you are required to create a separate CDF file for each Active Desktop item or Active Channel you author. For more information about CDF elements and their syntax, see the documentation on CDF Extensions for Active Desktop Items and the CDF Reference for Active Channels.

Basic syntax: The ITEM and USAGE elements

The CDF for an Active Desktop item must include at least one ITEM element under the top-level CHANNEL element with a USAGE child element marked as "DesktopComponent" (see the example below). It is this USAGE element that tells Internet Explorer the CDF file refers to an Active Desktop item, as opposed to an Active Channel. The CDF file should also include a SCHEDULE element to indicate when the item will be updated.

Additional ITEM elements

Since an Active Desktop item is comprised of a single HTML page, the only ITEM you need to include in the CDF file is the small Web page you want to embed in the user's desktop. This should be marked with the USAGE element as indicated in the example below. If you like, you can include additional ITEM elements for each page that the Active Desktop item links to. Including these as ITEMs in the CDF file has the additional benefit of keeping those pages "subscribed to" and available for offline viewing. The ITEMs other than the actual Active Desktop item URL are not exposed to the user. Note that this differs from Active Channels, which present a hierarchical list of their ITEM tags to the user in the form of the Internet Explorer Channel Pane.

CDF restrictions on Active Desktop items

The following restrictions are placed on CDF files for Active Desktop items:

  • If your CDF file has more than one ITEM element marked with USAGE equal to "DesktopComponent", Internet Explorer uses the first one it encounters.
  • Only the top-level CHANNEL element is valid. Nested CHANNEL elements have no effect because these additional items don't correspond to any list or hierarchy that the user can access.
  • USAGE elements set to anything other than "DesktopComponent" are ignored.

Active Desktop item CDF example

The following example shows a CDF file for an Active Desktop item.

<?XML version="1.0"?>
<Channel>

        <Schedule STOPDATE="1998.11.05T08:15-0500">
                <IntervalTime DAY="1"  />
                <EarliestTime HOUR="12"/>
                <LatestTime   HOUR="18"/>
        </Schedule>

        <Item HREF="http://www.microsoft.com" LastMod="1996.11.05T08:15-0500">

                <Title>My News Ticker</Title>    <!-- Friendly name               -->

                <Usage VALUE="DesktopComponent"> <!-- Required                    -->
                        <OpenAs VALUE="HTML"/>   <!-- "HTML" (default) or "Image" -->
                        <Width  VALUE="200" />   <!-- Width in pixels             -->
                        <Height VALUE="80"  />   <!-- Height in pixels            -->
            <CanResize VALUE="Yes"/> <!-- Yes (default) or No	    -->
                </Usage>
        </Item>

        <!-- Other Item tags may go here.  IE4 won't display them anywhere, but   -->
        <!-- will use them for site crawling and place them in the user's cache. -->

        <Item HREF="http://www.foosports.com/topstories.html" LastMod="1996.11.05T08:15-0500" >
        </Item>

</Channel>

Post the CDF File

Post the CDF file by making it publicly available on your Web servers.

Offer the Active Desktop Item to Users

As with Active Channels, a link or button should be placed on any Web page that references the CDF file to allow users to subscribe to the new Active Desktop item. When the user clicks the link, Internet Explorer 4.0 automatically detects the USAGE element, which tells it that the CDF refers to an Active Desktop item. Internet Explorer 4.0 then activates the Active Desktop item Subscription Wizard on the user's computer and allows the user to receive updated information about this Active Desktop item. As the content contained in the Active Desktop item is added, removed, or modified, Web publishers should update the CDF file to reflect the changes. Information about button images and scripts used for enabling subscriptions is available in the Active Channels documentation.


Creating Software Update Channels

Software Update Channels are specialized channels that provide the ability to notify users of software updates and also to deliver and install program files onto users' computers.

Software developers can use Software Update Channels as a method of delivering updated versions of their software to their users. All users who subscribe to the developer's Software Update Channel will receive notification that a new version is available.

Corporations can use Software Update Channels to distribute applications and software updates to all of the desktops connected to their corporate network instead of updating each system individually.

Distributing Software

To distribute software using a Software Update Channel, the developer or corporation needs to:

  1. Create a Software Update Channel.
  2. Create an Open Software Description (OSD) file.
  3. Create a distribution unit.

Creating a Software Update Channel

A Software Update Channel is defined with a Channel Definition Format (CDF) file, which is written in the Extensible Markup Language (XML). For more information on CDF files, see CDF Reference for Active Channels. For Software Update Channel extensions to the CDF, see VERSION= (SOFTPKG)
. For information on XML, see XML Object Model documentation.

The VALUE= attribute of the USAGE tag is set to the value "SoftwareUpdate" in the CDF file to notify Microsoft® Internet Explorer 4.0 that this is a Software Update Channel. The shortcut for the channel will be created in the Software Updates folder in the Favorites menu.

For a Software Update Channel, the CDF file would contain details on the software distribution unit available. These details include:

  • The unique string name of the distribution unit. One way to ensure the name is unique is to use a globally unique identifier (GUID).
  • The title of the distribution unit, which should be something meaningful to the user.
  • The operating system for which the distribution unit is available.
  • The location of the distribution unit.

The following is an example of a CDF file for a Software Update Channel for a fictitious company, Awesome Computers.

<CHANNEL HREF="http://www.server.com/setup-page.htm">
<SELF HREF="http://www.awesome_computers.com/awesome_comp.cdf" />
<USAGE VALUE="SoftwareUpdate" />
<TITLE>Awesome Computer's Software Update Channel</TITLE>
<ABSTRACT>Awesome Computers' site for updated drivers and programs for all our awesome systems.
</ABSTRACT>

<LOGO HREF="http://www.awesome_computers.com/ac-channel.gif" STYLE="IMAGE" />
<LOGO HREF="http://www.awesome_computers.com/ac-channel.ico" STYLE="ICON" />

    <SOFTPKG NAME="{D27CDB6E-AE6D-11CF-96B8-444553540000}"
        HREF="http://www.awesome_computers.com/Update.htm"
        VERSION="2,0,0,0"
        AUTOINSTALL="Yes"
        STYLE="MSICD">
        <TITLE>Update for the system diagnostic control for Windows 95</TITLE>

        <ABSTRACT>System diagnostic control that tracks download efficency information.
        </ABSTRACT>

        <USAGE VALUE="email" />
        <IMPLEMENTATION>
                <OS VALUE="win95" />
                <CODEBASE HREF="http://www.awesome_computers.com/diagnostic.cab" />
        </IMPLEMENTATION>
    </SOFTPKG>
</CHANNEL>

The NAME= attribute of the VERSION= (SOFTPKG)
tag contains the unique string name for the distribution unit, which is a GUID in the example.

The TITLE tag contains the friendly title that is used to notify the user of the software distribution unit's availability.

The IMPLEMENTATION tag contains the information on the operating system and the location of the code. The VALUE= attribute of the OS tag indicates the operating system for which the distribution unit is available (Microsoft® Windows 95® in the example), and the HREF= attribute of the CODEBASE tag indicates the location of the distribution unit. If no CODEBASE tag is provided, the Active Channel acts as an advertisement for the software package. The content in the ABSTRACT tag should contain information about where to download the advertised software package.

The CDF file should contain scheduling information so that the user's computer knows how often to check the server for updates. The schedule should also provide information to let the user's computer randomize its checks. For details about adding schedule information to the CDF file, see the SCHEDULE tag in the CDF Reference for Active Channels.

For Software Update Channels that are provided for a one-time download, the DELETEONINSTALL tag can be added inside the VERSION= (SOFTPKG)
tag in the CDF file. The channel will be deleted after the installation of the software package has been completed.

Creating the Open Software Description file

The Open Software Description (OSD) file is also written in XML and is similar to the CDF file. This file contains the information about what the user's computer needs to do after it downloads the distribution unit from the server. For more information on OSD files, see http://www.microsoft.com/sitebuilder/standards/osd/ External link. For more information on XML, see http://www.microsoft.com/sitebuilder/standards/xml/ External link.

The following example is a sample OSD file for Awesome Computer's updated diagnostic control that indicates a download location for the updated control.

<?XML version="1.0" ?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd" >
<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

<SOFTPKG NAME="{D27CDB6E-AE6D-11CF-96B8-444553540000}" VERSION="2,0,0,0" STYLE="MSICD">
    <TITLE>System diagnostic control for Windows 95</TITLE>
    <ABSTRACT>This distribution contains updated diagnostic control.
    </ABSTRACT>

    <msicd::NATIVECODE>
        <CODE   NAME="diagnose.ocx"
                        CLASSID="{D27CDB6E-AE6D-11CF-96B8-444553540000}"
                        VERSION="2,0,0,0">
                <IMPLEMENTATION>
                    <OS VALUE="win95" />
                    <CODEBASE HREF="http://www.awesome_computers.com/diagnose.cab" />
                </IMPLEMENTATION>
        </CODE>
    </msicd::NATIVECODE>
</SOFTPKG>

The <!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd" > line sets the Document Type Definition (DTD) file, which defines the formal grammar for a type document. In this case, it is defining the grammar for an OSD file. This file allows an XML parser or other verifier to check if the OSD file is well-formed.

The <?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?> line specifies additional legal elements that will use the name space identifier defined by the as= attribute. For this example, the name space is "msicd".

The NATIVECODE tag defined in the Msicd.dtd file notifies the user's computer that the distribution unit is written in the native code of the operating system noted in the VALUE= attribute of the OS tag. The JAVA tag is used if the distribution unit contains a Java class, a Java application, or JavaBeans.

The DEPENDENCY tag can be added inside the VERSION= (SOFTPKG)
tag section to indicate a software dependency. The DEPENDENCY tag allows developers or corporations to have the distribution unit downloaded only if certain conditions exist. For example, you could set a dependency that a particular distribution unit has to be installed. If it is installed, it will download a distribution unit that contains a patch for the installed software.

Describing Java packages

Describing Java packages is similar to describing native code distribution units, except they use the JAVA tag instead of NATIVECODE and the PACKAGE tag instead of CODEBASE.

The following example shows the VERSION= (SOFTPKG)
tag section that describes a Java package.

<SOFTPKG NAME="StorePackage" VERSION="1,0,0,0">
<TITLE>The StoreData class</TITLE>

<ABSTRACT>StorePackage contains a single class called StoreData.
</ABSTRACT>

<msicd::JAVA>

    <PACKAGE NAME="com.ms.StorePackage" VERSION="1,0,0,2">
    <IMPLEMENTATION>
    </IMPLEMENTATION>
    </PACKAGE>

</msicd::JAVA>

</SOFTPKG>

Describing Java applications

The following example shows the VERSION= (SOFTPKG)
tag section that describes a Java application.

<SOFTPKG NAME="Some Application for Java" VERSION="1,0,0,0">

    <TITLE>MS Office for Java</TITLE>

    <ABSTRACT>Some Application for Java is a standalone Java application.
    </ABSTRACT>

        <msicd::JAVA>
            <NAMESPACE>Some Application for Java</NAMESPACE>
            <PACKAGE VERSION="1,0,0,2">

                <IMPLEMENTATION>
                </IMPLEMENTATION>

            </PACKAGE>

        </msicd::JAVA>

</SOFTPKG>

Describing JavaBeans

The OSD file can describe both JavaBeans and Microsoft® ActiveX™ Controls wrapped as JavaBeans. ActiveX Controls wrapped as JavaBeans require the CLASSID= attribute in the CLASS element and the ICON or TYPELIB element, while a regular JavaBean does not require these elements.

The following is a sample description of an ActiveX control wrapped as a JavaBean.

<msicd::JAVA>

    <NAMESPACE>some-namespace-string</NAMESPACE>

    <PACKAGE NAME="com.ms.JPMBrowser" VERSION="1,0,0,0">
        <CLASS NAME="Browserbean" CLASSID="{383807B5-2C60-11D0-A31D-00AA00B92C04}">
            <ISBEAN />
            <ICON FILENAME="Browser.ico" />
            <TYPELIB CLASSID="{...}" />
        </CLASS>
    </PACKAGE>
    <IMPLEMENTATION />
</msicd::JAVA>

Creating a distribution unit

The distribution unit contains the OSD file and the files that belong to an application. These files are compressed using the cabinet (CAB) compression format. The CAB file then must be digitally signed by a certificate authority. For more information on CABs, see the CAB SDK, which is provided as a self-extracting executable file (Cab-SDK.exe) in the \bin directory of the Internet Client SDK.

There are three ways to package a distribution unit:

  • Only the OSD file in the CAB file.
  • The OSD file and application files in the CAB file.
  • The OSD file and another CAB file in the CAB file.

Having only the OSD file in the CAB file is the minimal distribution unit possible. The OSD file would indicate the URL of the resource containing the software update in the CODEBASE tag of the OSD file.

The simplest case is to package the OSD file with the program files into the CAB file. In this case, the OSD file does not need a CODEBASE tag in it. When no CODEBASE is given, Internet Explorer automatically looks for the program file in the same CAB file where the OSD file was found.

When multiple program files are involved, and especially when the program files are separated into multiple subdirectories, it is easier to organize the distribution unit by creating a CAB file that contains the OSD file and another CAB file that contains the program files.

Related Topics

For more information on software update channels and OSD, see the following:

Open Software Description (OSD)
Contains more information about OSD and references for all the elements supported by OSD.
Internet Component Download
Contains information on the mechanism that handles the download and installation of software through the Internet.


CDF Reference

These documents contain reference information for Channel Definition Format (CDF) elements used with Active Channels, Active Desktop items, and Software Update Channels.

CDF Reference for Active Channels

CDF Extensions for Active Desktop Items

CDF Extensions for Software Update Channels


CDF Reference for Active Channels

The following section describes the suggested revision to Channel Definition Format (CDF) that Microsoft and other partners are presenting to the W3C (World Wide Web Consortium). For reference purposes, this revision is CDF version 0.4. CDF is an application of the Extensible Markup Language (XML). The original submission of CDF to the W3C can be found at http://www.w3.org.

CDF Syntax

CDF Elements

CDF Syntax

Note that the syntax might vary for different elements. The following table describes the possible formats in which the tags might appear.

Description Example
Empty element with attributes
<ELEMENT ATTR1="value" ATTR2="value"/>
Element with content and end tag
<ELEMENT>Element Content Here</ELEMENT>
Parent element with attributes and child elements
<PARENT ATTR1="value">
    <CHILD1>
        Content
    </CHILD1>
    <CHILD2 ATTR1="value"/>
</PARENT>

CDF Parsing Rules and Hints

To avoid some common mistakes, keep the following rules in mind when creating a CDF file.

Special Characters When placing text content between an element start and end tag, you must encode the following characters to prevent CDF parsing errors.
Character Encoded value
< &lt;
> &gt;
' &apos;
" &quot;
& &amp;

For a complete list of other named character set entities, see the documentation on HTML Character Sets (Charsets) and Named Entities.

Character Encoding | The CDF file supports encoding for any ASCII character with the format &#nnn. For example, the ampersand character could also be encoded with its ASCII decimal value of 38 by using the string &#038.
Attribute Syntax | All attribute values must be enclosed in quotation marks, even if the value is a number.
Comments | Any text you want to be ignored by the CDF parser should be placed between the comment start tag (<!--) and the comment end tag (-->).

CDF Elements

This section describes the elements and associated attributes used to create Channel Definition Format (CDF) files for Active Channels. Some CDF files may be used for other types of Webcasting, such as Active Desktop items and Software Update Channels, depending on the value of the USAGE element.

?XML A ABSTRACT CHANNEL
EARLIESTTIME HTTP-EQUIV INTERVALTIME ITEM
LATESTTIME LOG LOGIN LOGO
LOGTARGET PURGETIME SCHEDULE TITLE
USAGE


?XML

<?XML
 ENCODING="char-set"
 VERSION="n.n"
?>

Indicates an Extensible Markup Language (XML) document and specifies the version and character set for the current document. This tag should occur only once at the beginning of the CDF file.

ENCODING="char-set"
Character set used in the document. The default is "UTF-8". Additional information on character encoding and character sets is available in the CDF Parsing Rules and Hints section.
VERSION="n.n"
Major and minor version of XML the CDF file supports. If not specified, the default value is "1.0".

Number of allowed occurrences: One
Parent elements | Child elements
None | None

Example

<?XML ENCODING="UTF-8" VERSION="1.0"?>


A

<A
 HREF="url"
>

Defines a hypertext link for an element. The URL specified in the HREF= attribute will be displayed in the browser channel pane if the TITLE element is not present.

HREF="url"
Required. Specifies the URL associated with the parent element. The browser navigates to this location when the parent element is clicked.

Number of allowed occurrences: None or one (per parent element)
Parent elements | Child elements
CHANNEL | None
ITEM

The HREF= attribute of the parent element must be omitted when using the A element. To a CDF client, including the A element is functionally equivalent to using the HREF= attribute with the parent element and omitting the A element.

The end tag </A> is required.

Example

<ITEM>
    <A HREF="http://www.foosports.com/page1.htm">This is a link to page 1.</A>
</ITEM>


ABSTRACT

<ABSTRACT
 XML-SPACE="DEFAULT" | "PRESERVE" >

Represents a description of the associated CHANNEL or ITEM parent element. Microsoft® Internet Explorer displays this text in a ToolTip to the right of the icon in the browser channel pane when the cursor is paused over the channel or item title.

When applied to the top-level CHANNEL element, the abstract should appear near the top of the CDF file before any ITEM or nested CHANNEL elements.

XML-SPACE="DEFAULT" | "PRESERVE"
Specifies how white space, such as tabs, spaces, and blank lines, should be handled. The default behavior (XML-SPACE="DEFAULT") indicates that white space characters are not considered significant, and therefore some of these characters may be filtered out during file processing. Set the value of this attribute to "PRESERVE" to ensure that all white space characters are retained. This attribute can be used with any CDF element that uses significant white space. When used as an attribute of a parent element, the XML-SPACE value applies to all child elements unless specifically overridden with another XML-SPACE attribute.

Number of allowed occurrences: None or one
Parent elements | Child elements
CHANNEL | None
ITEM
SOFTPKG

The ABSTRACT element can optionally be used as an attribute with the CHANNEL and ITEM elements to support previous implementations of CDF. Any new CDF files should use ABSTRACT as a child element.

The end tag </ABSTRACT> is required.

Example

<ABSTRACT>This article describes how to create a CDF file.</ABSTRACT>


CHANNEL

<CHANNEL
BASE="url"
HREF="url"
LASTMOD="date"
LEVEL="n"
PRECACHE="YES" | "NO"
>

Defines a channel or subchannel. The channel is defined by the first occurrence of the CHANNEL element and the corresponding </CHANNEL> end tag. All CHANNEL elements contained within the top-level channel represent subchannel folders that are used to create a hierarchy of channel items.

BASE="url"
Base URL for the channel. This is used to resolve relative URLs specified in ITEM and CHANNEL elements contained within this channel. The BASE value applies to all child elements of the current channel or subchannel. This attribute supersedes the BASE value previously defined by a parent CHANNEL element, if any exist. The URL specified must end with a trailing "/", or the last word will be removed.
HREF="url"
Uniform Resource Locator associated with the channel. The browser navigates to this location when the user activates the channel. The HREF attribute should be omitted if the CHANNEL element contains an anchor (A) as a child element.
LASTMOD="date"
Last date/time in GMT that the page indexed by the HREF attribute was modified. GMT is Greenwich Mean Time, also known as Universal Time Coordinated (UTC). Note that the LASTMOD date/time is not necessarily your local time. This attribute allows the channel client to determine whether the content has changed since the last time it was downloaded. The item is downloaded only if the date associated with the cached item is older than the LASTMOD value in the CDF file. Additional information on optimizing channels is available in the Creating Active Channels documentation. The date format used in the LASTMOD attribute is specified in the form yyyy-mm-ddThh:mm, where:
yyyy | Specifies the year.
mm | Specifies the month (01-12).
dd | Specifies the day of the month (01-31).
hh | Specifies the hour of the day (00-23).
mm | Specifies the minutes (00-59).
LEVEL="n"
Number of levels (or links) deep the client should "site crawl" and precache the HTML content from the URL specified in the HREF attribute. The default is zero, which specifies to only precache the URL of the CHANNEL, along with any images it uses. If the URL contains frames, the client will also retrieve all content inside the frames. By default, the maximum number of levels that can be specified for site crawling is three.
PRECACHE="YES" | "NO"
Specifies whether content should be downloaded and cached on the client computer. If PRECACHE is omitted or set to "YES", content is downloaded only if the user of Internet Explorer has specified that channel content should be downloaded. If PRECACHE is set to "NO", content is not downloaded and the LEVEL attribute is ignored.

Number of allowed occurrences: Any number
Parent elements | Child elements
None | ABSTRACT
CHANNEL
ITEM
LOG
LOGIN
LOGO
LOGTARGET
SCHEDULE
SOFTPKG
TITLE

An optional SELF= attribute can be added in the top-level CHANNEL to indicate the location of the CDF file to use for creating a channel subscription. Note that this attribute is unnecessary and is only supported for backward compatibility.

If more than one mechanism is used to specify a URL for a channel, Internet Explorer will look for URLs in this order of precedence:

  1. The HREF= attribute of the CHANNEL element.
    <CHANNEL HREF="http://...">
  2. The HREF of the anchor (A) element that is the immediate child of the CHANNEL element.
    <CHANNEL>
    <A HREF="http://...">My Channel</A>
  3. The optional INFOURI=url attribute of the CHANNEL element. This attribute is available for compatibility with other CDF parsers.
    <CHANNEL INFOURI="http://...">

The end tag </CHANNEL> is required.


EARLIESTTIME

<EARLIESTTIME
 DAY="n"
HOUR="n"
MIN="n"
/>

Specifies the beginning of the valid range of time that the update to the CDF can occur. By default, if this value is not specified, the earliest time is set to the beginning of the INTERVALTIME value. The days, hours, and minutes are totaled to determine the offset value from the start of the INTERVALTIME. Additional information on scheduled updates is available in the Creating Active Channels documentation.

DAY="n"
First day within the INTERVALTIME that the schedule can be updated.
HOUR="n"
First hour within the INTERVALTIME that the schedule can be updated.
MIN="n"
First minute within the INTERVALTIME that the schedule can be updated.

Number of allowed occurrences: None or one
Parent elements | Child elements
SCHEDULE | None

Client applications can round the specified value to the nearest value that they consider significant.


HTTP-EQUIV

<HTTP-EQUIV
 NAME="headerparam"
VALUE="text"
/>

Supplies information that can also be provided through HTTP response headers. In the context of sending files over the HTTP protocol through the LOGTARGET element, it indicates that an HTTP header parameter based on the information in this tag should be added.

NAME="headerparam"
Required. Specifies the name of the HTTP header parameter sent with the log file, such as "Encoding-Type."
VALUE="text"
Required. Specifies the value of the corresponding parameter.

Number of allowed occurrences: Any number
Parent elements | Child elements
LOGTARGET | None

Example

The following example shows how to send a compressed log file back to the server.

<LOGTARGET HREF="http://www.mysite.com/logging/" METHOD="POST">
    <HTTP-EQUIV NAME="encoding-type" VALUE="gzip" />
</LOGTARGET>


INTERVALTIME

<INTERVALTIME
 DAY="n"
HOUR="n"
MIN="n"
/>

Indicates the interval of time over which the schedule should repeat. The days, hours, and minutes are totaled to determine the length of the repeating range. Additional information on scheduled updates is available in the Creating Active Channels documentation.

DAY="n"
Number of days over which the schedule will repeat.
HOUR="n"
Number of hours over which the schedule will repeat.
MIN="n"
Number of minutes over which the schedule will repeat.

Number of allowed occurrences: None or one
Parent elements | Child elements
SCHEDULE | None

The time quantity specified by this element will be rounded up to a fraction of a day (fourth, third, half, and so on) or rounded to the nearest multiple of a day. For example, 1-, 2-, 3-, and 4-hour increments will be used by Internet Explorer without rounding, but 5 hours will be rounded to 6 hours (a fourth of a day). An INTERVALTIME with a value greater than a half day but less than a day will be rounded up to a day. This element is a required child element of SCHEDULE, and it must contain a nonzero value to be considered valid.

Example

The following example shows a schedule that will update the channel every day during the month of December (1997) sometime between 10 A.M. and 2 P.M.

<SCHEDULE STARTDATE="1997-12-01" STOPDATE="1997-12-31">
<INTERVALTIME DAY="1" />
<EARLIESTTIME HOUR="10" />
<LATESTTIME HOUR="14" />
</SCHEDULE>


ITEM

<ITEM
HREF="url"
LASTMOD="date"
LEVEL="n"
PRECACHE="YES" | "NO"
>

Defines an item in a channel. An item is a unit of information that usually corresponds to a Web page. In an Active Channel, items will appear in the hierarchy exposed in the Channels Explorer Bar. To prevent an item from showing up in the Channels Explorer Bar, the USAGE element should be included as a child element of the ITEM with the VALUE attribute set to "None."

HREF="url"
Required. URL that represents the channel. The browser navigates to this location when the user activates the channel. There must be exactly one HREF attribute with the ITEM element. The HREF attribute should be omitted if the ITEM element contains an anchor (A) as a child element.
LASTMOD="date"
Last date/time in GMT that the page indexed by the HREF attribute was modified. GMT is Greenwich Mean Time, also known as Universal Time Coordinated (UTC). Note that the LASTMOD date/time is not necessarily your local time. This allows the channel client to determine whether the content has changed since the last time it was downloaded. The item is downloaded only if the date associated with the cached item is older than the LASTMOD value in the CDF file. Additional information on optimizing channels is available in the Creating Active Channels documentation. The date format used in the LASTMOD attribute is specified in the form yyyy-mm-ddThh:mm, where:
yyyy | Specifies the year.
mm | Specifies the month (01-12).
dd | Specifies the day of the month (01-31).
hh | Specifies the hour of the day (00-23).
mm | Specifies the minutes (00-59).
LEVEL="n"
Number of levels (or links) deep the client should site crawl and precache the HTML content from the URL specified in the HREF attribute. The default is zero, which specifies to precache only the URL of the item and the images it references. If the URL contains frames, the client also retrieves all content inside the frames.
PRECACHE="YES" | "NO"
Specifies whether content should be downloaded and cached on the client computer. If PRECACHE is omitted or set to "YES", content is downloaded only if the user of Internet Explorer has specified that channel content should be downloaded. If PRECACHE is set to "NO", content is not downloaded and the LEVEL attribute is ignored.

Number of allowed occurrences: Any number
Parent elements Child elements
CHANNEL ABSTRACT
LOG
LOGO
TITLE
USAGE

The end tag </ITEM> is required.

Example

<ITEM HREF="http://www.foosports.com/intro.htm" LASTMOD="1997-09-11T10:30">
    <TITLE>Welcome to FooSports!</TITLE>
    <ABSTRACT>FooSports articles, news, and promotional offers</ABSTRACT>
</ITEM>


LATESTTIME

<LATESTTIME
 DAY="n"
HOUR="n"
MIN="n"
/>

Specifies the latest time during the INTERVALTIME that the schedule will be applied and updated. The days, hours, and minutes are totaled to determine the offset value from the INTERVALTIME that represents the latest valid time for updating a channel. If omitted, the latest time is set to the beginning of INTERVALTIME. Additional information on scheduled updates is available in the Creating Active Channels documentation.

DAY="n"
Latest number of days to which the schedule will be applied.
HOUR="n"
Latest number of hours to which the schedule will be applied.
MIN="n"
Latest number of minutes to which the schedule will be applied.

Number of allowed occurrences: None or one
Parent elements | Child elements
SCHEDULE | None

Client applications can round the specified value to the nearest value that they consider significant.


LOG

<LOG
 VALUE="document:view"
/>

Specifies that the URL of the parent ITEM element should be recorded in a page-hit log file. Additional information on page-hit logging is available in the Creating Active Channels documentation.

VALUE="document:view"
Required. Specifies the event to be logged. Currently, "document:view" is the only value supported by Internet Explorer.

Number of allowed occurrences: Any number
Parent elements | Child elements
ITEM | None

An ITEM can be logged only if the path of the ITEM's HREF attribute falls under the path of the CDF file's URL or the path of the LOGTARGET's HREF. Note that this element is also valid for a CDF file being used as an Active Desktop item (<USAGE VALUE="DesktopComponent"></USAGE>).

There is no end tag associated with this element.

Example

<ITEM  HREF="http://www.foosports.com/promotion.htm">
    <LOG VALUE="document:view"/>
</ITEM>


LOGIN

<LOGIN/>

Specifies that the channel requires authentication for updates. A CDF file containing this element will prompt the user for a name and password during the channel subscription process.

Number of allowed occurrences: None or one (top-level channel only)
Parent elements | Child elements
CHANNEL | None

There is no end tag associated with this element.

Example

<LOGIN />


LOGO

<LOGO
 HREF="url"
STYLE="ICON" | "IMAGE" | "IMAGE-WIDE" />

Specifies an image that can be used to represent a channel or channel item.

HREF="url"
Required. Specifies the URL associated with the channel logo or icon image.
STYLE="ICON" | "IMAGE" | "IMAGE-WIDE"
Text string indicating the context in which a logo will be used, as follows:
Value | Image size | Display description
"ICON" | 16H x 16W | This image appears in the Channels Explorer Bar hierarchy and other areas of the Microsoft® Windows® name space, such as when viewing the contents of a folder containing the CDF.
"IMAGE" | 32H x 80W | This logo image is placed in the desktop Channel Bar to provide a quick launching mechanism for the main channel page.
"IMAGE-WIDE" | 32H x 194W | Wide logos are displayed in the Channels Explorer Bar to provide a link to the main channel page. When clicked, this image will also expand or contract the channel's hierarchy (if one exists) in the Channels Explorer Bar.

Number of allowed occurrences: None or one (per STYLE attribute)

Note GIF, JPEG, and other standard image formats supported by Internet Explorer can be used for logo images. However, animated GIF files are not supported with this element. Image formats and styles are subject to change.
Parent elements | Child elements
CHANNEL | None
ITEM
SOFTPKG

There is no end tag associated with this element.

Example

<LOGO HREF="http://www.foosports.com/images/logo.gif" STYLE="IMAGE"/>


LOGTARGET

<LOGTARGET
 HREF="url"
METHOD="POST"
SCOPE="ALL" | "OFFLINE" | "ONLINE"
>

Specifies where to send a CDF client page-hit log file. This element must occur before any ITEM elements in the CDF file. For details about the type of information gathered, see the Page-Hit Logging section.

HREF="url"
Required. Specifies the URL of where the log should be sent.
METHOD="POST"
Required. Specifies the HTTP method to be used for sending the data.
SCOPE="ALL" | "OFFLINE" | "ONLINE"
Specifies which type of page hits should be logged. Page hits can be logged for offline (read from local cache) or online (read from URL) browsing. The default for this attribute is "ALL", which logs both types of hits.

Number of allowed occurrences: None or one (top-level channel only)
Parent elements Child elements
CHANNEL HTTP-EQUIV
PURGETIME

The end tag </LOGTARGET> is required.

Example

<LOGTARGET HREF="http://www.foosports.com/logging" Method="POST" SCOPE="OFFLINE">
    <PURGETIME HOUR="12"/>
    <HTTP-EQUIV NAME="ENCODING-TYPE" VALUE="gzip"/>
</LOGTARGET>


PURGETIME

<PURGETIME
 HOUR="n"
/>

When the log file is being uploaded, any page hits older than PURGETIME will not be reported.

HOUR="n"
Number of hours for which the logging information is considered valid.

Number of allowed occurrences: None or one
Parent elements | Child elements
LOGTARGET | None

There is no end tag associated with this element.

The log file (filename.log) is stored in the user's local cache in the %userprofile%\history\log folder. This file is cleared after it is successfully posted to the HTTP server during the CDF update.


SCHEDULE

<SCHEDULE
 STARTDATE="date"
STOPDATE="date"
TIMEZONE="offset"
>

Defines the schedule used for channel updating. Starting at midnight on STARTDATE, channel updating occurs once within each consecutive time interval specified by the INTERVALTIME child element. The EARLIESTTIME and LATESTTIME child elements specify offsets that define the valid range of time within each interval that channel updates can occur.

The schedule must be placed directly under the top-level channel element, and it must contain a nonzero INTERVALTIME value to be considered valid. This schedule is relative to the time zone in TIMEZONE, if present; otherwise, the schedule is relative to the local time of the user. This schedule applies to the channel only if the user accepts the default "publisher's recommended schedule" when subscribing to the channel. Additional information on scheduled updates is available in the Creating Active Channels documentation.

This element should appear near the top of the CDF file, after the top-level CHANNEL element and before any ITEM or nested CHANNEL elements.

ENDDATE="date"
Obsolete. Do not use. This attribute has been replaced by STOPDATE.
STARTDATE="date"
Day on which the schedule will start to apply. If this attribute is omitted, the schedule will start to apply on the current day. The date for this attribute is specified in the form yyyy-mm-dd, where:
yyyy | Specifies the year.
mm | Specifies the month (01-12).
dd | Specifies the day of the month (01-31).
STOPDATE="date"
Day on which the schedule stops updating (expires). If this attribute is omitted, the schedule will not expire. The date for this attribute is specified in the form yyyy-mm-dd, where:
yyyy | Specifies the year.
mm | Specifies the month (01-12).
dd | Specifies the day of the month (01-31).
TIMEZONE="offset"
Difference between local time and Universal Time Coordinated (UTC). This allows channel publishers to specify an absolute time for an update schedule. The offset specified for this attribute adjusts the EARLIESTTIME and LATESTTIME child elements accordingly. The date for this attribute is specified in the form szzzz, where:
s | Specifies the relationship of the local time to UTC. A minus (-) or plus (+) sign is used to indicate whether the local time is earlier or later than UTC.
zzzz | Specifies the offset from UTC in hours and minutes.

Number of allowed occurrences: None or one (top-level channel only)
Parent elements Child elements
CHANNEL EARLIESTTIME
ITEM INTERVALTIME
LATESTTIME

The end tag </SCHEDULE> is required.

For example, to specify the U.S. Eastern Standard Time (EST), which is 5 hours earlier than UTC, use: TIMEZONE="-0500".

Example

The following example shows a schedule that takes effect immediately and updates the channel once per day, sometime between noon and 6 P.M. The channel will stop receiving updates on December 1, 1997.

<SCHEDULE ENDDATE="1997-12-01">
    <INTERVALTIME DAY="1"/>
    <EARLIESTTIME HOUR="12"/>
    <LATESTTIME HOUR="18"/>
</SCHEDULE>


TITLE

<TITLE
 XML-SPACE="DEFAULT" | "PRESERVE" >

Specifies a text string representing the title of the CHANNEL or ITEM element. Internet Explorer displays this title to the right of the item's icon in the Channels Explorer Bar. A TITLE element that is the direct child of the top-level channel element appears in place of the channel logo in the Channels Explorer Bar when another channel is selected by the user.

When applied to the top-level CHANNEL element, the title should appear near the top of the CDF file before any ITEM or nested CHANNEL elements.

XML-SPACE="DEFAULT" | "PRESERVE"
Specifies how white space, such as tabs, spaces, and blank lines, should be handled. The default behavior (XML-SPACE="DEFAULT") indicates that white space characters are not considered significant, and therefore some of these characters may be filtered out during file processing. Set the value of this attribute to "PRESERVE" to ensure that all white space characters are retained. This attribute can be used with any CDF element that uses significant white space. When used as an attribute of a parent element, the XML-SPACE value applies to all child elements unless specifically overridden with another XML-SPACE attribute.

Number of allowed occurrences: None or one
Parent elements | Child elements
CHANNEL | None
ITEM
SOFTPKG

The TITLE element can optionally be used as an attribute with the CHANNEL and ITEM elements to support previous implementations of CDF. Any new CDF files should use TITLE as a child element.

The end tag </TITLE> is required.

Example

<TITLE>CDF Reference</TITLE>


USAGE

<USAGE
 VALUE="Channel" | "Email" | "DesktopComponent" | "NONE" | "ScreenSaver" | "SoftwareUpdate" >

Indicates how an ITEM element should be used.

VALUE="Channel" | "Email" | "DesktopComponent" | "NONE" | "ScreenSaver" | "SoftwareUpdate"
Required. Specifies a special usage of the parent element.
"Channel" | These items appear in the browser channel pane. This is the default behavior when no USAGE element appears under an ITEM.
"Email" | This one item is e-mailed when the channel content is updated (one per CDF).
"NONE" | If a "NONE" value is used as the only USAGE element in an ITEM, the item will not appear in the Channels Explorer Bar.
"DesktopComponent" | These items are displayed in a frame located on the Active Desktop. A CDF with this usage value can only be used in the context of an Active Desktop item. An Active Channel would require a separate CDF file.
"ScreenSaver" | This one item is displayed in the special Internet Explorer screen saver (one per CDF).
"SoftwareUpdate" | This indicates the CDF file is being used for a Software Update channel, which allows software to be automatically updated over the Web. This value is only valid for the top-level channel. For more information on Software Update channels, see Creating Software Update Channels and the Open Software Description (OSD) documentation.

Number of allowed occurrences: Any number
Parent elements | Child elements
ITEM | None
SOFTPKG

For information on additional CDF elements supported for "DesktopComponent" usage, see CDF Extensions for Active Desktop Items.

For information on additional CDF elements supported for "SoftwareUpdate" usage, see CDF Extensions for Software Update Channels.

Some older implementations of CDF clients look for a SHOW attribute instead of the USAGE child element inside the ITEM element. An attribute of SHOW="string" in an ITEM element is functionally equivalent to adding a child element of <USAGE VALUE="string"></USAGE> to an ITEM element.

The end tag </USAGE> is required. The content of the element is optional and varies according to the VALUE attribute.

Example

<ITEM HREF="http://www.foosports.com/screensaver.htm">
    <USAGE VALUE="ScreenSaver"></USAGE>
</ITEM>

Note "SmartScreen," a trademark of PointCast Inc., can be used in place of "ScreenSaver".


CDF Extensions for Active Desktop Items

The following reference information applies to Channel Definition Format (CDF) files created for Active Desktop items. For the complete CDF element reference, see the CDF Reference for Active Channels. The elements listed here are valid only when used as a child element within the USAGE element for an Active Desktop item.


CANRESIZE

<CANRESIZE
 VALUE="No" | "Yes"
/>

Indicates whether the Active Desktop item can be resized along both the x and y axes by the user. The value of this element overrides the CANRESIZEX and CANRESIZEY elements.

VALUE="No" | "Yes"
Specifies whether the Active Desktop item can be resized. The default is "Yes".

Number of allowed occurrences: Exactly one.
Parent elements | Child elements
USAGE | None


CANRESIZEX

<CANRESIZEX
 VALUE="No" | "Yes"
/>

Indicates whether the Active Desktop item can be resized along the x-axis by the user.

VALUE="No" | "Yes"
Specifies whether the width of the Active Desktop item can be resized. The default is "Yes".

Number of allowed occurrences: Exactly one.
Parent elements | Child elements
USAGE | None


CANRESIZEY

<CANRESIZEY
 VALUE="No" | "Yes"
/>

Indicates whether the Active Desktop item can be resized along the y-axis by the user.

VALUE="No" | "Yes"
Specifies whether the height of the Active Desktop item can be resized. The default is "Yes".

Number of allowed occurrences: Exactly one.
Parent elements | Child elements
USAGE | None


HEIGHT

<HEIGHT
 VALUE="pixels"
>

Indicates the height, in pixels, of the Active Desktop item specified in the ITEM element.

VALUE="pixels"
Required. Specifies the height of the Active Desktop item.

Number of allowed occurrences: Exactly one.
Parent elements | Child elements
USAGE | None


OPENAS

<OPENAS
 VALUE="HTML" | "Image"
>

Indicates the content type of the Active Desktop item specified in the ITEM element.

VALUE="HTML" | "Image"
Content type of the Active Desktop item. This determines how the content will be hosted in the user's Active Desktop Desktop.htm file. HTML items are hosted with IFRAME elements, and images are hosted with IMG elements. The default is "HTML".

Number of allowed occurrences: None or one.
Parent elements | Child elements
USAGE | None


WIDTH

<WIDTH
 VALUE="pixels"
>

Indicates the width, in pixels, of the Active Desktop item specified in the ITEM element.

VALUE="pixels"
Required. Specifies the width of the Active Desktop item.

Number of allowed occurrences: Exactly one.
Parent elements | Child elements
USAGE | None


CDF Extensions for Software Update Channels

This section describes the elements and associated attributes used to create Channel Definition Format (CDF) and Open Software Description (OSD) files for Software Update Channels. This new technology allows users to automatically have new versions of software downloaded and installed from the Web. More information on CDF files is available in CDF Reference for Active Channels. For more information on OSD, see Open Software Description (OSD). Also, for more information on Microsoft Internet Code Download, which includes elements that enhance OSD files, see Microsoft Internet Code Download.

The reference for each element defined below includes an "Applies To" section indicating which type of file (OSD or CDF) uses the element.

CDF Elements
DELETEONINSTALL
OSD Elements
ABSTRACT CODEBASE DISKSIZE
IMPLEMENTATION IMPLTYPE LANGUAGE
LICENSE MEMSIZE OS
OSVERSION PROCESSOR SOFTPKG
TITLE VM
MSICD Elements
CLASS CODE CODEBASE
ICON IMPLEMENTATION ISBEAN
JAVA LANGUAGE NAMESPACE
NATIVECODE NEEDSTRUSTEDSOURCE OS
OSVERSION PACKAGE PROCESSOR
SOFTPKG SYSTEM TYPELIB

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


DELETEONINSTALL

<DELETEONINSTALL />

Indicates that the software subscription should unregister itself when the software it describes has been successfully downloaded and installed, either through AUTOINSTALL or manually by the user. Therefore, DELETEONINSTALL subscriptions are not permanent.

Number of allowed occurrences: None or one
Parent elements | Child elements
SOFTPKG | None

Applies To

CDF


Tools

The tools in this section help Web publishers who are developing content for use with Microsoft® Internet Explorer 4.0.

Microsoft CDF Generator

Profile Assistant


Microsoft CDF Generator

Microsoft CDF Generator is an easy-to-use, highly efficient tool for the creation of Channel Definition Format files (CDFs).

  • It has a simple and intuitive graphical interface that you will get used to in a few minutes.
  • It doesn't require previous knowledge of channels.
  • It supports all CDF tags.
  • It supports UTF-8 encoding.
  • It can also be used for testing purposes, since it parses the CDF files and detects the errors.
  • It supports drag and drop, so there less to type.

Note: Microsoft CDF Generator is able to parse a Channel Definition Format file only if Internet Explorer 4.0 is installed on your machine.

Updates: For the latest versions and information of Microsoft CDF Generator check SiteBuilder Network Downloads.

THE USER INTERFACE
CREATING A NEW CDF
OPENING AND MODIFYING EXISTING AND NEW CDF FILES
ADDING ELEMENTS
MODIFYING ELEMENTS
DELETING ELEMENTS
OTHER OPTIONS

THE USER INTERFACE

The user interface of Microsoft CDF Generator consists of two main parts:

Tree pane: The left side of the main window includes a hierarchical representation of the channel definition format that you are creating. By default all the elements (tags) are visible, but it also allows you to hide some of the elements that are not important.

Code pane: The right side of the main window shows the complete code of the file. Any change in the tree pane is automatically reflected in code pane. In Platform Preview 2, this pane is read-only, and user is not able to change the content in order to modify the CDF file

Microsoft CDF Generator User Interface

CREATING A NEW CDF

Selecting New from the File menu will automatically launch a sequence of the five wizards that you can use to add elements or attributes to your channel, see the wizards section for more details.

PAGES THAT YOU WILL FIND IN THE WIZARDS

Each one of the wizards shows a different subset of pages where you can specify the different attributes of the element you are adding.

  1. The General - Channel - Information page
    • HREF: the URL for the top page of the channel (Select Attribute or Anchor type)
    • BASE: the URL or root of the site where the channel is published (used for resolving relative paths)
    • SELF: The URL where the CDF will be published (full, including the name of the CDF)

  2. The General - Item - Information page
    • HREF: the URL for the item that you are adding (Select Attribute or Anchor type)
    • Last Modified date (ISO date, time, time zone format)
    • The Level
    • Whether the item should be pre-cached or not (checkbox)
    • The Usage attribute for the Item

  3. The - Common - child elements page

    4. Select the checkbox of the elements that you want to associate with the channel and type in their respective properties:

    • Title: the title of the channel, a short text description that will appear as a tool-tip or when the user selects to see it in the channel changer.
    • Abstract: a text description (2 sentences max. recommended) describing the content of the channel, to be used as a tool-tip or in channel guides.
    • Log: type of events that you want to have logged for tracking purposes.

  4. The Logos information

    5. Select the checkbox, and type in the URL of the logos that you want to represent a channel or an item:

    • Icon: URL to the .ICO, .GIF or .JPG file that will be used when viewing large icons in the channel changer
    • Image: URL to the .GIF or .JPG (80x32) file that will be used by default in the desktop channel bar.
    • Wide: URL to the .GIF or .JPG (194x32) file that will be used in the browser channel changer.

  5. The Schedule page

    6. Toggle the top level check box to choose if you want to have a delivery schedule associated with your channel, and if you do want a schedule, edit the schedule dates and the delivery timings sections according to your preferences.

  6. The Log Target page

    7. Again, check or uncheck the element depending on your preferences and edit the characteristics of your tracking notifications.

  7. The Authentication or Login page

    8. Speaks for itself.

OPENING AND MODIFYING EXISTING AND NEW CDF FILES

Microsoft CDF Generator uses COM objects of Internet Explorer 4.0 to parse existing files, which means that it needs to be installed on a machine with Microsoft Internet Explorer 4.0 for this feature to work properly.

To open an existing file, simply select Open from the File menu and point to the CDF file. If an error occurs, or the CDF file contains errors and cannot be parsed, a dialog box appears with details.

Once you have defined a channel (just created or opened) you can Add, Modify or Delete any element in the CDF file.

ADDING ELEMENTS

There are 3 ways of doing this:

  1. Through the main menu, i.e. to add an item to a channel, select that channel in the tree pane (click on it) and then select Tag, New, Item from the main menu.
  2. Right click on the element that you want to modify, i.e. to add an item to a channel, right click on that channel in the Tree pane and select New, Item from the context menu.
  3. Drag and drop; you can drag URL links, links from a web page (<A> - anchor tags) opened in Internet Explorer browser, small icon beside the address (address bar) of the currently opened page in your browser, etc. These objects must be dropped into the channel element of Microsoft CDF Generator that will be its parent. This will launch the Item Wizard and insert the address of the link you had opened into the appropriate box in the Wizard

Microsoft CDF Generator is "intelligent" in the sense that it will not let you add a child element twice if only one child element of that kind is supported for that element. For example if you have already added a title to a channel, it will not display the "Title" element as an option in the menu. Or when you add a sub-channel to a channel it will not even display the schedule page in the wizard.

MODIFYING ELEMENTS

Simply double click (or right click and select Properties) on the element that you want to modify, then type in the new values into the appropriate boxes

DELETING ELEMENTS

Click on the element that you want to delete and press the Delete key, or right click and select Delete.

OTHER OPTIONS

OPENING A REMOTE CDF FILE

To download and open an existing file from the web, select Open (URL) from the File menu and type the URL of the CDF file you want to open.

Note: You will not be able to save this file back to the web server. Save it on your local drive instead.

MANUAL EDITING

You can manually edit a CDF file in the Code Pane. In order to do that, check Edit Mode from the View menu. The content of the Tree Pane will be destroyed, and rebuilt again when you decide to exit the Edit Mode, using the same procedure (View|EditMode).

TESTING YOUR CDF FILE

Select Test from the Tag menu, and all the child elements of the currently selected item in the Tree Pane will be recursively tested.

Note: Only the visible elements are tested.

ENCODING (UTF-8)

Microsoft CDF Generator allows users to save files in UTF-8 format by converting the text using UTF-8 encoding standards. Select View, Options from the main menu, and in General page, type 'UTF-8' in the encoding field.

Note: All HTML character sets are valid in this field (i.e. windows-1250, big5, etc.)

VISIBILITY

If a channel includes a large amount of sub-channels and items, the tree pane (left) can become overpopulated, making the structure hard to follow. To improve performance, the user can hide any tag in the tree pane. Select View, Options from the main menu, and in Advanced page uncheck the boxes beside the tags that should be hidden.

Note: If the channel tag is hidden, the tree pane disappears.

REORDERING

New elements inserted into the CDF file are inserted according to an internal sort order. If you want to modify the order of an element, drag the element, and drop it onto the element to be placed after the dragged element.


Profile Assistant

This document describes how Web publishers can use the new Microsoft® Internet Explorer 4.0 Profile Assistant to collect profile information from the user. All information submitted to the Web server requires the user's approval.

Introduction

Using the Profile Assistant

Authoring an HTML Form

Introduction

The Platform for Privacy Preferences (P3) is a World Wide Web Consortium (W3C) project determining the overall architecture for enabling privacy on the Web. The Profile Assistant in Internet Explorer 4.0 is the first implementation of the types of privacy capabilities enabled by P3.

This new architecture defines a means by which user profiles can be exchanged between Web clients and servers while respecting the user's right to privacy. This profile information is valuable, but it cannot be used by companies or service organizations unless a standard mechanism is defined by which the information can be programmatically accessed on either the client or the server. Such a mechanism must respect a user's privacy constraints. Therefore, a Web site cannot be allowed to retrieve user information to which it is not entitled. Sites should not be hindered, however, from accessing profile information with the informed consent of the user, as defined by the P3 architecture.

This article includes a description of the scripting object model exposed on the client user-agent (Internet Explorer 4.0). The new userProfile object allows Web publishers to create scripts in Web pages that request read access to private information within the constraints of the privacy guidelines defined by the P3 architecture. Note that Internet Explorer 4.0 does not yet allow for write access to the user profile as specified in the P3 architecture. Instead, Internet Explorer 4.0 implements a subset of the P3 schema, which is undergoing the standardization process at the W3C. To install the Profile Assistant, you must use either the "standard" or "full" installation option for Internet Explorer 4.0. The Profile Assistant is available only on the Microsoft® Windows® 95 and Windows NT® versions of Internet Explorer 4.0.

Using the Profile Assistant

The purpose of the Profile Assistant is to make it easy for users to share registration and demographic information with sites that require this information. The goal is to eliminate the need for users to repeatedly enter information such as their address or e-mail name for each site's registration page. This is accomplished, while at the same time maintaining user privacy, by giving users complete control over access to their data. User information is stored securely in protected storage on the client computer. Web servers can request to read this information, but it is shared only if users give their consent in the Profile Assistant confirmation dialog box. This dialog box is required, and it is not possible to access this data without the user's permission.

Populating the client data store

In Internet Explorer 4.0, the user can enter data into the secure client profile storage by using an edit dialog box accessed through the Content tab in the View/Internet Options dialog box. This form allows the user to enter or change all data elements in the store. Note that the Profile Assistant is automatically populated with registration information collected from the user by Internet Explorer 4.0. If there is no data, or if you wish to edit the data previously collected, follow this simple process:

  1. Open the Internet Explorer 4.0 browser.
  2. From the View menu, select Internet Options.
  3. From the Internet Options dialog box, click the Content tab.
  4. On the Content tab, click the Edit Profile button.
  5. Enter or edit your information, and click OK.

The following illustration shows a typical Profile Assistant data entry.

Profile Assistant Data Entry

Authoring an HTML Form

Authoring an HTML form for use with the Profile Assistant is accomplished by adding some scripting code to an HTML page. This makes retrofitting existing forms easy. Note that if your registration page is viewed frequently in the same session, you may want to write some scripting code to ensure that the user is prompted only once. Please view the source for the sample page (Proftest.htm) shown in the next section.

Object model for the Profile Assistant

To be able to write scripts for the Profile Assistant, you need to first understand the Profile Assistant object and its associated methods. The object model consists of a single object, the userProfile object. This object is available to scripts running on Internet Explorer 4.0 through the HTML document object model as window.navigator.userProfile.

The following diagram shows the relation of objects in the object model.

    window
      |
      +---navigator
             |
             +---userProfile

Methods of the userProfile object

The userProfile object provides methods that allow a script to request read access to a user's profile information and also to perform read actions. Note that the requests are queued up before the action of reading or writing is performed. This simplifies the user's experience by prompting for profile release permissions once for a batch of requests. Web pages utilizing the Profile Assistant should follow this logic sequence:

  1. Use clearRequest to clear out the request queue.
    clearRequest();
  2. Perform a series of addReadRequests to fill the request queue with the items that will be requested from the client storage. This method uses a predefined attribute name as the parameter.
    addReadRequest("Vcard.FirstName");
  3. Issue a doReadRequest to prompt the user with the confirmation dialog box. When confirmed, return the requested data from the client store. Parameters are an integer (0-12) representing a standard usage code and optional strings for the header.
    doReadRequest(10, "XYZ Corp.");
  4. Access the data elements that have been pulled from the client with the getAttribute method. This method takes a predefined attribute name as a parameter and returns the user's stored value as a string.
    getAttribute("Vcard.FirstName");

Profile Assistant scripting examples

The following excerpt is an example of a script written in JScript that can be run on Internet Explorer 4.0 to read various values from the user's profile information store.

Note User profile attributes are specified with the format Vcard.attribute. The Vcard_attribute format is no longer supported by Internet Explorer 4.0.

// This ensures that the request queue is in a clean, known state.
navigator.userProfile.clearRequest();

// Queue up a request for read access to multiple profile attributes.
navigator.userProfile.addReadRequest("Vcard.FirstName");
navigator.userProfile.addReadRequest("Vcard.Gender");

// Request access to specific information via a confirmation dialog box.
navigator.userProfile.doReadRequest(usage-code, "Foobar Inc.");

// Perform read operations to access the information.
name = navigator.userProfile.getAttribute("Vcard.FirstName");
gender  = navigator.userProfile.getAttribute("Vcard.Gender");

// The script can now use the 'name' and 'gender' variables
// to personalize content or to send information back to the server.

An HTML page called Proftest.htm containing the HTML code shown in the next section is available in the Samples directory of the Internet Client SDK. This is a simple registration form that asks the user to enter a name, an e-mail address, and a telephone number. When navigating to this form, users will be prompted with a dialog box informing them that profile information is being requested. As you will see, there are several elements to this user interface:

  • The URL of the site requesting the user's information.
  • A list of all the data elements requested. The Profile Assistant allows the user to view exactly what information is being requested and to deliberately exclude information if desired.
  • The usage code that specifies how the data will be used by the site. An example would be "disclosed to others, who may contact you for marketing of services and/or products". A list of usage codes is provided with the doReadRequest documentation.
  • Information about the connection security. Since the user's information is transferred over the Internet, the data is only as secure as its connection. This identifies if data is transferred over an SSL connection and, if so, allows the user to verify the site identity by viewing the certificate.

The information provided on the dialog box helps the user verify who is requesting the data, choose which particular data elements (if any) to share with the Web publisher, and understand the intended usage as specified by the site. Clicking the OK button will add the information to the form. Users consenting to the information request will not be asked for confirmation when visiting this page later unless the "Always allow site to see checked items" box is cleared.

The following illustration shows the Profile Assistant confirmation dialog box.

Profile Assistant Confirmation Dialog Box

The following HTML file (Proftest.htm) shows how a simple page can be set up to populate a form with data requested from the user's profile. If the user chooses not to disclose information from one or more of the requested fields, those text fields will remain blank. An explanation of the script is provided after the listing of the entire HTML page.

Note This sample must be placed on an HTTP server to work properly. If the file is opened locally with the "file://" protocol, it will automatically access the profile data without requiring user consent.

<html>

<head>
<title>Sample Profile Assistant HTML</title>
</head>
<body>

<form method=POST action="http://www.foobar.com/cgi/bin/collectInfo">
<table>
  <tr>
    <td align="right">Last Name:       </td>
    <td align="left"><input type=text name=user  size=32 maxlength=80></td>
  </tr>
  <tr>
    <td align="right">Email:       </td>
    <td align="left"><input type=text name=email  size=32 maxlength=80></td>
  </tr>
  <tr>
    <td align="right">Phone #:       </td>
    <td align="left"><input type=text name=phone  size=16 maxlength=80></td>
  </tr>
  <tr>
    <td></td>
    <td><input type=submit></td>
  </tr>
</table>
</form>

<script language="JavaScript">

    var profile = navigator.userProfile;

    profile.clearRequest();

    profile.addReadRequest("Vcard.LastName");
    profile.addReadRequest("Vcard.Email");
    profile.addReadRequest("Vcard.Business.Phone");

    profile.doReadRequest(1,"foobar Inc.");

    var myForm = document.forms[0];

    myForm.elements["user"].value = profile.getAttribute("Vcard.LastName");
    myForm.elements["email"].value = profile.getAttribute("Vcard.Email");
    myForm.elements["phone"].value = profile.getAttribute("Vcard.Business.Phone");

    profile.clearRequest();

</script>

</body>
</html>

Following is a step-by-step explanation of the required elements for the Profile Assistant and how they are used in the preceding example.

var profile = navigator.userProfile;

Set the variable profile to be client.userProfile so less typing is required. This is an optional step.

profile.clearRequest();

Clear the queue of requests for profile information.

profile.addReadRequest("Vcard.LastName");
profile.addReadRequest("Vcard.Email");
profile.addReadRequest("Vcard.Business.Phone");

Queue up requests for user information. All fields the Web publisher wants to view should be added to the request queue at this time.

profile.doReadRequest(1,"Foobar Inc.");

Begin processing the current batch of read requests and display the user confirm/deny dialog box. This example shows that the Web publisher has specified a usage code of 1, indicating the data will be used for research and product development purposes. The name of the organization requesting this information is "Foobar Inc."

myForm.elements["user"].value = profile.getAttribute("Vcard.LastName");
myForm.elements["email"].value = profile.getAttribute("Vcard.Email");
myForm.elements["phone"].value = profile.getAttribute("Vcard.Business.Phone");

Populate the form input fields using the data obtained from the user with the getAttribute method.

profile.clearRequest();

Clear the queue of requests for profile information. This is an optional step.

When opened in the browser, the HTML file is displayed as:

Example HTML File


Internet Tools & Technologies

This section describes the services and technologies provided with Internet Explorer 4.0 and explains how to exploit them in your own components and applications.

Active Desktop Interface

Asynchronous and URL Monikers

Cache Container Tool

Common Controls

Microsoft CryptoAPI 2.0

Microsoft DirectX Media SDK

Hit Logging API

HTML Clipboard Format

HTMLHelp API Reference

Hyperlinks

IE4/MSHTML Data Binding Interfaces

Information Delivery API

Microsoft Internet Component Download

Internet Explorer Address Book

Internet Mail and News Registry Layout

Internet Ratings

Internet Shortcuts API Reference

Offline Browsing

Open Software Description (OSD)

Pluggable Protocols

Predefined Protocols

Programming the Document Object Model from C/C++

Reusing the WebBrowser and MSHTML

Microsoft Script Debugger for Internet Explorer

Task Scheduler API

URL Security Zones

Microsoft Web Publishing SDK

Windows Scripting Host

Windows Shell API

WinInet API

XML Object Model


Active Desktop Interface

This article contains information on the IActiveDesktop interface that is part of the Microsoft® Windows® Shell API. This interface and its methods allow you to add, remove, and change items on the desktop.

Overview of the Active Desktop Interface

ActiveDesktop Object

IActiveDesktop Interface

Methods

Structures

Flags

Overview of the Active Desktop Interface

The Active Desktop is a feature of Microsoft Internet Explorer 4.0 that allows you to include HTML documents and items (such as ActiveX™ Controls and Java applets) directly to your desktop. The IActiveDesktop interface, which is part of the Windows Shell API, is used to programmatically add, remove, and modify the items on the desktop. Active Desktop items can also be added using a Channel Definition Format (CDF) file. For information about creating Active Desktop items and adding them with a CDF file, see Creating Active Desktop Items. For more information on CDF files, see Creating Active Channels for Internet Explorer 4.0.

Accessing the Active Desktop

To access the Active Desktop, a client application would need to create an instance of the Active Desktop object with the CoCreateInstance function and get a pointer to its IActiveDesktop interface.

The following sample shows how to get a pointer to the IActiveDesktop interface.

HRESULT hr;
IActiveDesktop *pActiveDesktop;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

//Insert code to call the IActiveDesktop methods

// Call the Release method
pActiveDesktop->Release();

Adding a Desktop Item

There are three methods that can be used to add a desktop item: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI, and IActiveDesktop::AddUrl. Each desktop item added to the Active Desktop must have a different source URL.

The IActiveDesktop::AddDesktopItemWithUI and IActiveDesktop::AddUrl both provide the option to display the various user interfaces that can be displayed before adding a desktop item to the Active Desktop. The interfaces will verify if the user really wants to add the desktop item to their Active Desktop, notify the user of any security risks that are warranted by the URL security zone settings, and ask the user if the user would like to create a subscription for this desktop item. Both methods also provide a way of suppressing the user interfaces. The IActiveDesktop::AddDesktopItem method requires a call to IActiveDesktop::ApplyChanges in order to update the registry. For the IActiveDesktop::AddDesktopItemWithUI, the client application must immediately release the IActiveDesktop interface and then use the CoCreateInstance function to get an interface to an instance of the Active Desktop object that includes the newly added desktop item.

The IActiveDesktop::AddDesktopItem method will add the specified desktop item to the Active Desktop without any user interface, unless the URL security zone settings prevent it. If the URL security zone settings do not allow the desktop item to be added without prompting the user, the method will fail. IActiveDesktop::AddDesktopItem also requires a call to IActiveDesktop::ApplyChanges in order to update the registry.

The following sample demonstrates how to add a desktop item with the IActiveDesktop::AddDesktopItem method.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

// Initialize the COMPONENT structure
compDesktopItem.dwSize = sizeof(COMPONENT);

// Insert code that adds the information about the desktop item to the COMPONENT structure

// Add the desktop item
pActiveDesktop->AddDesktopItem(&compDesktopItem,0);

// Save the changes to the registry
pActiveDesktop->ApplyChanges(AD_APPLY_ALL);

Enumerating the Desktop Items

To enumerate the desktop items currently installed on the Active Desktop, the client application needs to get the total number of desktop items installed using the IActiveDesktop::GetDesktopItemCount method and then creating a loop that retrieves the COMPONENT structure for each desktop item by calling the IActiveDesktop::GetDesktopItem method using the desktop item index.

The following sample demonstrates one way to enumerate the desktop items.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;
int intCount;
int intIndex = 0;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

pActiveDesktop->GetDesktopItemCount(&intCount,0);

compDesktopItem.dwSize = sizeof(COMPONENT);

while(intIndex<=(intCount-1))
{
    //get the COMPONENT structure for the current desktop item
    pActiveDesktop->GetDesktopItem(intIndex, &compDesktopItem,0);

    //Insert code that processes the structure

    //Increment the index
    intIndex++;

    //Insert code to clean-up structure for next component
}

// Call the Release method
pActiveDesktop->Release();


ActiveDesktop Object ActiveDesktop Object *
  * Previous Topic: Active Desktop Interface
  * Next Topic: Active Desktop

ActiveDesktop Object

This section contains the reference information for the ActiveDesktop object.

Active Desktop


Active Desktop Active Desktop *
  * Previous Topic: ActiveDesktop Object
  * Next Topic: IActiveDesktop Interface

Active Desktop

CLSID_ActiveDesktop

Manages the Active Desktop. Has one interface, IActiveDesktop.


IActiveDesktop Interface

This section contains the reference information for the IActiveDesktop interface and its methods.

IActiveDesktop


IActiveDesktop

Allows a client program to manage the desktop items and wallpaper on a local computer.
Methods | Description
AddDesktopItem | Adds a desktop item.
AddDesktopItemWithUI | Adds a desktop item to the Active Desktop using a user interface.
AddUrl | Adds the desktop item associated with the specified URL.
ApplyChanges | Applies changes to the Active Desktop.
GenerateDesktopItemHtml | Generates a generic HTML page containing the given desktop item.
GetDesktopItem | Retrieves the specified desktop item.
GetDesktopItemByID | Retrieves the desktop item that matches the given identification.
GetDesktopItemBySource | Retrieves a desktop item using its source URL.
GetDesktopItemCount | Retrieves a count of the desktop items.
GetDesktopItemOptions | Retrieves the desktop item's options.
GetPattern | Retrieves the pattern currently being used.
GetWallpaper | Retrieves the wallpaper currently being used.
GetWallpaperOptions | Retrieves the wallpaper options.
ModifyDesktopItem | Modifies the desktop item.
RemoveDesktopItem | Removes the specified desktop item from the desktop.
SetDesktopItemOptions | Sets the item's options.
SetPattern | Sets the ActiveDesktop pattern.
SetWallpaper | Sets the wallpaper for the Active Desktop.
SetWallpaperOptions | Sets the wallpaper options.


Methods

This section describes the methods exposed by the IActiveDesktop interface.

IActiveDesktop::AddDesktopItem
IActiveDesktop::AddDesktopItemWithUI
IActiveDesktop::AddUrl
IActiveDesktop::ApplyChanges
IActiveDesktop::GenerateDesktopItemHtml
IActiveDesktop::GetDesktopItem
IActiveDesktop::GetDesktopItemByID
IActiveDesktop::GetDesktopItemBySource
IActiveDesktop::GetDesktopItemCount
IActiveDesktop::GetDesktopItemOptions
IActiveDesktop::GetPattern
IActiveDesktop::GetWallpaper
IActiveDesktop::GetWallpaperOptions
IActiveDesktop::ModifyDesktopItem
IActiveDesktop::RemoveDesktopItem
IActiveDesktop::SetDesktopItemOptions
IActiveDesktop::SetPattern
IActiveDesktop::SetWallpaper
IActiveDesktop::SetWallpaperOptions


IActiveDesktop::AddDesktopItem

HRESULT AddDesktopItem(
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Adds a desktop item.

pcomp
Address of the COMPONENT structure associated with the item to be added.
dwReserved
Reserved. Must be set to zero.

If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.

The desktop item is added to the desktop, but it does not save it to the registry. The client application must call IActiveDesktop::ApplyChanges separately to update the registry.


IActiveDesktop::AddDesktopItemWithUI

HRESULT AddDesktopItemWithUI(
    HWND hwnd,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Adds a desktop item to the Active Desktop after displaying user interfaces that confirm the addition of the desktop item, verify security zone permissions, and ask if the user wants to create a subscription.

hwnd
Handle of the parent window. If NULL, the desktop item will be added without displaying any user interface.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwReserved
Reserved. Must be set to zero.

If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.

This method creates a second instance of the Active Desktop to add the desktop item, so the desktop item will not appear in the current instance. The application must call the IUnknown::Release method on this IActiveDesktop interface and the use the CoCreateInstance function to get the Active Desktop object with the newly added component.


IActiveDesktop::AddUrl

HRESULT AddUrl(
    HWND hwnd,
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwFlags
);

Adds the desktop item associated with the specified URL.

hwnd
Handle to the parent window for the user interface.
pszSource
String containing the URL of the desktop item.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwFlags
Unsigned long integer value that controls this method. Can be set to ADDURL_SILENT to add a desktop item without displaying any user interfaces.

If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.

By default, this method will display some user interface and then add the desktop item to the Active Desktop. Like IActiveDesktop::AddDesktopItem, the client application must call IActiveDesktop::ApplyChanges to have the changes saved to the registry.


IActiveDesktop::ApplyChanges

HRESULT ApplyChanges(
    DWORD dwFlags
);

Applies changes to the Active Desktop and saves them in the registry.

dwFlags
Unsigned long integer value that contains the changes to be applied. Can be one of the following values:
AD_APPLY_SAVE
AD_APPLY_HTMLGEN
AD_APPLY_REFRESH
AD_APPLY_ALL
AD_APPLY_FORCE


IActiveDesktop::GenerateDesktopItemHtml

HRESULT GenerateDesktopItemHtml(
    LPCWSTR pwszFileName,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Generates a generic HTML page containing the given desktop item.

pwszFileName
String value containing the name to store the HTML file under.
pcomp
Address of the COMPONENT structure of the desktop item to insert in the HTML page.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::GetDesktopItem

HRESULT GetDesktopItem(
    int nComponent,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves the specified desktop item.

nComponent
Unsigned long integer value that contains the desktop item's index. The index values start at zero. Use IActiveDesktop::GetDesktopItemCount to get a count on the total number of desktop items.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

The index values will change as desktop items are added and removed from the Active Desktop. Applications cannot assume that an index value will always be associated with a particular desktop item.


IActiveDesktop::GetDesktopItemByID

HRESULT GetComponentByID(
    DWORD dwID,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves the desktop item that matches the given identification.

dwID
Unsigned long integer value that contains the desktop item's identification.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

The desktop item's identification is returned in the dwID member of the COMPONENT structure returned from the IActiveDesktop::GetDesktopItem method. This identification is only valid until the IActiveDesktop::ApplyChanges method is called. Applications that need to get the same desktop item consistently should enumerate the desktop items using the IActiveDesktop::GetDesktopItem and IActiveDesktop::GetDesktopItemCount methods.


IActiveDesktop::GetDesktopItemBySource

HRESULT GetDesktopItemBySource (
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves a desktop item using its source URL.

pszSource
String value containing the source URL of the desktop item.
pcomp
Address of the COMPONENT structure that will be used to store the details about the desktop item. The size of the structure must be initialized in order for it to work properly.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::GetDesktopItemCount

HRESULT GetDesktopItemCount(
    LPINT lpiCount,
    DWORD dwReserved
);

Retrieves a count of the desktop items.

lpiCount
Address of an integer value that contains the count.
dwReserved
Reserved. Must be set to zero.

The lpiCount value can be used to enumerate all desktop items. The index values start at zero and go to lpiCount minus one.


IActiveDesktop::GetDesktopItemOptions

HRESULT GetDesktopItemOptions(
    LPCOMPONENTSOPT pco
    DWORD dwReserved
);

Retrieves the desktop item's options.

pco
Address of the COMPONENTSOPT structure containing the options that are currently set.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::GetPattern

HRESULT GetPattern(
    LPWSTR pwszPattern,
    UINT cchPattern,
    DWORD dwReserved
);

Retrieves the pattern currently being used.

pwszPattern
String value that contains a string of decimals whose bit pattern represents a picture.
cchPattern
Unsigned long integer value that contains the size of the string.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::GetWallpaper

HRESULT GetWallpaper(
    LPWSTR pwszWallpaper,
    UINT cchWallpaper,
    DWORD dwReserved
);

Retrieves the wallpaper currently being used.

pwszWallpaper
String value that contains the file name of the wallpaper.
cchWallpaper
Unsigned integer value that contains size of the string.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::GetWallpaperOptions

HRESULT GetWallpaperOptions(
    LPWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Retrieves the wallpaper options.

pwpo
Address of a WALLPAPEROPT structure containing the options currently set.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::ModifyDesktopItem

HRESULT ModifyDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwFlags
);

Modifies the desktop item.

pcomp
Address of the COMPONENT structure containing the modifications. The desktop item associated with the wszSource member of the structure will be modified.
dwFlags
Unsigned long integer value containing the flags used for the modification. Can be one of the following values:
AD_APPLY_SAVE
AD_APPLY_HTMLGEN
AD_APPLY_REFRESH
AD_APPLY_ALL
AD_APPLY_FORCE


IActiveDesktop::RemoveDesktopItem

HRESULT RemoveDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwReserved
);

Removes the specified desktop item from the desktop.

pcomp
Address of the COMPONENT structure that specifies the item to be removed. The desktop item associated with the wszSource member of the structure will be removed.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::SetDesktopItemOptions

HRESULT SetDesktopItemOptions(
    LPCCOMPONENTSOPT pcomp,
    DWORD dwReserved
);

Sets the item's options.

pcomp
Address of the COMPONENTSOPT structure that contains the options to set.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::SetPattern

HRESULT SetPattern(
    LPCWSTR pwszPattern,
    DWORD dwReserved
);

Sets the Active Desktop pattern.

pwszPattern
String value that contains a string of decimals whose bit pattern represents a picture.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::SetWallpaper

HRESULT SetWallpaper(
    LPCWSTR pwszWallpaper,
    DWORD dwReserved
);

Sets the wallpaper for the Active Desktop.

pwszWallpaper
String value containing the file name of the wallpaper to be set.
dwReserved
Reserved. Must be set to zero.


IActiveDesktop::SetWallpaperOptions

HRESULT SetWallpaperOptions(
    LPCWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Sets the wallpaper options.

pwpo
Address of the WALLPAPEROPT structure containing the options to be set.
dwReserved
Reserved. Must be set to zero.


Structures

This section describes the structures used by the methods of the IActiveDesktop interface.
COMPONENT
COMPONENTSOPT
COMPPOS
WALLPAPEROPT


COMPONENT

typedef struct _tagCOMPONENT {
    DWORD dwSize;
    DWORD dwID;
    int iComponentType;
    BOOL fChecked;
    BOOL fDirty;
    BOOL fNoScroll;
    COMPPOS cpPos;
    WCHAR wszFriendlyName[MAX_PATH];
    WCHAR wszSource[INTERNET_MAX_URL_LENGTH];
} COMPONENT;

Contains the information related to a desktop item.

dwSize
Unsigned long integer value that contains the size of the structure.
dwID
Reserved. Must be set to zero. Will contain the desktop item's identification number when returned from IActiveDesktop::GetDesktopItem.
iComponentType
Integer value that indicates the item type. Can be one of the following values:
COMP_TYPE_CFHTML
COMP_TYPE_CONTROL
COMP_TYPE_HTMLDOC
COMP_TYPE_MAX
COMP_TYPE_PICTURE
COMP_TYPE_WEBSITE
fChecked
Boolean value that indicates whether the component is enabled.
fDirty
Boolean value that indicates whether the component has been modified, but has not been saved yet.
fNoScroll
Boolean value that indicates whether the component is scrollable.
cpPos
COMPPOS structure that contains the position information of the item.
wszFriendlyName
Wide character string that contains the friendly name of the item.
wszSource
Wide character string that contains the URL of the item.


COMPONENTSOPT

typedef struct _tagCOMPONENTSOPT {
    DWORD dwSize;
    BOOL fEnableComponents;
    BOOL fActiveDesktop;
} COMPONENTSOPT;

Contains the desktop item options.

dwSize
Unsigned long integer value that contains the size of the structure.
fEnableComponents
Boolean value that determines if desktop items are enabled.
fActiveDesktop
Boolean value that determines if the Active Desktop is enabled.


COMPPOS

typedef _tagCOMPPOS {
    DWORD dwSize;
    int iLeft;
    int iTop;
    DWORD dwWidth;
    DWORD dwHeight;
    int izIndex;
    BOOL fCanResize;
    BOOL fCanResizeX;
    BOOL fCanResizeY;
    int iPreferredLeftPercent;
    int iPreferredTopPercent;
} COMPPOS;

Contains the position information for a desktop item.

dwSize
Unsigned long integer value that contains the size of the structure.
iLeft
Integer value that contains the horizontal location of the top-left corner of the item, in pixels.
iTop
Integer value that contains the vertical location of the top-left corner of the item, in pixels.
dwWidth
Unsigned long integer value that contains the width of the item, in pixels.
dwHeight
Unsigned long integer value that contains the height of the item, in pixels.
izIndex
Integer value that indicates the z-order of the item.
fCanResize
Boolean value that determines if the item can be resized.
fCanResizeX
Boolean value that determines if the width of the item is adjustable.
fCanResizeY
Boolean value that determines if the height of the item is adjustable.
iPreferredLeftPercent
Integer value that indicates the preferred horizontal distance between the top-left corner of the screen and the top-left corner of the item as a percentage of the screen.
iPreferredTopPercent
Integer value that indicates the preferred vertical distance between the top-left corner of the screen and the top-left corner of the item as a percentage of the screen.


WALLPAPEROPT

typedef struct _tagWALLPAPEROPT {
    DWORD dwSize;
    DWORD dwStyle;
} WALLPAPEROPT;

Contains the wallpaper options.

dwSize
Unsigned long integer value that contains the size of the WALLPAPEROPT structure.
dwStyle
Unsigned long integer value that contains the wallpaper style. Can be one of the following values:
WPSTYLE_CENTER
WPSTYLE_TILE
WPSTYLE_STRETCH
WPSTYLE_MAX


Flags

This section contains the flags used by the methods of the IActiveDesktop interface.

AD_APPLY_ALL
Aggregate of the AD_APPLY_SAVE, AD_APPLY_HTMLGEN, and AD_APPLY_REFRESH values.
AD_APPLY_BUFFERED_REFRESH
AD_APPLY_FORCE
Force an Active Desktop change.
AD_APPLY_HTMLGEN
Regenerate the desktop HTML file.
AD_APPLY_REFRESH
Refresh the desktop item.
AD_APPLY_SAVE
Save the desktop item.
COMP_ELEM_ALL
Aggregate of the COMP_ELEM_* values.
COMP_ELEM_CHECKED
The item has been checked.
COMP_ELEM_DIRTY
The item has been changed, but the changes have not been saved.
COMP_ELEM_FRIENDLYNAME
The friendly name of the item.
COMP_ELEM_NOSCROLL
The item is not scrollable.
COMP_ELEM_POS_LEFT
The horizontal position of the item.
COMP_ELEM_POS_TOP
The vertical position of the item.
COMP_ELEM_POS_ZINDEX
The z-index of the item.
COMP_ELEM_SIZE_HEIGHT
The height of the item.
COMP_ELEM_SIZE_WIDTH
The width of the item.
COMP_ELEM_SOURCE
The original source of the item.
COMP_ELEM_TYPE
The item type.
COMP_TYPE_CFHTML
Compressed format HTML.
COMP_TYPE_CONTROL
The item is a control.
COMP_TYPE_HTMLDOC
The item is an HTML document.
COMP_TYPE_MAX
The maximum value of a COMP_TYPE_* flag.
COMP_TYPE_PICTURE
The item is a picture.
COMP_TYPE_WEBSITE
The item is a Web site.
COMPONENT_TOP
An izOrder value meaning the item is at the top.
WPSTYLE_CENTER
The wallpaper is centered.
WPSTYLE_MAX
The maximum value of a WPSTYLE_* flag.
WPSTYLE_STRETCH
The wallpaper is stretched to fit the entire screen.
WPSTYLE_TILE
The wallpaper is tiled.


Asynchronous and URL Monikers

Asynchronous monikers allow an application to bind monikers to an object asynchronously. A URL Moniker, which is an application of asynchronous monikers, allows an application to bind a resource specified by the given Uniform Resource Locator (URL) to a moniker.

Asynchronous and URL Monikers Overview

Asynchronous and URL Monikers Reference


Asynchronous and URL Monikers Overview

Monikers bind objects or Uniform Resource Locators (URLs). This section covers the moniker functionality exported by the Urlmon.dll dynamic-link library (DLL).

Introduction

About URLs and Name Spaces

About Monikers

Creating a URL Moniker

Handling BINDINFO Structures

Using the URL Functions

Appendix A: MIME Type Detection in Internet Explorer 4.0

Introduction

If you want to compile programs that use the functionality provided in Urlmon.dll, you must make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory, of the C/C++ compiler you use.

This documentation assumes that you have an understanding of Microsoft® Win32® programming. Also, for asynchronous monikers, asynchronous pluggable protocols, and URL monikers you should have an understanding of OLE and COM programming. For the Internet-related interfaces, methods, and functions, an understanding of the format and syntax of URLs is also required. For more information, see RFC 1738, Uniform Resource Locators (URL). You can find this document at http://ds.internic.net/rfc/rfc1738.txt. External Link

About URLs and Name Spaces

A Uniform Resource Locator (URL) follows the syntax described in RFC 1738, which specifies a protocol scheme followed by a scheme-specific portion (<scheme>:<scheme-specific portion>). For example, in the URL http://www.microsoft.com/, "http" is the scheme and "//www.microsoft.com/" is the scheme-specific portion.

The beginning portion of the scheme-specific portion of the URL contains the server name. This portion of the URL is often referred to as the URL name space.

About Monikers

Monikers are used as the basis for linking in OLE. After a moniker is bound to an object, the moniker's IMoniker interface can be used to locate, activate, and access the bound object without having any other specific information on where the actual object is located. For standard monikers, this binding process occurs synchronously, which does not impact performance dramatically because the moniker and object are usually on a local system. Examples of objects that can be bound to a moniker include files, items, and pointers.

Binding a moniker to a URL synchronously impacts performance because the process has to wait for responses from the network before completing the binding process. That is where asynchronous monikers, URL monikers, and the URL functions come in.

Asynchronous Monikers

The functionality provided in Urlmon.dll allows a client program to create monikers that can instantiate a named object and return a pointer to one of the object's interfaces asynchronously.

Interfaces related to asynchronous monikers

  • IAsyncMoniker
  • IBinding
  • IBindStatusCallback
  • IPersistMoniker

Functions related to asynchronous monikers

  • CreateAsyncBindCtx
  • IsAsyncMoniker
  • RegisterBindStatusCallback
  • RevokeBindStatusCallback

URL Monikers

A URL moniker is a specific implementation of asynchronous monikers that allows a client program to create a moniker whose data is referenced by a URL.

Interfaces related to URL monikers

  • IAuthenticate
  • IBindHost
  • ICodeInstall
  • IHttpNegotiate
  • IHttpSecurity
  • IWindowForBindingUI
  • IWinInetHttpInfo
  • IWinInetInfo

Functions related to URL monikers

  • CoGetClassObjectFromURL
  • CreateFormatEnumerator
  • CreateURLMoniker
  • FindMediaTypeClass
  • IsValidURL
  • MkParseDisplayNameEx
  • RegisterFormatEnumerator
  • RegisterMediaTypeClass
  • RegisterMediaTypes
  • RevokeFormatEnumerator
  • UrlMkGetSessionOption
  • UrlMkSetSessionOption

URL Functions

The URL functions combine the capabilities of asynchronous monikers and URL monikers into easy-to-use functions.

URL functions

  • URLDownloadToCacheFile
  • URLDownloadToFile
  • URLOpenBlockingStream
  • URLOpenPullStream
  • URLOpenStream

Creating a URL Moniker

Follow these steps to create a URL moniker for an application:

  1. Optional, but recommended. Implement the IBindStatusCallback interface.
  2. Optional, but recommended. Create an instance of your IBindStatusCallback interface.
  3. Call CreateURLMoniker with the URL and get the IMoniker interface.
  4. Call CreateAsyncBindCtx and get the IBindCtx interface.
  5. If IBindStatusCallback has been implemented, call RegisterBindStatusCallback with the IBindCtx and IBindStatusCallback interfaces.
  6. Call one of the IMoniker binding methods (either IMoniker::BindToStorage or IMoniker::BindToObject) with the IBindCtx interface. In the asynchronous case (where IBindStatusCallback has been implemented), the client application may get a pointer to the IStream or IStorage interface. The client application should call the IUnknown::Release method on the interface and use the interface returned in the IBindStatusCallback::OnDataAvailable call.
  7. If IBindStatusCallback has been implemented, the IBindStatusCallback::GetBindInfo method is called by the IMoniker binding method to get the bind information.

    Warning The size of the BINDINFO structure used by IBindStatusCallback::GetBindInfo has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of the IBindStatusCallback::GetBindInfo method before writing to members of the structure. For more information, see the Handling BINDINFO Structures section.

  8. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
  9. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
  10. If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IMoniker::BindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IMoniker::BindToObject was used) will be called.
  11. If IBindStatusCallback has been implemented, steps 9 and 10 are repeated until the binding is completed.
  12. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStopBinding method will be called.

Follow these steps to create a URL moniker for a control:

  1. Optional, but recommended. Implement the IBindStatusCallback interface.
  2. Optional, but recommended. Create an instance of the IBindStatusCallback interface.
  3. Call CreateAsyncBindCtx and get the IBindCtx interface.
  4. Call IBindHost::CreateMoniker with the IBindCtx interface and get the IMoniker interface.
  5. Call one of the IBindHost binding methods (either IBindHost::MonikerBindToStorage or IBindHost::MonikerBindToObject) with the IBindCtx, IMoniker, and IBindStatusCallback (if implemented) interfaces.
  6. If IBindStatusCallback has been implemented, the IBindStatusCallback::GetBindInfo method is called by the IMoniker binding method to get the bind information.

    Warning The size of the BINDINFO structure used by IBindStatusCallback::GetBindInfo has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of the IBindStatusCallback::GetBindInfo method before writing to members of the structure. For more information, see the Handling BINDINFO Structures section.

  7. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
  8. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
  9. If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IBindHost::MonikerBindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IBindHost::MonikerBindToObject was used) will be called.
  10. If IBindStatusCallback has been implemented, steps 8 and 9 are repeated until the binding is completed.
  11. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStopBinding method will be called.

Note IE4/MSHTML does not support the IBindStatusCallback interface. Applications that are hosting IE4/MSHTML and want to get callbacks on the progress of the bind operation should implement the IPropertyNotifySink interface.

Handling BINDINFO Structures

The BINDINFO structure is used by methods, such as IBindStatusCallback::GetBindInfo, to pass information that specifies how a bind operation should be handled. To properly write information to this structure, the client application should:

  • Clear the BINDINFO structure.
  • Check the size of the BINDINFO structure to determine what version has been passed.

Clearing the BINDINFO structure, before writing information into it, prevents members that are not being used from containing incorrect data. The following code fragment demonstrates how to clear the structure.

//pbindinfo is a pointer to a BINDINFO structure
DWORD cbSize = pbindinfo->cbSize;
memset(pbindinfo,0,cbSize);
pbindinfo->cbSize = cbSize;

Since the size of the BINDINFO structure has increased in Internet Explorer 4.0, client applications should check the size of the structure that is passed into their implementation of any methods that use this structure.

The following sample demonstrates how to check the size of the structure for accessing members of the BINDINFO structure beyond cbstgmedData.

if (pbindinfo->cbSize >= offsetof(BINDINFO, dwReserved))
{
    // Write to additional fields.
}
else
{
    // Added functionality is not available, so make any adjustments necessary.
}

Using the URL Functions

The URLDownloadToCacheFile, URLDownloadToFile, URLOpenBlockingStream, URLOpenPullStream, and URLOpenStream functions combine the capabilities of asynchronous monikers and URL monikers into easy-to-use functions.

The following sample demonstrates how to use the URLOpenBlockingStream function.

IStream* pStream;
char buffer[0x100];
DWORD dwGot;
HRESULT hr = NOERROR;

// Open a blocking type stream to the web site stored in the string szWebSite.
URLOpenBlockingStream( 0, szWebSite, &pStream, 0, 0);

do {
    hr = pStream->Read( buffer, sizeof(buffer), &dwGot );
    // Do something with contents of buffer.
} while( SUCCEEDED(hr) && hr != S_FALSE);

return TRUE;

pStream->Release();


Appendix A: MIME Type Detection in Internet Explorer 4.0

The purpose of MIME type detection, or datasniffing, is to determine the MIME type (also known as content type or media type) of downloaded content using information from the following four sources:

  • The server-supplied MIME type, if available
  • An examination of the actual contents associated with a downloaded URL
  • The file name associated with the downloaded content (assumed to be derived from the associated URL)
  • Registry settings (file extension/MIME type associations or registered applications) in effect during the download

MIME type determination occurs in URL monikers through the FindMimeFromData method. Determining the MIME type allows URL monikers and other components to find and launch the correct object server or application to handle the associated content. This section provides a brief summary of the logic used in determining the MIME type from these sources, and discusses some of the issues involved.

FindMimeFromData contains hard-coded tests for (currently 26) separate MIME types (see Known MIME Types). This means that if a given buffer contains data in the format of one of these MIME types, a test exists in FindMimeFromData that is designed (by scanning through the buffer contents) to recognize the corresponding MIME type. A MIME type is known if it is one of these N MIME types. A MIME type is ambiguous if it is 'text/plain', 'application/octet-stream', an empty string, or null (that is, the server failed to provide it). A MIME type that is neither known nor ambiguous is termed unknown. The MIME types 'text/plain' and 'application/octet-stream' are termed ambiguous because they generally do not provide clear indications of which application or CLSID should be associated as the content handler. A MIME type inferred from any one of the four possible sources can be categorized into one of these three classifications.

FindMimeFromData typically receives three parameters when invoked—the cache file name (assumed to be derived from the associated URL), a pointer to a buffer containing up to the first 256 bytes of the content, and a "suggested" MIME type that typically corresponds to the server-provided MIME type (through the Content-type header). Determining the MIME type proceeds as follows:

  1. If the "suggested" (server-provided) MIME type is unknown (not known and not ambiguous), FindMimeFromData immediately returns this MIME type as the final determination. The reason for this is that new MIME types are continually emerging, and these MIME types might have formats that are difficult to distinguish from the set of hard-coded MIME types for which tests exist. A good example of this is SGML, which can easily be classified incorrectly as HTML because it contains many of the same tags. Rather than weakening the hard-coded tests or risk incorrectly classifying new and as-yet-unknown MIME types for hard-coded known ones, priority is given to the server-supplied MIME type if it is unknown, since these MIME types are both specific and likely uncommon, and there are no hard-coded tests that can positively identify them.
  2. If the server-provided MIME type is either known or ambiguous, the buffer is scanned in an attempt to verify or obtain a MIME type from the actual content. If a positive match is found (one of the hard-coded tests succeeded), this MIME type is immediately returned as the final determination, overriding the server-provided MIME type (this type of behavior is necessary to identify a .gif file being sent as text/html). During scanning, it is determined if the buffer is predominantly text or binary.
  3. If no positive match is obtained during the data scan, and if the server-provided MIME type is known, an attempt is made to determine if the format (text or binary) of the known MIME type conflicts with the format (text or binary) that was determined from scanning the buffer. If no conflict exists (the data scan indicates primarily text and the server-provided MIME type has a text format, or the data scan indicates binary and the server-provided MIME type is a binary format), the server-provided MIME type is returned. The reasoning behind this is that new formats of MIME types might be added over time (image/tif is one example) and the hard-coded tests might not recognize these new formats (a different pattern match might be required). With the assumption that the basic format of MIME types will not change over time from primarily text to binary or vice-versa, it will suffice that the formats of the server-provided MIME type and the format found from scanning the data do not disagree. If this is the case, the server-provided MIME type is returned. The format types for known MIME types are stored in a media information structure in URL monikers.
  4. If no positive match is obtained during the data scan, and the server-provided MIME type is ambiguous or the server-provided MIME type is known, and the data format agreement test in the previous step failed, an attempt is made to parse a file extension from the file name passed in. If this is successful, an attempt is made to find the MIME type associated with the file extension in the registry. This will be returned as the final determination if the MIME type associated with the file extension is unknown. The reason for this added requirement is as follows: If the file extension yields an ambiguous MIME type, this adds no information to what was already obtained through scanning the data. If the file extension yields a known MIME type, this MIME type should have been found during scanning. Since it was not, it is suspect, and is rejected. An example of this is an arbitrary plain-text file being returned through an ISAPI DLL, with the server returning 'text/plain' as the MIME type. Since the server-provided MIME type is ambiguous, a scan of the data is conducted that only confirms that the data is plain text. Subsequently, the file name is parsed for an extension. In this case, because the contents were downloaded using an ISAPI DLL, the URL and hence the cache file name will have a .dll file extension that has the MIME type 'application/x-msdownload' associated in the registry. This MIME type was already scanned for (application/x-msdownload is a known MIME type), was not found, and is therefore the wrong determination (this results in a file download as opposed to the desired behavior, which is to display the text in-pane).
  5. If all of the preceding steps have failed to yield an unambiguous MIME type, a last check is made to see if any application is associated in the registry with the file extension parsed from the file name, if one exists. If an associated application is found, the final determination is automatically set to 'application/octet-stream'. This default value ensures that the registered application will be launched by the shell with the downloaded data, rather than displaying the data in-pane. As an example, this is necessary when downloading, among others, .bat and .cmd files, which are plain text files, are frequently identified by the server as 'text/plain', and have no associated MIME type in the registry. Without the final check for an associated application, these would be displayed in-pane, whereas the desired behavior is to launch the command interpreter. This is ensured by checking for an associated application, and defaulting to the final determined MIME type of 'application/octet-stream'. Other types of files, such as .reg files, behave similarly.
  6. Finally, if no file extension is found, or one is found with no associated MIME type or registered application, the MIME type 'text/plain' is returned if the data scan indicated predominantly text, or 'application/octet-stream' if the data scan indicated binary, since this is the furthest correct determination that could be made.

Known MIME Types

Hard-coded tests exist for the following MIME types that currently exist in URL Moniker:
text/richtext
text/html
audio/x-aiff
audio/basic
audio/wav
image/gif
image/jpeg
image/pjpeg
image/tiff
image/x-png
image/x-xbitmap
image/bmp
image/x-jg
image/x-emf
image/x-wmf
video/avi
video/mpeg
application/postscript
application/base64
application/macbinhex40
application/pdf
application/x-compressed
application/x-zip-compressed
application/x-gzip-compressed
application/java
application/x-msdownload

Registry Locations

Location used by FindMimeFromData to find MIME type and progid from file extension:

HKEY_CLASSES_ROOT\.***

Location used by FindMimeFromData to find application from progid:

HKEY_CLASSES_ROOT\<ProgId>\shell\open\command

Location used by URL monikers to find CLSIDs from MIME types:

HKEY_CLASSES_ROOT\MIME\Database\Content Type


Asynchronous and URL Monikers Reference

This reference covers the APIs that are exported from the Urlmon.dll dynamic-link library. These APIs allow a developer to:

  • Create monikers that can instantiate a named object and return a pointer to one of the object's interfaces asynchronously.
  • Create an asynchronous moniker whose data is referenced by a URL (Uniform Resource Locator).
  • Implement customized URL protocols, name space handlers, and MIME filters.
  • Use functions that combine the functionality of asynchronous monikers and URL monikers.
  • Manage URL security zones.

The reference contains the interfaces, methods, functions, structures, enumerated types, security zone flags, and error codes used by these APIs.

Interfaces

Methods

Functions

Structures

Enumerated Types

Error Codes


Interfaces

This section contains the interfaces exposed by monikers, URLs, security zones, and pluggable protocols.
IAsyncMoniker
IAuthenticate
IBindHost
IBinding
IBindProtocol
IBindStatusCallback
ICodeInstall
IHttpNegotiate
IHttpSecurity
IPersistMoniker
ISoftDistExt
IWindowForBindingUI
IWinInetHttpInfo
IWinInetInfo


IAsyncMoniker

IAsyncMoniker provides an implementation of the IUnknown interface, which allows client programs to determine if a moniker supports asynchronous binding. No additional methods are supported by this interface.


IAuthenticate

This interface is implemented by the client application to provide the URL moniker with information to authenticate the user.
IAuthenticate method | Description
Authenticate | Supplies authentication support to a URL moniker from a client application.

Urlmon.dll uses the IUnknown::QueryInterface method on your implementation of IBindStatusCallback to obtain a pointer to your IAuthenticate interface. If the application is hosting Mshtml.dll, Mshtml.dll will request a pointer to your IAuthenticate interface by calling IUnknown::QueryInterface on your IServiceProvider interface.

See also IHttpNegotiate, IServiceProvider, IWindowForBindingUI, IWinInetInfo


IBindHost

This interface is implemented by an ActiveX container that wants controls to do asynchronous data transfers through it.
IBindHost methods | Description
CreateMoniker | Creates a moniker to bind to a URL.
MonikerBindToObject | Binds the moniker to an object.
MonikerBindToStorage | Binds the moniker to storage.


IBinding

This interface provides methods that allow the client program using an asynchronous moniker to control the progress of the bind operation. An asynchronous moniker calls the client's IBindStatusCallback::OnStartBinding method to provide the client program with a pointer to the IBinding interface.
IBinding methods | Description
Abort | Permanently ends the bind operation
GetBindResult | Queries the protocol-specific outcome of a bind operation.
GetPriority | Not currently implemented.
Resume | Not currently implemented.
SetPriority | Not currently implemented.
Suspend | Not currently implemented.


IBindProtocol IBindProtocol *
  * Previous Topic: IBinding
  * Next Topic: IBindStatusCallback

IBindProtocol

Not currently supported.


IBindStatusCallback

This interface accepts information on an asynchronous binding operation. A client requesting an asynchronous bind operation must provide a notification object exposing the IBindStatusCallback interface. The asynchronous moniker provides information on the bind operation to the client by calling notification methods on the client's IBindStatusCallback interface. This interface also allows the client to pass additional bind information to the moniker by calling IBindStatusCallback::GetBindInfo and IBindStatusCallback::GetPriority after receiving a call from IMoniker::BindToObject or IMoniker::BindToStorage.

Only the last IBindStatusCallback interface that was registered will be called.
IBindStatusCallback methods | Description
GetBindInfo | Gets bind information for the bind operation.
GetPriority | Gets data during asynchronous bind operations.
OnDataAvailable | Provides data to the client as it becomes available during asynchronous bind operations.
OnLowResource | Not currently implemented.
OnObjectAvailable | Passes the requested object interface pointer to the client.
OnProgress | Indicates the current progress of this bind operation.
OnStartBinding | Tells the client which callback methods it is registered to receive.
OnStopBinding | Indicates the end of the bind operation.


ICodeInstall ICodeInstall *
  * Previous Topic: IBindStatusCallback
  * Next Topic: IHttpNegotiate

ICodeInstall

Obsolete. Do not use.


IHttpNegotiate

This interface is implemented by a client application to provide support for HTTP negotiations.
IHttpNegotiate methods | Description
BeginningTransaction | Notifies a client of a URL being bound to at the beginning of the HTTP transaction.
OnResponse | Notifies a client upon receiving a response to an HTTP request.

Urlmon.dll will use the IUnknown::QueryInterface method on your implementation of IBindStatusCallback to obtain a pointer to your IHttpNegotiate interface.

See also IWindowForBindingUI, IWinInetInfo


IHttpSecurity

This interface notifies a client application of authentication problems.
IHttpSecurity method | Description
OnSecurityProblem | Notifies the client application about an authentication problem.

Urlmon.dll uses the IUnknown::QueryInterface method on your implementation of IBindStatusCallback to obtain a pointer to your IHttpSecurity interface. If the application is hosting Mshtml.dll, Mshtml.dll will request a pointer to your IHttpSecurity interface by calling IUnknown::QueryInterface on your IServiceProvider interface.


IPersistMoniker

This interface provides methods that offer more control over the binding of persistent data.
IPersist method | Description
GetClassID | Returns the class identifier (CLSID) for the object.
IPersistMoniker methods | Description
GetCurMoniker | Retrieves the moniker that refers to the object's persistent state.
IsDirty | Checks an object for changes since it was last saved.
Load | Loads an object using a specified moniker.
Save | Saves the object, specifying a destination moniker.
SaveCompleted | Notifies the object that the save operation is complete.


ISoftDistExt ISoftDistExt *
  * Previous Topic: IPersistMoniker
  * Next Topic: IWindowForBindingUI

ISoftDistExt

Not currently implemented.


IWindowForBindingUI

This interface allows clients of URL monikers to display information in the client's user interface when necessary. This interface is usually implemented by OLE containers that also implement the IBindHost interface.
IWindowForBindingUI method | Description
GetWindow | Returns an HWND for displaying user interface information.


IWinInetHttpInfo

This interface checks information on HTTP requests made through the underlying Win32® Internet functions.
IWinInetHttpInfo methods | Description
QueryInfo | Queries information about an HTTP request.

Client applications can call IUnknown::QueryInterface on the IBinding interface to get a pointer to the IWinInetHttpInfo interface after your implementation of the IBindStatusCallback::OnProgress method has been called. Not all protocol schemes support this interface.


IWinInetInfo

This interface checks information on the underlying Win32 Internet functions.
IWinInetInfo methods | Description
QueryOption | Retrieves the Win32 Internet function option indicated.

Client applications can call IUnknown::QueryInterface on the IBinding interface to get a pointer to the IWinInetInfo interface after your implementation of the IBindStatusCallback::OnProgress method has been called. Not all protocol schemes support this interface.


Methods

This section contains the methods exposed by monikers, URLs, security zones, and pluggable protocols.
IAuthenticate::Authenticate
IBindHost::CreateMoniker
IBindHost::MonikerBindToObject
IBindHost::MonikerBindToStorage
IBinding::Abort
IBinding::GetBindResult
IBinding::GetPriority
IBinding::Resume
IBinding::SetPriority
IBinding::Suspend
IBindStatusCallback::GetBindInfo
IBindStatusCallback::GetPriority
IBindStatusCallback::OnDataAvailable
IBindStatusCallback::OnLowResource
IBindStatusCallback::OnObjectAvailable
IBindStatusCallback::OnProgress
IBindStatusCallback::OnStartBinding
IBindStatusCallback::OnStopBinding
IHttpNegotiate::BeginningTransaction
IHttpNegotiate::OnResponse
IHttpSecurity::OnSecurityProblem
IPersistMoniker::GetCurMoniker
IPersistMoniker::IsDirty
IPersistMoniker::Load
IPersistMoniker::Save
IPersistMoniker::SaveCompleted
IWindowForBindingUI::GetWindow
IWinInetHttpInfo::QueryInfo
IWinInetInfo::QueryOption


IAuthenticate::Authenticate

HRESULT Authenticate(
    [out] HWND *phwnd,
    [out] LPWSTR *pszUserName,
    [out] LPWSTR *pszPassword
);

Supplies authentication support to a URL moniker from a client application.

  • Returns one of the following values:
    S_OK | Authentication was successful.
    E_ACCESSDENIED | Authentication failed.
    E_INVALIDARG | One or more of the parameters are invalid.
phwnd
Address of a client-provided HWND of the parent window for a default user interface. If no user interface is desired, the client must provide a username and password in the other parameters, and this handle is set to zero.
pszUserName
String that contains the username to use for authentication. If the client returns a value here, it should also set phwnd to zero.
pszPassword
String that contains the password to use for authentication. If the client returns a value here, it should also set phwnd to zero.

The default user interface is able to handle any authentication schemes recognized by the Win32 Internet API. Currently, the username and password options only handle the Basic authentication scheme.

This method is related to the InternetErrorDlg function in the Win32 Internet API. For more information about the Win32 Internet API, see Win32 Internet Functions Overview.


IBindHost::CreateMoniker

HRESULT CreateMoniker (
    [in] LPOLESTR szName,
    [in] IBindCtx *pBC,
    [out] IMoniker **ppmk,
    [in] DWORD dwReserved
);

Creates a moniker to bind to a URL.

szName
URL to bind to.
pBC
Address of the IBindCtx interface.
ppmk
Address of the pointer to the moniker that is created.
dwReserved
Reserved. Must be set to zero.


IBindHost::MonikerBindToObject

HRESULT MonikerBindToObject (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] void **ppvObj
);

Binds a moniker to an object.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the interface that the client application wants to use to communicate with the object.
ppvObj
Address of the interface identified by riid. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.


IBindHost::MonikerBindToStorage

HRESULT MonikerBindToStorage (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] void **ppvObj
);

Binds a moniker to storage.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the storage interface requested.
ppvObj
Address of the storage interface. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.


IBinding::Abort

HRESULT Abort(void);

Permanently ends the bind operation.

  • Returns one of the following values:
    S_OK | Success.
    E_FAIL | The bind operation could not be aborted.
    S_FALSE | The bind operation was already aborted.

This method cannot be called from within an implementation of the IBindStatusCallback::OnStartBinding method.

After aborting the bind operation, the client must still release any pointers obtained during the binding. No IBindStatusCallback notifications will be called except IBindStatusCallback::OnStopBinding.

Releasing the last IBinding interface does not terminate the bind operation.

See also IBindStatusCallback::OnStopBinding


IBinding::GetBindResult

HRESULT GetBindResult(
    [out] CLSID *pclsidProtocol,
    [out] DWORD *pdwBindResult,
    [out] LPWSTR *pszBindResult,
    [in] DWORD dwReserved
);

Queries the protocol-specific outcome of a bind operation.

  • Returns S_OK if successful, or E_INVALIDARG if one of the parameters is not valid.
pclsidProtocol
Address of the CLSID variable for the protocol used.
pdwBindResult
Address of the DWORD variable containing the protocol-specific bind result string.
pszBindResult
Address of the LPWSTR variable containing the protocol-specific bind result.
dwReserved
Reserved for future use; must be NULL.

This method is typically called by the client of an asynchronous moniker when the client's IBindStatusCallback::OnStopBinding method is called.

See also IBindStatusCallback::OnStopBinding


IBinding::GetPriority IBinding::GetPriority *
  * Previous Topic: IBinding::GetBindResult
  * Next Topic: IBinding::Resume

IBinding::GetPriority

HRESULT GetPriority(
    [out] LONG *pnPriority
);

Not currently implemented.


IBinding::Resume IBinding::Resume *
  * Previous Topic: IBinding::GetPriority
  * Next Topic: IBinding::SetPriority

IBinding::Resume

HRESULT Resume(void);

Not currently implemented.


IBinding::SetPriority IBinding::SetPriority *
  * Previous Topic: IBinding::Resume
  * Next Topic: IBinding::Suspend

IBinding::SetPriority

HRESULT SetPriority(
    [in] LONG nPriority
);

Not currently implemented.


IBinding::Suspend IBinding::Suspend *
  * Previous Topic: IBinding::SetPriority
  * Next Topic: IBindStatusCallback::GetBindInfo

IBinding::Suspend

HRESULT Suspend(void);

Suspends the bind operation.


IBindStatusCallback::GetBindInfo

HRESULT GetBindInfo(
    [out] DWORD *pgrfBINDF,
    [in, out] BINDINFO *pbindinfo
);

Obtains the bind information for the bind operation when called by an asynchronous moniker.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
pgrfBINDF
Address of a value taken from the BINDF enumeration indicating whether the bind should proceed synchronously or asynchronously.
pbindinfo
Address of the BINDINFO structure, which describes how the client wants the binding to occur.

The moniker calls this method in its implementations of the IMoniker::BindToObject and IMoniker::BindToStorage methods to obtain information about the specific bind operation.

Asynchronous moniker clients should be aware that a moniker might call this method more than once during a bind operation. A proper implementation of IBindStatusCallback::GetBindInfo should prepare for this possibility. If returning data in the pbindinfo parameter, the implementation should allocate the appropriate data (szExtraInfo and/or stgmedData) at the time of each call. In this way, if the callback is never called, data is never allocated; if the callback is called more than once, it will work correctly. The first time this callback is received by the asynchronous moniker client is before the call to IMoniker::BindToStorage or IMoniker::BindToObject.

Even when the value of pgrfBINDF is BINDF_ASYNCHRONOUS, it is possible that the original call to IMoniker::BindToStorage or IMoniker::BindToObject might return synchronously rather than returning the MK_S_ASYNCHRONOUS flag. Clients of asynchronous monikers should always prepare for this possibility. Specifically, to avoid memory leaks, it is important to make sure to release the pointer returned by a call to either method.

One way to deal with this case is to call your own implementation of IBindStatusCallback::OnDataAvailable or IBindStatusCallback::OnObjectAvailable in order to use the same code path (regardless of whether you bind synchronously or asynchronously).

If the BINDF_PULLDATA value is not set in the pgrfBINDF parameter, Urlmon.dll sets the BINDF_NEEDFILE value. If BINDF_NEEDFILE is set, binding of resources that cannot be cached (such as an https resource) will fail.

Warning The size of the BINDINFO structure has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of this method before writing to members of the structure. See Handling BINDINFO Structures in Asynchronous and URL Monikers Overview for more information.

See also BINDF, BINDINFO, RegisterBindStatusCallback


IBindStatusCallback::GetPriority

HRESULT GetPriority(
    [out] LONG *pnPriority
);

Obtains the priority for the bind operation when called by an asynchronous moniker.

  • Returns S_OK if successful, or E_INVALIDARG if the pnPriority parameter is invalid.
pnPriority
Address of a LONG value indicating the priority of this bind operation. Priorities can be any of the constants defined for prioritizing threads. For details, see the Win32 documentation for SetThreadPriority and GetThreadPriority.

The moniker calls this method, typically prior to initiating the bind operation, to obtain the priority for the bind operation. This method can be called at any time during the bind operation if the moniker needs to make new priority decisions.

The moniker can use pnPriority to set the priority of a thread associated with a bind operation, but more commonly it will interpret the priority to perform its own scheduling among multiple bind operations. Note that the policy for determining priority for URL monikers is not yet determined. The moniker must not change the priority of the thread used for calling IMoniker::BindToStorage or IMoniker::BindToObject.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.


IBindStatusCallback::OnDataAvailable

HRESULT OnDataAvailable(
    [in] DWORD  grfBSCF,
    [in] DWORD  dwSize,
    [in] FORMATETC *pfmtetc,
    [in] STGMEDIUM *pstgmed
);

Provides data to the client as it becomes available during asynchronous bind operations.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
grfBSCF
DWORD value taken from the BSCF enumeration indicating the kind of data available.
dwSize
Size, in bytes, of total data available from the current bind operation.
pfmtetc
Address of the FORMATETC structure that indicates the format of the available data. This parameter is used when the bind operation is a result of the IMoniker::BindToStorage method. If there is no format associated with the available data, pfmtetc might contain CF_NULL. Each different call to IBindStatusCallback::OnDataAvailable can pass in a new value for this parameter, although they all should always point to the same data.
pstgmed
Address of the STGMEDIUM structure that contains the pointers to the interfaces (such as IStream and IStorage) that can be used to access the data. In the asynchronous case, client applications may have received a second pointer to the IStream or IStorage interface from the IMoniker::BindToStorage method, upon which the client application must call IUnknown::Release to avoid memory leaks.

During asynchronous IMoniker::BindToStorage bind operations, an asynchronous moniker calls this method to provide data to the client as it becomes available.

Note that the behavior of the storage returned in pstgmed depends on the BINDF flags returned in the IBindStatusCallback::GetBindInfo method. This storage can be asynchronous or blocking, and the bind operation can follow a data pull model or a data push model. Furthermore, it is important to note that for BINDF_PULLDATA bind operations, it is not possible to seek backward into data streams provided in IBindStatusCallback::OnDataAvailable. On the other hand, for data push model bind operations, it is commonly possible to seek back into a data stream and read any data that has been downloaded for an ongoing IMoniker::BindToStorage operation.

See also BINDF, BSCF, IBindStatusCallback::GetBindInfo


IBindStatusCallback::OnLowResource IBindStatusCallback::OnLowResource *
  * Previous Topic: IBindStatusCallback::OnDataAvailable
  * Next Topic: IBindStatusCallback::OnObjectAvailable

IBindStatusCallback::OnLowResource

HRESULT OnLowResource(
    [in] DWORD  dwReserved
);

Not currently implemented.


IBindStatusCallback::OnObjectAvailable

HRESULT OnObjectAvailable(
    [in] REFIID  riid,
    [in] IUnknown *punk
);

Passes the requested object interface pointer to the client. This method is called in response to an IMoniker::BindToObject operation.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
riid
Interface identifier of the requested interface.
punk
Address of the IUnknown interface on the object requested in the call to IMoniker::BindToObject. The client should call AddRef on this pointer to maintain a reference to the object.

This method is never called for IMoniker::BindToStorage operations.

See also IBindStatusCallback::OnDataAvailable


IBindStatusCallback::OnProgress

HRESULT OnProgress(
    [in] ULONG  ulProgress,
    [in] ULONG  ulProgressMax,
    [in] ULONG  ulStatusCode,
    [in] LPCWSTR  szStatusText
);

Indicates the current progress of the bind operation.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
ulProgress
Current progress of the bind operation relative to the expected maximum indicated in the ulProgressMax parameter.
ulProgressMax
Expected maximum value of the ulProgress parameter for the duration of calls to IBindStatusCallback::OnProgress for this bind operation. Note that this value might change across calls to this method. A value of zero means that the maximum value of ulProgress is unknown (for example, in the IMoniker::BindToStorage method when the data download size is unknown).
ulStatusCode
Additional information regarding the progress of the bind operation. Valid values are taken from the BINDSTATUS enumeration and include:
BINDSTATUS_BEGINDOWNLOADCOMPONENTS | The download operation has begun downloading code for COM components that will be installed before the object can be instantiated. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the component being downloaded.
BINDSTATUS_INSTALLINGCOMPONENTS | The download operation has downloaded code and is installing it. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the component being installed.
BINDSTATUS_ENDDOWNLOADCOMPONENTS | The download operation has finished downloading and installing all the necessary code. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the newly installed component.
szStatusText
Textual information indicating the current progress of the bind operation. The text reflects the BINDSTATUS value of the ulStatusCode parameter and is appropriate for display in the user interface of the client.

The moniker calls this method repeatedly to indicate the current progress of the bind operation, typically at reasonable intervals during a lengthy operation.

The client can use the progress notification to provide progress information to the user from the ulProgress, ulProgressMax, and szStatusText parameters, or to make programmatic decisions based on the ulStatusCode parameter.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

See also BINDSTATUS


IBindStatusCallback::OnStartBinding

HRESULT OnStartBinding(
    [in] DWORD  dwReserved,
    [in] IBinding *pbinding
);

Notifies the client about the callback methods it is registered to receive. This notification is a response to the flags the client requested in the RegisterBindStatusCallback function.

  • Returns S_OK if successful, or E_INVALIDARG if the pbinding parameter is invalid.
dwReserved
Reserved for future use. Must be zero.
pbinding
Address of the IBinding interface of the current bind operation. Cannot be NULL. The client should call AddRef on this pointer to keep a reference to the binding object.

Asynchronous monikers typically call this method before the call to the IMoniker::BindToStorage or IMoniker::BindToObject method has returned.

In the call to this method, the moniker also provides the client with a pointer to the IBinding interface for the binding object associated with the current bind operation. The client can use the IBinding interface to control the progress of the bind operation.

To keep a reference to the binding object, the client must store the pointer to the IBinding interface and call AddRef on it. When the client no longer needs the reference, it must call Release on it. Note that calling Release does not cancel the bind operation; it simply frees the reference to the IBinding interface sent in the callback.

Notes to implementers

A client can return E_NOTIMPL or S_OK if it is not interested in receiving this notification.

The IBinding::Abort method will not work properly within an implementation of IBindStatusCallback::OnStartBinding. To abort the binding, IBindStatusCallback::OnStartBinding should return E_FAIL.

See also IBinding, IBindStatusCallback::OnStopBinding, RegisterBindStatusCallback


IBindStatusCallback::OnStopBinding

HRESULT OnStopBinding(
    [in] HRESULT  hrStatus,
    [in] LPCWSTR  szStatusText
);

Indicates the end of the bind operation.

hrStatus
Status code returned from the bind operation.
szStatusText
Status text. In case of error, this text describes the error. In the current implementation of URL monikers, this string is empty.

This method is always called, whether the bind operation succeeded, failed, or was aborted by a client. At this point the moniker client can use IBinding::GetBindResult to query for protocol-specific information about the outcome of the bind operation. When this method has completed, the moniker client must call IUnknown::Release on the IBinding pointer it received in IBindStatusCallback::OnStartBinding.

Because URL monikers work asynchronously, the status code returned by IBindStatusCallback::OnStopBinding and the status code returned by the binding methods (such as IMoniker::BindToStorage and IMoniker::BindToObject) may differ.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

See also IBinding, IBindStatusCallback::OnStartBinding


IHttpNegotiate::BeginningTransaction

HRESULT BeginningTransaction(
    [in] LPCWSTR  szURL,
    [in] DWORD  dwReserved,
    [in] LPCWSTR  szHeaders,
    [out] LPWSTR * pszAdditionalHeaders
);

Notifies the client of the URL being bound to at the beginning of an HTTP transaction.

  • Returns one of the following values:
    S_OK | Success, and any additional headers specified are appended.
    E_ABORT | The HTTP transaction has been terminated.
    E_INVALIDARG | A parameter is invalid.
szURL
URL for the HTTP transaction.
dwReserved
Reserved for future use.
szHeaders
Current request headers.
pszAdditionalHeaders
Optional additional headers to append to the HTTP request. If these conflict with existing values in szHeaders, the new request headers take precedence. If pszAdditionalHeaders is set to NULL, no headers are added to the HTTP request.

The URL moniker calls this method before sending an HTTP request. It notifies the client of the URL being bound to at the beginning of the HTTP transaction. It also allows the client to add additional headers, such as Accept-Language, to the request.

See also IHttpNegotiate::OnResponse


IHttpNegotiate::OnResponse

HRESULT OnResponse(
    [in] DWORD  dwResponseCode,
    [in] LPCWSTR  szResponseHeaders,
    [in] LPCWSTR  szRequestHeaders,
    [out] LPWSTR * pszAdditionalRequestHeaders
);

Allows the client of a bind operation to examine the response headers, optionally terminate the bind operation, and add HTTP headers to a request before resending the request.

  • Returns one of the following values:
    S_OK | The operation completed successfully. If dwResponseCode indicates an error, any szAdditionalRequestHeaders are appended and the request is sent again.
    E_ABORT | Terminate the HTTP transaction.
    E_INVALIDARG | The parameter is invalid.
dwResponseCode
HTTP response code returned in response to a previous HTTP request. For information about these codes, see the HTTP specification.
szResponseHeaders
Response headers from the HTTP server. For more information, see the HTTP specification.
szRequestHeaders
If dwResponseCode indicates an error, contains HTTP request headers that will be used when the request is sent again.
pszAdditionalRequestHeaders
If dwResponseCode indicates an error, contains optional, additional headers to add before the request is sent again. If the specified header value conflicts with existing values in szRequestHeaders, the new headers take precedence. If pszAdditionalRequestHeaders is set to NULL, no headers are added to the HTTP request.

The URL moniker calls this method when it receives a response to an HTTP request. If dwResponseCode indicates a success, the client can examine the response headers and can optionally abort the bind operation. If dwResponseCode indicates a failure, the client can add HTTP headers to the request before it is sent again.

Note that if multiple clients have registered on the bind context for a given bind operation, more than one of these clients can provide an IHttpNegotiate callback interface. Every client providing this callback receives notifications. Each one is given a chance to add HTTP headers or to abort the HTTP transaction. In such cases, the last client to receive callback notification is the client driving the download operation, and it will dictate the final decision.

See also IHttpNegotiate::BeginningTransaction


IHttpSecurity::OnSecurityProblem

HRESULT OnSecurityProblem (
    [in] DWORD dwProblem
);

Notifies the client application about an authentication problem. This interface should be implemented by applications that want to handle any authentication problems themselves, instead of using the default user interface.

dwProblem
Double-word value that contains the authentication problem encountered. Can be one of the following values:
ERROR_INTERNET_SEC_CERT_DATE_INVALID
ERROR_INTERNET_SEC_CERT_CN_INVALID
ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR
ERROR_INTERNET_HTTPS_TO_HTTP_ON_REDIR
ERROR_HTTP_REDIRECT_NEEDS_CONFIRMATION
ERROR_INTERNET_INVALID_CA
ERROR_INTERNET_CLIENT_AUTH_CERT_NEEDED


IPersistMoniker::GetCurMoniker

HRESULT GetCurMoniker(
    [out] IMoniker **ppimkCur
);

Retrieves the moniker that refers to the object's persistent state.

  • Returns S_OK if a valid absolute path was successfully returned, or E_INVALIDARG if the ppimkCur parameter is invalid.
ppimkCur
Indirect pointer to the moniker that references the object's current persistent state.

Typically, this method returns the moniker last passed to the object by means of the IPersistMoniker::Load, IPersistMoniker::Save, or IPersistMoniker::SaveCompleted method.


IPersistMoniker::IsDirty

HRESULT IsDirty(void);

Checks an object for changes since it was last saved.

  • Returns S_OK if the object has changed since it was last saved, or S_FALSE if not.

This method checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved.

See also IPersistMoniker::Save


IPersistMoniker::Load

HRESULT Load(
    [in] BOOL fFullyAvailable,
    [in] IMoniker *pmkSrc,
    [in] IBindCtx *pbc,
    [in] DWORD grfMode
);

Loads the object from its persistent state indicated by a supplied moniker.

  • Returns S_OK if the object was successfully loaded, or E_INVALIDARG if one or more parameters are invalid.
fFullyAvailable
If TRUE, the data referred to by the moniker has already been loaded once, and subsequent binding to the moniker should be synchronous. If FALSE, an asynchronous bind operation should be launched.
pmkSrc
Address of a moniker that references the persistent state for the object to be loaded.
pbc
Address of the IBindCtx interface for the bind context to be used for any moniker binding during this method.
grfMode
Combination of values from the STGM enumeration, which indicates the access mode to use when binding to the persistent state. The IPersistMoniker::Load method can treat this value as a suggestion, adding more restrictive permissions if necessary. If grfMode is zero, the implementation should bind to the persistent state using default permissions.

Typically, the object will immediately bind to its persistent state through a call to the source moniker's IMoniker::BindToStorage method, requesting either the IStream or IStorage interface.

See also IPersistMoniker::Save, IPersistMoniker::SaveCompleted


IPersistMoniker::Save

HRESULT Save(
    [in] IMoniker *pmkDst,
    [in] IBindCtx *pbc,
    [in] BOOL fRemember
);

Requests that the object save itself to the location referred to by the pmkDst parameter.

  • Returns S_OK if the object was successfully saved, or E_INVALIDARG if one or more parameters are invalid.
pmkDst
Address of the moniker referencing the location where the object should persistently store itself.
pbc
Address of the IBindCtx interface for the bind context to be used for any moniker binding during this method.
fRemember
Indicator of whether pmkDst is to be used as the reference to the current persistent state after the save. If TRUE, pmkDst becomes the reference to the current persistent state, and the object should clear its dirty flag after the save. If FALSE, this save operation is a "Save A Copy As ..." operation. In this case, the reference to the current persistent state is unchanged, and the object should not clear its dirty flag. If pmkDst is NULL, the implementation should ignore the fRemember flag.

See also IPersistMoniker::GetCurMoniker, IPersistMoniker::Load, IPersistMoniker::SaveCompleted


IPersistMoniker::SaveCompleted

HRESULT SaveCompleted(
    [in] IMoniker *pmkNew,
    [in] IBindCtx *pbc
);

Notifies the object that it has been completely saved, and points it to its new persisted state.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
pmkNew
Address of the moniker for the object's new persistent state. This parameter can be NULL if the moniker to the object's new persistent state is the same as the previous moniker to the object's persistent state. This optimization is allowed only if there was a prior call to IPersistMoniker::Save with the fRemember parameter set to TRUE, in which case the object need not rebind to pmkNew.
pbc
Address of the bind context to use for any moniker binding during this method.

See also IPersistMoniker::Load, IPersistMoniker::Save


IWindowForBindingUI::GetWindow

HRESULT GetWindow(
    [in] GUID  guidReason,
    [out] HWND  *phwnd
);

Returns a handle to a window to present information in the user interface during a bind operation.

  • Returns S_OK if the window handle was successfully returned, or E_INVALIDARG if the phwnd parameter is invalid.
guidReason
Same value as IID_IAuthenticate or IID_IHttpSecurity.
phwnd
Address of a window handle to the parent window to use for displaying user interface information.

Notes to implementers

If you implement this interface, you can return S_FALSE for this method to indicate that no window is available for displaying user interface information.

See also IAuthenticate, IHttpNegotiate, IWinInetInfo


IWinInetHttpInfo::QueryInfo

HRESULT QueryInfo (
    [in] DWORD dwOption,
    [in, out] LPVOID pBuffer,
    [in, out] DWORD *pcbBuf,
    [in, out] DWORD *pdwFlags,
    [in, out] DWORD *pdw Reserved
);

Retrieves the specified information from an HTTP request.

dwOption
DWORD value that indicates the information to be queried. Can be set to WININETINFO_OPTION_LOCK_HANDLE to return the lock handle from WinInet. Can also be one of the Option Flags values used by InternetQueryOption.
pBuffer
Address of the buffer where the information will be stored.
pcbBuf
Address of a DWORD value that indicates the size of the buffer.
pdwFlags
Address of a DWORD value that contains the flags controlling the query.
pdwReserved
Reserved. Must be set to NULL.


IWinInetInfo::QueryOption

HRESULT QueryOption (
    [in] DWORD dwOption,
    [in, out] LPVOID pBuffer,
    [in, out] DWORD *pcbBuf
);

Retrieves the Win32 Internet function option indicated.

dwOption
DWORD value that indicates the option to retrieve. Can be one of the QUERYOPTION values.
pBuffer
Address of the buffer where the information will be stored.
pcbBuf
Address of a DWORD value that contains the size of the buffer.


Functions

This section describes the functions included in monikers, URLs, security zones, and pluggable protocols.
CoGetClassObjectFromURL
CoInternetCombineUrl
CoInternetCompareUrl
CoInternetQueryInfo
CopyBindInfo
CopyStgMedium
CreateAsyncBindCtx
CreateAsyncBindCtxEx
CreateFormatEnumerator
CreateURLBinding
CreateURLMoniker
FindMediaType
FindMediaTypeClass
FindMimeFromData
GetClassURL
IsAsyncMoniker
IsValidURL
MkParseDisplayNameEx
ObtainUserAgentString
RegisterBindStatusCallback
RegisterFormatEnumerator
RegisterMediaTypeClass
RegisterMediaTypes
ReleaseBindInfo
RevokeBindStatusCallback
RevokeFormatEnumerator
URLDownloadToCacheFile
URLDownloadToFile
UrlMkGetSessionOption
UrlMkSetSessionOption
URLOpenBlockingStream
URLOpenPullStream
URLOpenStream


CoGetClassObjectFromURL

STDAPI CoGetClassObjectFromURL(
    [in] REFCLSID rclsid,
    [in] LPCWSTR szCodeURL,
    [in] DWORD dwFileVersionMS,
    [in] DWORD dwFileVersionLS,
    [in] LPCWSTR szContentType,
    [in] LPBINDCTX pBindCtx,
    [in] DWORD dwClsContext,
    [in] LPVOID pvReserved,
    [in] REFIID riid,
    [out] VOID ppv * *
);

Returns a factory object for a given CLSID.

  • Returns one of the following values:
    S_OK | The operation completed successfully and the ppv parameter contains the requested interface pointer.
    E_NOINTERFACE | The desired interface pointer is not available.
    MK_S_ASYNCHRONOUS | Component code will be downloaded and installed asynchronously. The client will receive notifications through the IBindStatusCallback interface registered on pBindCtx.
rclsid
CLSID of the ActiveX™ object to be installed. If the value is CLSID_NULL, szContentType is used to determine the CLSID.
szCodeURL
URL pointing to the code for the ActiveX object.
dwFileVersionMS
Major version number for the object to be installed. If this value and the value for dwFileVersionLS are both 0xFFFFFFFF, it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.
dwFileVersionLS
Minor version number for the object to be installed. If this value and the value for dwFileVersionMS are both 0xFFFFFFFF, it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.
szContentType
MIME type to be understood by the installed ActiveX object. If rclsid is CLSID_NULL, this string is used to determine the CLSID of the object to be installed. Note that this parameter is useful only when trying to download a viewer for a particular media type, when the MIME type of media is known but the CLSID is not.
pBindCtx
Bind context to use for downloading/installing component code. Register IBindStatusCallback in this bind context to receive callbacks during the download and installation process.
dwClsContext
Values taken from the CLSCTX enumeration specifying the execution context for the class object.
pvReserved
Reserved. Must be set to NULL.
riid
Interface to obtain on the factory object. Usually, this interface is IClassFactory.
ppv
Upon return for synchronous calls, the pointer in which to store the interface pointer.

If no CLSID is specified (CLSID_NULL), this function chooses the appropriate CLSID for interpreting the Internet mail extensions (MIME) type specified in szContentType. If the desired object is installed on the system, it is instantiated. Otherwise, the necessary code is downloaded and installed from the location specified in szCodeURL.


CoInternetCombineUrl

STDAPI CoInternetCombineUrl(
    LPCWSTR pwzBaseUrl,
    LPCWSTR pwzRelativeUrl,
    DWORD dwCombineFlags,
    LPWSTR pwzResult,
    DWORD cchResult,
    DWORD *pcchResult,
    DWORD dwReserved
);

Combines a base and relative URL into a full URL.

  • Returns one of the following values:
    S_OK | Success.
    S_FALSE | The buffer was too small to contain the resulting URL.
    INET_E_DEFAULT_ACTION
pwzBaseUrl
String value containing the base URL.
pwzRelativeUrl
String value containing the relative URL.
dwCombineFlags
Double-word value that controls the combining process.
pwzResult
String variable where the full URL will be stored.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value to store the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.


CoInternetCompareUrl

STDAPI CoInternetCompareUrl(
    [in] LPCWSTR pwzUrl1,
    [in] LPCWSTR pwzUrl2,
    [in] DWORD dwCompareFlags
);

Compares two URLs and determines if they are equal.

  • Returns S_OK if equal, or S_FALSE otherwise.
pwzUrl1
String value that contains the first URL.
pwzUrl2
String value that contains the second URL.
dwCompareFlags
Double-word value that controls how the comparison should be done. Set to TRUE to ignore slashes, FALSE otherwise.


CoInternetQueryInfo

STDAPI CoInternetQueryInfo(
    LPCWSTR pwzUrl,
    QUERYOPTION QueryOption,
    DWORD dwQueryFlags,
    LPVOID pvBuffer,
    DWORD cbBuffer,
    DWORD *pcbBuffer,
    DWORD dwReserved
);

Retrieves information related to the specified URL.

  • Returns one of the following values:
    S_OK | Success.
    S_FALSE | The buffer was too small to store the information.
    INET_E_QUERYOPTION_UNKNOWN | The option requested is unknown.
pwzUrl
String value containing the URL.
QueryOption
QUERYOPTION value that indicates what option to query.
dwQueryFlags
Double-word value containing the query flags.
pvBuffer
Address of the buffer where the information will be stored.
cbBuffer
Double-word value containing the size of the buffer.
pcbBuffer
Address of a double-word variable where the size of the requested information will be stored.
dwReserved
Reserved. Must be set to zero.


CopyBindInfo

HRESULT CopyBindInfo(
    const BINDINFO *pcbiSrc,
    BINDINFO *pcbiDest
);

Copies the given BINDINFO structure.

pcbiSrc
Address of the BINDINFO structure to be copied.
pcbiDest
Address of the BINDINFO structure to store the copy.


CopyStgMedium

HRESULT CopyStgMedium(
    const STGMEDIUM *pcstgmedSrc,
    STGMEDIUM *pstgmedDest
);

Copies the given STGMEDIUM structure.

pcstgmedSrc
Address of the STGMEDIUM structure to copy.
pstgmedDest
Address of the STGMEDIUM structure to store the copy in.


CreateAsyncBindCtx

HRESULT CreateAsyncBindCtx(
    [in] DWORD dwReserved,
    [in] IBindStatusCallback *pbsc,
    [in] IEnumFORMATETC *penumfmtetc,
    [out] IBindCtx **ppbc
);

Creates an asynchronous bind context for use with asynchronous monikers.

  • Returns one of the following values:
    S_OK | Success.
    E_INVALIDARG | One or more parameters are invalid.
    E_OUTOFMEMORY | The method ran out of memory and did not complete.
dwReserved
Reserved for future use; must be zero.
pbsc
Address of the IBindStatusCallback interface used for receiving data availability and progress notification.
penumfmtetc
Address of the IEnumFORMATETC interface that can be used to enumerate formats for format negotiation during binding. This parameter can be NULL, in which case the calling application is not interested in format negotiation during binding, and the default format of the object will be bound to it.
ppbc
Indirect pointer to the IBindCtx interface for the new bind context.

This function automatically registers the IBindStatusCallback and the IEnumFORMATETC interfaces with the bind context. If the client does not want to receive certain notifications, it can choose to implement those callback methods as empty function stubs (returning E_NOTIMPL), and they should not be called.

The RegisterBindStatusCallback function can also be used to register callback interfaces in the bind context.

See also IBindStatusCallback, RegisterBindStatusCallback


CreateAsyncBindCtxEx

STDAPI CreateAsyncBindCtxEx(
    IBindCtx *pbc,
    DWORD dwOptions,
    IBindStatusCallback *pBSCb,
    IEnumFORMATETC *pEnum,
    IBindCtx **ppBC,
    DWORD reserved
);

Creates an asynchronous bind context for use with asynchronous monikers.

pbc
Address of the IBindCtx interface.
dwOptions
Double-word value that contains the option values.
pBSCb
Address of the IBindStatusCallback interface.
pEnum
Address of the IEnumFORMATETC interface.
ppBC
Address of a pointer to the IBindCtx interface that is returned.
reserved
Reserved. Must be set to zero.


CreateFormatEnumerator

HRESULT CreateFormatEnumerator(
    [in] UINT cfmtetc,
    [in] FORMATETC *rgfmtetc,
    [out] IEnumFORMATETC **ppenumfmtetc
);

Creates an object that implements IEnumFORMATETC over a static array of FORMATETC structures.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
cfmtetc
Number of FORMATETC structures in the static array specified by the rgfmtetc parameter. The cfmtetc parameter cannot be zero.
rgfmtetc
Address of a static array of FORMATETC structures.
ppenumfmtetc
Indirect pointer to the IEnumFORMATETC interface on the enumerator object.

See also RegisterFormatEnumerator, RevokeFormatEnumerator


CreateURLBinding

STDAPI CreateURLBinding(
    LPCWSTR lpszUrl,
    IBindCtx *pbc,
    IBinding **ppBdg
);

Creates an IBinding interface associated with the specified URL.

lpszUrl
String value that contains the URL.
pbc
Address of the IBindCtx interface associated with the URL.
ppBdg
Address of a pointer to the IBinding interface that is created.


CreateURLMoniker

HRESULT CreateURLMoniker(
    [in] IMoniker *pmkContext,
    [in] LPWSTR szURL,
    [out] IMoniker **ppmk
);

Creates a URL moniker from either a full URL string or from a base context URL moniker and a partial URL string.

  • Returns one of the following values:
    S_OK | Success.
    E_OUTOFMEMORY | The operation ran out of memory.
    MK_E_SYNTAX | A moniker could not be created because szURL does not correspond to valid URL syntax for a full or partial URL. This is uncommon, because most parsing of the URL occurs during binding and because the syntax for URLs is extremely flexible.
pmkContext
Address of the IMoniker interface for the URL moniker to use as the base context when the szURL parameter is a partial URL string. The pmkContext parameter can be NULL.
szURL
Display name to be parsed.
ppmk
Indirect pointer to an IMoniker interface for the new URL moniker.


FindMediaType

STDAPI FindMediaType(
    LPCSTR rgszTypes,
    CLIPFORMAT *rgcfTypes
);

Retrieves the media type.

rgszTypes
String value that contains the media types.
rgcfTypes
Address of the CLIPFORMAT value.


FindMediaTypeClass

HRESULT FindMediaTypeClass(
    [in] LPBC pbc,
    [in] LPCSTR szType,
    [out] CLSID *pclsID,
    [in] DWORD dwReserved
);

Retrieves the CLSID for the specified media type.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
pbc
Address of the bind context on which the media type is registered.
szType
String identifying the media types. This parameter cannot be NULL.
pclsID
Address of the CLSID corresponding to the specified media types in szType.
dwReserved
Reserved for future use; must be zero.

See also RegisterMediaTypeClass, RegisterMediaTypes


FindMimeFromData

FindMimeFromData(
    LPBC pBC,
    LPCWSTR pwzUrl,
    LPVOID pBuffer,
    DWORD cbSize,
    LPCWSTR pwzMimeProposed,
    DWORD dwMimeFlags,
    LPWSTR *ppwzMimeOut,
    DWORD dwReserved
);

Determines the MIME type from the data provided.

pBC
Address of the bind context. Can be set to NULL.
pwzUrl
String value that contains the URL of the data. Can be set to NULL if pBuffer contains the data to be sniffed.
pBuffer
Address of the buffer containing the data to be sniffed. Can be set to NULL if pwzUrl contains a valid URL.
cbSize
Double-word value that contains the size of the buffer.
pwzMimeProposed
String value containing the proposed MIME type. Can be set to NULL.
dwMimeFlags
Not currently defined. Must be set to zero.
ppwzMimeOut
Address of a string value containing the suggested MIME type.
dwReserved
Reserved. Must be set to zero.


GetClassURL

STDAPI GetClassURL(
    LPCWSTR szURL,
    CLSID *pClsID
);

Gets the class identification associated with the URL.

szURL
String that contains the URL.
pClsID
Address of the class identification associated with the URL.


IsAsyncMoniker

HRESULT IsAsyncMoniker(
    [in] IMoniker *pmk
);

Tests if a moniker supports asynchronous binding.

  • Returns S_OK if the specified moniker is asynchronous, or E_INVALIDARG if the pmk parameter is invalid.
pmk
Address of the IMoniker interface on the moniker to be tested.

A moniker implementation indicates that it is asynchronous by supporting the IAsyncMoniker interface, an empty interface that is just an implementation of IUnknown. The IsAsyncMoniker function tests for support of IAsyncMoniker and also handles composite monikers correctly.

See also IAsyncMoniker


IsValidURL

HRESULT IsValidURL(
    [in] LPBC pBC,
    [in] LPCWSTR szURL,
    [in] DWORD dwReserved
);

Determines if a specified string is a valid URL.

  • Returns one of the following values:
    S_OK | The szURL parameter contains a valid URL.
    S_FALSE | The szURL parameter does not contain a valid URL.
    E_INVALIDARG | One of the parameters is invalid.
pBC
Address of the IBindCtx interface. Optional and currently ignored. Should be set to NULL.
szURL
URL whose validity is to be checked. For the purposes of this function, a valid URL must specify an absolute path.
dwReserved
Reserved for future use. Must be set to zero.

Relative URLs are not considered valid by this function.


MkParseDisplayNameEx

HRESULT MkParseDisplayNameEx(
    [in] IBindCtx*pbc,
    [in] LPWSTR  szDisplayName,
    [out] ULONG *pcchEaten,
    [out] IMoniker **ppmk
);

Given a string, returns a moniker of the object that the string denotes.

  • Returns one of the following values:
    S_OK | Success.
    E_OUTOFMEMORY | The operation ran out of memory.
    MK_E_SYNTAX | Parsing failed because szDisplayName could only be partially resolved into a moniker. In this case, pcchEaten has the number of characters that were successfully parsed into a moniker prefix.
pbc
Address of the bind context in which to accumulate bound objects.
szDisplayName
Display name to be parsed.
pcchEaten
Address of the number of characters of the display name that were successfully parsed. Most useful on syntax error, when a nonzero value is often returned and therefore a subsequent call to MkParseDisplayNameEx with the same pbc parameter and a shortened szDisplayName parameter should return a valid moniker.
ppmk
Indirect pointer to the resulting moniker.

See also IParseDisplayName


ObtainUserAgentString

HRESULT ObtainUserAgentString(
    DWORD dwOption,
    LPCSTR pcszUAOut,
    DWORD *cbSize
);

Retrieves the user agent string in use.

dwOption
Reserved. Must be set to zero.
pcszUAOut
String value that contains the user agent string currently being used.
cbSize
Address of an unsigned long integer value that contains the length of the string.


RegisterBindStatusCallback

HRESULT RegisterBindStatusCallback(
    [in] IBindCtx *pbc,
    [in] IBindStatusCallback *pbsc,
    [out] IBindStatusCallback **ppbscPrevious,
    [in] DWORD  dwReserved
);

Registers a callback interface with an existing bind context.

  • Returns one of the following values:
    S_OK | Success.
    E_INVALIDARG | One or more parameters are invalid.
    E_OUTOFMEMORY | There was insufficient memory to register the callback with the bind context.
pbc
Address of the IBindCtx interface to receive callbacks from.
pbsc
Address of the IBindStatusCallback interface implementation to be registered.
ppbscPrevious
Address of a pointer to a previously registered instance of IBindStatusCallback.
dwReserved
Reserved for future use.

The IBindStatusCallback interface passed into the pbsc parameter will receive callbacks on any binding operations using the bind context passed into the pbc parameter.

Only the last IBindStatusCallback interface that was registered to a particular bind context will receive callbacks. The implementation of IBindStatusCallback could pass the callbacks it receives to the previously registered IBindStatusCallback interface using the address of a pointer in the ppbscPrevious parameter.

See also IBindStatusCallback, RevokeBindStatusCallback


RegisterFormatEnumerator

HRESULT RegisterFormatEnumerator(
    [in] LPBC pBC,
    [in] IEnumFORMATETC *pEFetc,
    [in] DWORD  reserved
);

Registers a FORMATETC enumerator object onto the given bind context.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
pBC
Address of the IBindCtx interface for the bind context on which to register the enumerator.
pEFetc
Address of the IEnumFORMATETC interface for the enumerator to be registered.
reserved
Reserved. Must be set to zero.

The enumerator is used to determine what format types are preferred for the bind operation. Typically, the pEFetc parameter would be the pointer obtained through a call to CreateFormatEnumerator.

See also CreateFormatEnumerator, RevokeFormatEnumerator


RegisterMediaTypeClass

HRESULT RegisterMediaTypeClass(
    [in] LPBC pbc,
    [in] UINT ctypes,
    [in] LPCSTR  *rgszTypes,
    [in] CLSID  *rgclsID,
    [in] DWORD  dwReserved
);

Registers a mapping of media types to CLSIDs to override the default mapping specified in the registry. The new mapping is used in calls to IMoniker::BindToObject when binding objects in the specified bind context.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
pbc
Address of the IBindCtx interface for the bind context in which the media types are to be registered.
ctypes
Number of media type strings in the rgszTypes array. This parameter cannot be zero.
rgszTypes
Address of an array of strings identifying the media types to be registered. None of these strings can be NULL.
rgclsID
Address of an array of CLSIDs corresponding to the media type strings in the rgszTypes array.
dwReserved
Reserved for future use; must be zero.

This function is primarily used by moniker clients calling IMoniker::BindToObject to override the default registry mapping between MIME types and CLSIDs. In most cases, the default mapping provided in the registry is used. However, a Web browser might want the CLSID for its HTML viewer to be associated with .txt files without changing the default registry association for text files. The override is used for all bind operations using the specified bind context.

See also RegisterMediaTypes


RegisterMediaTypes

HRESULT RegisterMediaTypes (
    [in] UINT  ctypes,
    [in] LPCSTR *rgszTypes,
    [out] CLIPFORMAT *rgcfTypes
);

Registers media type strings.

  • Returns S_OK if successful, or E_INVALIDARG if one or more parameters are invalid.
ctypes
Number of media type strings in the rgszTypes array. This parameter cannot be zero.
rgszTypes
Address of an array of strings identifying the media types to be registered. None of the strings in the array can be NULL. Can be one of the values in the following list.
Value | Meaning
CF_NULL | 0
SZ_URLCONTEXT | (L"URL Context")
CFSTR_MIME_FRACTALS | (TEXT("application/fractals"))
CFSTR_MIME_POSTSCRIPT | (TEXT("application/postscript"))
CFSTR_MIME_RAWDATA | (TEXT("application/octet"))
CFSTR_MIME_AIIF | (TEXT("audio/aiif"))
CFSTR_MIME_BASICAUDIO | (TEXT("audio/basic"))
CFSTR_MIME_WAV | (TEXT("audio/wav"))
CFSTR_MIME_X_AIIF | (TEXT("audio/x-aiif"))
CFSTR_MIME_X_REALAUDIO | (TEXT("audio/x-pn-realaudio"))
CFSTR_MIME_X_WAV | (TEXT("audio/x-wav"))
CFSTR_MIME_BMP | (TEXT("image/bmp"))
CFSTR_MIME_GIF | (TEXT("image/gif"))
CFSTR_MIME_JPEG | (TEXT("image/jpeg"))
CFSTR_MIME_TIFF | (TEXT("image/tiff"))
CFSTR_MIME_XBM | (TEXT("image/xbm"))
CFSTR_MIME_X_BITMAP | (TEXT("image/x-bitmap"))
CFSTR_MIME_HTML | (TEXT("text/html"))
CFSTR_MIME_TEXT | (TEXT("text/plain"))
CFSTR_MIME_AVI | (TEXT("video/avi"))
CFSTR_MIME_MPEG | (TEXT("video/mpeg"))
CFSTR_MIME_QUICKTIME | TEXT("video/quicktime"))
CFSTR_MIME_X_MSVIDEO | (TEXT("video/x-msvideo"))
CFSTR_MIME_X_SGI_MOVIE | (TEXT("video/x-sgi-movie"))
rgcfTypes
Address of an array of the 32-bit values assigned to corresponding media types in rgszTypes.

See also RegisterMediaTypeClass


ReleaseBindInfo

ReleaseBindInfo(
    BINDINFO *pbindinfo
);

Releases the resources used by the specified BINDINFO structure.

pbindinfo
Address of the specified BINDINFO structure.


RevokeBindStatusCallback

HRESULT RevokeBindStatusCallback(
    [in] IBindCtx *pbc,
    [in] IBindStatusCallback *pbsc
);

Revokes a bind status callback interface previously registered on a bind context.

  • Returns one of the following values:
    S_OK | Success.
    E_FAIL | The callback interface specified is not registered on the specified bind context.
    E_INVALIDARG | One or more parameters are invalid.
pbc
Address of the IBindCtx interface for the bind context from which the callback interface is to be revoked.
pbsc
Address of the IBindStatusCallback interface to revoke.

This function will not succeed if it is made during a bind operation.

Note that it is not necessary to make this call for every use of a bind context. It is possible, although not recommended, to reuse the same bind context and the same callback for several bind operations. Upon calling the IUnknown::Release method, all registered objects on that bind context are revoked, including the callback interfaces. Therefore, releasing a bind context implicitly releases all registered callbacks. However, if you choose to reuse a bind context, you can use RevokeBindStatusCallback to remove a registered callback so it is not reused.

See also IBindStatusCallback, RegisterBindStatusCallback


RevokeFormatEnumerator

HRESULT RevokeFormatEnumerator(
    [in] LPBC pbc,
    [in] IEnumFORMATETC *pEFetc
);

Removes a format enumerator from the given bind context.

  • Returns S_OK if the enumerator was successfully removed, or E_INVALIDARG if one or more parameters are invalid.
pbc
Address of the IBindCtx interface for the bind context from which the enumerator is to be revoked.
pEFetc
Address of the IEnumFORMATETC interface for the enumerator to revoke.

This function removes a format enumerator from the bind context specified in pbc. It must previously have been registered with a call to RegisterFormatEnumerator.

Note that it is not necessary to make this call for every use of a bind context. It is possible (although not recommended) to reuse the same bind context and the same format enumerator for several bind operations. Upon calling IUnknown::Release, all registered objects on that bind context are revoked, including the format enumerator interfaces. Therefore, releasing a bind context implicitly releases all registered format enumerators. However, if you choose to reuse a bind context, you can use RevokeFormatEnumerator to remove a registered format enumerator so it is not reused.

See also RegisterFormatEnumerator


URLDownloadToCacheFile

HRESULT URLDownloadToCacheFile(
    LPUNKNOWN lpUnkcaller,
    LPCSTR szURL,
    LPTSTR szFileName,
    DWORD dwBufLength,
    DWORD dwReserved,
    IBindStatusCallback *pBSC
);

Downloads data into the Internet cache and returns the file name of the cache location for retrieving the bits. The client can choose to be notified of progress through a notification callback.

lpUnkcaller
Address of the controlling IUnknown interface of the calling ActiveX™ component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
URL to be downloaded. Cannot be NULL.
szFileName
Name of the downloaded file. Cannot be NULL.
dwBufLength
DWORD value that contains the size of the szFileName buffer or a flag. If a flag is set to dwBufLength, the buffer is assumed to be of size MAX_PATH. The flag can be one of the following values:
URLOSTRM_GETNEWESTVERSION | Download the resource from the Internet, if it is newer, and store it in the cache.
URLOSTRM_USECACHEDCOPY | Download the resource from the cache if it is available; otherwise, download it from the Internet.
URLOSTRM_USECACHEDCOPY_ONLY | Only download the resource from the cache.
dwReserved
Reserved. Must be set to zero.
pBSC
Address of the caller's IBindStatusCallback interface. URLDownloadToCacheFile calls this interface's IBindStatusCallback::OnProgress method on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call. Can be NULL.

This function always returns a file name if the download operation succeeds. If the given URL is a "file:" URL, URLDownloadToCacheFile directly returns the file name for the "file:" URL rather than making a copy to the cache. If the given URL is an Internet URL ("http:", "ftp:"), URLDownloadToCacheFile downloads this file and returns the local file name of the cached copy. Using this function ensures that a file name is returned without unnecessary copying of data.


URLDownloadToFile

HRESULT URLDownloadToFile(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    LPCSTR szFileName,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Downloads bits from the Internet and saves them to a file. The client can choose to be notified of progress through a notification callback.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the calling application is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be downloaded. Cannot be NULL.
szFileName
String containing the name of the file to create for bits that come from the download.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface. URLDownloadToFile calls this interface's IBindStatusCallback::OnProgress method on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call. Can be NULL.


UrlMkGetSessionOption

WINOLEAPI UrlMkGetSessionOption(
    [in] DWORD dwOption,
    [in] LPVOID pBuffer,
    [in] DWORD dwBufferLength,
    [out] DWORD *pdwBufferLength,
    [in] DWORD dwReserved
);

Sets options for the current Internet session.

  • Returns one of the following values:
    S_OK | Option was successfully set.
    E_INVALIDARG | The option is not supported.
    E_FAIL | Unable to set the option.
dwOption
Unsigned long integer value containing the session options to be retrieved. Currently, URL monikers support only the URLMON_OPTION_USERAGENT value, which retrieves the current user agent string.
pBuffer
Address of the buffer containing the new session settings.
dwBufferLength
Double-word value containing the size of pBuffer.
pdwBufferLength
Address of a double-word value containing the size of the data stored in the buffer or the size required to store the data if the buffer size was insufficient.
dwReserved
Reserved for future use. Must be set to zero.


UrlMkSetSessionOption

HRESULT UrlMkSetSessionOption(
    [in] DWORD dwOption,
    [in] LPVOID pBuffer,
    [in] DWORD dwBufferLength,
    [in] DWORD dwReserved
);

Sets options for the current Internet session.

  • Returns S_OK if options were successfully set, or E_INVALIDARG if one of the parameters is invalid.
dwOption
Session option to be set. Can be one of the following values:
INTERNET_OPTION_PROXY | Sets the proxy settings. pBuffer must contain an INTERNET_PROXY_INFO structure. INTERNET_OPTION_PROXY and INTERNET_PROXY_INFO are defined in the Wininet.h file. For more information, see the Microsoft Win32 Internet Function Reference.
INTERNET_OPTION_REFRESH | Sets the value that determines if the proxy information can be reread from the registry. The value TRUE indicates that the proxy information can be reread from the registry. For more information on this value, see the Microsoft Win32 Internet Function Reference.
pBuffer
Buffer containing the new session settings.
dwBufferLength
Size of pBuffer.
dwReserved
Reserved for future use. Must be set to zero.

This function maps directly to the Windows® Internet function InternetSetOption, although UrlMkSetSessionOption allows only global options to be set.

To use this function, the client code must include the Wininet.h header file, which declares values for the dwOption parameter and structures for the pBuffer parameter.


URLOpenBlockingStream

HRESULT URLOpenBlockingStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    LPSTREAM *ppStream,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a blocking type stream object from a URL and downloads the data from the Internet. When the data is downloaded, the client application or control can read it using the IStream::Read method.

pCaller
Address of the controlling IUnknown interface. If the client application or control is not a COM object or ActiveX control, the parameter can be set to NULL.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
ppStream
Address of the IStream interface on the stream object created by this function. The caller can read from the stream as soon as it has this pointer.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface. Can be set to NULL.

This function is synchronous and will only return after all the data has been downloaded from the Internet.

URLOpenBlockingStream calls the IBindStatusCallback::OnProgress method (if provided) on a connection activity, including the arrival of data. IBindStatusCallback::OnDataAvailable is never called. Implementing IBindStatusCallback::OnProgress allows a caller to implement a user interface or other progress monitoring functionality. It also allows the download operation to be canceled by returning E_ABORT from the IBindStatusCallback::OnProgress call.


URLOpenPullStream

HRESULT URLOpenPullStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a pull type stream object from a URL.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface, on which URLOpenPullStream calls IBindStatusCallback::OnDataAvailable when data arrives from the Internet. IBindStatusCallback::OnDataAvailable can return E_ABORT to abort the download.

The pull model is slightly more cumbersome than the push model, but it allows the client to control the amount of Internet access for the download.

The data is downloaded from the Internet on demand. If not enough data is available locally to satisfy the requests, the IStream::Read call will not block until enough data has arrived. Instead, IStream::Read immediately returns E_PENDING, and URLOpenPullStream requests the next packet of data from the Internet server.


URLOpenStream

HRESULT URLOpenStream(
    LPUNKNOWN pCaller,
    LPCSTR szURL,
    DWORD dwReserved,
    LPBINDSTATUSCALLBACK lpfnCB
);

Creates a push type stream object from a URL.

pCaller
Address of the controlling IUnknown interface of the calling ActiveX component (if the caller is an ActiveX component). If the caller is not an ActiveX component, this value can be set to NULL. Otherwise, the caller is a COM object that is contained in another component (such as an ActiveX control within the context of an HTML page). This parameter represents the outermost IUnknown of the calling component. The function attempts the download within the context of the ActiveX client framework and allows the caller's container to receive callbacks on the progress of the download.
szURL
String containing the URL to be converted to a stream object. Cannot be NULL.
dwReserved
Reserved for future use. Must be zero.
lpfnCB
Address of the caller's IBindStatusCallback interface, on which URLOpenStream calls IBindStatusCallback::OnDataAvailable when data arrives from the Internet. IBindStatusCallback::OnDataAvailable can return E_ABORT to abort the download.

The data is downloaded from the Internet as fast as possible. When data is available, it is pushed at the client through a notification callback.


Structures

This section contains the structures that are exposed by Urlmon.dll.
BINDINFO
PROTOCOLDATA
PROTOCOLFILTERDATA
ZONEATTRIBUTES


BINDINFO

typedef struct _tagBINDINFO {
    ULONG cbSize;
    LPWSTR szExtraInfo;
    STGMEDIUM stgmedData;
    DWORD grfBindInfoF;
    DWORD dwBindVerb;
    LPWSTR szCustomVerb;
    DWORD cbStgmedData;
    DWORD dwOptions;
    DWORD dwOptionsFlags;
    DWORD dwCodePage;
    SECURITY_ATTRIBUTES securityAttributes;
    IID iid;
    IUnknown *pUnk;
    DWORD dwReserved;
} BINDINFO;

Contains additional information on the requested binding operation. The meaning of this structure is specific to the type of asynchronous moniker.

cbSize
Size of the structure, in bytes.
szExtraInfo
Behavior of this field is moniker-specific. For URL monikers, this string is appended to the URL when the bind operation is started. Like other OLE strings, this value is a Unicode string that the client should allocate using CoTaskMemAlloc. The URL moniker frees the memory later.
stgmedData
Data to be used in a PUT or POST operation specified by the dwBindVerb member.
grfBindInfoF
Flag from the BINDINFOF enumeration that determines the use of URL encoding during the binding operation. This member is specific to URL monikers.
dwBindVerb
Value from the BINDVERB enumeration specifying an action to be performed during the bind operation.
szCustomVerb
String specifying a protocol-specific custom action to be performed during the bind operation (only if dwBindVerb is set to BINDVERB_CUSTOM).
cbStgmedData
Size of the data provided in the stgmedData member.
dwOptions
Double-word value that contains additional options.
dwOptionsFlags
Double-word value that contains the option flags.
dwCodePage
Double-word value that contains the code used to convert the URL.
securityAttributes
SECURITY_ATTRIBUTES structure that contains the descriptor for the object being bound to and specifies whether the handle retrieved by specifying this structure is inheritable.
iid
Interface identifier of the IUnknown interface referred to by pUnk.
pUnk
Address of the IUnknown interface.
dwReserved
Reserved. Must be set to zero.

The size of this structure has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of this method before writing to members of the structure. See Handling BINDINFO Structures in Asynchronous and URL Monikers Overview for more information.

See also BINDINFOF, BINDVERB, IBindStatusCallback::GetBindInfo


Enumerated Types

This section contains the enumerated types that are exposed by Urlmon.dll.
BINDF
BINDINFOF
BINDSTATUS
BINDSTRING
BINDVERB
BSCF
CIP_STATUS
QUERYOPTION


BINDF

typedef  {
    BINDF_ASYNCHRONOUS = 0x00000001,
    BINDF_ASYNCSTORAGE = 0x00000002,
    BINDF_NOPROGRESSIVERENDERING = 0x00000004,
    BINDF_OFFLINEOPERATION = 0x00000008,
    BINDF_GETNEWESTVERSION = 0x00000010,
    BINDF_NOWRITECACHE = 0x00000020,
    BINDF_NEEDFILE = 0x00000040,
    BINDF_PULLDATA = 0x00000080,
    BINDF_IGNORESECURITYPROBLEM = 0x00000100,
    BINDF_RESYNCHRONIZE = 0x00000200,
    BINDF_HYPERLINK = 0x00000400,
    BINDF_NO_UI = 0x00000800,
    BINDF_SILENTOPERATION = 0x00001000,
    BINDF_PRAGMA_NO_CACHE = 0x00002000,
    BINDF_FREE_THREADED = 0x00010000,
    BINDF_DIRECT_READ = 0x00020000,
    BINDF_FORMS_SUBMIT = 0x00040000,
    BINDF_GETFROMCACHE_IF_NET_FAIL = 0x00080000
} BINDF;

Values from the BINDF enumeration are returned to the moniker from the client's IBindStatusCallback::GetBindInfo method. These values specify the type of binding the client wants from the moniker.

BINDF_ASYNCHRONOUS
Moniker should return immediately from IMoniker::BindToStorage or IMoniker::BindToObject. The actual result of the object bind or the data backing the storage arrives asynchronously. The client is notified through calls to its IBindStatusCallback::OnDataAvailable or IBindStatusCallback::OnObjectAvailable method. If the client does not specify this flag, the bind operation will be synchronous, and the client will not receive any data from the bind operation until the IMoniker::BindTo Xxx call returns.
BINDF_ASYNCSTORAGE
Client of the IMoniker::BindToStorage method prefers that the storage and stream objects returned in IBindStatusCallback::OnDataAvailable return E_PENDING when they reference data not yet available through their read methods, rather than blocking until the data becomes available. This flag applies only to BINDF_ASYNCHRONOUS operations. Note that asynchronous stream objects return E_PENDING while data is still downloading and return S_FALSE for the end of the file.
BINDF_NOPROGRESSIVERENDERING
Do not allow progressive rendering.
BINDF_OFFLINEOPERATION
Bind to a cached version of the resource.
BINDF_GETNEWESTVERSION
Bind operation should retrieve the newest version of the data/object possible. For URL monikers, this flag maps to the Win32 Internet API flag, INTERNET_FLAG_RELOAD, which forces a dowload of the requested resource.
BINDF_NOWRITECACHE
Bind operation should not store retrieved data in the disk cache.
BINDF_NEEDFILE
Downloaded resource must be saved in the cache.
BINDF_PULLDATA
Asynchronous moniker allows the client of IMoniker::BindToStorage to drive the bind operation by pulling the data, rather than having the moniker drive the operation by pushing the data to the client. Specifically, when this flag is specified, new data is only read/downloaded after the client finishes reading all data that is currently available. This means data is only downloaded for the client after the client does an IStream::Read operation that blocks or returns E_PENDING. When the client specifies this flag, it must be sure to read all the data it can, even data that is not necessarily available yet. When this flag is not specified, the moniker continues downloading data and calls the client with IBindStatusCallback::OnDataAvailable whenever new data is available. This flag applies only to BINDF_ASYNCHRONOUS bind operations.
BINDF_IGNORESECURITYPROBLEM
Ignore any security problems.
BINDF_RESYNCHRONIZE
Resynchronizes the resource. For URL monikers, this flag maps to the Win32 Internet API flag, INTERNET_FLAG_RESYNCHRONIZE, which reloads an HTTP resource if the resource has been modified since the last time it was downloaded. All FTP and Gopher resources are reloaded.
BINDF_HYPERLINK
Allow hyperlinks.
BINDF_NO_UI
Do not display any user interfaces.
BINDF_SILENTOPERATION
Operate silently. No user interface or user notification should occur.
BINDF_PRAGMA_NO_CACHE
Do not store the resource in the cache.
BINDF_FREE_THREADED
Reserved for future use.
BINDF_DIRECT_READ
Client does not need to know the exact size of the data available, so the information is read directly from the source.
BINDF_FORMS_SUBMIT
Handle this transaction as a forms submittal.
BINDF_GETFROMCACHE_IF_NET_FAIL
Retrieve the resource from the cache if the attempt to download the resource from the network fails.

See also IBindStatusCallback::OnDataAvailable, IBindStatusCallback::OnObjectAvailable, IBindStatusCallback::OnStartBinding


BINDINFOF

typedef enum tagBINDINFOF {
    BINDINFOF_URLENCODESTGMEDDATA,
    BINDINFOF_URLENCODEDEXTRAINFO
} BINDINFOF;

Values from the BINDINFOF enumeration are passed to the moniker as part of the BINDINFO structure. The moniker calls the IBindStatusCallback::GetBindInfo method on the client to obtain additional information about the bind operation in the BINDINFO structure. The grfBindInfoF member of the BINDINFO structure determines the use of URL encoding during the binding operation.

BINDINFOF_URLENCODESTGMEDDATA
Use URL encoding to pass in the data provided in the stgmedData member of the BINDINFO structure for PUT and POST operations.
BINDINFOF_URLENCODEDEXTRAINFO
Use URL encoding to pass in the data provided in the szExtraInfo member of the BINDINFO structure.

See also IBindStatusCallback::GetBindInfo, BINDINFO


BINDSTATUS

typedef enum tagBINDSTATUS {
    BINDSTATUS_FINDINGRESOURCE,
    BINDSTATUS_CONNECTING,
    BINDSTATUS_REDIRECTING,
    BINDSTATUS_BEGINDOWNLOADDATA,
    BINDSTATUS_DOWNLOADINGDATA,
    BINDSTATUS_ENDDOWNLOADDATA,
    BINDSTATUS_BEGINDOWNLOADCOMPONENTS,
    BINDSTATUS_INSTALLINGCOMPONENTS,
    BINDSTATUS_ENDDOWNLOADCOMPONENTS,
    BINDSTATUS_USINGCACHEDCOPY,
    BINDSTATUS_SENDINGREQUEST,
    BINDSTATUS_CLASSIDAVAILABLE,
    BINDSTATUS_MIMETYPEAVAILABLE,
    BINDSTATUS_CACHEFILENAMEAVAILABLE,
    BINDSTATUS_BEGINSYNCOPERATION,
    BINDSTATUS_ENDSYNCOPERATION,
    BINDSTATUS_BEGINUPLOADDATA,
    BINDSTATUS_UPLOADINGDATA,
    BINDSTATUS_ENDUPLOADINGDATA,
    BINDSTATUS_PROTOCOLCLASSID,
    BINDSTATUS_ENCODING,
    BINDSTATUS_VERFIEDMIMETYPEAVAILABLE,
    BINDSTATUS_CLASSINSTALLLOCATION,
    BINDSTATUS_DECODING
} BINDSTATUS;

A single value from the BINDSTATUS enumeration is passed to the client in the IBindStatusCallback::OnProgress method to indicate the progress of the bind operation.

BINDSTATUS_FINDINGRESOURCE
Bind operation is finding the resource that holds the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the resource being searched for (for example, "www.microsoft.com").
BINDSTATUS_CONNECTING
Bind operation is connecting to the resource that holds the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the resource being connected to (for example, an IP address).
BINDSTATUS_REDIRECTING
Bind operation has been redirected to a different data location. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the new data location.
BINDSTATUS_BEGINDOWNLOADDATA
Bind operation has begun receiving the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the data location.
BINDSTATUS_DOWNLOADINGDATA
Bind operation continues to receive the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the data location.
BINDSTATUS_ENDDOWNLOADDATA
Bind operation has finished receiving the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the data location.
BINDSTATUS_BEGINDOWNLOADCOMPONENTS
Bind operation is beginning to download the component.
BINDSTATUS_INSTALLINGCOMPONENTS
Bind operation is installing the component.
BINDSTATUS_ENDDOWNLOADCOMPONENTS
Bind operation has finished downloading the component.
BINDSTATUS_USINGCACHEDCOPY
Bind operation is retrieving the requested object or storage from a cached copy. The szStatusText parameter to the IBindStatusCallback::OnProgress method is NULL.
BINDSTATUS_SENDINGREQUEST
Bind operation is requesting the object or storage being bound to. The szStatusText parameter to the IBindStatusCallback::OnProgress method provides the display name of the object (for example, a file name).
BINDSTATUS_CLASSIDAVAILABLE
CLSID available.
BINDSTATUS_MIMETYPEAVAILABLE
MIME type is available.
BINDSTATUS_CACHEFILENAMEAVAILABLE
Temporary or cache file name is available. The temporary file name may be returned if BINDF_NOWRITECACHE is called. The temporary file will be deleted once the storage is released.
BINDSTATUS_BEGINSYNCOPERATION
Synchronous operation started.
BINDSTATUS_ENDSYNCOPERATION
Synchronous operation completed.
BINDSTATUS_BEGINUPLOADDATA
File upload started.
BINDSTATUS_UPLOADINGDATA
File upload in progress.
BINDSTATUS_ENDUPLOADINGDATA
File upload completed.
BINDSTATUS_PROTOCOLCLASSID
CLSID associated with the protocol scheme is available.
BINDSTATUS_ENCODING
Encoding data.
BINDSTATUS_VERFIEDMIMETYPEAVAILABLE
Verfied MIME type available.
BINDSTATUS_CLASSINSTALLLOCATION
Class install location available.
BINDSTATUS_DECODING
Decoding data.

See also IBindStatusCallback::OnProgress


BINDSTRING

typedef enum tagBINDSTRING{
    BINDSTRING_HEADERS = 1,
    BINDSTRING_ACCEPT_MIMES,
    BINDSTRING_EXTRA_URL,
    BINDSTRING_LANGUAGE,
    BINDSTRING_USERNAME,
    BINDSTRING_PASSWORD,
    BINDSTRING_UA_PIXELS,
    BINDSTRING_UA_COLOR,
    BINDSTRING_OS,
    BINDSTRING_USERAGENT,
    BINDSTRING_ACCEPT_ENCODINGS,
    BINDSTRING_POST_COOKIE,
    BINDSTRING_POST_DATA_MIME,
    BINDSTRING_URL
} BINDSTRING;

Contains the values for the bind string types available for IInternetBindInfo::GetBindString.

BINDSTRING_HEADERS
Retrieve the headers associated with the request.
BINDSTRING_ACCEPT_MIMES
Retrieve the accepted MIME types.
BINDSTRING_EXTRA_URL
BINDSTRING_LANGUAGE
Retrieve the language types accepted.
BINDSTRING_USERNAME
Retrieve the username sent with the request.
BINDSTRING_PASSWORD
Retrieve the password sent with the request.
BINDSTRING_UA_PIXELS
BINDSTRING_UA_COLOR
BINDSTRING_OS
Retrieve the server's operating system.
BINDSTRING_USERAGENT
Retrieve the user agent string used.
BINDSTRING_ACCEPT_ENCODINGS
Retrieve the encoding types accepted.
BINDSTRING_POST_COOKIE
Retrieve the posted cookie.
BINDSTRING_POST_DATA_MIME
Retrieve the MIME type of the posted data.
BINDSTRING_URL
Retrieve the URL.


BINDVERB

typedef enum {
    BINDVERB_GET,
    BINDVERB_POST,
    BINDVERB_PUT,
    BINDVERB_CUSTOM
} BINDVERB;

Values from the BINDVERB enumeration are passed to the moniker as part of the BINDINFO structure. The moniker calls the IBindStatusCallback::OnProgress method on the client to obtain additional information about the bind operation in the BINDINFO structure. The dwBindVerb member of the BINDINFO structure specifies an action, such as an HTTP request, to be performed during the binding operation.

BINDVERB_GET
Perform an HTTP GET operation, the default operation. The stgmedData member of the BINDINFO structure should be set to TYMED_NULL for the GET operation.
BINDVERB_POST
Perform an HTTP POST operation. The data to be posted should be specified in the stgmedData member of the BINDINFO structure.
BINDVERB_PUT
Perform an HTTP PUT operation. The data to put should be specified in the stgmedData member of the BINDINFO structure.
BINDVERB_CUSTOM
Perform a custom operation that is protocol-specific. See the szCustomVerb member of the BINDINFO structure. The data to be used in the custom operation should be specified in the stgmedData member of the BINDINFO structure.

See also IBindStatusCallback::GetBindInfo, BINDINFO


BSCF

typedef {
    BSCF_FIRSTDATANOTIFICATION,
    BSCF_INTERMEDIATEDATANOTIFICATION
    BSCF_LASTDATANOTIFICATION,
    BSCF_DATAFULLYAVAILABLE,
    BSCF_AVAILABLEDATASIZEUNKNOWN
} BSCF;

Values from the BSCF enumeration are passed to the client in IBindStatusCallback::OnDataAvailable to indicate the type of data that is available.

BSCF_FIRSTDATANOTIFICATION
Identify the first call to IBindStatusCallback::OnDataAvailable for a given bind operation.
BSCF_INTERMEDIATEDATANOTIFICATION
Identify an intermediate call to IBindStatusCallback::OnDataAvailable for a bind operation.
BSCF_LASTDATANOTIFICATION
Identify the last call to IBindStatusCallback::OnDataAvailable for a bind operation.
BSCF_DATAFULLYAVAILABLE
All of the requested data is available.
BSCF_AVAILABLEDATASIZEUNKNOWN
Size of the data available is unknown.


*
  * Previous Topic: BSCF
  * Next Topic: QUERYOPTION

CIP_STATUS

Obsolete. Do not use.


QUERYOPTION

typdef enum _tagQUERYOPTION {
    QUERY_EXPIRATION_DATE = 1,
    QUERY_TIME_OF_LAST_CHANGE,
    QUERY_CONTENT_ENCODING,
    QUERY_CONTENT_TYPE,
    QUERY_REFRESH,
    QUERY_RECOMBINE,
    QUERY_CAN_NAVIGATE,
    QUERY_USES_NETWORK,
    QUERY_IS_CACHED,
    QUERY_IS_INSTALLEDENTRY,
    QUERY_IS_CACHED_OR_MAPPED,
    QUERY_USES_CACHE
} QUERYOPTION;

This enumerated type contains the available query options.

QUERY_EXPIRATION_DATE
Request the expiration date in a SYSTEMTIME format.
QUERY_TIME_OF_LAST_CHANGE
Request the last changed date in a SYSTEMTIME format.
QUERY_CONTENT_ENCODING
Request the content encoding schema.
QUERY_CONTENT_TYPE
Request the content type header.
QUERY_REFRESH
Request a refresh.
QUERY_RECOMBINE
Combine the page URL with the nearest base URL if TRUE.
QUERY_CAN_NAVIGATE
Check if the protocol can navigate.
QUERY_USES_NETWORK
Check if the URL needs to access the network.
QUERY_IS_CACHED
Check if the resource is cached locally.
QUERY_IS_INSTALLEDENTRY
Check if this resource is installed locally on a CD-ROM.
QUERY_IS_CACHED_OR_MAPPED
Check if this resource is stored in the cache or if it is on a mapped drive (in a cache container).
QUERY_USES_CACHE
Check if the specified protocol uses the Internet cache.


Error Codes

This section lists the error codes and messages exposed by monikers, URLs, security zones, and pluggable protocols.

INET_E_AUTHENTICATION_REQUIRED
Authentication is needed to access the object.
INET_E_CANNOT_CONNECT
The attempt to connect to the Internet has failed.
INET_E_CANNOT_INSTANTIATE_OBJECT
CoCreateInstance failed.
INET_E_CANNOT_LOAD_DATA
The object could not be loaded.
INET_E_CANNOT_LOCK_REQUEST
The requested resource could not be locked.
INET_E_CONNECTION_TIMEOUT
The Internet connection has timed out.
INET_E_DATA_NOT_AVAILABLE
An Internet connection was established, but the data cannot be retrieved.
INET_E_DEFAULT_ACTION
Use the default action.
INET_E_DOWNLOAD_FAILURE
The download has failed (the connection was interrupted).
INET_E_INVALID_REQUEST
The request was invalid.
INET_E_INVALID_URL
The URL could not be parsed.
INET_E_NO_SESSION
No Internet session was established.
INET_E_NO_VALID_MEDIA
The object is not in one of the required types.
INET_E_OBJECT_NOT_FOUND
The object was not found.
INET_E_QUERYOPTION_UNKNOWN
The requested option is unknown.
INET_E_REDIRECT)TO_DIR
The request is being redirected to a directory.
INET_E_REDIRECTING
The request is being redirected.
INET_E_RESOURCE_NOT_FOUND
The server or proxy was not found.
INET_E_SECURITY_PROBLEM
A security problem was encountered.
INET_E_UNKNOWN_PROTOCOL
The protocol is not known and no pluggable protocols have been entered that match.
INET_E_USE_DEFAULT_PROTOCOLHANDLER
Use the default protocol handler.
INET_E_USE_DEFAULT_SETTINGS
Use the default settings.


Cache Container Tool

The Cache Container Tool (Cdcache.exe) is an AutoRun executable file that allows content outside of the cache to be associated with a specified URL, which can be referenced by Microsoft Internet Explorer 4.0. This tool allows you to assign a URL that will reference content from another directory or CD-ROM.

The tool creates a cache container in the Internet Explorer persistent URL cache. When a user enters the URL, the browser looks for the resource in the location specified by the cache container.

If an earlier version of Microsoft Internet Explorer is installed on the computer, a message appears, notifying the user that Microsoft Internet Explorer 4.0 is required, unless the /NoIE4Msg or /Silent command-line option is used.

The tool can be found in the \bin directory of the Internet Client SDK.

Usage

Command-Line Options

Usage

Use the following steps to install a cache container that references a CD-ROM:

  1. Create an Autorun.inf file.
  2. In the Autorun.inf file, enter the following text:
    [autorun]
open=cdcache.exe
icon=cdcache.exe, 1

    If you want to use one of the Command-Line Options, add it to the open= line in the Autorun.inf file. The following example would install the cache container without displaying any user interface.

    [autorun]
open=cdcache.exe /Silent
icon=cdcache.exe,1
  3. In the Autorun.inf file, add one or more entries to create a cache container. This section must contain less than 64K of data. It must be in the following format:
    [Add.CacheContainer]
<Friendly Name>=<INF Section Name>

    The friendly name can be either the name of the company or the name of the product for which the cache container is being created. INF Section Name is the label you will use in the .inf file to define the details of your cache container.

    The following example shows an entry for two cache containers: one for Awesome Computers and one for Trey Research.

    [Add.CacheContainer]
Awesome Computers=AwesomeComp
Trey Research=TreyResearch
  4. In the Autorun.inf file, add a cache container detail section for each cache container defined in the previous step. It must be in the following format:
    [INF Section Name]
CachePrefix=<string>
CacheRoot=<relative path to the data>
KBCacheLimit=<numerical amount in KB>
AutoDelete=<Yes|No>
IncludeSubDirs=<Yes|No>
VolumeTitle=<string>
    CachePrefix | Determines the URL pattern that the cache container will provide data for. For the cache container to work properly, the pattern cannot end with a backslash (/). For example, the URL pattern http://www.awesome_computers.com/ is incorrect. It must be http://www.awesome_computers.com to work properly. The same is true of patterns that include directories. For example, the URL pattern http://www.trey_research.com/awards/ must be set as http://www.trey_research.com/awards.
    CacheRoot Contains the relative path to the data provided by the cache container. The following replaceable parameters can be used for this entry:
    %EXE_DRIVE%
    Automatically replaced with the drive letter (including the colon) of the execution path of the Cdcache.exe tool.
    %EXE_ROOT%
    Automatically replaced with the full directory path of the Cdcache.exe tool.
    KBCacheLimit | Contains the maximum number of kilobytes of data that can be stored in the user's local cache.
    AutoDelete | Determines if the cache container data residing in the user's local cache should be purged after an interval (predetermined by Microsoft Internet Explorer 4.0) of non-use.
    IncludeSubDirs | Specifies whether directories residing below the main CacheRoot= should be used to supply cache container data. Without this flag, only resources in the immediate CacheRoot= directory will be used to supply cache container data.
    VolumeTitle | Contains the title or friendly name of the CD-ROM that the container was created for.

    The following example shows entries for two cache container detail sections.

    [AwesomeComp]
CachePrefix=http://www.awesome_computers.com
CacheRoot=%EXE_DRIVE%\data\http\
KBCacheLimit=1000
AutoDelete=Yes
IncludeSubDirs=Yes

[TreyResearch]
CachePrefix=http://www.trey_research.com/awards
CacheRoot=%EXE_DRIVE%\data\http\awards\
KBCacheLimit=500
AutoDelete=Yes
IncludeSubDirs=Yes
  5. Place the Autorun.inf file at the root directory of the CD-ROM, which contains the content you want to register.

Command-Line Options

The Cdcache.exe tool supports the following command-line options:

/NoIE4Msg | Disables the message that informs the user that Microsoft Internet Explorer 4.0 is required.
/Silent | Installs all cache containers in the Autorun.inf file without displaying any user interface. This option will also cause it to fail silently.
/Remove | Uninstalls all the cache containers listed in the Autorun.inf file.
/Uninstall | Same as /Remove.


Microsoft CryptoAPI 2.0 Microsoft CryptoAPI 2.0 *
  * Previous Topic:

 UDACCEL
  * Next Topic: Microsoft DirectX Media SDK

Microsoft CryptoAPI 2.0

For information about Microsoft Cryptography, see the CryptoAPI site.


Hit Logging API

The Channel Definition Format (CDF) files allow content providers to determine which hits get logged for the items included in the CDF file. These logs are posted to the server during a scheduled update and cleared. This API allows developers to verify if hit logging is enabled and write customized entries in the log.

To use these functions, make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory of the C/C++ compiler you use.

About Logging

Functions

Structures

About Logging

The logs that are created contain the URL of the resource, the browsing context, whether the information was viewed from the cache, date viewed, time that the viewing started, duration it was viewed, and the custom information. Only the browsing context (normal browser window, theater view, Active Desktop Item, or Microsoft Internet Exporer screen saver) cannot be set by the WriteHitLogging function.

For more information about logging, see the Page-Hit Logging and Client-Side Logging sections in the Creating Active Channels documentation.


Functions Functions *
  * Previous Topic: Hit Logging API
  * Next Topic: IsLoggingEnabled

Functions

The following section contains the functions used for hit logging.


IsLoggingEnabled

BOOL IsLoggingEnabled
    IN LPCTSTR pszUrl
);

Determines if hit logging is enabled for the specified Internet site.

  • Returns TRUE if logging is enabled for the specified URL, or FALSE otherwise.
pszUrl
String value containing the URL of the resource to check.


WriteHitLogging

BOOL WriteHitLogging(
    IN LPHIT_LOGGING_INFO lpLogginginfo
);

Writes an entry into the log for the given resource.

  • Returns TRUE if the log was entered, or FALSE otherwise. Call GetLastError for specific error information. Can be one of the following error codes:
    ERROR_FILE_NOT_FOUND | The URL was not located in the cache log index.
    ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available in the cache to write this log.
lpLogginginfo
Address of the HIT_LOGGING_INFO structure that contains the information to add to the log.


Structures

The following section contains the structure used for hit logging.

HIT_LOGGING_INFO


HIT_LOGGING_INFO

typedef struct _HIT_LOGGING_INFO (
    DWORD dwStructSize;
    LPSTR lpszLoggedUrlName;
    SYSTEMTIME StartTime;
    SYSTEMTIME EndTime;
    LPSTR lpszExtendedInfo
) HIT_LOGGING_INFO, *LPHIT_LOGGING_INFO;

Contains the information to write into a hit log.

dwStructSize
Unsigned long integer value that contains the size, in bytes, of this structure.
lpszLoggedUrlName
String value that contains the name of the cache entry. The name string should not contain any escape characters.
StartTime
SYSTEMTIME value that contains the time to start logging for this URL.
EndTime
SYSTEMTIME value that contains the time to stop logging for this URL. This time is used to determine the duration that the user viewed the resource.
lpszExtendedInfo
String value containing custom information.


HTMLHelp API Reference

The HtmlHelp API currently resides in the file HTMLHELP.DLL, however this is very likely to be moved to a different DLL before HTML Help ships. If you are not using GetProcAddress to get a pointer to the HtmlHelp function, then you must plan on changing the library you link to.

The functionality provided by the HtmlHelp API resides in the file HHCTRL.OCX. Because this functionality requires loading various other DLLs such as ole32.dll, the API itself resides in a DLL that requires no additional DLLs to be loaded. Only when the API is actually called will ole32 and other DLLs be loaded.

The HtmlHelp API is modeled after the WinHelp API function to make it easy to convert existing programs to use HTML Help instead of WinHelp to display their help. By the time HTML Help ships, there will also be an IHHWindow interface that can be used in place of the HtmlHelp API. This can be used by programs that already load OLE32.DLL or by programs like Visual Basic.

In its simplest form, the HtmlHelp API creates a child window which in turn hosts SHDOCVW and displays the HTML file you specify. The window is a child of whatever parent window you specify, and will automatically stay on top of that parent window, and close when the parent window is closed. You can also take complete control of the window-creation process by defining the window styles, coordinates, caption, and display state. This means you can embed SHDOCVW even in a non-OLE activated program.

SYNTAX

HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData);

hwndCaller
Specifies the handle of the window calling the HtmlHelp API. If the HtmlHelp API call results in messages being sent from the HTML Help window, they will be sent to this window handle.
pszFile
Specifies an HTML file, a URL, a compiled HTML file, or a window definition (preceeded with a ‘>’ character). If the command being used does not require a file or URL, this value may be NULL.
uCommand
Specifies the action to perform. See the Comments section for details.
dwData
Specifies any data that may be required based on the value of the uCommand parameter.

Comments

The uCommand parameter determines what action to take, and what needs to be supplied for the pszFile and dwData parameters. The following table lists the commands, actions, and required parameters:
Command | Description | pszFile | dwData
HH_DISPLAY_TOPIC | Displays an HTML file. If a window type is not specified, a default window type is used. If the window type or default window type is already being displayed, the HTML file will replace what is currently being displayed. | File, URL, or compiled HTML file. If the greater then character (>) is used, it must be followed by the name of the window type to display the topic in. | May be zero or a pointer to a File, URL, or compiled HTML file. This parameter may be a pointer to a filename within a compiled HTML file if the pszFile parameter points to that compiled HTML file.
HH_DISPLAY_TEXT_POPUP | Displays text from a string resource, text string, or text file in a popup window. | Text filename if text resides in a file. Use NULL if the text is in a string resource id or specified in the HH_POPUP structure. | Points to a HH_POPUP structure.
HH_SET_WIN_TYPE | Creates a new window type, or modifies an existing window type. | Ignored. | Points to a HH_WINTYPE structure.
HH_GET_WIN_TYPE | Retrieves the HH_WINTYPE structure associated with a window type. If the window type has not been specified, the return value is -1. If the window type has been specified, the return value is the handle of the window (NULL if the window hasn’t been created). | Specifies the name of the window. The window name must begin with a ‘>’ character, and may optionally be preceded by the name of the compiled HTML file. | Points to the address of a PHH_WINTYPE pointer. Do not modify the structure this pointer points to.
HH_GET_WIN_HANDLE | Retrieves the handle of the window associated with the specified window type. If the window type has not been created, the return value is NULL. | Ignored | Pointer to the name of the window type.
HH_SET_INFO_TYPES | Sets all the information types to be used in a window. In a tri-pane window, this will cause the navigation pane to redraw (if currently displayed) to reflect any changes in the Information Types being used. | Ignored. | Points to a HH_WINTYPE structure. The cbStruct and ainfoTypes members must be filled in.
HH_SET_INFO_TYPES | Sets all the hidden information types to be used in a window. This command will not affect any Information Types chosen by the user. In a tri-pane window, this will cause the navigation pane to redraw (if currently displayed) to reflect any changes in the Information Types being used. | Ignored. | Points to a HH_WINTYPE structure. The cbStruct and ainfoTypes members must be filled in.
HH_SYNC | Synchronizes the Table of Contents of a tri-pane window with the specified URL. This should only be used with windows thatwhich are not auto-syncnchronized. | Specifies the name of the window to sychronizesynchronize. | Specifies the URL to synchronize with. This URL does not need to be currently displayed...
HH_ADD_NAV_UI | Adds a navigational window to use in the navigational pane of a tri-pane window. | Address of an HhWinCallBack function to support the new UI. | Unique numeric value representing the UI. The UI may be switched to by specifying this value in the curNavType member of the HH_WINTYPE structure.
HH_ADD_BUTTON | Adds a button to the toolbar of a tri-pane window. | Address of an HhWinCallBack function to support the button. | Unique numeric value representing the button.
HH_KEYWORD_LOOKUP | Attempts to find the given keyword in a .HHK file. If found, the topic is displayed in the specified (or current, if not specified) window. | If NULL, the .HHK file associated with the current window is used. If a string containing a window definition is used, but not a .HHK file, then the .HHK from the specified window is used, and if the topic is found, it will be displayed in that window. If a .HHK file is specified, that file will be used. | Points to a string containing one or more keywords,keywords separated by a semi-colon.

HH_WINTYPE structure

Window types may be defined by an author and stored in a compiled HTML file, or they may be defined by a program by using the HtmlHelp API. Each window type should have a unique name. If a call to the HtmlHelp API is made specifying a window type that does not exist, then a type will be created using the indicated type name, but with default properties. When creating, modifying, or retrieving a window type, the HH_WINTYPE structure is used. The following describes this structure:

typedef struct tagHH_WINTYPE {

int cbStruct; // IN: size of this structure including all Information Types

BOOL fUniCodeStrings; // IN/OUT: TRUE if all strings are in UNICODE

LPCTSTR pszType; // IN/OUT: Name of a type of window

DWORD fsValidMembers; // IN: Bit flag of valid members (HHWIN_PARAM_)

DWORD fsWinProperties; // IN/OUT: Properties/attributes of the window (HHWIN_)

LPCTSTR pszCaption; // IN/OUT: Window title

DWORD dwStyles; // IN/OUT: Window styles

DWORD dwExStyles; // IN/OUT: Extended Window styles

RECT rcWindowPos; // IN: Starting position, OUT: current position

int nShowState; // IN: show state (e.g., SW_SHOW)

HWND hwndHelp; // OUT: window handle

HWND hwndCaller; // OUT: who called this window

HH_INFOTYPE* paInfoTypes; // IN: Pointer to an array of Information Types

// The following members are only valid if HHWIN_PROP_TRI_PANE is set

HWND hwndToolBar; // OUT: toolbar window in tri-pane window

HWND hwndNavigation; // OUT: navigation window in tri-pane window

HWND hwndHTML; // OUT: window displaying HTML in tri-pane window

int iNavWidth; // IN/OUT: width of navigation window

RECT rcHTML; // OUT: HTML window coordinates

LPCTSTR pszToc; // IN: Location of the table of contents file

LPCTSTR pszIndex; // IN: Location of the index file

LPCTSTR pszFile; // IN: Location of the html file

LPCTSTR pszHome; // IN/OUT: html file to display when Home button is clicked

DWORD fsToolBarFlags; // IN: flags controlingcontrolling the appearance of the toolbar

BOOL fExpanded; // IN: TRUE/FALSE to expand or contract, OUT: current state

int curNavType; // IN/OUT: UI to display in the navigational pane

int tabpos; // IN/OUT: NAVTAB_TOP, NAVTAB_LEFT, or NAVTAB_BOTTOM

int idNotify; // IN: ID to use for WM_NOTIFY messages

BYTE tabOrder[HH_MAX_TABS + 1]; // IN/OUT: tab order: Contents, Index, Search, History, Favorites, Reserved 1-5, Custom tabs

} HH_WINTYPE;
Member | Description
cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to the HtmlHelp API.
fUniCodeStrings | Specifies whether the strings used in this structure are UNICODE or not.
pszType | Specifies a null-terminated string containing the name of the window type.
fsValidMembers | Specifies which members in the structure are valid. See the following Comments section for a description of this member.
fsWinProperties | Specifies the properties of the window. See the following Comments section for a description of this member.
pszCaption | Specifies a null-terminated string contain the caption to display in the title bar of the window.
dwStyles | Specifies the styles used to create the window. These styles may be ignored, combined with default styles, or used exclusively depending on the value of fsValidMembers and fsWinProperties.
dwExStyles | Specifies the extended styles used to create the window. These styles may be ignored, combined with default styles, or used exclusively depending on the value of fsValidMembers and fsWinProperties.
rcWindowPos | Specifies the coordinates of the window. When setting this value, any negative member will be ignored. For example, to change the position, but not the width and height, the left and top positions would be set and the right and bottom RECT members would be set to -1.
nShowState | Specifies the initial display state of the window.
hwndHelp | Specifies the handle of the window if the window has been created.
hwndCaller | Specifies the window to send messages to.
paInfoTypes | This specifies the Information Types to display. Each Information Type is a bit flag, with bit zero indicating whether or not all Information Types should be shown. If bit zero is not set, then all HTML Help commands that use Information Types will this information to determine what navigational UI should be displayed, and where hyperlinks should jump to.
hwndToolBar | Specifies the handle of the window containing the toolbar in a tri-pane window.
hwndNavigation | Specifies the handle of the window containing the current navigation UI in a tri-pane window.
hwndHTML | Specifies the handle of the window that displays HTML files in a tri-pane window. This window is a host for SHDOCVW.
iNavWidth | Specifies the width of the navigation pane in a tri-pane window when the tri-pane window is expanded.
rcHTML | Specifies the coordinates of the HTML pane in a tri-pane window.
pszToc | In a tri-pane window, this specifies the file or URL to use for the Table of Contents.
pszIndex | In a tri-pane window, this specifies the file or URL to use for the Index.
pszFile | In a tri-pane window, this specifies the file or URL to display in the right pane. This file will be displayed if the user clicks the Home button in the toolbar.
pszHome | In a tri-pane window, this specifies the file or URL to display in the right pane when the Home button is clicked.
fsToolBarFlags | In a tri-pane window, this determines which buttons will be displayed in the toolbar pane. See the section below describing HHWIN_BUTTON constants.
fExpanded | In a tri-pane window, this determines whether or not the navigational pane is to be shown.
curNavType | Specifies which navigational UI is displayed in the navigational pane of a tri-pane window.
tabpos | Specifies where the tabs are to be placed in the navigational pane of a tri-pane window. The tabs may be set on the top, left or bottom.
idNotify | Specifies the ID to use as the WPARAM member of WM_NOTIFY messages.
tabOrder | Specifies the order that tabs appear in the navigation pane of a Tri-pane window. Set the HHWIN_PARAM_TABORDER flag if you use this member. The first ten positions are reserved for default HTML Help tabs: Contents, Index, Search, History, Favorites, and Reserved 1-5 (for future expansion). Each byte represents the numeric position, starting with zero. For example, to put the Index tab first and the Contents tab second, you would specify tabOrder[HH_TAB_CONTENTS] = 1, and tabOrder[HH_TAB_INDEX] = 0.
cHistory | Specifies the number of history items to keep. This member is currently ignored, but will be used in the future.
pszJump1 | Specifies the URL to jump to when the Jump1 button is clicked.
pszJump1 | Specifies the URL to jump to when the Jump2 button is clicked.

The fsValidMembers member is used when modifying an existing window type, and determines which of the other members should be updated. This parameter may be a combination of one or more of the following values:
HHWIN_PARAM_PROPERTIES | The fsWinProperties member is valid.
HHWIN_PARAM_STYLES | The dwStyles member is valid.
HHWIN_PARAM_EXSTYLES | The dwExStyles member is valid.
HHWIN_PARAM_RECT | The rcWindowPos member is valid.
HHWIN_PARAM_NAV_WIDTH | The rcNavigation member is valid.
HHWIN_PARAM_SHOWSTATE | The nShowState member is valid.
HHWIN_PARAM_INFOTYPES | The ainfoTypes member is valid.
HHWIN_PARAM_TB_FLAGS | The fsToolBarFlags member is valid.
HHWIN_PARAM_EXPANSION | The fExpanded member is valid.
HHWIN_PARAM_TABPOS | The tabpos member is valid
HHWIN_PARAM_TABORDER | The tabOrder member is valid.
HHWIN_PARAM_HISTORY_COUNT | The cHistory member is valid.

The fsWinProperties member is used to define various properties for the window, and is also used to control how the window is created. This member may be a combination of one or more of the following values:
HHWIN_PROP_ONTOP | Specifies that the window is to be kept on top of every window on the desktop instead of just being on top of the caller’s window.
HHWIN_PROP_NOTITLEBAR | Specifies that the window should not contain a title bar.
HHWIN_PROP_NODEF_STYLES Specifies that no default styles should be used when creating the window. If this flag is not specified, a window will be created with the following default styles:

WS_THICKFRAME | WS_OVERLAPPED | WS_VISIBLE

HHWIN_PROP_NODEF_EXSTYLES | Specifies that no default extended styles should be used when creating the window. If this flag is used with the HHWIN_PROP_ONTOP flag, then the HHWIN_PROP_ONTOP flag will be ignored.
HHWIN_PROP_TRI_PANE | Specifies that a tri-pane window is to be created. Once a window has already been created, this flag cannot be used to change the existing window.
HHWIN_PROP_NOTB_TEXT | Specifies that the toolbar of a tri-pane window should not contain text underneath the buttons.
HHWIN_PROP_POST_QUIT | Specifies that when the help window is closed, a WM_QUIT message is posted to the calling programs message queue. This will normally cause the calling program to terminate.
HHWIN_PROP_AUTO_SYNC | Specifies that if the Contents or Index navigational pane is currently displayed, then if the user jumps to a different HTML file, the Contents or Index will scroll to the entry or keyword that points to the current URL. If the URL cannot be located in the current navigational pane, no action will be taken.
HHWIN_PROP_TRACKING | Specifies that tracking notification messages should be sent to the caller.
HHWIN_PROP_TAB_SEARCH | Specifies that a full-text search tab is to be included as one of the navigation panes in a tri-pane window.
HHWIN_PROP_TAB_HISTORY | Specified that a history tab is to be included as one of the navigation panes in a tri-pane window. This property is not supported in version 1.
HHWIN_PROP_TAB_FAVORITES | Specifies that a favorites tab is to be included as one of the navigation panes in a tri-pane windowsin a tri-pane window. This property is not supported in version 1.
HHWIN_PROP_CHANGE_TITLE | Specifies that the title bar of the HTML Help window should reflect the title of any HTML file displayed in the HTML pane.
HHWIN_PROP_TAB_ADVANCED | Specifies that an advanced search tab is to be included as one of the navigation panes of a tri-pane window.

The fsToolBarFlags member is used to specify which buttons to display in the toolbar. This member may be a combination of one or more of the following values:
HHWIN_BUTTON_EXPAND | Expand/contract button (for the navigational pane)
HHWIN_BUTTON_BACK | Back button.
HHWIN_BUTTON_FORWARD | Forward button.
HHWIN_BUTTON_STOP | Stop button.
HHWIN_BUTTON_REFRESH | Refresh button.
HHWIN_BUTTON_HOME | Home button (to the HTML file defined for the window).
HHWIN_BUTTON_HISTORY | History button.
HHWIN_BUTTON_FAVORITES | Favorites button.
HHWIN_BUTTON_TOC | Table of Contents button.
HHWIN_BUTTON_INDEX | Index button.
HHWIN_BUTTON_SEARCH | Simple search button.
HHWIN_BUTTON_HISTORY | History button.
HHWIN_BUTTON_FAVORITES | Favorites button.
HHWIN_BUTTON_JUMP1 | Jump1 button.
HHWIN_BUTTON_JUMP2 | Jump2 button

The curNavType membmermember is used to specify which navigational UI tab should be activated. This member may be one of the following values:
HHWIN_NAVTYPE_TOC | Displays the Contents tab.
HHWIN_NAVTYPE_INDEX | Displays the Index tab.

The tabpos member is used to specify where the tabs are to be placed on the navigational pane of a tri-pane window. This member may be one of the following values:
HHWIN_NAVTAB_TOP | Places the tabs at the top.
HHWIN_NAVTAB_LEFT | Places the tabs at the left.
HHWIN_NAVTAB_BOTTOM | Places the tabs at the bottom.

HH_POPUP structure

The HH_POPUP structure is used when displaying a text-only popup. Because of the speed in which they display, text-only popups should be used when no formatting is needed. The text to display may reside in a resource file, in a text string, or in a text file.

typedef struct tagHH_POPUP

{

int cbStruct; // sizeof this structure

HINSTANCE hinst; // instance handle for string resource

UINT idString; // string resource id, or text id if pszFile is specified in HtmlHelp call

LPCTSTR pszText; // used if idString is zero

POINT pt; // top center of popup window

COLORREF clrForeground; // use -1 for default

COLORREF clrBackground; // use -1 for default

RECT rcMargins; // amount of space between edges of window and text, -1 for each member to ignore

LPCTSTR pszFont; // facename, point size, char set, BOLD ITALIC UNDERLINE

} HH_POPUP;
Member Description

cbStruct

Specifies the size of the structure. This value must always be filled in before passing the structure to the HtmlHelp API.

hinst

Instance handle of the program or dll to retrieve the string resource from. Ignored if idString is zero, or a filename was passed to the HtmlHelp API.

idString

Specifies either a resource id, or a thethe topic number in a text file.

pszText

Specifies the text to display if idString is zero.

pt

Specifies where the top center of the popup should be located.

clrForeground

Specifies the RGB value to use for the foreground color. If this value is -1, the system color for window text will be used.

clrBackground

Specifies the RGB value to use for the background color. If this value is -1, the system color for window background will be used.

rcMargins

Specifies the margins to use on the left, top, right, and bottom sides of the popup. A -1 for any of the rectangle members will use the default.

pszFont

Specifies an optional text string containing: facename[,point size[,charset[,color[, BOLD ITALIC UNDERLINE]]]]. This string specifies a font, its point size, its character set, its color, and various attributes. Options may be omitted by simply specifying the next comma. For example, to create a bold, 10-pt MS Sans Serif font, the parameter value would be: MS Sans Serif, 10, , , BOLD

TRI-PANE Windows

A tri-pane window consists of three panes (child windows) consisting of a toolbar pane at the top, a navigation pane on the left, and an HTML pane that hosts SHDOCVW on the right. The navigation pane may be expanded or contracted by the user or programmatically. Expansion always enlarges the window by a fixed amount – that amount is 250 pixels by default, but may be set by the author or programmer as part of the window description.

If more then one navigational UI is specified, then a tabbed control will be used to switch between the navigational UI. By default, the tabs for this control will run vertically – but a window may be defined to have the tabs on top or the bottom.

An embedded window can take advantage of the toolbar pane without having a navigational pane by simply not including the Expand button. For example, the Help tab of the Index editor in HTML Help Workshop (displayed when editing a keyword) uses a tri-pane window without the navigation pane.

Notification Messages

If the idNotify member of the HH_WINTYPE structure is non-zero, then WM_NOTIFY messages will be sent to the last caller of the HTML Help window.
Notification | lParam | Description
HHN_NAVCOMPLETE | HHNNAVCOMPLETE* | Sent when the user successfully navigates to a URL.
HHN_TRACK | HHNTRACK* | Sent if the window has tracking properties and the user uses a toolbar button or switches navigational tabs. The message is sent before the action is taken. If the action changes to a different URL, a HHN_NAVCOMPLETE notification will be sent after this notification.

HHNNAVCOMPLETE structure

typedef struct tagHHNNAVCOMPLETE {

NMHDR hdr;

PCSTR pszUrl;

} HHNNAVCOMPLETE;
Member | Description
hdr | Standard WM_NOTIFY header
pszUrl | Multi-byte, zero terminated string specifying the URL that has been navigated to.

HHNTRACK structure

typedef struct tagHHNTRACK

{

NMHDR hdr;

PCSTR pszCurUrl; // Multi-byte, null-terminated string

int idAction; // HHACT_ value

} HHNTRACK;

Member | Description
hdr | Standard WM_NOTIFY header
pszCurUrl | Multi-byte, zero terminated string specifying the current URL before the action is taken.
idAction | Specifies the action the user is about to take. This is one of the HHACT_ constants described below.

The idAction parameter may be one of the following values:
Value | Description
HHACT_EXPAND | The user is about to expand the navigation pane.
HHACT_CONTRACT | The user is about to contract the navigation pane.
HHACT_BACK | The user clicked the Back button.
HHACT_FORWARD | The user clicked the Forward button.
HHACT_STOP | The user clicked the Stop button.
HHACT_REFRESH | The user clicked the Refresh button.
HHACT_HOME | The user clicked the Home button.
HHACT_SYNC | The user clicked the Sync button.
HHACT_OPTIONS | The user clicked the Options button.
HHACT_PRINT | The user clicked the Print button.
HHACT_TAB_CONTENTS | The user switched to the Contents tab.
HHACT_TAB_INDEX | The user switched to the Index tab.
HHACT_TAB_FIND | The user switched to the Find tab.
HHACT_TAB_HISTORY | The user switched to the History tab.
HHACT_TAB_FAVORITES | The user switched to the Favorites tab.

Keyword Lookup

A caller may use the HtmlHelp API to lookup a keyword in a .HHK file, whether or not that file is the current keyword index or not. The .HHK file to be searched can exist on its own, or it can be in a compiled HTML file. The path to the file may be preceded with %SystemRoot% to make the path relative to the Windows directory. If the file is not found, it will be searched for in the following locations (and in the following order):

  • The registry (HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help\base filename). The filename without the path is used as the key, and the value contains the path where the file is located.
  • The Windows\help folder.
  • The [FILES] section of HH.INI. The keyword is the filename without the path, and the value is aan optionally quoted path optionally followed by a message to prompt the user if the file still cannot be found. For example: myfile.hhk="d:\myapp" Please insert the MyDisk CD into your CDROM drive.

If the filename portion of the HtmlHelp API call contains both a filename and a window type, then the window type will be used to determine what window to display the result in. This window type will overrrideoverride any window type specified in the .HHK file.

If the window type is not specified, the current window will be used (if there is one) unless the .HHK file specifies a window type. If no window type is specified either in the filename or the .HHK file, a default window type called "Keyword Lookup" will be created and used.

If the filename portion is not specified, but the window type is (for example, ">MyWindow") then the .HHK file associated with that window type will be searched.


Hyperlinks

This topic describes ActiveX™ Hyperlinking and the interfaces involved in adding hyperlink navigation to your document or application.

Introduction

Reference

Introduction

One of the most compelling ease-of-use features of World Wide Web applications is the navigation-based user interface model that includes point-and-click hyperlink navigation, a History list (with commands such as Go Back and Go Forward), and a Favorites list. Like other ActiveX-based technologies, ActiveX Hyperlinks enable you to add this hyperlink functionality to your documents and applications, allowing you to integrate them seamlessly with other hyperlinking applications, including Web browsers. ActiveX Hyperlinks allow you to:

  • Add hyperlinking support to existing documents, objects, and applications.
  • Integrate the documents of your application into enabled World Wide Web browsers.
  • Support and integrate with key features of ActiveX Hyperlink applications (History, Favorites, Go Back, Go Forward, Go Home).
  • Support navigation to documents on the Internet or an intranet.

This section provides an overview of hyperlinks, a description of the ActiveX Hyperlinking architecture (including the interfaces required to add hyperlink support to an application), and examples. Applications can choose to support various degrees of integration with the ActiveX Hyperlinking architecture. Where applicable, this document describes how to provide minimal or simple hyperlinking support, and also how to extend this support for more complete hyperlinking integration. For basic COM information, refer to The Component Object Model.

What Is a Hyperlink?

A hyperlink is a COM object that implements, at a minimum, the IHlink interface and acts as a link to an object at another location (the target). This target can be a reference to a location in the same document/object that contains the hyperlink; a different (top-level or embedded) document/object of the same class; or a different document/object of a different class. A hyperlink is made up of four parts:

  • A moniker that identifies the target's location
  • A string for the location within the target
  • A friendly, or displayable, name for the target
  • A string that can contain additional parameters

The data of the document/object can be stored in file system files, computers on the Internet (referred to by URLs, or universal resource locators), or any arbitrary location that can be referenced through monikers. Navigation to the location can be done by binding to the target and then asking it to jump to the location. How a hyperlink is presented to the user is up to the hyperlink container and the context of the hyperlink. While there are no user interface requirements limiting the presentation of hyperlinks, guidelines suggest that the hyperlinks should be made clear through coloring and/or underlining the hyperlink text, or by changing the cursor when selecting the hyperlink with the mouse.

What Is Hyperlink Navigation?

Hyperlink navigation involves a transition from one document, object, or application (the hyperlink container) to another document, object, or application (the hyperlink target). Usually both the hyperlink container and target remain running, but the hyperlink target is displayed over the hyperlink container. Hyperlink containers and targets can be top-level documents or Active Document objects in a browser application. Because of this variation, there are many possible forms of navigation. These include navigating from:

  • One top-level document to another top-level document (in the absence of a browser).
  • A top-level document to an Active Document object in a browser (for example, navigating from a stand-alone application to an HTML document).
  • One Active Document object in a browser to another Active Document object in the same browser (for example, navigating from one HTML document to another).
  • An Active Document object in a browser to an Active Document object in a binder-like application (for example, if the hyperlink target is embedded in an Office Binder document).
  • One location in an object/document to another location in the same object/document.

In the third and fifth cases above, the window is reused. In the other cases, the hyperlink target appears in a new window. The ActiveX Hyperlinks architecture suggests a mechanism for creating the illusion of window reuse in such cases: the hyperlink container passes its current window position to the hyperlink target, and the hyperlink target positions its window in the exact same location. Upon successful navigation, the hyperlink container hides its window.

What Is a Browse Context?

By looking at the possible forms of navigation, it is clear that multiple objects/documents (perhaps from different processes) share some global context. This context knows the order in which documents have been visited. All jumps are recorded with this context, and this context chains them together in a stack that can be navigated using Go Back and Go Forward operations. This global context is called the browse context.

Even though a browse context is global and spans multiple processes, it need not be global per user, such as History and Favorites lists. There can be multiple browse contexts active at once. For example, in certain Web browsers you can start a new browse context using the right-mouse pop-up menu item Open In New Window. ActiveX Hyperlinking defines the interface for the standard system browse context. This allows hyperlink-aware documents and applications to integrate the browse context's navigation stack through the standard hyperlinking interfaces and their methods.

The Simple Hyperlinking API

There are two methods of dealing with hyperlinks, depending on the needed complexity of the hyperlink operation. The simple hyperlink navigation model is a helper API aimed at common navigation scenarios such as a control (like a pushbutton) embedded on a Web page that allows the user to jump to another page when it is clicked.

The simple hyperlink functions are an encapsulation of the more complex full hyperlinking interfaces. These full hyperlinking interfaces offer a much richer set of navigation operations. For example, you can use these interfaces for operations such as supporting navigation to a location within a new document type, or allowing the cutting and pasting or dragging and dropping of hyperlinks. The simple hyperlink navigation API allows hyperlink navigation without knowledge of any other hyperlink interfaces or objects (basically saying, "here is where I want to jump to, now go there"). This API includes the following functions:

  • HlinkSimpleNavigateToString—Jumps to the location pointed to by a URL string.
  • HlinkSimpleNavigateToMoniker—Jumps to the location pointed to by a URL moniker.
  • HlinkGoBack—Jumps to the previous location on the History list (if object pointed to is hosted in an ActiveX hyperlink frame).
  • HlinkGoForward—Navigates to the next location on the History list (if object pointed to is hosted in an ActiveX hyperlink frame).

These functions work within any ActiveX hyperlink frame application. A hyperlink frame is the outer container that contains the document processing the user's request to navigate (when a navigation action occurs). An application must expose the IHlinkFrame interface to be a hyperlink frame application. For example, Microsoft® Internet Explorer 3.0 is a hyperlink frame application that knows the user's current location in the navigation stack, and goes forward and backward properly.

The programmer is shielded from the architectural details of figuring out the History list to move forward and backward. An ActiveX Control or document hosted in a frame simply calls these functions to figure out where to go.

The calling object needs to know where in the navigation stack the user currently is so the user can go forward or backward properly. To do this, all that the calling object must pass in is the interface pointer to itself. In reality, this is the IUnknown pointer to the document or object that is initiating the hyperlink. (Note that this must be the pUnkOuter parameter for an aggregated COM object.) If the pointer is NULL, the hyperlink is assumed to originate from an ActiveX-unaware application (an application that does not expose the IHlinkFrame interface), and the navigation history list will not be updated. Using this object pointer, the API travels through the interface hierarchy of that object to locate its outer container to calculate navigation history and do the in-frame navigation.

The Hyperlink Architecture

The following sections describe the various components in the ActiveX Hyperlinks architecture and the interfaces they implement. Some of the components are standard, system-provided objects; the others are user-defined components that participate in ActiveX hyperlinking because they implement the appropriate interface(s).

The hyperlink target

A hyperlink target is a COM object that implements the IHlinkTarget interface and supplies its moniker, friendly name, and other information that other hyperlink objects will use to navigate to it. This can be a persisted ActiveX object that exposes IHlinkTarget, a persisted ActiveX object that exposes IOleObject, or any file that is viewed when its viewer application is launched through ShellExecute. An object (document) that wants to be targeted by hyperlinks can choose to implement all or part of the IHlinkTarget interface to integrate tightly with ActiveX Hyperlinks. If the object does not support IHlinkTarget, it can still act as a hyperlink target, but it won't be able to support internal navigation, and it will not have access to the common browse context that holds the navigation stack. A hyperlink target can be a top-level container document, an embedded object of arbitrary nesting, or, in general, any object that can be referenced through a moniker.

How to implement IHlinkTarget

An existing application that supports COM linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application can also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile. Supporting IHlinkTarget from an Active Document object is the recommended way to make sure your document is viewable by browsers and participates in hyperlinking smoothly.

The hyperlink object

A hyperlink object implements the IHlink interface and encapsulates four pieces of reference information: a moniker to the hyperlink target; a string for the location within the target; a friendly name for the target; and additional parameters.

The hyperlink object completely encapsulates the behavior of navigating to a referenced location. It also supports the ability to save and load itself through the IPersistStream interface, and the ability to be transferred through the clipboard or through drag-and-drop operations by means of IDataObject. A standard hyperlink object implementation is provided with the system, and it is not advisable to implement another version. A document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the work of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. Standard hyperlink objects are created through the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream functions. The standard hyperlink object implements the IHlink, IPersistStream, and IDataObject interfaces.

The hyperlink container

A hyperlink container is a document or application that contains hyperlinks. The container supports hyperlinks by implementing the IHlinkSite interface and, if the container's objects can be targets of other hyperlinks, the IHlinkTarget interface.

Note Generally, an object that acts as a hyperlink container can also act as a hyperlink target.

The hyperlink site

A hyperlink site is a COM object that implements the IHlinkSite interface and supplies either the moniker or interface identifier of its hyperlink container. One hyperlink site can serve multiple hyperlinks. The moniker supplied by the hyperlink site is used to evaluate relative monikers to the hyperlink target. If the relative moniker is NULL, the target of the link is in the same container object, and IHlink::Navigate can result in an efficient internal jump

Note The standard hyperlink object performs internal jumps by retrieving the container's IHlinkTarget interface using IHlinkSite::GetInterface (which avoids an unnecessary moniker bind). The object then asks the container to navigate directly through the IHlinkTarget::Navigate method.

The hyperlink frame

A hyperlink frame is a COM object that implements the IHlinkFrame interface and controls the top-level navigation and display of hyperlinks for the frame's container and the hyperlink target's server. Browser applications such as Microsoft Internet Explorer and the Microsoft Office Binder are examples of hyperlink frames. Ideally, a hyperlink frame also serves as an Active Document object frame, allowing it to support browsing and hyperlinking between various document objects.

The hyperlink browse context

The hyperlink browse context maintains the navigation stack that is passed during navigation from one document or application to another. As with the hyperlink object, the browse context is a standard object provided with the system.

In addition to maintaining the navigation stack, the browse context knows whether or not to enable Go Back and Go Forward commands. For example, if you navigate from A to B, A would create an instance of the browse context object (if it had not been given one before) and pass it to B. Next, if you navigate to C, B would pass the same browse context pointer to C. At this moment, the navigation stack of the browse context contains A, B, and C. Go Back is enabled but Go Forward is disabled. Now if you do Go Back, you will navigate to B and the navigation stack still contains the same three items. Now both Go Back and Go Forward are enabled. If you Go Back again, you will navigate to A, and again the navigation stack contains the same three elements. But now Go Back is disabled and only Go Forward is enabled.

In addition to maintaining the navigation stack, the browse context object manages the hyperlink frame window and hyperlink target object's window. This window position information allows hyperlinking from one top-level window to another while giving the illusion of window reuse (by positioning the windows on top of each other). Each hyperlink target is passed a browse context (through IHlinkTarget::SetBrowseContext) the first time it is navigated to. The hyperlink target registers with the browse context (through IHlinkBrowseContext::Register) and holds a reference to it. The target must also notify the browse context each time it is navigated to through IHlinkBrowseContext::OnNavigateHlink. The browse context uses this information to maintain the navigation stack, to remember the current item in the stack, and to manage the lifetimes of registered hyperlink target applications.

An Example of Simple Hyperlinking

The navigation in this example takes place between simple hyperlink containers and simple hyperlink targets, none of which understand how to use the hyperlinking browse context. For ActiveX Controls or Active Document objects hosted within a browser such as Microsoft Internet Explorer, this is the only hyperlinking support that is necessary to integrate fully in the navigation stack and history list. The following pseudo-code outlines the order or execution of methods among the various objects during navigation.

Note Simple hyperlinking is simple mainly for the hyperlink container and the hyperlink target, particularly if both are document objects hosted in a document object frame. In these cases, the frame takes over all responsibility for providing a navigation stack and integrated history/favorites. Note that there is no definition of simple hyperlinking for hyperlink frames.

Starting with a hyperlink container

The hyperlink container (for example, a document or an ActiveX Control embedded within a document) initiates the hyperlink navigation using one of the simple hyperlinking functions.

// do the navigation
HlinkSimpleNavigateToString( "http://www.microsoft.com/foo.htm", NULL,  NULL,
    punkMe, 0, pbc, pbsc, 0);

The hyperlink frame (for example, Microsoft Internet Explorer) is called from within the simple navigation API (which packages up the call into a full call to HlinkNavigate). This is the frame's chance to provide an integrated user interface, progress feedback, cancellation options, and so forth. Often the hyperlink frame simply sets some flags and defers to the IHlink::Navigate method. Other frames might choose to do more work. For instance, a frame might decide to provide its own IBindStatusCallback in order to listen in on progress notifications during navigation.

Calling the hyperlink target

Usually, the system-provided hyperlink object gains control to do the navigation on behalf of the container or frame, resulting in a call to the hyperlink target.The hyperlink target then receives control to navigate to the specific location within the target. Notice that support for "sublocations" is optional. Also, the interpretation of location strings is left to the interpretation of the target object.

STDMETHODIMP
IHlinkTarget::Navigate(DWORD grfHLNF, LPCWSTR szLocation)
{
    IHlinkFrame* phlFrame = NULL;
    // if szLocation is not visible show it

    // if this hyperlink target is an Active Document object, try to
    // retrieve the hyperlink frame pointer from the IOleInPlaceFrame
    if (m_poleinplaceframe)
        m_poleinplaceframe->QueryInterface(IID_IHlinkFrame, (void**)&phlFrame);

    // notify the hlink frame and the browse context that the navigation
    // is complete. Note: either phlFrame or m_phlbc may be NULL
    HlinkOnNavigate(phlFrame, NULL, grfHLNF, m_pmk, szLocation, szFriendlyName);

    m_fHide = FALSE;
    m_fHideFrame = FALSE;
}  // IHlinkTarget::Navigate

Receiving success notification

The hyperlink frame next receives notification of a successful navigation from IHlinkTarget::Navigate in order to reposition its windows and update its windows' visibility. If this is the same frame that hosted the hyperlink container that initiated the navigation, the flags set will ensure that the frame remains visible.

An Example of Complex Hyperlinking

The navigation in this example takes place between hyperlink containers and hyperlink targets that understand how to use the hyperlinking browse context. The following pseudo-code outlines the order or execution of methods among the various objects during navigation.

Starting with a hyperlink container

Before any navigation occurs, the container starts with a hyperlink object that has either been created (using HlinkCreateFromData, HlinkCreateFromMoniker, or HlinkCreateFromString) or loaded from persistent data (using OleLoadFromStream). The hyperlink container might initialize the hyperlink through the IHlink::SetHlinkSite method by passing in an IHlinkSite interface and hyperlink-specific data (dwSiteData), which allows the hyperlink container to use the same hyperlink site to service multiple hyperlinks.

When the container decides to navigate the link as a result of user action, it does the following:

// retrieve the hyperlink frame pointer
if (!m_fTriedToGetFrame && m_poleinplaceframe && m_phlFrame == NULL) {
    m_fTriedToGetFrame = TRUE;
    m_poleinplaceframe->QueryInterface(IID_IHlinkFrame,
    (void**)&m_phlFrame);
    }

if (m_phlbc == NULL) {
    // get the browse context pointer
    if (m_phlFrame)
        m_phlFrame->GetBrowseContext(&m_phlbc);
    else
        HlinkCreateBrowseContext(&m_phlbc);
    if (m_phlbc == NULL)
        return E_FAIL;

    // register with the browse context
    m_phlbc->Register(pmkThis, phls, &m_dwRegister);

    // because we want the user to be able to come back to this
    // object via GoBack functionality add self to the
    // navigation stack. This effectively tells the browse context
    // that the current hyperlink container referred to by pmkThis
    // is a member (at the top) of the navigation stack
    m_phlbc->OnNavigateHlink(NULL, pmkThis, szLocation, szFriendlyName);
    }

    if (m_phlFrame == NULL)    {
        HLBWINFO hlbwinfo;

        // initialize hlbwinfo with window locations and flags

        // register the browse window info in the browse context
        // so it is later available to the hyperlink target and
        m_phlbc->SetBrowseWindowInfo(&hlbwinfo)

        // set the flag indicating that this window should be
        // hidden after navigation. But this flag is cleared in the
        // IHlinkTarget::Navigate and IHlinkFrame::OnNavigate methods.
        m_fHide = TRUE;
        v_fHideAppFrame = TRUE;  // only the MDI applications need this
                                 //separate flag
        }
    else {
        m_fHide = FALSE;
        v_fHideAppFrame = FALSE;
    }

    hr = HlinkNavigate(pkl, m_phlFrame, NULL,  pbc /* could be NULL */,
    pibsc, m_phlbc);

    if (hr == NOERROR) {
        if (m_fHide)
            // Hide this document
        if (m_vfHideAppFrame)
            // Hide/Minimize application's frame window
        }

Calling the hyperlink frame

The hyperlink frame is called from within HlinkNavigate. This is the frame's chance to provide an integrated user interface, progress feedback, cancellation ability, and so forth. Often the hyperlink frame simply sets some flags and defers to the IHlink::Navigate method.

STDMETHODIMP
IHlinkFrame::Navigate(DWORD grfHLNF, IBindCtx* pbc,
    IBindStatusCallback* pbsc,  IHlink* phlDest)
{
    // This flag gets cleared in IHlinkFrame::OnNavigate().
    // Thus if the Navigation is within the same frame window
    // then we will get the right behavior as this flag gets
    // cleared in the OnNavigate() method.
    m_fHide = TRUE;

    // some frames need only the following function so that
    // they can properly show and hide themselves.
    // others may hook themselves into the IBindStatusCallback
    // for progress notification
    hr = IHlink::Navigate(NULL, pbc, pbsc, phlDest);
    if (SUCCEEDED(hr) && m_fHide)
        // Hide the frame window
}  // IHlinkFrame::Navigate

Other frames might choose to do more work. For instance, a frame may decide to provide its own IBindStatusCallback in order to listen in on progress notifications during navigation.

Jumping to the hyperlink target

When called by the hyperlink frame, the system hyperlink object gains control to do most of the navigation work and to integrate the results with the browse context. The following code is a sample implementation of a hyperlink object. The system-provided hyperlink object uses similar code.

STDMETHODIMP
IHlink::Navigate(DWORD grfHLNF, IBindCtx* pbc,  IBindStatusCallback*
    pbsc, IHlinkBrowseContext* phlbc)
{
    IHlinkTarget* phlTarget = NULL;
    IMoniker* pmkLeft = NULL;

    if (grfHLNF & HLNF_USEBROWSECONTEXTCLONE) {
        grfHLNF &= ~HLNF_USEBROWSECONTEXTCLONE;
        phlbc->Clone(NULL, IID_IHlinkBrowseContext, &phlbc);
        }
    else {
        hr = m_phlSite->GetMoniker(m_dwSiteData,
        OLEGETMONIKER_ONLYIFTHERE, OLEWHICHMK_CONTAINER, &pmkLeft);
        if (FAILED(hr) || m_pmkTarget->IsEqual(pmkLeft)) {
            hr = m_phlSite->GetInterface(dwSiteData, 0, IID_IHlinkTarget,
                (void**)&phlTarget);
            if (FAILED(hr))
                phlbc->GetObject(m_pmkTarget, &phlTarget);
            }

    if (phlTarget == NULL) {
        // Set the pbsc in the pbc to get asynch and notification
        // binding behavior requested by caller
        m_pmkTarget->BindToObject(pmkLeft, IID_IHlinkTarget, &phlTarget);
        phlTarget->SetBrowseContext(phlbc);
        }

    phlTarget->Navigate(grfHLNF, m_szLocation);
}  // IHlink::Navigate

Setting the browse context

During the execution of the above code, the hyperlink target receives the browse context for the navigation. This provides information about the hyperlink navigation stack and window positions for the hyperlinking.

Note This function is not called in all hyperlinking circumstances, for example in the Simple Hyperlinking example above. A simple hyperlink target need not implement this function.

STDMETHODIMP
CHlinkTarget::SetBrowseContext(IHlinkBrowseContext* phlbc)
{
    if (m_phlbc != NULL) {
        m_phlbc->Revoke(m_dwRegister);
        m_phlbc->Release();
        }
    m_phlbc = phlbc;
    if (m_phlbc != NULL) {
        m_phlbc->AddRef();
        m_phlbc->Register(0, (IUnknown*)this, m_pmk, &m_dwRegister);
        }

    return S_OK;
}  // CHlinkTarget::SetBrowseContext

The hyperlink target then receives control to navigate to the specific location within the target.

STDMETHODIMP
IHlinkTarget::Navigate(DWORD grfHLNF, LPCWSTR szLocation)
{
    IHlinkFrame* phlFrame = NULL;

    // if the object is not visible, activate it and show it.
    // jump to the location indicated by szLocation

    // if this hyperlink target is an Active Document object,
    // try to retrieve the hyperlink frame pointer
    // from the IOleInPlaceFrame
    if (m_poleinplaceframe)
        m_poleinplaceframe->QueryInterface(IID_IHlinkFrame,
        (void**)&phlFrame);

    // notify the hlink frame and the browse context that
    //the navigation is complete.
    // Note: either phlFrame or m_phlbc may be NULL
    HlinkOnNavigate(phlFrame, m_phlbc, grfHLNF, m_pmk, szLocation,
    szFriendlyName);

    if (phlFrame == NULL && !(grfHLNF & HLNF_INTERNALJUMP)) {
        HLBWINFO hlbwi;
        phlbc->GetBrowseWindowInfo(&hlbwi);

        // adjust the document and frame windows according
        // to the dimensions in HLBWI
    }

    m_fHide = FALSE;
    m_fHideFrame = FALSE;
}  // IHlinkTarget::Navigate

Receiving success notification

The hyperlink frame next receives notification of a successful navigation from within IHlinkTarget::Navigate in order to reposition its windows and update their visibility. If this is the same frame that hosted the hyperlink container that initiated the navigation, the m_fHide flag set below will ensure that the frame remains visible.

STDMETHODIMP
IHlinkFrame::OnNavigate(DWORD grfHLNF)
{
    if (!(grfHLNF & HLNF_INTERNALJUMP)) {
        HLBWINFO hlbwi;
        m_phlbc->GetBrowseWindowInfo(&hlbwi);
        // Adjust this document/frame windows according to the
        // dimensions in hlbwi
    }
    m_fHide = FALSE;
}  // IHlinkFrame::OnNavigate

Finally, the browse context receives notification of a successful navigation from IHlinkTarget::Navigate in order to update the navigation stack.

STDMETHODIMP
IHlinkBrowseContext::OnNavigateHlink(DWORD grfHLNF, IMoniker*
    pmkTarget, LPCWSTR szLocation, LPCWSTR szFriendlyName)
{
    // if CreateNoHistory or NavigatingToStackItem, return immediately
    // unless NavigatingBack or NavigatingForward is also set
    if (grfHLNF & (HLNF_CREATENOHISTORY | HLNF_NAVIGATINGTOSTACKITEM)) {
        if (!(grfHLNF & (HLNF_NAVIGATINGBACK | HLNF_NAVIGATINGFORWARD)))
            return NOERROR;
        }
    if (grfHLNF & HLNF_NAVIGATINGBACK)
        --m_iCurrent;
    else if (grfHLNF & HLNF_NAVIGATINGFORWARD)
        ++m_iCurrent;
    else {
        // Add this hyperlink to the navigation stack at m_iCurrent+1;
        // remove all items greater than m_iCurrent+1,

        ++m_iCurrent;
        }
}  // IHlinkBrowseContext::OnNavigateHlink


Reference

This ActiveX Hyperlinks reference contains the following sections:

  • Interfaces
  • Functions
  • Enumerations
  • Structures
  • Objects


Interfaces

This section describes the following interfaces:

  • IHlink
  • IHlinkBrowseContext
  • IHlinkFrame
  • IHlinkSite
  • IHlinkTarget


Hlink

The IHlink interface enables a COM object known as a hyperlink to completely encapsulate the behavior of navigating to its target location.

Hyperlinks are managed by COM hyperlink container objects, which support the IHlinkSite interface for hyperlinks within the container, and the IHlinkTarget interface for hyperlinks referring to documents or document objects within it.

IHlink provides methods for a hyperlink object to navigate to its target, access a friendly name for display purposes, and identify itself to its container and frame.

Implementing IHlink

Typically, you don't need to implement this interface. A standard implementation of a hyperlink component is provided as part of the system, and it is not advisable to implement another version. A document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the capability of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. The standard hyperlink object implements IHlink, IPersistStream, and IDataObject interfaces.

The support for IPersistStream means that hyperlink objects can be saved to or loaded from a stream, and the support for IDataObject means that hyperlink objects can be cut and pasted.

Using IHlink

IHlink interfaces are typically called by an application's hyperlink container as part of a user interface for creating new hyperlinks. Standard hyperlink objects are created through the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream functions.

While the hyperlink object provides many useful functions that are needed for general-purpose uses, often applications are only interested in navigating to a hyperlink target. For simple navigation needs, there are a number of "helper" functions, such as HlinkSimpleNavigateToString, HlinkSimpleNavigateToMoniker, and HlinkNavigateToStringReference, that allow simple hyperlink navigation without any knowledge of other hyperlink interfaces or objects.

Hyperlink navigation involves transitioning from one document/object/application—a hyperlink container—to another document/object/application—a hyperlink target. Usually, both remain running, but the hyperlink target visually replaces the hyperlink container (from which the navigation originated). There are three "flavors" of hyperlink containers and targets:

  1. Top-level documents.
  2. Active Document objects in a browser.
  3. Active Document objects in an Office Binder-like application that does not support OLE in-place/DocObj server functionality, and, therefore, can't be shown in-place in a browser.

The following are possible forms of navigation:

  • From one top-level document to another top-level document (for example, between Office documents in the absence of a browser).
  • From a top-level document to an Active Document in a browser (for example, from a stand-alone application to an HTML document).
  • From one Active Document object in a browser to another Active Document object in the same browser (for example, one HTML document to another).
  • From one Active Document object in a browser to an Active Document object in a Binder-type application (for example, a hyperlink target embedded as an Active Document object in an Office Binder document; in this scenario, the end-user model gets complicated and confusing if the embedded Active Document object is shown in the browser's window, instead of letting it appear in its own container's window).
  • From one location in an object/document to another location in the same object/document (applicable to all three flavors of hyperlink containers/hyperlink targets).

IHlink Methods in Vtable Order

IHlink methods | Description
SetHlinkSite | Saves the interface pointer on the site object.
GetHlinkSite | Retrieves the interface pointer on the site object.
SetMonikerReference | Sets the moniker reference of the target.
GetMonikerReference | Retrieves the moniker and location portions of the target.
SetStringReference | Sets the name and location portions of the target.
GetStringReference | Retrieves the name and location portions of the target.
SetFriendlyName | Sets the friendly name of the target.
GetFriendlyName | Retrieves the friendly name of the target.
SetTargetFrameName | Sets the name of the target frame.
GetTargetFrameName | Retrieves the name of the target frame.
GetMiscStatus | Queries if hyperlink is absolute or relative.
Navigate | Navigates to the given target.
SetAdditionalParams | Sets additional hyperlink parameters.
GetAdditionalParams | Retrieves additional hyperlink parameters.


IHlink::GetAdditionalParams

HRESULT GetAdditionalParams(
    LPWSTR * ppwzAdditionalParams    //Extensible parameter string
   );

Retrieves additional parameters or properties for the hyperlink.

  • Returns S_OK after the hyperlink's additional parameter strings are retrieved.
ppwzAdditionalParams
[out] On return, points to the location to return the string containing a list of parameters or properties for the hyperlink in the following format:
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">

The parameters retrieved in this string are primarily interpreted by the hyperlink frame.

See also IHlink::SetAdditionalParams


IHlink::GetFriendlyName

HRESULT GetFriendlyName(
    DWORD grfHLFNAMEF,           //Flag specifying the friendly name to return.
    LPWSTR * ppwzFriendlyName    //Buffer to receive the friendly name.
   );

Retrieves the friendly name of the target. The container normally uses this name to determine how to represent the hyperlink in its user interface.

  • Returns S_OK after the friendly name string of the hyperlink is retrieved.
grfHLFNAMEF
[in] Flag specifying the friendly name to return.
ppwzFriendlyName
[out] Address of the buffer to return the friendly name. This string must be allocated using CoTaskMemAlloc. It is the caller's responsibility to free this string using CoTaskMemFree.

See also IHlink::SetFriendlyName, IHlinkTarget::GetFriendlyName


IHlink::GetHlinkSite

HRESULT GetHlinkSite(
    IHlinkSite * ppihlSite,    //Receives the hyperlink site interface
    DWORD *pdwSiteData         //Receives additional site data
   );

Retrieves the hyperlink site and associated site data from a hyperlink object.

  • Returns S_OK after the hyperlink site and associated data have been successfully retrieved.
ppihlSite
[out] On return, points to the IHlinkSite interface pointer on the hyperlink object. This cannot be a NULL pointer on input.
pdwSiteData
[out] On return, points to the site data of the hyperlink target. This must not be a NULL pointer on input.

See also IHlink::SetHlinkSite


IHlink::GetMiscStatus

HRESULT GetMiscStatus(
    DWORD * pdwStatus    //Receives absolute/relative status of hyperlink
   );

Queries whether the hyperlink is an absolute or a relative link.

  • Returns S_OK after the hyperlink status has been successfully retrieved.
pdwStatus
[out] On return, points to a value from the HLINKMISC enumeration. Must not be NULL.

See also HLINKMISC


IHlink::GetMonikerReference

HRESULT GetMonikerReference(
    DWORD dwWhichRef,          /Absolute or relative reference
    IMoniker * ppimkTarget,    //Receives a pointer to the moniker of the hyperlink target
    LPWSTR * ppwzLocation      //Receives the location portion of the hyperlink target
   );

Retrieves the moniker and location portions of the hyperlink reference.

  • Returns S_OK to indicate the moniker and location portions of the target of the hyperlink target have been successfully supplied.
dwWhichRef
[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.
ppimkTarget
[out] On return, points to the IMoniker pointer of the target's moniker object, if any. Can be NULL, in which case the caller is not interested in the moniker to the hyperlink reference.
ppwzLocation
[out] On return, points to the string location portion of the target, if any. If NULL, the caller is not interested in the location portion of the hyperlink reference.

See also HLINKGETREF, IHlinkSite::GetMoniker, IHlinkTarget::GetMoniker


IHlink::GetStringReference

HRESULT GetStringReference(
    DWORD dwWhichRef,         //Absolute or relative reference
    LPWSTR * ppwzTarget,      //Receives the string that helps identify the hyperlink target
    LPWSTR * ppwzLocation     //Receives the location portion of the hyperlink target
   );

Retrieves strings that identify the hyperlink target and the location within the hyperlink target.

  • Returns S_OK to indicate the target and location strings of the hyperlink target have been successfully supplied.
dwWhichRef
[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.
ppwzTarget
[out] On return, points to a string that helps identify the hyperlink target of the hyperlink reference. If NULL, the caller is not interested in the target string of the hyperlink reference.
ppwzLocation
[out] On return, points to the location portion of the hyperlink reference. If NULL, the caller is not interested in the location portion of the hyperlink reference.

See also IHlink::GetMonikerReference, HLINKGETREF, HlinkNavigateToStringReference, HlinkSimpleNavigateToString


IHlink::GetTargetFrameName

HRESULT GetTargetFrameName(
    LPWSTR * ppwzTargetFrameName    //Receives the target frame name for the hyperlink
   );

Retrieves the name of the target frame for the hyperlink.

  • Returns S_OK if the target frame name string for the hyperlink was retrieved.
ppwzTargetFrameName
[out] On return, points to the target frame name for the hyperlink. Must not be NULL.

See also IHlink::SetTargetFrameName


IHlink::Navigate

HRESULT Navigate(
    DWORD grfHLNF,    //Navigation flags
    LPBC pibc,        //Bind context interface pointer
    IBindStatusCallback * pibsc,    //Bind-status-context interface pointer
    IHlinkBrowseContext * pihlbc    //Browse context interface pointer
   );

Navigates to the hyperlink reference. IHlink::Navigate is the heart of the navigation process that implements the action of resolving a hyperlink target.

  • Returns S_OK if navigation to the hyperlink has been completed successfully.
grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pibc
[in, unique] IBindCtx interface pointer to the bind context to be used for any moniker binding during this operation. Cannot be NULL.
pibsc
[in, unique] IBindStatusCallback interface pointer to the bind status context to use for any asynchronous moniker binding performed during the navigation. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information
pihlbc
[in, unique] Address of the IHlinkBrowseContext interface to use for this navigation. Cannot be NULL. As part of navigation, this browse context's navigation stack can be updated (depending on the navigation flags in grfHLNF), and its cache of hyperlink targets is consulted for a matching to the current hyperlink target.

See also HlinkNavigate, HLNF, IHlinkFrame::Navigate, IHlinkTarget::Navigate


IHlink::SetAdditionalParams

HRESULT SetAdditionalParams(
    LPCWSTR  pwzAdditionalParams    //Extensible parameter string
   );

Sets the additional parameters or properties for the hyperlink.

  • Returns S_OK if the hyperlink's additional parameters string was set.
pwzAdditionalParams
[in, unique] The string containing a list of parameters or properties for the hyperlink in the following format:
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">

The parameters saved in this string are primarily interpreted by the hyperlink frame.

See also IHlink::GetAdditionalParams


IHlink::SetFriendlyName

HRESULT SetFriendlyName(
    LPCWSTR pwzFriendlyName    //Friendly name of the hyperlink
   );

Sets the friendly name for the hyperlink. The friendly name is used by hyperlink containers to represent the hyperlink within their user interface.

  • Returns S_OK if the friendly name string of the hyperlink was set.
pwzFriendlyName
[in, unique] The friendly name string of the hyperlink target.

See also IHlink::GetFriendlyName


IHlink::SetHlinkSite

HRESULT SetHlinkSite(
    IHlinkSite * pihlSite,    //Interface pointer to the new hyperlink site
    DWORD dwSiteData          //Additional site data
   );

Sets the hyperlink site and associated site data on a hyperlink object.

  • Returns S_OK if the hyperlink site object and its site data have been successfully set.
pihlSite
[in, unique] Address of a new IHlinkSite object for this hyperlink.
dwSiteData
[in] DWORD that specifies additional information about the site. For instance, each site can differ in color or style from other sites in the same container.

See also IHlink::GetHlinkSite


IHlink::SetMonikerReference

HRESULT SetMonikerReference(
    DWORD grfHLSETF,    //Specifies whether to set the hyperlink target, the location
                        // within the target, or both.
    IMoniker * pimkTarget,   //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation      //Location within the hyperlink target of new hyperlink
   );

Sets the target moniker or location string values for a hyperlink object.

  • Returns S_OK if the moniker reference for the hyperlink was set.
grfHLSETF
[in] Used to indicate whether to set the hyperlink target, the location within the target, or both.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.

See also HLINKSETF


IHlink::SetStringReference

HRESULT SetStringReference(
    DWORD grfHLSETF,       //Specifies whether to set the hyperlink target, the location within the target,
                           // or both.
    LPCWSTR pwzTarget,     //Target name for the hyperlink
    LPCWSTR pwzLocation    //Location within the hyperlink target of new hyperlink
   );

Sets the target string or location string values for a hyperlink object.

  • Returns S_OK if the string reference of the hyperlink was set.
grfHLSETF
[in] Used to indicate whether to set the hyperlink target, the location within the target, or both.
pwzTarget
[in, unique] The string target name for the hyperlink.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.

See also HLINKSETF


IHlink::SetTargetFrameName

HRESULT SetTargetFrameName(
    LPCWSTR  pwzTargetFrameName    //Target frame name for the hyperlink
   );

Sets the target frame name for the hyperlink.

  • Returns S_OK if the target frame name string for the hyperlink was set.
pwzTargetFrameName
[in, unique] The string target frame name for the hyperlink.

See also IHlink::GetTargetFrameName


IHlinkBrowseContext

The IHlinkBrowseContext interface enables a COM object to define and manage the browsing context for an ActiveX hyperlink application.

A hyperlink browse context keeps track of the order in which the object/documents (perhaps belonging to different processes) have been visited and chains them together into a navigation stack. The context also keeps track of enabling or disabling buttons such as Go Forward or Go Back for each entry in the navigation stack. In addition, the context maintains window positioning information for hyperlink targets so that a hyperlink application can provide a seamless user interface.

Browse context objects are not required for hyperlink navigation. HlinkSimpleNavigateToString and HlinkSimpleNavigateToMoniker provide examples of navigation between hyperlink containers and hyperlink targets that do not use a browsing context.

IHlinkBrowseContext provides methods that maintain the hyperlink navigation stack and keep track of window position information.

Implementing IHlinkBrowseContext

The system provides a default implementation.

IHlinkBrowseContext Methods in Vtable Order

IHlinkBrowseContext methods | Description
Register | Registers an object with the browse context.
GetObject | Retrieves an object previously registered in the browse context under the given name.
Revoke | Revokes an object previously registered with this browse context.
SetBrowseWindowInfo | Establishes the browse window information structure of this browse context.
GetBrowseWindowInfo | Retrieves the browse window information structure associated with this browse context.
EnumNavigationStack | Retrieves an enumerator that can be used to enumerate the current contents of the navigation stack.
QueryHlink | Tests the validity of a hyperlink ID value.
GetHlink | Retrieves a hyperlink from this browse context.
SetCurrentHlink | Sets the current hyperlink in this browse context's navigation stack.
OnNavigateHlink | Notifies a browse context that a hyperlink has been navigated.
Clone | Duplicates a browse context.
Close | Closes the hyperlink browse context.


IHlinkBrowseContext::Clone

HRESULT Clone(
    IUnknown* piunkOuter,    //Controlling IUnknown interface for new browse context
    REFIID riid,             //Interface ID to return on the new browse context
    IUnknown** ppiunkObj     //Indirect pointer to the clone of the browse context object
   );

Duplicates a browse context.

  • Returns S_OK if the browse context has been duplicated.
piunkOuter
[in, unique] Address of the controlling IUnknown interface for the new browse context. If NULL, the new browse context is not aggregated.
riid
[in] The interface to return on the new hyperlink. Typically IID_IHlink or IID_IUnknown when punkOuter is non-NULL.
ppiunkObj
[out, iid_is] Indirect pointer to the clone of the browse context object.


IHlinkBrowseContext::Close

HRESULT Close(
    DWORD dwReserved    //Reserved for future use
   );

Closes the hyperlink browse context. Releases all hyperlink targets that have been registered with the browse context.

  • Returns S_OK if the hyperlink browse context has been successfully closed.
dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

See also IHlinkBrowseContext::Register


IHlinkBrowseContext::EnumNavigationStack

HRESULT EnumNavigationStack(
    DWORD dwReserved,     //Reserved for future use
    DWORD grfHLFNAMEF,    //Specifies what kind of friendly names to enumerate for the Hlink objects in the navigation stack.
    IEnumHLITEM ** ppienumhlitem    //Location to receive the enumeration interface pointer
   );

Retrieves an enumerator that can be used to enumerate the current contents of the navigation stack.

  • Returns S_OK if the enumerator has been successfully retrieved.
dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.
grfHLFNAMEF
[in] Indicator of what kind of friendly names to enumerate for the Hlink objects in the navigation stack.
ppienumhlitem
[out] Location to return the IEnumHLITEM enumeration interface over the set of hyperlinks in this navigation stack.

See also HLID, HLITEM, IEnumHLITEM


IHlinkBrowseContext::GetBrowseWindowInfo

HRESULT GetBrowseWindowInfo(
    HLBWINFO * phlbwi    //Location to receive the HLBWINFO structure
   );

Retrieves the HLBWINFO structure currently associated with this browse context.

  • Returns S_OK if the HLBWINFO structure for this browse window has been retrieved.
phlbwi
[out] Address of the location to return the current HLBWINFO structure.

See also HLBWINFO, IHlinkBrowseContext::SetBrowseWindowInfo


IHlinkBrowseContext::GetHlink

HRESULT GetHlink(
    ULONG uHLID,       //Hyperlink to retrieve
    IHlink * ppihl     //Buffer to return the IHlink interface of the hyperlink
   );

Retrieves a hyperlink from this browse context.

  • Returns S_OK if the hyperlink has been successfully retrieved from this browse context, or E_FAIL if the specified hyperlink does not exist in this browse context.
uHLID
[in] Used to identify the hyperlink to retrieve. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.
ppihl
[out] Address of the buffer to return the IHlink interface pointer of the hyperlink object.

See also HLID, IHlink, IHlinkBrowseContext::SetCurrentHlink


IHlinkBrowseContext::GetObject

HRESULT GetObject(
    IMoniker * pimk,         //Moniker interface pointer of the object being retrieved
    BOOL fBindIfRootRegistered,    //Determines binding to the moniker and retrieval of the object
    IUnknown ** ppiunk       //Location to receive the unknown interface pointer of requested object
   );

Retrieves an object previously registered in the browse context.

  • Returns S_OK to indicate the previously registered object has been retrieved, or S_FALSE to indicate no object indicated by pimk was registered in the browse context.
pimk
[in,unique] Used to identify the object being retrieved.
fBindIfRootRegistered
[in] If set to TRUE, this method binds to the moniker and retrieves the object (if the object referred to by pimk is not registered in the browse context).
ppiunk
[out] Indirect pointer to the IUnknown interface of the object being retrieved.

If the object referred to by pimk is not registered in the browse context, this method binds to the full moniker and retrieves the object if the following conditions are met:

  • fBindIfRootRegistered is set to TRUE.
  • The moniker is referring to an embedded object (the moniker pimk is a generic composite moniker).
  • The root object of the containment hierarchy is registered with the browse context.

See also IHlinkBrowseContext::Register


IHlinkBrowseContext::OnNavigateHlink

HRESULT OnNavigateHlink(
    DWORD grfHLNF,      //Navigation flags
    IMoniker * pimkTarget,     //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation,       //Location within the hyperlink target of new hyperlink
    LPCWSTR pwzFriendlyName,   //Friendly name of the hyperlink
    ULONG * puHLID      //Pointer to hyperlink identifier
   );

Notifies a browse context that a hyperlink has been navigated.

  • Returns S_OK if the browse context has been successfully notified that a hyperlink has been navigated.
grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.
pwzFriendlyName
[in, unique] The friendly name of the location within the hyperlink target that has been navigated to. Must not be NULL.
puHLID
[out] Address of the hyperlink indentifier to set in the current browse context's navigation stack.

See also HlinkOnNavigate, HLNF, IHlinkFrame::OnNavigate, IHlinkSite::OnNavigationComplete


IHlinkBrowseContext::QueryHlink

HRESULT QueryHlink(
    DWORD grfHLQF,    //Value from the HLQF enumeration
    ULONG uHLID       //Hyperlink identifier to query
   );

Tests the validity of a uHLID value.

  • Returns one of the following values:
    S_OK | If grfHLQF is HLQF_ISVALID, uHLID identifies a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID identifies the current hyperlink of the browse context.
    S_FALSE | If grfHLQF is HLQF_ISVALID, uHLID does not identify a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID does not identify the current hyperlink of the browse context.
grfHLQF
[in] A single value taken from the HLQF enumeration.
uHLID
[in] Used to identify the hyperlink to query about. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

See also HLID, HLQF


IHlinkBrowseContext::Register

HRESULT Register(
    DWORD dwReserved,      //Reserved for future use
    IUnknown piunk,        //Object being registered
    IMoniker * pimk,       //Moniker interface pointer of the object being registered
    DWORD * pdwRegister    //Receives the registration value
   );

Registers an object with the browse context.

  • Returns one of the following values:
    S_OK | The object has been registered.
    MK_S_MONIKERALREADYREGISTERED | The object was successfully registered, but another object (possibly the same object) has already been registered with the same moniker in this browse context.
    E_OUTOFMEMORY | There was insufficient memory to register the object with the browse context.
dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.
piunk
[in, unique] The object being registered.
pimk
[in, unique] Address of the IMoniker interface pointer that identifies the object being registered.
pdwRegister
[out] Address of a location to return a value identifying the registration, which can be used to subsequently revoke the registration.

See also HlinkCreateBrowseContext, IHlinkBrowseContext::Close, IHlinkBrowseContext::Revoke


IHlinkBrowseContext::Revoke

HRESULT Revoke(
    DWORD dwRegister    //Object to revoke
   );

Revokes an object previously registered with this browse context.

  • Returns S_OK if the previously registered object has been revoked from this browse context.
dwRegister
[in] Used to identify the object to revoke. Returned by a previous call to IHlinkBrowseContext::Register.

See also IHlinkBrowseContext::Register


IHlinkBrowseContext::SetBrowseWindowInfo

HRESULT SetBrowseWindowInfo(
    HLBWINFO * phlbwi    //Pointer to the new HLBWINFO structure for this browse context
   );

Establishes the HLBWINFO structure of this browse context.

  • Returns S_OK if the HLBWINFO structure for this browse window has been established.
phlbwi
[in,unique] Address of the new HLBWINFO structure for this browse context.

See also HLBWINFO, IHlinkBrowseContext::GetBrowseWindowInfo


IHlinkBrowseContext::SetCurrentHlink

HRESULT SetCurrentHlink(
    ULONG uHLID    //Hyperlink ID to set in the navigation stack
   );

Sets the current hyperlink in this browse context's navigation stack.

  • Returns S_OK to indicate this hyperlink has been successfully set in the current browse context's navigation stack, or E_FAIL if not.
uHLID
[in] Used to identify the hyperlink to set in the current browse context's navigation stack. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

See also HLID, IHlinkBrowseContext::GetHlink


IHlinkFrame

The IHlinkFrame interface provides methods that allow a hyperlink frame to interpose itself in the navigation process to allow an application to provide a seamless user interface when navigating from one document/object/application to another when resolving a hyperlink.

Implementing IHlinkFrame

This interface is typically implemented by a document container object, such as Microsoft Internet Explorer or Microsoft Office Binder. A document container implementing the IHlinkFrame interface can host documents that support in-frame navigation from one to another.

Using IHlinkFrame

You do not normally call the IHlinkFrame methods directly. They are referenced by the IHlink::Navigate routines when a hyperlink frame is detected.

IHlinkFrame Methods in Vtable Order

IHlinkFrame methods | Description
GetBrowseContext | Retrieves the browse context of the hyperlink frame.
Navigate | Navigates to the target hyperlink.
OnNavigate | Notifies the hyperlink frame of a hyperlink navigation.
SetBrowseContext | Sets the browse context of the hyperlink frame.
UpdateHlink | Updates the hyperlink frame.


IHlinkFrame::GetBrowseContext

HRESULT GetBrowseContext(
    IHlinkBrowseContext * ppihlbc    //Buffer to receive the interface of the current browse context
   );

Retrieves the browse context of the hyperlink frame.

  • Returns S_OK if the browse context has been successfully retrieved, or E_NOTIMPL if the hyperlink target does not understand browse contexts.
ppihlbc
[out] Location to return the browse context interface's pointer.

See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::SetBrowseContext, IHlinkTarget


IHlinkFrame::Navigate

HRESULT Navigate(
    DWORD grfHLNF,    //Navigation flags
    LPBC pbc,        //Bind context interface pointer
    IBindStatusCallback * pibsc,    //Bind-status callback  interface pointer
    IHlink * pihlNavigate           //Hyperlink target interface pointer
   );

Navigates to the hyperlink target.

  • Returns one of the following:
    S_OK | The navigation to the target has been successful.
    IHlink::Navigate errors | Since IHlinkFrame::Navigate calls IHlink::Navigate, the errors associated with this method can be returned.
grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pbc
[in, unique] Address of the bind context interface to use for any moniker binding during this operation. Must not be NULL.
pibsc
[in, unique] Address of the IBindStatusCallback object interface to use for any asynchronous moniker binding performed during the navigation. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
pihlNavigate
[in, unique] Address of the IHlink object interface to the hyperlink target.

See also HLNF, IHlink::Navigate


IHlinkFrame::OnNavigate

HRESULT OnNavigate(
    DWORD grfHLNF,            //Navigation flags
    IMoniker * pimkTarget,    //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation,      //Location within the hyperlink target of new hyperlink
    LPCWSTR pwzFriendlyName   //Friendly name of the hyperlink
   );

Notifies the hyperlink frame that a hyperlink has been navigated to.

  • Returns S_OK if the hyperlink frame has been successfully notified.
grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.
pwzFriendlyName
[in, unique] The friendly name of the location within the hyperlink target that has been navigated to. Must not be NULL.

See also HlinkOnNavigate, HLNF, IHlinkBrowseContext::OnNavigateHlink, IHlinkSite::OnNavigationComplete


IHlinkFrame::SetBrowseContext

HRESULT SetBrowseContext(
    IHlinkBrowseContext * phlbc    //Interface pointer of the current browse context
   );

Sets the browse context of the hyperlink frame.

  • Returns S_OK if the browse context has been successfully set, or E_NOTIMPL if the hyperlink target does not understand browse contexts.
phlbc
[in] The browse context interface's pointer.

See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::SetBrowseContext


IHlinkFrame::UpdateHlink

HRESULT UpdateHlink(
    ULONG uHLID,              //Hyperlink to retrieve
    IMoniker * pimkTarget,    //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation,      //Location within the hyperlink target of new hyperlink
    LPCWSTR pwzFriendlyName   //Friendly name of the hyperlink
   );

Updates the hyperlink frame.

  • Returns S_OK if the hyperlink frame has been successfully updated.
uHLID
[in] Used to identify the hyperlink to retrieve. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.
pwzFriendlyName
[in, unique] The friendly name of the location within the hyperlink target that has been navigated to. Must not be NULL.

This method is called before navigation, typically by the IHlinkSite::ReadyToNavigate method. An application that does not implement the IHlinkSite interface can call this method before calling the navigation function.

See also HlinkOnNavigate, HLID, IHlinkBrowseContext::OnNavigateHlink, IHlinkSite::OnNavigationComplete


IHlinkSite

The IHlinkSite interface provides methods for a hyperlink to retrieve the moniker or the interface on its hyperlink container. The navigation process that resolves a hyperlink uses this information to efficiently handle internal (within the same container) and external (to a different container) hyperlink references.

Implementing IHlinkSite

Implement IHlinkSite when you want to hyperlink to other documents. For each hyperlink object provided by the system, a third party, or that you create, you provide an IHlinkSite object. One site object can support multiple hyperlinks.

IHlinkSite Methods in Vtable Order

IHlinkSite methods | Description
QueryService | Queries any service or other interface from the hyperlink site object.
GetMoniker | Retrieves the moniker to the hyperlink target.
ReadyToNavigate | Notifies the hyperlink site that the hyperlink navigation is about to occur.
OnNavigationComplete | Notifies the hyperlink site that hyperlink navigation is complete.


IHlinkSite::GetMoniker

HRESULT GetMoniker(
    DWORD dwSiteData,    //Site data for the new hyperlink object
    DWORD dwAssign,      //Whether or not to create a moniker if one not found
    DWORD dwWhich,       //Which moniker to retrieve
    IMoniker * ppimk     //Buffer to receive the requested moniker interface pointer
   );

Returns the relative moniker of the hyperlink's container.

  • Returns S_OK if the moniker of the hyperlink's site container was successfully supplied, or E_FAIL if a moniker does not exist for this hyperlink target and OLEGETMONIKER_ONLYIFTHERE was specified for dwAssign.
dwSiteData
[in] Used to identify the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite.
dwAssign
[in] A value from the OLEGETMONIKER enumeration. This is typically either OLEGETMONIKER_ONLYIFTHERE, indicating the function should not force a moniker to be created if one does not already exist, or OLEGETMONIKER_FORCEASSIGN, indicating that the function should create a moniker if one does not exist.
dwWhich
[in] A value from the OLEWHICHMK enumeration. This is typically OLEWHICHMK_CONTAINER, indicating that the site should return the moniker of the hyperlink container.
ppimk
[out] Location to return the IMoniker interface.

See also IHlink::GetMonikerReference, IHlinkTarget::GetMoniker


IHlinkSite::OnNavigationComplete

HRESULT OnNavigationComplete(
    DWORD dwSiteData,    //Site data for the hyperlink object
    DWORD dwReserved,    //Reserved for future use
    HRESULT hrError,     //Result of the hyperlink navigation
    LPCWSTR pwzError     //Description of the failure, if any
   );

Notifies the hyperlink site that a hyperlink navigation has been successful.

  • Returns S_OK if the hyperlink site has been successfully notified.
dwSiteData
[in] Used to identify the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite.
dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.
hrError
[in] Result of the hyperlink navigation. Either S_OK for success, or E_ABORT or E_FAIL for failure.
pwzError
[in] Address of the string describing the failure that occurred.

This notification is particularly useful if the hyperlink has been navigated asynchronously, because it is the only notification the hyperlink receives to realize that hyperlinking has completed.

See also HlinkOnNavigate, IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate


IHlinkSite::QueryService

HRESULT QueryService(
    DWORD dwSiteData,        //Site data to identify the hyperlink its site
    REFGUID guidService,    //TBD
    REFIID riid,             //Location to return the riid interface
    IUnknown* ppiunk         //Location to receive the unknown interface pointer of service query
   );

Allows querying of any service or other interface from the hyperlink site object. This is similar to IServiceProvider::QueryService.

  • Returns S_OK if the hyperlink container interface was successfully retrieved, or E_NOINTERFACE if the desired interface is not available.
dwSiteData
[in] Used to identify the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite.
guidService
[in] Not currently implemented.
riid
[in] Location to return the riid interface.
ppiunk
[iid_is, out] Location to return the IUnknown interface of the service query.

See also IHlinkSite::GetMoniker


IHlinkSite::ReadyToNavigate

HRESULT ReadyToNavigate(
    DWORD dwSiteData,    //Site data for the hyperlink object
    DWORD dwReserved     //Reserved for future use
   );

Notifies the hyperlink site that the hyperlink navigation is about to occur. To back out of the operation, return E_ABORT.

  • Returns S_OK if the hyperlink site has been successfully notified.
dwSiteData
[in] Used to identify the hyperlink to the hyperlink site. The hyperlink site initializes the hyperlink with this value as part of IHlink::SetHlinkSite.
dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

See also HlinkOnNavigate, IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate


IHlinkTarget

A hyperlink target implements the IHlinkTarget interface and gives out hyperlink references to its contents.

Implementing IHlinkTarget

Implement this interface when you have an application that can be the target for a hyperlink. In other words, hyperlinks from other applications use this interface to determine how to find, display, and navigate to your target.

An existing OLE document application that supports OLE linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application can also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile.

Note that an Active Document object need not implement this interface if hyperlink navigation is only occuring within a document object container such as Microsoft Internet Explorer. In such a situation, IHlinkTarget provides the capability to navigate to a location within the document, but it is not necessary for navigation to be completed.

Using IHlinkTarget

You do not normally call these methods directly. When an end user selects a hyperlink through an application's user interface, the implementation of IHlink::Navigate calls these methods to determine how to display, locate, and navigate to the target.

IHlinkTarget Methods in Vtable Order

IHlinkTarget methods | Description
SetBrowseContext | Establishes the current browse context for this hyperlink target.
GetBrowseContext | Retrieves the current browse context within which this hyperlink target is currently running.
Navigate | If the given location is not visible, navigates to and shows that position within the target.
GetMoniker | Returns a moniker to the hyperlink target object.
GetFriendlyName | Returns a friendly name for the given hyperlink location within this target.


IHlinkTarget::GetBrowseContext

HRESULT GetBrowseContext(
    IHlinkBrowseContext * ppihlbc    //Buffer to receive the current browse context's interface pointer
   );

Retrieves the browse context in which this hyperlink target is currently running.

  • Returns S_OK if the browse context has been successfully retrieved, or E_NOTIMPL if the hyperlink target does not understand browse contexts.
ppihlbc
[out] Address of the location to return the browse context object's interface pointer.

See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::SetBrowseContext


IHlinkTarget::GetFriendlyName

HRESULT GetFriendlyName(
    LPCWSTR pwzLocation,     //Hyperlink location within this target
    LPWSTR * ppwzFriendlyName    //Buffer to receive the friendly name
   );

Retrieves a friendly name for the given hyperlink destination within this target.

  • Returns S_OK if the friendly name string of the hyperlink destination with this target has been retrieved, or E_OUTOFMEMORY if there is insufficient memory to retrieve the friendly name.
pwzLocation
[in, unique] String that indicates the position of the hyperlink destination within this hyperlink target.
ppwzFriendlyName
[out] Address of the buffer to return the friendly name. This string must be allocated using CoTaskMemAlloc. It is the caller's responsibility to free this string using CoTaskMemFree.

See also IHlink::GetFriendlyName


IHlinkTarget::GetMoniker

HRESULT GetMoniker(
    LPCWSTR pwzLocation,     //Hyperlink destination within this target
    DWORD dwAssign,     //Whether or not to create a moniker if one not found
    IMoniker * ppimkLocation    //Buffer to receive this moniker
   );

Returns a moniker to the hyperlink target object for the given hyperlink destination szLocation.

  • Returns one of the following
    S_OK | The moniker to the hyperlink target object was retrieved.
    E_FAIL | A moniker does not exist for this hyperlink target, and OLEGETMONIKER_ONLYIFTHERE was specified for dwAssign.
    CreateFileMoniker, MkParseDisplayName, and other moniker creation API errors
pwzLocation
[in, unique] Used to identify the hyperlink destination within this target.
dwAssign
[in] A value from the OLEGETMONIKER enumeration. This is typically either OLEGETMONIKER_ONLYIFTHERE, indicating the function should not force a moniker to be created if one does not already exist, or OLEGETMONIKER_FORCEASSIGN, indicating that the function should create a moniker if one does not exist.
ppimkLocation
[out] Address of location to return the IMoniker interface pointer to the hyperlink target object for this szLocation.

See also HlinkSimpleNavigateToMoniker, IHlink::GetMonikerReference, IHlinkSite::GetMoniker


IHlinkTarget::Navigate

HRESULT Navigate(
    DWORD grfHLNF,    //Value from the HLNF enumeration
    LPCWSTR * pwzJumpLocation    //Location within the hyperlink target to navigate to
   );

If the given location is not visible, navigates to and shows the location position within the object/document.

  • Returns S_OK if navigation to the hyperlink target has been successful.
grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pwzJumpLocation
[in, unique] The string location portion of the hyperlink reference.

See also HlinkNavigate, HlinkNavigateToStringReference, HLNF, IHlinkFrame::Navigate, IHlink::Navigate


IHlinkTarget::SetBrowseContext

HRESULT SetBrowseContext(
    IHlinkBrowseContext * pihlbc    //Browse context interface pointer to set for the hyperlink target
   );

Establishes the current browse context for this hyperlink target.

  • Returns S_OK if the browse context has been successfully set, or E_NOTIMPL if the hyperlink target does not understand browse contexts.
pihlbc
[in, unique] Address of the browse context object's interface.

See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::SetBrowseContext, IHlinkTarget::GetBrowseContext


Functions

This section describes the following functions:

  • HlinkCreateBrowseContext
  • HlinkCreateFromData
  • HlinkCreateFromMoniker
  • HlinkCreateFromString
  • HlinkGetSpecialReference
  • HlinkGoBack
  • HlinkGoForward
  • HlinkNavigate
  • HlinkNavigateMoniker
  • HlinkNavigateString
  • HlinkNavigateToStringReference
  • HlinkOnNavigate
  • HlinkQueryCreateFromData
  • HlinkSetSpecialReference
  • HlinkSimpleNavigateToMoniker
  • HlinkSimpleNavigateToString


HlinkCreateBrowseContext

HRESULT HlinkCreateBrowseContext(
    IUnknown *piunkOuter,    //Controlling unknown for possible aggregation
    REFIID riid,        //Interface identifier to return on the new browse context
    void **ppvObj       //Receives the requested interface's pointer
   );

Creates an empty, default instance of the system browse context object.

  • Returns S_OK if the browse context was created and the interface pointer retrieved.
piunkOuter
[in] Address of the controlling IUnknown interface for the new browse context. Typically NULL, in which case the new browse context is not aggregated. This interface must be derived from IUnknown.
riid
[in] Used to identify the interface to return on the new browse context. Typically IID_IHlinkBrowseContext, although it must be IID_IUnknown when punkOuter is non-NULL so that the aggregator can retrieve the new browse context's inner IUnknown for future delegation of QueryInterface. See the COM aggregation documentation for details.
ppvObj
[out] Location to return the riid interface.

This helper function is identical to calling the following:

coCreateInstance(CLSID_StdHlinkBrowseContext, punkOuter, CLSCTX_SERVER, riid, ppv)

See also IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::GetBrowseContext


HlinkCreateFromData

HRESULT HlinkCreateFromData(
    IDataObject* piDataObj,    //Interface on target data from which to create the hyperlink
    IHlinkSite* pihlsite,      //Interface on hyperlink site
    DWORD dwSiteData,          //Additional site data
    IUnknown *piunkOuter,      //Interface that controls aggregation
    REFIID riid,       //Interface identifier on new hyperlink object
    Void ** ppvObj     //Receives the requested interface's pointer
   );

Creates a standard hyperlink object from a COM object that supports the IDataObject interface.

  • Returns S_OK if the new hyperlink object was created successfully, or E_NOINTERFACE if the object did not support the riid interface.
piDataObj
[in] Address of the IDataObject interface on the data object of interest. Used to access the methods to retrieve the data from the object.
pihlsite
[in] Address of the IHlinkSite interface for the new hyperlink within its container.
dwSiteData
[in] Additional site data associated with the hyperlink site.
piunkOuter
[in] Address of the controlling IUnknown interface for the new hyperlink object. If NULL, the new hyperlink object is not aggregated.
riid
[in] Used to identify the interface to return on the new hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter is non-NULL.
ppvObj
[out] On return, indirect pointer to the requested interface.

Typically, this object originates from a data transfer operation, such as copying to and pasting from the clipboard, or through a drag-and-drop operation.

HlinkCreateFromData is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met. To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.

HlinkCreateFromData is typically used by a hyperlink container as part of a user interface that creates new hyperlinks through the clipboard or a drag-and-drop operation.

See also HlinkCreateFromMoniker, HlinkCreateFromString, HlinkQueryCreateFromData


HlinkCreateFromMoniker

HRESULT HlinkCreateFromMoniker(
    IMoniker * pimkTrgt,    //Interface on hyperlink target moniker
    LPCWSTR pwzLocation,    //Named location of hyperlink reference within target
    LPCWSTR pwzFriendlyName,     //Display name of hyperlink
    IHlinkSite * pihlsite,       //Interface on hyperlink site
    DWORD dwSiteData,       //Additional site data
    IUnknown * piunkOuter,       //Whether or not object is part of an aggregate
    REFIID riid,        //Interface identifier on new hyperlink object
    Void * ppvObj       //Receives the requested interface's pointer
   );

Creates a new system hyperlink object from a moniker, a location string, and a friendly name string (used for displaying the hyperlink).

  • Returns S_OK if a new hyperlink object was created successfully.
pimkTrgt
[in] Address of the moniker to the hyperlink target for the new hyperlink. Must not be NULL.
pwzLocation
[in] Address of a named location within the hyperlink target that resolves to the hyperlink reference.
pwzFriendlyName
[in] Address of a string to use as the display name for the hyperlink.
pihlsite
[in] Address of the IHlinkSite object for the new hyperlink within the hyperlink container.
dwSiteData
[in] Additional site data for the new hyperlink object.
piunkOuter
[in] Address of the controlling IUnknown interface for the new hyperlink object. If NULL, the new hyperlink object is not aggregated.
riid
[in] Used to identify the interface to return on the new hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter is non-NULL.
ppvObj
[out] On return, indirect pointer to the requested interface.

HlinkCreateFromMoniker is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met. To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.

HlinkCreateFromMoniker creates new hyperlinks from an existing target moniker, a location string within the target, and a friendly name string used to identify how to display the hyperlink. This method's typical use is as part of a user interface for creating new hyperlinks from existing hyperlinks, or for editing existing hyperlinks, using a dialog box or form to prompt for the strings. This function is significantly faster than HlinkCreateFromString.

See also HlinkCreateFromData, HlinkCreateFromString, HlinkQueryCreateFromData


HlinkCreateFromString

HRESULT HlinkCreateFromString(
    LPCWSTR pwzTarget,    //String helping to identify the hyperlink target
    LPCWSTR pwzLocation,        //Location within the hyperlink target of new hyperlink object
    LPCWSTR pwzFriendlyName,    //Friendly name of the hyperlink
    IHlinkSite * pihlsite,      //Site for the new hyperlink object
    DWORD dwSiteData,     //Additional site data for the new hyperlink object
    IUnknown * piunkOuter,      //Whether or not object is part of an aggregate
    REFIID riid,     //Interface identifier on new browse context object
    Void * ppvObj    //Location of the requested interface's pointer
   );

Creates a new hyperlink object from strings representing the hyperlink target, the location within the target, and a friendly name.

  • Returns S_OK if a new hyperlink object was created.
pwzTarget
[in] Address of the string to help identify the hyperlink target. This string is resolved into a moniker through MkParseDisplayNameEx.
pwzLocation
[in] Address of the string representing the location within the hyperlink target for the new hyperlink. Must not be NULL.
pwzFriendlyName
[in] Address of the string to use as the friendly name for the hyperlink. This is typically a display name referenced by the user interface.
pihlsite
[in] Address of the IHlinkSite object for the new hyperlink within the hyperlink container.
dwSiteData
[in] Additional site data for the new hyperlink object.
piunkOuter
[in] Address of the controlling IUnknown interface for the new browse context. If NULL, the new browse context is not aggregated.
riid
[in] Used to identify the interface to return on the new hyperlink. Typically IID_IHlink, or IID_IUnknown when punkOuter is non-NULL.
ppvObj
[out] On return, indirect pointer to the requested interface.

HlinkCreateFromString is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met.

To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.

HlinkCreateFromString is typically used by hyperlink containers as part of the user interface for creating brand new hyperlinks, where the user fills in a form or dialog box of items—target, location, friendly name—that are used to construct the hyperlink.

See also HlinkCreateFromData, HlinkCreateFromMoniker, HlinkQueryCreateFromData


HlinkGetSpecialReference

HRESULT HlinkGetSpecialReference(
    ULONG uReference,    //Special reference flags
    LPWSTR * ppwzReference    //Buffer to return special reference string
   );

For a given value from the HLSR enumeration, this function returns the current user's default global home, search, or history page for browsing as a string.

uReference
[in] A value taken from the HLSR enumeration.
ppwzReference
[out] Indirect pointer to the location to return the special reference string. Must not be NULL.

See also HlinkSetSpecialReference, HLSR


HlinkGoBack

HRESULT HlinkGoBack(
    IUnknown *pUnk    //IUnknown pointer to the initiating document or object
   );

Executes a hyperlink jump backward within the navigation stack.

  • Returns S_OK if the hyperlink jump has executed successfully.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. Must not be NULL.

The HlinkGoBack helper function should be used by all applications, documents, and objects that have simple navigational needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

The specified pointer pUnk must point to an object that is hosted within a hyperlink-aware container, such as Microsoft Internet Explorer or an ActiveX hyperlink frame.

Note that this function will work only if the object calling the function is the current object in the navigation stack. In HTML pages with frame sets, HlinkGoBack only affects the current frame.

See also HlinkGoForward


HlinkGoForward

HRESULT HlinkGoForward(
    IUnknown *pUnk    //IUnknown pointer to the initiating document or object
   );

Executes a hyperlink jump forward within the navigation stack.

  • Returns S_OK if the hyperlink jump has executed successfully.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. Must not be NULL.

The HlinkGoForward helper function should be used by all applications, documents, and objects that have simple navigational needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

The specified pointer pUnk must point to an object that is hosted within a hyperlink-aware container, such as Microsoft Internet Explorer or an ActiveX hyperlink frame.

Note that this function will work only if the object calling the function is the current object in the navigation stack. In HTML pages with frame sets, HlinkGoForward only affects the current frame.

See also HlinkGoBack


HlinkNavigate

HRESULT HlinkNavigate(
    IHlink * pihl,    //The target hyperlink
    IHlinkFrame * pihlframe,    //The hyperlink frame of the hyperlink container
    DWORD grfHLNF,    //Navigation flags
    LPBC pbc,    //Bind context object interface pointer
    IBindStatusCallback * pibsc,    //Bind status callback object interface pointer
    IHlinkBrowseContext * pihlbc    //Browse context object interface pointer
   );

Navigates to a hyperlink, given a hyperlink object and an optional hyperlink frame object.

pihl
[in] Address of the IHlink interface on the target hyperlink.
pihlframe
[in] Address of the IHlinkFrame interface of the hyperlink container. Can be NULL if the hyperlink container does not have a hyperlink frame.
grfHLNF
[in] Value taken from the HLNF enumeration.
pbc
[in] Address of the IBindCtx interface on the bind context to use for any moniker binding performed during the navigation. Must not be NULL.
pibsc
[in] Address of the IBindStatusCallback interface on the bind status context to use for any asynchronous moniker binding performed during the navigation. Can be NULL, in which case the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
pihlbc
[in] Address of the IHlinkBrowseContext interface pointer to use for this navigation. The browse context includes history information in which this navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).

HlinkNavigate encapsulates the following common sequence of calls:

if (phlFrame)
    phlFrame->Navigate(grfHLNF, pbc, pbsc, phl);
else if (phl)
    phl->Navigate(grfHLNF, pbc, pbsc, phlbc);

See also IHlinkBrowseContext, IHlink::Navigate, IHlinkFrame::Navigate, IHlinkTarget::Navigate


HlinkNavigateMoniker

HRESULT HlinkNavigateMoniker(
    IUnknown * pUnk,        //IUnknown pointer to the initiating document or object
    IMoniker * pmkTarget    //Moniker of the hyperlink target
   );

Executes a hyperlink jump to a new document or object (specified in pmkTarget).

  • Returns S_OK if a hyperlink jump to a new document or object has executed successfully.

    This function can also return any value returned by IHlink::Navigate.

pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application.
pmkTarget
[in] Address of the moniker that identifies the hyperlink target. If NULL, the navigation is within a document.

HlinkNavigateMoniker is implemented as a simple macro that calls the HlinkSimpleNavigateToMoniker function, passing it NULL for most parameters.

The HlinkNavigateMoniker helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateString, HlinkNavigateToStringReference, HlinkSimpleNavigateToMoniker, IHlink::Navigate


HlinkNavigateString

HRESULT HlinkNavigateString(
    IUnknown * pUnk,    //IUnknown pointer to the initiating document or object
    LPCWSTR szTarget    //Moniker of the hyperlink target
   );

Executes a hyperlink jump to a new document or object (specified in szTarget).

  • Returns S_OK if a hyperlink jump to a new document or object has executed successfully.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application.
szTarget
[in] String that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. If NULL, the navigation is within a document.

HlinkNavigateString is implemented as a simple macro that calls the HlinkSimpleNavigateToString function, passing it NULL for most parameters.

The HlinkNavigateString helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateMoniker, HlinkNavigateToStringReference, HlinkSimpleNavigateToString, IHlink::Navigate


HlinkNavigateToStringReference

HRESULT HlinkNavigateToStringReference(
    LPCWSTR pwzTarget,        //String helping to identify the hyperlink target
    LPCWSTR pwzLocation,      //Location within the hyperlink target of new hyperlink
    IHlinkSite * pihlsite,    //Site object interface for the new hyperlink object
    DWORD dwSiteData,         //Additional site data for the new hyperlink object
    IHlinkFrame * pihlframe,  //Frame object interface for the new hyperlink object
    DWORD grfHLNF,    //Navigation flags
    LPBC pibc,        //Bind context object
    IBindStatusCallback * pibsc,    //Bind status callback object
    IHlinkBrowseContext * pihlbc    //Browse context object
   );

Creates a hyperlink site from strings representing the hyperlink target, the location within the target, and a friendly name, and then navigates to that site.

  • Returns S_OK if a hyperlink site was created and navigated to.
pwzTarget
[in] Address of the string that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. Must not be NULL.
pwzLocation
[in] Address of the location within the hyperlink target of the new hyperlink object.
pihlsite
[in] Address of the IHlinkSite interface on the site object for the new hyperlink object. This is optional, in which case szTarget must be an absolute reference.
dwSiteData
[in] Additional site data for the new hyperlink object.
pihlframe
[in] Address of the IHlinkFrame interface for the hyperlink frame object of the hyperlink container object. Can be NULL if the hyperlink container does not have a hyperlink frame.
grfHLNF
[in] Value taken from the HLNF enumeration.
pibc
[in] Address of the IBindCtx interface on the bind context object to use for any moniker binding performed during the navigation. Must not be NULL.
pibsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback object to use for any asynchronous moniker binding performed during the navigation. Can be NULL, in which case the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
pihlbc
[in] IHlinkBrowseContext interface pointer to the browse context object to use for this navigation. The browse context includes history information in which this navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).

This helper function is identical to calling the following:

// create hyperlink site, IBindStatusCallback,
    // gather bind context, and browse context
HlinkCreateFromString(pwzTarget, pwzLocation,
    pwzFriendlyName, &hlSite, dwSiteData, NULL,
    IID_IHlink, (void**)&phl);
HlinkNavigate(pihl, pihlframe, grfHLNF, pbc, pibsc, pihlbc);
phl->Release();

See also HLNF, HlinkNavigate, HlinkCreateFromString, HlinkSimpleNavigateToString


HlinkOnNavigate

HRESULT HlinkOnNavigate(
    IHlinkFrame * pihlframe,    //Frame object interface for the new hyperlink
    IHlinkBrowseContext * pihlbc,    //Browse context object to use for this navigation
    DWORD grfHLNF,      //Navigation flags
    IMoniker * pimkTarget,      //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation,        //Location within the hyperlink target of new hyperlink
    LPCWSTR pwzFriendlyName,    //Friendly name of the hyperlink
    ULONG * puHLID      // Pointer to hyperlink identifier
   );

Notifies a hyperlink browse context and hyperlink frame, if it exists, that a hyperlink target has been navigated to.

  • Returns S_OK if the browse context and the frame, if it exists, have been notified of the hyperlink navigation.
pihlframe
[in] Address of the IHlinkFrame interface of the hyperlink container. Can be NULL if the hyperlink container does not have a hyperlink frame.
pihlbc
[in] Address of the IHlinkBrowseContext interface for the browse context object to use for this navigation. The browse context includes history information in which this navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).
grfHLNF
[in] Value taken from the HLNF enumeration.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in] Address of the location within the hyperlink target of the new hyperlink object.
pwzFriendlyName
[in] Address of the friendly name of the hyperlink.
puHLID
[out] Address of the hyperlink identifier to set in the current browse context's navigation stack.

HlinkOnNavigate is a helper function typically called during IHlinkTarget::Navigate, which encapsulates the following calls:

phlbc->OnNavigateHlink(grfHLNF, pimkTarget, pwzLocation, pwzFriendlyName);
if (phlFrame)
    phlFrame->OnNavigate(grfHLNF);

See also IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate, IHlinkSite::OnNavigationComplete


HlinkQueryCreateFromData

HRESULT HlinkQueryCreateFromData(
    IDataObject* piDataObj    //Data object to query
   );

Determines if a new hyperlink can be created from an IDataObject interface.

  • Returns S_OK if a hyperlink can be created from the data object, or S_FALSE if not.
piDataObj
[in] Address of the IDataObject interface supplying the hyperlink formats.

The application must call the HlinkQueryCreateFromData function to find out whether the hyperlink can be created from the data object obtained from the clipboard, from a drag-and-drop operation, or from any other means.

A hyperlink can be created if the IDataObject interface supports one of the following formats: cfHyperlink, cfUniformResourceLocator, CF_HDROP, or cfFileName.

See also HlinkCreateFromData


HlinkSetSpecialReference

HRESULT HlinkSetSpecialReference(
    ULONG uReference,       //Special reference flags
    LPCWSTR pwzReference    //The special reference string
   );

For a given value from the HLSR enumeration, sets the current user's default global home, search, or history page for browsing as a string.

uReference
[in] A value taken from the HLSR enumeration.
pwzReference
[in] Address of the special reference string.

See also HlinkGetSpecialReference, HLSR


HlinkSimpleNavigateToMoniker

HRESULT HlinkSimpleNavigateToMoniker(
    IMoniker * pmkTarget,    //Moniker of the hyperlink target
    LPCWSTR szLocation,      //Optional string representing location within target
    LPCWSTR szTargetFrameName,    //Optional string naming the target frame
    IUnknown * pUnk,         //IUnknown pointer to the initiating document or object
    IBindCtx * pbc,          //Bind context object
    IBindStatusCallback * pbsc,    //Bind status callback
    DWORD grfHLNF,           //Navigation flags
    DWORD dwReserved         //Reserved for future use
   );

Executes a hyperlink jump to a new document or object (specified in pmkTarget).

  • Returns S_OK if a hyperlink knowing the moniker of its target has navigated to it successfully.

    This function can also return any value returned by IHlink::Navigate.

pmkTarget
[in] Address of the moniker that identifies the hyperlink target. If NULL, the navigation is within a document.
szLocation
[in] Optional string representing the location within the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for the hyperlink navigation. This argument only affects navigation within a document container that understands frame sets.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application. Note that if the caller of this function is an ActiveX Control or Document Object, you must pass a valid value for this parameter in order for navigation to work correctly.
pbc
[in] Address of the IBindCtx interface on the bind context to use for any moniker binding performed during the navigation. Must not be NULL.
pbsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback to use for any asynchronous moniker binding performed during the navigation. The bind-status-callback will only return the standard IUnknown methods: AddRef and QueryInterface. When navigating in a new window, the only BindStatusCallback method that gets called is GetBindInfo. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
grfHLNF
[in] Value taken from the HLNF enumeration.
dwReserved
[in] Reserved for future use; must be set to NULL.

The HlinkSimpleNavigateToMoniker helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateToStringReference, HlinkSimpleNavigateToString, IHlink::Navigate


HlinkSimpleNavigateToString

HRESULT HlinkSimpleNavigateToString(
    LPCWSTR szTarget,    //String to be resolved into target's moniker
    LPCWSTR szLocation,    //Optional string representing location within target
    LPCWSTR szTargetFrameName,    //Optional string naming the target frame
    IUnknown * pUnk,     //IUnknown pointer to the initiating document or object
    IBindCtx * pbc,      //Bind context object
    IBindStatusCallback * pbsc,   //Bind status callback
    DWORD grfHLNF,       //Navigation flags
    DWORD dwReserved     //Reserved for future use
   );

Executes a hyperlink jump to a new document or object (specified in szTarget).

  • Returns S_OK if a hyperlink knowing the name of its target has navigated to it successfully.
szTarget
[in] String that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. If NULL, the navigation is within a document. This parameter is required.
szLocation
[in] Optional string representing the location within the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for the hyperlink navigation. This argument only affects navigation within a document container that understands frame sets.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application. Note that if the caller of this function is an ActiveX Control or Document Object, you must pass a valid value for this parameter in order for navigation to work correctly.
pbc
[in] Address of the IBindCtx interface on the bind context to use for any moniker binding performed during the navigation. Must not be NULL.
pbsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback to use for any asynchronous moniker binding performed during the navigation. The bind-status-callback will only return the standard IUnknown methods: AddRef and QueryInterface. When navigating in a new window, the only BindStatusCallback method that gets called is GetBindInfo. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
grfHLNF
[in] Value taken from the HLNF enumeration.
dwReserved
[in] Reserved for future use; must be set to NULL.

The HlinkSimpleNavigateToString helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateToStringReference, HlinkSimpleNavigateToMoniker, IHlink::Navigate


Enumerations

This section describes the following enumerations:

  • HLBWIF
  • HLFNAMEF
  • HLID
  • HLINKGETREF
  • HLINKMISC
  • HLINKSETF
  • HLINKWHICHMK
  • HLNF
  • HLQF
  • HLSR


HLBWIF

typedef enum tagHLBWIF
{
    HLBWIF_HASFRAMEWNDINFO,    =  1,
    HLBWIF_HASDOCWNDINFO,      =  2,
    HLBWIF_FRAMEWNDMAXIMIZED,  =  4,
    HLBWIF_DOCWNDMAXIMIZED,    =  8,
} HLBWIF;

Contains values relating to the locations and sizes of frame- and document-level windows within a browse context.

HLBWIF_HASFRAMEWNDINFO
This browse context has available frame-level window positioning information.
HLBWIF_HASDOCWNDINFO
This browse context has available document-level window positioning information.
HLBWIF_FRAMEWNDMAXIMIZED
Only useful in combination with HLBWIF_HASFRAMEWNDINFO. Indicates that frame-level windows of the browse context should appear maximized.
HLBWIF_DOCWNDMAXIMIZED
Only useful in combination with HLBWIF_HASDOCWNDINFO. Indicates that document-level windows of the browse context should appear maximized.

The HLBWINFO structure is retrieved from the browse context using IHlinkBrowseContext::GetBrowseWindowInfo, and put into the browse context using IHlinkBrowseContext::SetBrowseWindowInfo. Hyperlink targets retrieve the HLBWINFO structure during IHlinkTarget::Navigate in order to reposition their user interface properly and ensure as seamless a transition as possible to the new document or object.

See also HLBWINFO, IHlinkBrowseContext::GetBrowseWindowInfo, IHlinkBrowseContext::SetBrowseWindowInfo


HLFNAMEF

typedef enum tagHLFNAMEF
{
    HLFNAMEF_DEFAULT,          =  0,
    HLFNAMEF_TRYCACHE,         =  1,
    HLFNAMEF_TRYPRETTYTARGET,  =  2,
    HLFNAMEF_TRYFULLTARGET,    =  4,
    HLFNAMEF_TRYWIN95SHORTCUT  =  8,
} HLFNAMEF ;

Specifies which friendly name a client is requesting. The flags are used by the IHlink::GetFriendlyName interface.

HLFNAMEF_DEFAULT
The cached friendly name, or else the simplified display name.
HLFNAMEF_TRYCACHE
The friendly name that is cached in the hyperlink object.
HLFNAMEF_TRYPRETTYTARGET
A beautified version of the display name of the hyperlink target.
HLFNAMEF_TRYFULLTARGET
The full display name of the hyperlink target.
HLFNAMEF_TRYWIN95SHORTCUT
A simplified version of the full display name of the hyperlink target.

See also IHlink::GetFriendlyName


HLID

typedef enum tagHLID
{
    HLID_PREVIOUS,
    HLID_NEXT,
    HLID_CURRENT,
    HLID_STACKBOTTOM,
    HLID_STACKTOP
} HLID;

Identifies the logical positions of a hyperlink identifier in the hyperlink navigation stack. The constants are used in the IHlinkBrowseContext interface.

HLID_PREVIOUS
The hyperlink prior to the current one. If the current hyperlink is the first or only hyperlink in the navigation stack, or if there are no hyperlinks in the navigation stack, there is no previous hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.
HLID_NEXT
The hyperlink after the current one. If the current hyperlink is the last or only hyperlink in the navigation stack, or if there are no hyperlinks in the navigation stack, there is no next hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.
HLID_CURRENT
The current hyperlink. A browsing tool might offer a command to reload the current page, or to recenter the user interface around the beginning portion of the current hyperlink destination, or to restart animation, sound, or other activity by renavigating to the current hyperlink.
HLID_STACKBOTTOM
The very first hyperlink in the navigation stack. If there are no hyperlinks in the navigation stack, there is no stack-bottom hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.
HLID_STACKTOP
The very last hyperlink in the navigation stack. If there are no hyperlinks in the navigation stack, there is no stack-top hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.

For convenience and performance, individual hyperlink objects are often identified in a navigation stack like a browse context or a history/favorites list using a ULONG hyperlink identifier or HLID rather than an IHlink interface pointer. This prevents unnecessary passing of interface pointers across process boundaries in common user-interface scenarios, such as building a drop-down menu or scrollable list of the history, or when testing the current location in the navigation stack to enable Go Back and Go Forward.

See also HLQF, IHlinkBrowseContext::GetHlink, IHlinkBrowseContext::QueryHlink, IHlinkBrowseContext::SetCurrentHlink


HLINKGETREF

typedef enum tagHLINKGETREF
{
    HLINKGETREF_DEFAULT,   =  0,
    HLINKGETREF_ABSOLUTE,  =  1,
    HLINKGETREF_RELATIVE   =  2,
} HLINKGETREF ;

Specifies whether the client is requesting the absolute, relative, or default reference for the hyperlink target. The constants are used in the IHlink::GetMonikerReference and IHlink::GetStringReference methods.

HLINKGETREF_DEFAULT
Used to specify that the client of the hyperlink wants to retrieve the default reference for the hyperlink target. This depends on whether the hyperlink was initialized as a relative or an absolute reference.
HLINKGETREF_ABSOLUTE
Used to specify that the client of the hyperlink wants to retrieve the absolute reference for the hyperlink target.
HLINKGETREF_RELATIVE
Used to specify that the client of the hyperlink wants to retrieve the relative reference for the hyperlink target.

See also IHlink::GetMonikerReference, IHlink::GetStringReference


HLINKMISC

typedef enum tagHLINKMISC
{
    HLINKMISC_RELATIVE,  =  1,
} HLINKMISC ;

Specifies whether the hyperlink object is a relative hyperlink to its target. The constants are used in the IHlink::GetMiscStatus method.

HLINKMISC_RELATIVE
The given hyperlink object contains a relative reference to the hyperlink target.

See also IHlink::GetMiscStatus


HLINKSETF

typedef enum tagHLINKSETF
{
    HLINKSETF_TARGET,     1,
    HLINKSETF_LOCATION,   2,
} HLINKSETF ;

Specifies the operation of IHlink::SetMonikerReference. It allows a caller of this function to specify which Hlink parameter to set.

HLINKSETF_TARGET
Used to specify the setting of the pmkTarget parameter of the Hlink object.
HLINKSETF_LOCATION
Used to specify the setting of the szLocation parameter of the Hlink object.

See also IHlink::SetMonikerReference


HLINKWHICHMK

typedef enum tagHLINKWHICHMK
{
    HLINKWHICHMK_CONTAINER,  =  1,
    HLINKWHICHMK_BASE,       =  2,
} HLINKWHICHMK ;

Specifies whether a moniker being requested is the moniker for the container document or a base moniker specific to a hyperlink site. The constants are used in the IHlinkSite::GetMoniker method.

HLINKWHICHMK_CONTAINER
Used to specify that the hyperlink wants to retrieve the moniker for the hyperlink container corresponding to a particular hyperlink site.
HLINKWHICHMK_BASE
Used to specify that the hyperlink wants to request the base moniker corresponding to the particular hyperlink site. (These might be different, for example, if a BASE tag is used in HTML.)

See also IHlinkSite::GetMoniker


HLNF

typedef enum tagHLNF
{
    HLNF_INTERNALJUMP
    HLNF_OPENINNEWWINDOW
} HLNF;

Indicates how hyperlink navigation is to proceed. The enumeration is also used by the objects participating in the navigation protocol to convey to each other contextual information about the navigation.

HLNF_INTERNALJUMP
The navigation is an internal jump within the current hyperlink target.
HLNF_OPENINNEWWINDOW
An abbreviation for two commonly coincident options: HLNF_USEBROWSECONTEXTCLONE and HLNF_OFFSETWINDOWORG.

See also HlinkSimpleNavigateToMoniker, HlinkSimpleNavigateToString


HLQF

typedef enum tagHLQF
{
    HLQF_ISVALID,    =  1,
    HLQF_ISCURRENT,  =  2
} HLQF;

Specifies query flags used by IHlinkBrowseContext::QueryHlink to determine the state of a particular hyperlink.

HLQF_ISVALID
Used to test the validity of a particular hyperlink. The uHLID parameter can specify either a specific hyperlink within the navigation stack or a relative hyperlink, such as HLID_NEXT or HLID_PREVIOUS.
HLQF_ISCURRENT
Used to test if the specific hyperlink (identified by the uHLID parameter) is the user's current position within the navigation stack.

See also HLID, IHlinkBrowseContext::QueryHlink


HLSR

typedef enum tagHLSR
{
    HLSR_HOME,         =  0,
    HLSR_SEARCHPAGE,   =  1,
    HLSR_HISTORYFOLDER =  2,
} HLSR ;

Specifies which of the special hyperlink references to choose. The constants are used by the HlinkGetSpecialReference and HlinkSetSpecialReference functions.

HLSR_HOME
Used to specify the hyperlink reference to the global user "home" page.
HLSR_SEARCHPAGE
Used to specify the hyperlink reference to the global user "search page."
HLSR_HISTORYFOLDER
Used to specify the hyperlink reference to the global user "history folder" page.

See also HlinkGetSpecialReference, HlinkSetSpecialReference


Structures

This section describes the following structures:

  • HLBWINFO
  • HLITEM


HLBWINFO

typedef struct tagHLBWINFO
{
    ULONG cbSize;
    DWORD grfHLBWIF;
    RECT rcFramePos;
    RECT rcDocPos;
    HLTBINFO hltbinfo;
} HLBWINFO;

Contains parameters relating to the locations and sizes of frame- and document-level windows within a browse context.

cbSize
Total size of this structure, in bytes.
grfHLBWIF
Values taken from the HLBWIF enumeration.
rcFramePos
If grfHLBWIF & HLBWIF_HASFRAMEWNDINFO, contains the rectangle in screen coordinates of current frame-level windows within the browse context. When grfHLBWIF & HLBWIF_FRAMEWNDMAXIMIZED, frame-level windows are currently being displayed maximized. In this case, rcFramePos is the "normal" size of frame-level windows, that is, the rectangle to use for any frame-level window when it is nonmaximized.
rcDocPos
If grfHLBWIF & HLBWIF_HASDOCWNDINFO, contains the rectangle in screen coordinates of current document-level windows within the browse context. When grfHLBWIF & HLBWIF_DOCWNDMAXIMIZED, document-level windows are currently being displayed maximized. In this case, rcDocPos is the "normal" size of document-level windows, that is, the rectangle to use for any document-level window when it is nonmaximized.
hltbinfo
Provides information on the position of the Web toolbar. This enables the target application to display its toolbar in the same location.

The HLBWINFO structure is retrieved from the browse context using IHlinkBrowseContext::GetBrowseWindowInfo, and put into the browse context using IHlinkBrowseContext::SetBrowseWindowInfo. Hyperlink targets retrieve the HLBWINFO structure during IHlinkTarget::Navigate in order to reposition their user interface properly and ensure as seamless a transition as possible to the new document or object.

See also HLBWIF, IHlinkBrowseContext::GetBrowseWindowInfo, IHlinkBrowseContext::SetBrowseWindowInfo, IHlinkTarget::Navigate


HLITEM

typedef struct tagHLITEM
{
    ULONG uHLID;
    LPWSTR pwzFriendlyName;
} HLITEM;

Indicates the data structure used by the system browse context to track hyperlinks.

uHLID
Used to identify the hyperlink. Standard enumerators never return one of the logical HLID constants in this member, always an identifier.
pwzFriendlyName
Address of the hyperlink's friendly name. Appropriate for display in the user interface.

The HLITEM structure is returned by the IEnumHLITEM enumerator, which is returned from IHlinkBrowseContext::EnumNavigationStack.

See also HLID, IEnumHLITEM, IHlinkBrowseContext::EnumNavigationStack


Objects

This section describes the following object:

  • Hyperlink Object
  • Hyperlink Browse Context Object
  • Hyperlink Target Object


Hyperlink Object

A hyperlink object is a reference to another location within either a new or existing document. It encapsulates four pieces of reference information:

  • A moniker to the hyperlink target
  • A string for the sublocation within the target
  • A friendly name for the target
  • Additional parameters

A hyperlink object also supports the ability to save and load itself by using IPersistStream, and the ability to be transferred through the clipboard or through a drag-and-drop operation by using IDataObject.

It is notable that a document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the work of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks.

Implementation

A standard hyperlink implementation is provided with the operating system, and you should be able to use it for your applications. Custom implementations should be used only with the greatest caution.

Creation/Access API Functions
HlinkCreateFromData | Creates a hyperlink object from an object that supports the IDataObject interface (a data object).
HlinkCreateFromMoniker | Creates a new hyperlink from a moniker, a location within the target, and a friendly name string (used for displaying the hyperlink).
HlinkCreateFromString | Creates a new hyperlink object from strings representing the hyperlink target, the location within the target, and a friendly name.
OleLoadFromStream | Allows the hyperlink object to be loaded from persistent data.

Interfaces
IDataObject | Enables data transfer.
IHlink | Enables a hyperlink (a COM object) to encapsulate the behavior of navigating to its target location.
IHlinkSite | Indicates the implemented document/object that contains the hyperlink object. A hyperobject implementation uses this interface (if it's available) for resolving the relative monikers and also to notify before and after the target document/object is displayed.
IPersistStream | Provides methods for saving and loading objects that use a simple serial stream for their storage needs.


Hyperlink Browse Context Object

The hyperlink browse context maintains the navigation stack that is passed around during navigation from one document or application to another.

In addition to maintaining the navigation stack, the browse context knows whether the Go Forward and Go Back commands should be enabled. It is also used to pass around window-position information so that hyperlinking from one top-level window to another can happen while giving the illusion of window reuse (by positioning the windows on top of each other).

Implementation

Like the hyperlink object, the browse context is a standard object provided by the operating system.

Creation/Access API Functions
HlinkCreateBrowseContext Creates an empty default instance of the system browse context object.

Interfaces
IHlinkBrowseContext Enables a COM object to define and manage the browsing context for an OLE hyperlink application.


Hyperlink Target Object

A hyperlink target is a destination of hyperlink navigation. This can be a persisted OLE object that exposes IHlinkTarget, a persisted OLE object that exposes IOleObject, or any file that is viewed when its viewer application is launched by using ShellExecute.

A hyperlink target can be a top-level container document, an embedded object of arbitrary nesting, or generally any object that can be referenced by using a moniker.

Implementation

If an object (document) wants to be targeted by hyperlinks, it can integrate tightly with OLE hyperlinks by implementing the IHlinkTarget interface. If the object does not support IHlinkTarget, it can still act as a hyperlink target, but it won't be able to support internal navigation, and it will not have access to the common browse context that holds the navigation stack.

An existing OLE document application that supports OLE linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application can also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile. Supporting IHlinkTarget from an OLE document object is the recommended way to make sure your document is viewable by browsers and participates in hyperlinking smoothly.

Creation/Access API Functions

In a document, hyperlink objects implement the IHlink interface. When a user clicks a hyperlink, the application calls IHlink::Navigate, using a helper API function if preferred. The IHlink::Navigate implementation calls BindMoniker to get the pointer of the target object, requests the IHlinkTarget interface, and calls IHlinkTarget::Navigate.

Interfaces
IHlinkTarget | Provides for navigation to locations within the target's objects. A hyperlink target object implements this interface for this reason.
IOleObject | Allows an embedded object to communicate with and provide basic functionality to its container.


IE4/MSHTML Data Binding Interfaces

This section describes the IE4/MSHTML ability to bind data to an HTML page using a COM object or a Java applet. The following contain information on how to use these methods to do data binding.

COM Objects as Data Providers

OLE-DB Simple Provider: A Data Binding API for IE4/MSHTML

Java Applets as Data Providers

OLE-DB Simple Provider for Java: A Data Binding API for IE4/MSHTML


COM Objects as Data Providers

To date, IE4/MSHTML has used the typeinfo of a COM object to determine if it was a data provider. This was confusing, non-standard, and less than straightforward to implement with dual interface support.

This document specifies a new method for data providing COM objects to advertise that they are data providers. Additionally, it specifies a notification mechanism that can be used by data consumers to receive notifications when the underlying data set supplied by the object changes.

Recognizing COM Objects as Data Providers

Notifications for Data Set Changes

Recognizing COM Objects as Data Providers

Data-providing COM objects will identify themselves as data providers by implementing a method that, when called, returns an interface pointer to one of the IE4/MSHTML supported data interfaces. The signature for the method is as follows:

HRESULT msDataSourceObject(
    [in] BSTR qualifier,
    [out,retval] IUnknown **ppUnk);

The qualifier parameter will be used when a data-providing COM object supports access to more than one set of data. When the parameter is NULL or a null string (""), the COM object should return the data interface on its default data set. What constitutes the default data set is left to COM object.

IE4/MSHTML 1.0 will only support COM objects that supply a single data set. Therefore, IE4/MSHTML will only use the msDataSourceObject(0) form of the call when invoking the interface.

DISPID

This interface will be available at the reserved DispID -3900.

Notifications for Data Set Changes

There are instances where a consumer already has an interface to a data set supplied by the object, and the shape of the data set changes. For example, the number of columns changes, the name of the columns changes, the type of a column(s) changes, or the entire data set is reordered (result of a sort operation). In such an instance, there needs to be a way for the consumer to be notified of the change so it can retrieve a new interface on the (changed) data—using a call to msDataSourceObject. Consumers will do this by registering with the provider for a notification.

The object must support a method whereby the consumer can register for receiving such notifications. The method has the following signature:

HRESULT addDataSourceListener(
    [in] DataSourceListener *pEvent);

DataSourceListener is defined as follows:

[ local,
    object,
    version(1.0)
    uuid(7c0ffab2-cd84-11d0-949a-00a0c91110ed)
]

interface DataSourceListener : IUnknown
{
    HRESULT dataMemberChanged([in] BSTR qualifier);
    HRESULT dataMemberAdded([in] BSTR qualifier);
    HRESULT dataMemberRemoved([in] BSTR qualifier);
}

When a data change occurs, the object will call the dataMemberChanged method of DataSourceListener to notify the data consumer that the shape has changed. The object will pass the corresponding qualifier to the consumer. IE4/MSHTML 1.0 will only use the value NULL or "" for the qualifier. The dataMemberAdded and dataMemberRemoved methods are called to notify the consumer that a multiple-dataset-capable applet has a new data set available or has removed a previously existing data set. Since IE4/MSHTML 1.0 will not support multiple data sets, these events will be ignored.

Finally, a data consumer can notify a provider that it is no longer interested in data-shape-change notifications by calling addDataSourceListener(NULL). Note that this precludes multicasting event notifications but keeps requirements on controls simple.

IE4/MSHTML 1.0 will never examine the qualifier value in DataSourceListener::dataMemberChanged since providers with multiple datasets are not supported.

DISPID

This interface will be available at the reserved DispID -3901.


OLE-DB Simple Provider: A Data Binding API for IE4/MSHTML

IE4/MSHTML supports a very simple, easily implemented API for exposing data to HTML pages. The API supports access to string and variant data types and is built using array-like structures to expose rows and columns. Third parties can use the OLE-DB Simple Provider API to implement their custom data source objects.

Introduction

OLE-DB Simple Provider

OLE-DB Simple Provider Listener

Introduction

OLE-DB Simple Provider (OSP) is an interface specification that hosts can implement to expose their tabular data to HTML elements in IE4/MSHTML. OSP specifies only simple, minimal functionality that requires only minimal effort on the part of control/applet authors to expose their data. OSP specifies methods for adding, deleting, and setting the value of columns, searching through the set of data and receiving notifications on data events.

OLE-DB Simple Provider was formerly called Simple Tabular Data, or STD for short.

OLE-DB Simple Provider

OSP exposes a set of tabular data (data set) in an array-like structure. Elements of the data set are referenced by their row and column indexes.

Data references

Indexes begin with value 1 and increase. There are two special index values.
0 | Reserved for label information in the case of a row, and header information in the case of a column.
-1 | The wildcard value. Refers to an unknown value or all values. For example, Row=-1, Col=2 refers to the entire column 2.

OSP defines two distinct interfaces: OLEDBSimpleProvider and OLEDBSimpleProviderListener. As you would expect, OLEDBSimpleProvider implements the methods used for data access, and OLEDBSimpleProviderListener specifies the methods to be implemented by the host for receiving notification of data changes.

Interface ID

The OLEDBSimpleProvider interface is identified by the following IID:

{E0E270C0-C0BE-11d0-8FE4-00A0C90A6341}

The methods implemented by OLEDBSimpleProvider can be broken down into the following logical areas.

Schema functions

Three functions are provided for obtaining the schema for the underlying rows or columns.

HRESULT getRowCount([out, retval] LONG *pcRows)
Returns the number of rows in the data set.
HRESULT getColumnCount( [out,retval] LONG *pcColumns)
Returns the number of columns in the data set.
HRESULT getRWStatus([in] LONG iRow, [in] LONG iColumn, [out, retval] OSPRW *prwStatus)
Returns the read/write status for the specified row and column. If one or both of iRow and iColumn have a value of -1, the read/write status is returned for the entire column, row, or complete data set.

OSPRW is an enumeration with the following values:
OSPRW_READONLY | Cell, row, column, or data set is read-only.
OSPRW_READWRITE | Cell, row, column, or data set can be modified.
OSPRW_MIXED | Cell, row, column, or data set read-write status unknown or row, column, or data set mixed status.

Variant-oriented functions

Two functions are provided to allow retrieval and setting of variant values in the data set:

HRESULT getVariant([in] LONG iRow, [in] LONG iColumn, [in] OSPFORMAT fFormatted, [ out, retval] VARIANT *pVar)
Retrieves the value of the cell at the row and column indicated into the preallocated variant supplied in pVar. Based on the value specified in fFormatted, pVar will contain either a value with the type of the underlying column, a string that corresponds to the underlying type of the column, or an HTML fragment that corresponds to the underlying type of the column.
HRESULT setVariant([in] LONG iRow, [in] LONG iColumn, [in] OSPFORMAT fFormatted, [in, retval] VARIANT Var)
Sets the value of the cell at the row and column indicated to the value of the variant supplied in pVar in the type requested by the value of fFormatted.

OSPFORMAT is an enumeration with the following values:
OSPFORMAT_RAW | The underlying type of the column should be used to either set the value or get the value.
OSPFORMAT_FORMATTED | The underlying type of the column should be converted to a string and the string returned as a BSTR within the variant.
OSPFORMAT_HTML | The underlying type of the column should be converted to an HTML string.

Notes

  • For both functions, as per the definition of VARIANT, references are not supported.
  • For setVariant with any of the formatting options, it is the provider's responsibility to perform the appropriate coercion to the underlying type of the column. In cases where the coercion cannot be successfully completed, an appropriate error return code should be returned.
  • For setVariant with OSPFORMAT_FORMATTED, the provider is free to interpret the input string however it sees fit. Alternatively, the provider may attempt to parse the input string and heuristically determine an appropriate data type and value to place into the cell—for example, when updating formatted spreadsheet cells.
  • When OSPFORMAT_HTML is requested, the provider may, at its option, return a plain string (unadorned with HTML tags and so on).
  • A database NULL is indicated by returning a variant of type VT_NULL for any of the fFormatted types.
  • Wildcard values (-1) are not valid for the iRow and iColumn attributes in setVariant or getVariant.

Deletion and Insertion

Functions are provided to insert and delete rows. For all functions, the row numbers provide the position within the data set to which the row will be inserted. That is, the row inserted will have the index specified.
HRESULT deleteRows([in] LONG iRow, [in] LONG cRows, [out, retval] LONG *pcRowsDeleted)
Deletes cRows from the data set starting at row iRow. The number of rows successfully deleted is returned in pcRowsDeleted.
HRESULT insertRows([in] LONG iRow, [in] LONG cRows, [out, retval] LONG *pcRowsInserted)
Inserts cRows into the data set starting at row iRow. The number of rows successfully inserted is returned in pcRowsInserted.

Notes

  • In the case of an error, the provider may choose to insert/delete rows up to the point where the error occurred. In such a case, the [out] parameter specifies the number of rows actually inserted/deleted.
  • Values for the inserted rows are not specified. Use the setVariant function to set the value of the cells inserted.

Searching

A function is provided that supports some basic searching capability on the data set. The goal of this function is to be fairly easy for the provider to implement while providing the client with a meaningful set of functionality to perform complex searching.

HRESULT find([in] LONG iRowStart, [in] LONG iColumn, [in] VARIANT varSval, [in] OSPFIND findFlags, [in] OSPCOMP compType, [out, retval] LONG *piRowFound)
Searches for the values specified in varSval in column iColumn starting at row iRowStart. Upon successful completion, the row number with the matching value is returned in piRowFound.

Supported values for OSPFIND are:
OSPFIND_UP | Specifies scan should be decreasing in row number.
OSPFIND_CASESENSITIVE | Specifies that search should be case sensitive.

Supported values for OSPCOMP are:
OSPCOMP_LT | Specifies the first value less than varSval is being searched for.
OSPCOMP_LE | Specifies the first value less than or equal to varSval is being searched for.
OSPCOMP_GT | Specifies the first value greater than varSval is being searched for.
OSPCOMP_GE | Specifies the first value greater than or equal to varSval is being searched for.
OSPCOMP_EQ | Specifies the first value equal to varSval is being searched for.
OSPCOMP_NE | Specifies the first value not equal to varSval is being searched for.

Notes

  • Find does compares using the native type of the underlying column. Providers are encouraged to simply fail when the type of the varSval differs from the underlying type of the column.
  • Comparing string values always compares values as they would be returned from a call to GetVariant with OSPFORMAT_FORMATTED. Providers should not coerce values of varSval obtained from a previous call to GetVariant with OSPFORMAT_HTML.
  • If no corresponding match is found, Find should return the constant -1.

Asynchronous data population

The main function of an OSP is to provide data to an HTML page. In many cases, the data will need to be transported over high-latency, low bandwidth networks, in most cases using a 28.8K modem. The OSP design accounts for making data available as expediently as possible while maintaining an architecture and interface specification that is easy to author.

All OSP authors are encouraged to implement support for populating (or retrieving) the data they expose asynchronously. This allows the host to continue processing during data transmission instead of blocking on a call to the OSP until the entire data set has been transmitted to the client.

The majority of the work required to support asynchronous data delivery does not involve the OSP interface specifically; it is a requirement on the mechanisms to retrieve data from their underlying storages. Accordingly, three methods are required in the OSP interface: one to indicate whether the provider supports asynchronous population; one to return the progress of the asynchronous population; and a third to stop the asynchronous transmission of data.

Two additional events are added to the OSP event notifications. One event indicates when additional data has become available for access through the interface, while the other signals that the asynchronous data population has completed. Both events are specified below in the OLE-DB Simple Provider Events section.

HRESULT isAsync( [out, retval] BOOL *pbAsynch)
Returns a Boolean indicating whether data is being populated asynchronously.

Notes

IsAsynch should never block; it should always return the appropriate state.

HRESULT getEstimatedRows( [out, retval] LONG *piRows)
Returns the estimated total number of rows in the data set. Callers can use this in conjunction with GetRowCount with an asynchronous provider to obtain an estimate of the percentage of data received.

Notes

  • When the number of rows in the data set cannot be estimated, the provider should return the special value -1.
  • Synchronous providers should not block on the call to GetEstimatedRows. They should either return -1 to indicate that they cannot provide an estimate, or the actual row count (same as would be obtained through GetRowCount).
  • Providers should not return the final row count from EstimatedRows prior to firing the TransferComplete event (see below).
HRESULT stopTransfer()
Requests that the OSP discontinue asynchronous transfer of data.

Notes

  • Providers should make every effort to expose the data transferred prior to receiving this request. The provider must expose a valid, consistent OSP interface for such data—appropriate column/row count, read/write status, and so on.
  • Providers that cannot expose the data transferred prior to this request should discontinue the transfer of data and fail all subsequent calls to the OSP interface.

Internationalization

Implementers may have to consider cases where the consumer is running in a different locale from the source of the data. The provider is responsible for ensuring that data conversions are done in an appropriate fashion. In particular, be careful in cases where the string representation of many data types differs according to locale. For example, the float or double number 3.14 would be "3.14" in the US, and "3,14" in Germany. Date representations differ even more. For example, number (especially float, date) to string conversions done by GetVariant or SetVariant with the OSP_FORMATTED option specified should usually be done in the locale of the browser.

The Find method has more complicated issues to deal with to implement its ordered comparisons correctly across locale boundaries. These comparisons should, where possible, also be done in the locale of the browser, although this issue is not as clear cut. (For example, if the data consists of strings containing European accented characters, it is not clear that a browser in the en-us locale has any preferred sorting order for these strings. The sorting order of the provider locale might be more useful.)

It is anticipated that there will be cases where the consumer will need to know the locale of the data in order to perform proper operations on that data. A method is provided for the provider to return this information.

HRESULT getLocale([out,retval] BSTR *pbstrLocale)
Returns a string in pbstrLocale that indicates the locale of the data returned by GetLocale. This is used to perform the appropriate type conversions.

Notes

  • GetLocale should simply return the empty string ("") when the provider does not support localization. This will allow the consuming entity to use the default from the operating system.
  • For all values of pbstrLocale, the category LC_ALL is assumed by the consumer.

Sinking events

Methods are provided to attach and detach a unicast event handler for all events.

HRESULT addOLEDBSimpleProviderListener([in] OLEDBSimpleProviderListener *posplListener)
Registers the event handler interface specified by posplListener to receive notifications of changes to data.

Notes

  • If an event handler was specified previously, addOLEDBSimpleProviderListener releases the previous event handler prior to registering posplListener.
  • OSP events are unicast only. There can be only one listener.
HRESULT removeOLEDBSimpleProviderListener([in] OLEDBSimpleProviderListener *posplListener)
Unregisters the event handler interface specified by posplListener.

Notes

removeOLEDBSimpleProviderListener should always specify the posplListener previously registered. In the event that posplListener differs from the event handler registered, the call should fail.

OLE-DB Simple Provider Listener

OSP implementers fire notifications of changes to the underlying data through a single event handler. There are pre- and post-notifications for each event.

Interface ID

The OLEDBSimpleProviderListener interface can be identified by the following IID:

{E0E270C1-C0BE-11d0-8FE4-00A0C90A6341}

The event handler, registered through OLEDBSimpleProvider::addOLEDBSimpleProviderListener, should implement the following methods:

HRESULT aboutToChangeCell([in] LONG iRow, [in] LONG iColumn)
Indicates that the cell(s) indicated is about to change. This notification is fired when values are modified through SetVariant or internally by a provider. AboutToChangeCell should fire before any data values are changed.

Notes

  • Calls to GetVariant should return the original, unchanged value(s) prior to the return of control from firing the AboutToChangeCell event.
  • In AboutToChangeCell, the value -1 can be specified for iRow, iColumn, or both.
HRESULT cellChanged([in] LONG iRow, [in] LONG iColumn)
Indicates that the cell(s) indicated was changed. This notification is fired when values are modified through SetVariant or internally by a provider.

Notes

  • CellChanged should be fired after the data value(s) has changed. All subsequent calls to GetVariant should return the new value(s).
  • In CellChanged(), the value -1 can be specified for iRow, iColumn, or both.
HRESULT aboutToDeleteRows([in] LONG iRow, [in] LONG cRows)
Indicates that cRows beginning at row iRow are about to be deleted. This notification is fired just prior to the rows being deleted either from a call to DeleteRows or internally by the provider.

Notes

Access to cells in the deleted rows should remain valid until control is returned from the AboutToDeleteRows function.

HRESULT deletedRows([in] LONG iRow, [in] LONG cRows)
Indicates that cRows were deleted beginning at row iRow. This notification is fired when rows are deleted through DeleteRows or internally by a provider.

Notes

DeletedRows should be fired after the rows are deleted.

HRESULT aboutToInsertRows([in] LONG iRow, [in] LONG cRows)
Indicates that cRows beginning at row iRow are about to be inserted. This notification is fired just prior to the rows being inserted either from a call to InsertRows or internally by the provider.
HRESULT insertedRows([in] LONG iRow, [in] LONG cRows)
Indicates that cRows were inserted beginning at row iRow. This notification is fired when rows are inserted through InsertRows or internally by a provider.
HRESULT rowsAvailable([in] LONG iRow, [in] LONG cRows)
Indicates that cRows beginning at iRow are now available. This is useful for providers that obtain and expose their data asynchronously. The event notifies consumers that additional data is available.

Notes

OSP consumers expect periodic notifications when data is available since they will likely be displaying or processing the data as it arrives. Providers should weigh the advantages of code simplification by firing the event once for each row against the performance impact of doing so.

HRESULT transferComplete([in] OSPXFER doneReason)
All providers must fire this event to indicate that the data transfer is complete. The event should be fired after the entire data set exposed by the provider is available. doneReason indicates whether the population was completed successfully, or aborted, or stopped—the reason for why data population is complete.

Supported values for OSPXFER are:
OSPXFER_COMPLETE | Indicates that the data transmission is completed successfully.
OSPXFER_ABORT | Indicates that the data transmission is completed due to a call to the Stop method.
OSPXFER_ERROR | Indicates that the data transmission completed in an error state.

Notes

For providers that retrieve their data asynchronously, this event signifies that no additional RowsAvailable events will be called for this data set.

Notes for all events functions

The returned value is propagated back to the function that resulted in the notification. That is, if CellChanged returns E_BADVALUE, the SetVariant function will also return E_BADVALUE.


Java Applets as Data Providers

To date, IE4/MSHTML has supported ActiveX™ Controls as data providers when present on an HTML page and when the control supports either the OLE-DB Simple Provider interface or is an instance of the Advanced Data Connector (ADC), which provides OLE-DB interfaces. Note that ADC is the only OLE-DB interface supported in release 1.0 of IE4/MSHTML. As Java becomes more prevalent on the Internet, it will be desirable for IE4/MSHTML to support writing data sources in Java using JavaBeans.

The remainder of this article specifies the conventions to be used when constructing data-providing applets in Java. The internal IE4/MSHTML data binding agent implements support to detect and utilize such applets similar to the current support for ActiveX Controls.

Overview

Recognizing Java Applets as Data Providers

Notifications for Data Set Changes

Overview

Although IE4/MSHTML 1.0 will only support third-party providers that implement the OLE-DB Simple Provider interface, this specification is constructed to allow support for additional provider types when IE4/MSHTML adds support for those providers. All references to the OSP interfaces in this specification can be summarily changed to any of the additional provider interfaces supported by IE4/MSHTML.

Recognizing Java Applets as Data Providers

The applet writer needs a way to allow the IE4/MSHTML binding agent to detect the Java applet as a data provider. The most straightforward way to accomplish this is for the applet to implement a well-known method that the IE4/MSHTML binding agent will call to recognize the applet. The method will have the following signature:

public Object msDataSourceObject( String qualifier );

The qualifier parameter will be used when a data-providing applet supports access to more than one set of data. When the parameter is NULL or a null string (""), the applet should return the data interface on its default data set. What constitutes the default data set is left to the applet.

IE4/MSHTML 1.0 will only support applets that provide a single data set; therefore, it will use only the msDataSourceObject("") form of the call when invoking the interface.

Notifications for Data Set Changes

There are instances where a consumer already has an interface to a data set supplied by an applet, and the shape of the data set changes. For example, the number of columns changes, the name of the columns changes, the type of a column(s) changes, or the entire data set is reordered (result of a sort operation). In such an instance, there needs to be a way for the consumer to get notified of the change so it can retrieve a new interface on the (changed) data—using a call to msDataSourceObject. Consumers will do this by registering with the provider for a notification.

The applet must support a method whereby the consumer can register for receiving such notifications. The method has the following signature:

public void addDataSourceListener( DataSourceListener listener )
    throws java.util.TooManyListenersException;

IDataSourceListener is defined as follows:

public abstract interface DataSourceListener
{
   void dataMemberChanged( String qualifier );
   void dataMemberAdded( String qualifier );
   void dataMemberRemoved( String qualifier );
}

When a data change occurs, the applet will call the dataMemberChanged method on the DataSourceListener interface to notify the data consumer that the shape has changed. The qualifier will indicate which data interface has changed (for IE4/MSHTML 1.0, this will be ignored since data sources can only expose a single data set).

Finally, a data consumer must notify a provider that it is no longer interested in data-shape-change notifications by calling the following method:

public void removeDataSourceListener(
    DataSourceListener listener);

The DataSourceListener should be identical to the one passed to addDataSourceListener.


OLE-DB Simple Provider for Java: A Data Binding API for IE4/MSHTML

IE4/MSHTML supports a very simple, easily implemented API for exposing data to HTML pages. The API supports access to string and variant data types and is built using array-like structures to expose rows and columns. Third parties can use the OLE-DB Simple Provider API to implement their custom data source objects.

Introduction

OLE-DB Simple Provider

OLE-DB Simple Provider Listener

Interface Summary

Exceptions

Introduction

OLE-DB Simple Provider (OSP) is a JavaBeans interface specification that hosts can implement to expose their tabular data to HTML elements in IE4/MSHTML. OSP specifies only simple, minimal functionality that requires only minimal effort on the part of applet authors to expose their data. OSP specifies methods for adding, deleting, and setting the value of columns, searching through the set of data, and receiving notifications on data events.

OLE-DB Simple Provider

OSP exposes a set of tabular data (data set) in an array-like structure. Elements of the data set are referenced by their row and column indexes.

Data references

Indexes begin with value 1 and increase. There are two special index values:
0 | Reserved for label information in the case of a row, and header information in the case of a column.
-1 | The wildcard value. Refers to an unknown value or all values. For example, Row=-1, Col=2 refers to the entire column 2.

OSP defines two distinct interfaces: OLEDBSimpleProvider and OLEDBSimpleProviderListener. As you would expect, OLEDBSimpleProvider implements the methods used for data access, and OLEDBSimpleProviderListener specifies the methods to be implemented by the host for receiving notification of data changes.

Schema functions

Three functions are provided for obtaining the schema for the underlying rows or columns.

public int getRowCount( ) throws OSPException
Returns the number of rows in the data set.
public int getColumnCount( ) throws OSPException
Returns the number of columns in the data set.
public int getRWStatus(int iRow, int iColumn) throws OSPException
Returns the read/write status for the specified row and column. If one or both of iRow and iColumn have a value of -1, the read/write status is returned for the entire column, row, or complete data set.

OSPRW is an interface that defines the following return values.

public interface OSPRW
{
    public static final int OSPRW_DEFAULT = 1;
    public static final int OSPRW_READONLY = 0;
    public static final int OSPRW_READWRITE = 1;
    public static final int OSPRW_MIXED = 2;
}

The definitions for the values are:
OSPRW_READONLY | Cell, row, column, or data set is read-only.
OSPRW_READWRITE | Cell, row, column, or data set can be modified.
OSPRW_MIXED | Cell, row, column, or data set read-write status unknown or row, column or data set mixed status.

Variant-oriented functions

Two functions are provided to allow retrieval and setting of variant values in the data set.

public Object getVariant(int iRow, int iColumn, int fFormatted) throws OSPException
Returns the value of the cell at the row and column indicated. Based on the value specified in fFormatted, the returned value will contain either a value with the type of the underlying column, a string that corresponds to the underlying type of the column, or an HTML fragment that corresponds to the underlying type of the column.
public void setVariant(int iRow, int iColumn, int fFormatted, Object objVal) throws OSPException
Sets the value of the cell at the row and column indicated to the value of the Object supplied in objVal in the type requested by the value of fFormatted.

OSPFORMAT is an interface that defines the following values:

public interface OSPFORMAT
{
    public static final int OSPFORMAT_RAW = 0;
    public static final int OSPFORMAT_DEFAULT = 0;
    public static final int OSPFORMAT_FORMATTED = 1;
    public static final int OSPFORMAT_HTML = 2;
}

The definitions for the values are:
OSPFORMAT_RAW | The underlying type of the column should be used to either set the value or get the value.
OSPFORMAT_FORMATTED | The underlying type of the column should be converted to a string and the string returned as a BSTR within the variant.
OSPFORMAT_HTML | The underlying type of the column should be converted to an HTML string.

Notes

  • Valid Java class types for these interfaces are Integer, Long, Float, Double, String, Boolean, Date, and null.
  • Types other than those listed immediately above will be represented as String by calling the toString function on the class.
  • For setVariant with any of the formatting options, it is the provider's responsibility to perform the appropriate coercion to the underlying type of the column. In cases where the coercion cannot be successfully completed, an appropriate exception should be thrown.
  • For setVariant with OSPFORMAT_FORMATTED, the provider is free to interpret the input string however it sees fit. Alternatively, the provider may attempt to parse the input string and heuristically determine an appropriate data type and value to place into the cell—for example, when updating formatted spreadsheet cells.
  • When OSPFORMAT_HTML is requested, the provider can, at its option, return a plain string (unadorned with HTML tags and so on).
  • A database NULL is indicated by returning a null.
  • Wildcard values (-1) are not valid for the iRow and iColumn attributes in setVariant or getVariant. That is, only a single value can be returned/set from either call.

Deletion and insertion

Functions are provided to insert and delete rows. For all functions, the row numbers provide the position within the data set to which the row will be inserted. That is, the row inserted will have the index specified.

public int deleteRows(int iRow, int cRows) throws OSPException
Deletes cRows from the data set starting at row iRow. The number of rows successfully deleted is returned.
public int insertRows(int iRow, int cRows) throws OSPException
Inserts cRows into the data set starting at row iRow. The number of rows successfully inserted is returned.

Notes

  • In the case of an error, the provider can choose to insert/delete rows up to the point where the error occurred. In such a case, the return value specifies the number of rows actually inserted/deleted.
  • Values for the inserted rows are not specified. Use the setVariant function to set the value of the cells inside rows that were inserted.

Searching

A function is provided that supports some basic searching capability on the data set. The goal of this function is to be fairly easy for the provider to implement while providing the client with a meaningful set of functionality to perform complex searching.

public int find(int iRowStart, int iColumn, Object objVal, int findFlags, int compType) throws OSPException
Searches for the values specified in objVal in column iColumn starting at row iRowStart. Upon successful completion, the row number with the matching value is returned in piRowFound.

The OSPFIND interface defines the values for findFlags as follows:

public interface OSPFIND
{
    public static final int OSPFIND_DEFAULT = 0;
    public static final int OSPFIND_UP = 1;
    public static final int OSPFIND_CASESENSITIVE = 2;
}

The definitions for the values are:
OSPFIND_UP | Specifies scan should be decreasing in row number.
OSPFIND_CASESENSITIVE | Specifies that search should be case sensitive.

Similarly, the OSPCOMP interface defines the values for compType as follows:

public interface OSPCOMP
{
    public static final int OSPCOMP_EQ = 1;
    public static final int OSPCOMP_DEFAULT = 1;
    public static final int OSPCOMP_LT = 2;
    public static final int OSPCOMP_LE = 3;
    public static final int OSPCOMP_GE = 4;
    public static final int OSPCOMP_GT = 5;
    public static final int OSPCOMP_NE = 6;
}

The definitions for the values are:
OSPCOMP_LT | Specifies the first value less than objVal is being searched for.
OSPCOMP_LE | Specifies the first value less than or equal to objVal is being searched for.
OSPCOMP_GT | Specifies the first value greater than objVal is being searched for.
OSPCOMP_GE | Specifies the first value greater than or equal to objVal is being searched for.
OSPCOMP_EQ | Specifies the first value equal to objVal is being searched for.
OSPCOMP_NE | Specifies the first value not equal to objVal is being searched for.

Notes

  • Find does compares using the native type of the underlying column. Providers are encouraged to simply fail when the type of the objVal differs from the underlying type of the column.
  • Find supports the same object types for objVal as setVariant and getVariant.
  • Comparing string values always compares values as they would be returned from a call to getVariant with OSPFORMAT_FORMATTED. Providers should not coerce values of objVal obtained from a previous call to getVariant with OSPFORMAT_HTML.
  • If no corresponding match is found, Find should return the constant -1.

Asynchronous data population

The main function of an OSP is to provide data to an HTML page. In many cases, the data will need to be transported over high-latency, low bandwidth networks, in most cases using a 28.8K modem. The OSP design accounts for making data available as expediently as possible while maintaining an architecture and interface specification that is easy to author.

All OSP authors are encouraged to implement support for populating (or retrieving) the data they expose asynchronously. This allows the host to continue processing during data transmission instead of blocking on a call to the OSP until the entire data set has been transmitted to the client.

The majority of the work required to support asynchronous data delivery does not involve the OSP interface specifically—it is a requirement on the mechanisms to retrieve data from their underlying storages. Accordingly, three methods are required in the OSP interface: one to indicate whether the provider supports asynchronous population; one to return the progress of the asynchronous population; and a third to stop the asynchronous transmission of data.

Two additional events are added to the OSP event notifications. One event indicates when additional data has become available for access through the interface, while the other signals that the asynchronous data population has completed. Both events are specified below in the OLE-DB Simple Provider Listener section.

public boolean isAsync( ) throws OSPException
Returns a Boolean indicating whether data is being populated asynchronously.

Notes

isAsynch should never block; it should always return the appropriate state.

public int getEstimatedRows( ) throws OSPException
Returns the estimated total number of rows in the data set. Callers can use this in conjunction with getRowCount with an asynchronous provider to obtain an estimate of the percentage of data received.

Notes

  • When the number of rows in the data set cannot be estimated, the provider should return the special value -1.
  • Synchronous providers should not block on the call to getEstimatedRows. They should either return -1 to indicate that they cannot provide an estimate, or the actual row count (same as would be obtained through getRowCount).
  • Providers should not return the final row count from EstimatedRows prior to firing the transferComplete event (see below).
public void stopTransfer( ) throws OSPException
Requests that the OSP discontinue asynchronous transfer of data.

Notes

  • Providers should make every effort to expose the data transferred prior to receiving this request. The provider must expose a valid, consistent OSP interface for such data—appropriate column/row count, read/write status, and so on.
  • Providers that cannot expose the data transferred prior to this request should discontinue the transfer of data and fail all subsequent calls to the OSP interface.

Internationalization

Implementers might have to consider cases where the consumer is running in a different locale from the source of the data. The provider is responsible for ensuring that data conversions are done in an appropriate fashion. In particular, be careful in cases where the string representation of many data types differs according to locale. For example, the float or double number 3.14 would be "3.14" in the US, and "3,14" in Germany. Date representations differ even more. For example, number (especially float, date) to string conversions done by GetVariant or SetVariant with the OSP_FORMATTED option specified should usually be done in the locale of the browser.

The Find method has more complicated issues to deal with to implement its ordered comparisons correctly across locale boundaries. These comparisons should, where possible, also be done in the locale of the browser, although this issue is not as clear cut. (For example, if the data consists of strings containing European accented characters, it is not clear that a browser in the en-us locale has any preferred sorting order for these strings. The sorting order of the provider locale might be more useful.)

It is anticipated that there will be cases where the consumer will need to know the locale of the data in order to perform proper operations on that data. A method is provided for the provider to return this information.

public String getLocale( ) throws OSPException
Returns a string that indicates the locale of the data. This is used to perform the appropriate type conversions.

Notes

  • getLocale should simply return the empty string ("") when the provider does not support localization. This will allow the consuming entity to use the default from the operating system.
  • For all return values the category LC_ALL is assumed by the consumer.

Sinking events

Methods are provided to attach and detach a unicast event handler for all events.

public void addOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL) throws OSPException
Registers the event handler interface specified by objOSPL to receive notifications of changes to data.

Notes

  • If an event handler was specified previously, addOLEDBSimpleProviderListener replaces the previous event handler.
  • OSP events are unicast only. There can be only one listener.
public void removeOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL) throws OSPException
Unregisters the event handler interface specified by objOSPL.

Notes

removeOLEDBSimpleProviderListener should always specify the objOSPL previously registered. In the event that objOSPL differs from the event handler registered, the call should fail.

OLE-DB Simple Provider Listener

OSP implementers fire notifications of changes to the underlying data through a single event handler. There are pre- and post-notifications for each event.

The event handler, registered through addOLEDBSimpleProviderListener, should implement the following methods.

public void aboutToChangeCell(int iRow, int iColumn) throws Exception
Indicates that the cell(s) indicated is about to change. This notification is fired when values are modified through setVariant or internally by a provider. aboutToChangeCell should fire before any data values are changed.

Notes

  • Calls to getVariant should return the original, unchanged value(s) prior to the return of control from firing the aboutToChangeCell event.
  • In aboutToChangeCell, the value -1 can be specified for iRow, iColumn, or both.
public void cellChanged(int iRow, int iColumn) throws Exception
Indicates that the cell(s) indicated was changed. This notification is fired when values are modified through setVariant or internally by a provider.

Notes

  • cellChanged should be fired after the data value(s) has changed. All subsequent calls to getVariant should return the new value(s).
  • In cellChanged, the value -1 can be specified for iRow, iColumn, or both.
public void aboutToDeleteRows(int iRow, int cRows) throws Exception
Indicates that cRows beginning at row iRow are about to be deleted. This notification is fired just prior to the rows being deleted either from a call to deleteRows or internally by the provider.

Notes

Access to cells in the deleted rows should remain valid until control is returned from the aboutToDeleteRows function.

public void deletedRows(int iRow, int cRows) throws Exception
Indicates that cRows were deleted beginning at row iRow. This notification is fired when rows are deleted through deleteRows or internally by a provider.

Notes

deletedRows should be fired after the rows are deleted.

public void aboutToInsertRows(int iRow, int cRows) throws Exception
Indicates that cRows beginning at row iRow are about to be inserted. This notification is fired just prior to the rows being inserted either from a call to insertRows or internally by the provider.
public void insertedRows(int iRow, int cRows) throws Exception
Indicates that cRows were inserted beginning at row iRow. This notification is fired when rows are inserted through insertRows or internally by a provider.
public void rowsAvailable(int iRow, int cRows) throws Exception
Indicates that cRows beginning at iRow are now available. This is useful for providers that obtain and expose their data asynchronously. The event notifies consumers that additional data is available.

Notes

OSP consumers expect periodic notifications when data is available since they will likely be displaying or processing the data as it arrives. Providers should weigh the advantages of code simplification by firing the event once for each row against the performance impact of doing so.

public void transferComplete(int doneReason) throws Exception
All providers must fire this event to indicate that the data transfer is complete. The event should be fired after the entire data set exposed by the provider is available. doneReason indicates whether the population was completed successfully, aborted, or was stopped—the reason for why data population is complete.

The OSPXFER interface defines values for doneReason as follows:

public interface OSPXFER
{
    public static final int OSPXFER_COMPLETE = 0;
    public static final int OSPXFER_ABORT = 1;
    public static final int OSPXFER_ERROR = 2;
}

The definitions for the values are:
OSPXFER_COMPLETE | Indicates that data transmission is completed successfully.
OSPXFER_ABORT | Indicates that the data transmission is completed due to a call to the Stop method.
OSPXFER_ERROR | Indicates that the data transmission completed in an error state.

Notes

For providers that retrieve their data asynchronously, this event signifies that no additional rowsAvailable events will be called for this data set.

Notes for all events functions

If your provider does not require any additional processing, it is not necessary to catch exceptions from the event routines. The unhandled exceptions will return up through to the setVariant, or [insert|delete]Rows call from which it initiated. The the exception should be handled there.

Interface Summary

All interfaces are part of the com.ms.osp package. The interfaces are as follows:

public interface OLEDBSimpleProvider
{
    public int getRowCount( ) throws OSPException;
    public int getColumnCount( ) throws OSPException;
    public int getRWStatus(int iRow, int iColumn) throws OSPException;
    public Object getVariant(int iRow, int iColumn, int fFormatted) throws OSPException;
    public void setVariant(int iRow, int iColumn, int fFormatted, Object obj) throws OSPException;
    public int deleteRows(int iRow, int cRows) throws OSPException;
    public int insertRows(int iRow, int cRows) throws OSPException;
    public int find(int iRowStart, int iColumn, Object objVal, int findFlags, int compType)
        throws OSPException;
    public boolean isAsync( ) throws OSPException;
    public int getEstimatedRows( ) throws OSPException;
    public void stopTransfer( ) throws OSPException;
    public String getLocale( ) throws OSPException;
    public void addOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL)
        throws OSPException,
                                                                                java.util.TooManyListenersException;
    public void removeOLEDBSimpleProviderListener(OLEDBSimpleProviderListener objOSPL)
        throws OSPException;
}

abstract interface OLEDBSimpleProviderListener
{
    public void aboutToChangeCell(int iRow, int iColumn) throws Exception;
    public void cellChanged(int iRow, int iColumn) throws Exception;
    public void aboutToDeleteRows(int iRow, int cRows) throws Exception;
    public void deletedRows(int iRow, int cRows) throws Exception;
    public void aboutToInsertRows(int iRow, int cRows) throws Exception;
    public void insertedRows(int iRow, int cRows) throws Exception;
    public void rowsAvailable(int iRow, int cRows) throws Exception;
    public void transferComplete(int doneReason) throws Exception;
}

public interface OSPRW
{
    public static final int OSPRW_DEFAULT = 1;
    public static final int OSPRW_READONLY = 0;
    public static final int OSPRW_READWRITE = 1;
    public static final int OSPRW_MIXED = 2;
}

public interface OSPFORMAT
{
    public static final int OSPFORMAT_RAW = 0;
    public static final int OSPFORMAT_DEFAULT = 0;
    public static final int OSPFORMAT_FORMATTED = 1;
    public static final int OSPFORMAT_HTML = 2;
}

public interface OSPFIND
{
    public static final int OSPFIND_DEFAULT = 0;
    public static final int OSPFIND_UP = 1;
    public static final int OSPFIND_CASESENSITIVE = 2;
}

public interface OSPCOMP
{
    public static final int OSPCOMP_EQ = 1;
    public static final int OSPCOMP_DEFAULT = 1;
    public static final int OSPCOMP_LT = 2;
    public static final int OSPCOMP_LE = 3;
    public static final int OSPCOMP_GE = 4;
    public static final int OSPCOMP_GT = 5;
    public static final int OSPCOMP_NE = 6;
}

public interface OSPXFER
{
    public static final int OSPXFER_COMPLETE = 0;
    public static final int OSPXFER_ABORT = 1;
    public static final int OSPXFER_ERROR = 2;
}

Exceptions

OSP supports a number of exceptions. They are defined as follows:

  • AccessDeniedException: An inability to read/write the data has occurred.
  • ConversionException: An error occurred attempting to coerce data types.
  • IllegalArgumentException: A method was passed an invalid or inappropriate argument or was invoked on an inappropriate object.
  • NotImplementedException: The functionality of a called method is not implemented.
  • OSPException: A failure has occurred calling an OSP method. This is used in all cases not covered by the previous exceptions.


Information Delivery API

This section describes the Microsoft® Information Delivery API, which allows you to create subscriptions and add channels that can be used to deliver content to a user's computer.

Microsoft Information Delivery API Overview

Microsoft Information Delivery API Reference


Microsoft Information Delivery API Overview

The Microsoft® Information Delivery API allows you to create subscriptions and add channels that can be used to deliver content to a user's computer. This section is an overview of the services provided by the Information Delivery API.

The Microsoft Information Delivery API Overview no longer includes information on the notification manager and the interfaces and methods related to it. The implementation of the underlying architecture for the Information Delivery API will be changed after Microsoft Internet Explorer 4.0 is released, so the sections that will be affected (such as the notification manager) have been removed for this release.

Introduction

About the Channel Manager

About the Subscription Manager

Checking Updates

Refreshing the Channel Pane

Introduction

The Microsoft® Information Delivery API provides a channel manager and subscription manager to manage channels and subscriptions.

The channel manager is used to add and delete Active Channels and channel categories from the channel pane. The channel manager can also retrieve an enumerator that can be used to enumerate all of the current Active Channels. The channel manager does not create a subscription to an Active Channel. To create a subscription to an Active Channel, the client application must access the subscription manager.

The subscription manager provides the ability to create and delete subscriptions to Web sites and Active Channels. The subscription manager also provides the ability to start an update for a specified subscription or all subscriptions.

To use the channel manager, the Chanmgr.h header file must be included. Also, the Subsmgr.h header file must be included for any C/C++ programs that utilize the subscription manager.

This documentation assumes that the reader has an understanding of OLE/COM programming and a basic understanding of Active Desktop and other features of Microsoft Internet Explorer 4.0. For more information, see Introducing Internet Explorer 4.0 in the Internet Client SDK.

About the Channel Manager

The channel manager allows a client application to add and delete categories and Active Channels in the desktop channel bar. The channel manager can also provide an enumerator that will allow a client application to enumerate all of the Active Channels. The channel manager does not create a subscription to the Active channel. To subscribe to an Active Channel, the subscription manager must be used.

About the Subscription Manager

The subscription manager gives a client application the ability to create, update, and delete subscriptions to Web sites and channels. The subscription manager also provides the ability to get information about a subscription type and information on a specific subscription.

Checking Updates

Currently, the Information Delivery API does not provide a programatic way of checking the last time a file has been updated. If the file is stored in the Internet cache or in a cache container, the Win32 Interenet function, GetUrlCacheEntryInfoEx, can be used to retrieve information on the cache entry. This information includes:

  • Last modified time
  • Expire time
  • Last access time
  • Last synchronization time
  • Returned headers
  • Hit rate
  • File size
  • Local file name
  • User count

For more information on the retrieving cache entry information, see Retrieving cache entry information in the Microsoft Win32 Internet Function Overview. The article demonstrates the use of the GetUrlCacheEntryInfo function, which is almost identical to GetUrlCacheEntryInfoEx, except GetUrlCacheEntryInfo does not translate through the offline redirects.

Refreshing the Channel Pane

The Information Delivery API does not provide any programatic way to refresh the channel pane. To refresh the channel pane, the client application needs to use the SHChangeNotify function with the full path of the channel shortcut.

The following sample demonstrates a call to SHChangeNotify to refresh the channel pane to show changes to the Awesome Computers channel.

SHChangeNotify(SHCNE_UPDATEDIR, SHCNF_PATH,
                                    (void*)"c:\windows\favorites\channels\awesome_computer", NULL);


Microsoft Information Delivery API Reference

This reference describes the objects, interfaces, agents, methods, structures, types, flags, and properties included in the Information Delivery API.

The Microsoft Information Delivery API Reference no longer includes information on the notification manager and the interfaces and methods related to it. The implementation of the underlying architecture for the Information Delivery API will be changed after Microsoft Internet Explorer 4.0 is released, so the sections that will be affected (such as the notification manager) have been removed for this release.

Objects

Interfaces

Methods

Structures

Enumerated Types

Return Values


Objects Objects *
  * Previous Topic: Microsoft Information Delivery API Reference
  * Next Topic: Channel Manager Object

Objects

This section describes the objects included in the Information Delivery API.


Channel Manager Object Channel Manager Object *
  * Previous Topic: Objects
  * Next Topic: Subscription Manager Object

Channel Manager Object

CLSID_ChannelMgr

Manages channels.

Interface
IChannelMgr


Subscription Manager Object Subscription Manager Object *
  * Previous Topic: Channel Manager Object
  * Next Topic: Interfaces

Subscription Manager Object

CLSID_SubscriptionMgr

Handles subscriptions.

Interface
ISubscriptionMgr


Interfaces Interfaces *
  * Previous Topic: Subscription Manager Object
  * Next Topic: IChannelMgr

Interfaces

This section describes the interfaces included in the Information Delivery API.


IChannelMgr

Provides the ability to add and delete Active Channels and channel categories in the desktop channel bar.

Methods
AddCategory
Adds a channel category to the desktop channel bar.
AddChannelShortcut
Installs an Active Channel into the desktop channel bar.
DeleteCategory
Deletes a channel category from the desktop channel bar.
DeleteChannelShortcut
Deletes an existing Active Channel.
EnumChannels
Creates a channel enumerator.


IEnumChannels

Enumerates channels.

Methods
Clone
Creates another enumeration that contains the same enumeration state as the current enumeration.
Next
Retrieves a specified number of items in the enumeration sequence.
Reset
Resets the enumeration sequence.
Skip
Skips over a specified number of items in the enumeration sequence.


ISubscriptionMgr

Allows a client program to control the subscription manager.

Methods
CreateSubscription
Creates a subscription.
DeleteSubscription
Deletes a subscription.
GetDefaultInfo
Retrieves the default information associated with a subscription type.
GetSubscriptionInfo
Retrieves the information associated with a specific subscription.
IsSubscribed
Checks if the user is subscribed to a particular site.
ShowSubscriptionProperties
Displays the subscription properties.
UpdateAll
Updates all the subscriptions.
UpdateSubscription
Updates the specified subscription.


Methods

This section describes the methods in the Information Delivery API.

IChannelMgr::AddCategory
IChannelMgr::AddChannelShortcut
IChannelMgr::DeleteCategory
IChannelMgr::DeleteChannelShortcut
IChannelMgr::EnumChannels
IEnumChannels::Clone
IEnumChannels::Next
IEnumChannels::Reset
IEnumChannels::Skip
ISubscriptionMgr::CreateSubscription
ISubscriptionMgr::DeleteSubscription
ISubscriptionMgr::GetDefaultInfo
ISubscriptionMgr::GetSubscriptionInfo
ISubscriptionMgr::IsSubscribed
ISubscriptionMgr::ShowSubscriptionProperties
ISubscriptionMgr::UpdateAll
ISubscriptionMgr::UpdateSubscription


IChannelMgr::AddCategory

HRESULT AddCategory(
    [in] CHANNELCATEGORYINFO *pCategoryInfo
);

Adds a channel category to the desktop channel bar.

  • Returns E_INVALIDARG if any of the required fields in the CHANNELCATEGORYINFO structure are not provided.
pCategoryInfo
Address of the CHANNELCATEGORYINFO structure associated with the category to be added to the desktop channel bar.


IChannelMgr::AddChannelShortcut

HRESULT AddChannelShortcut(
    [in] CHANNELSHORTCUTINFO *pChannelInfo
);

Adds an Active Channel to the desktop channel bar.

  • Returns E_INVALIDARG if any of the required fields in the CHANNELSHORTCUTINFO structure are not provided.
pChannelInfo
Address of a CHANNELSHORTCUTINFO structure that contains the information associated with the Active Channel to be added.

This method only adds an entry into the desktop channel bar. To subscribe to the Active Channel, the client application must use the subscription manager.


IChannelMgr::DeleteCategory

HRESULT DeleteCategory(
    [in] LPWSTR pszTitle
);

Deletes a channel category from the desktop channel bar.

  • Returns S_FALSE if the specified channel category does not exist.
pszTitle
String value that contains the title of the channel category to be deleted from the desktop channel bar.


IChannelMgr::DeleteChannelShortcut

HRESULT DeleteChannelShortcut(
    [in] LPWSTR pszTitle
);

Deletes an Active Channel from the desktop channel bar.

  • Returns S_FALSE if the specified Active Channel does not exist.
pszTitle
String value that contains the title of the Active Channel to be deleted from the desktop channel bar.

This method does not delete the subscription, if one was created, for this Active Channel. The ISubscriptionMgr::DeleteSubscription method must be used to remove the subscription.


IChannelMgr::EnumChannels

HRESULT EnumChannels(
    [in] DWORD dwEnumFlags,
    [in] LPCWSTR pszURL,
    [out] IEnumChannels **pIEnumChannels
);

Creates a channel enumerator.

dwEnumFlags
Unsigned integer value that contains the flags that control the enumeration. Can be one of the CHANNELENUMFLAGS values or one of the following aggregate values:
CHANENUM_ALL | Aggregate of all the CHANNELENUMFLAGS values.
CHANENUM_ALLDATA | Aggregate of the CHANENUM_TITLE, CHANENUM_PATH, CHANENUM_URL, and the CHANENUM_SUBSCRIBESTATE values.
CHANENUM_ALLFOLDERS | Aggregate of the CHANENUM_CHANNELFOLDER, CHANENUM_SOFTUPDATEFOLDER, and CHANENUM_DESKTOPFOLDER values.
pszURL
Optional. String value that contains the URL of the CDF file.
pIEnumChannels
Address of the pointer to the IEnumChannels interface of the enumerator.


IEnumChannels::Clone

HRESULT Clone(
    [in] IEnumChannels **ppenum
);

Creates another enumerator that contains the same enumeration state as the current enumeration.

ppenum
Address of a pointer to the IEnumChannels interface of the clone.


IEnumChannels::Next

HRESULT Next(
    [in] ULONG celt,
    [out] CHANNELENUMINFO *rgChanInf,
    [out] ULONG *pceltFetched
);

Retrieves a specified number of items in the enumeration sequence.

celt
Unsigned long integer value that contains the number of CHANNELENUMINFO structures being requested.
rgChanInf
Address of a buffer containing the CHANNELENUMINFO structures.
pceltFetched
Unsigned long integer value that indicates the actual number of structures received.


IEnumChannels::Reset IEnumChannels::Reset *
  * Previous Topic: IEnumChannels::Next
  * Next Topic: IEnumChannels::Skip

IEnumChannels::Reset

HRESULT Reset();

Resets the enumeration sequence.


IEnumChannels::Skip

HRESULT Skip(
    [in] ULONG celt;
);

Skips over a specified number of items in the enumeration sequence.

celt
Unsigned long integer value containing the number of CHANNELENUMINFO structures to skip.


ISubscriptionMgr::CreateSubscription

HRESULT CreateSubscription(
    [in] HWND hwnd;
    [in] LPCWSTR pwszURL,
    [in] LPCWSTR pwszFriendlyName,
    [in] DWORD dwFlags,
    [in] SUBSCRIPTIONTYPE subsType,
    [in,out] SUBSCRIPTIONINFO *pInfo
);

Creates a subscription.

hwnd
Handle to the parent window.
pwszURL
String value that contains the URL of the site to subscribe to.
pwszFriendlyName
String value that contains a friendly name for the site.
dwFlags
Unsigned long integer value that contains the flags that control the creation of the subscription. Can be a combination of the CREATESUBSCRIPTIONFLAGS values.
subType
SUBSCRIPTIONTYPE value that determines how the subscription will be handled.
pInfo
Address of a SUBSCRIPTIONINFO structure containing the subscription information.


ISubscriptionMgr::DeleteSubscription

HRESULT DeleteSubscription(
    [in] LPCWSTR pwszURL,
    [in] HWND hwnd
);

Deletes a subscription.

pwszURL
String value containing the URL of the subscription to delete.
hwnd
Handle of the parent window.


ISubscriptionMgr::GetDefaultInfo

HRESULT GetDefaultInfo(
    [in] SUBSCRIPTIONTYPE subType,
    [out] SUBSCRIPTIONINFO *pInfo
);

Retrieves the default information associated with a subscription type.

subType
SUBSCRIPTIONTYPE value that contains the subscription type.
pInfo
Address of a SUBSCRIPTIONINFO structure containing the default information for the specified subscription type.


ISubscriptionMgr::GetSubscriptionInfo

HRESULT GetSubscriptionInfo(
    [in] LPCWSTR pwszURL,
    [out] SUBSCRIPTIONINFO *pInfo
);

Retrieves the information associated with a specific subscription.

pwszURL
String value that contains the URL associated with the subscription.
pInfo
Address of the SUBSCRIPTIONINFO structure containing the information about the specified subscription.


ISubscriptionMgr::IsSubscribed

HRESULT IsSubscribed(
    [in] LPCWSTR pwszURL,
    [out] BOOL *pfSubscribed
);

Checks if the user is subscribed to a particular site.

pwszURL
String value containing the URL to look for.
pfSubscribed
Address of a Boolean value that will be TRUE if a subscription exists, or FALSE otherwise.


ISubscriptionMgr::ShowSubscriptionProperties

HRESULT ShowSubscriptionProperties(
    [in] LPCWSTR pwszURL,
    [in] HWND hwnd
);

Displays the subscription properties.

pwszURL
String value containing the URL of the subscription.
hwnd
Handle to the parent window.


ISubscriptionMgr::UpdateAll ISubscriptionMgr::UpdateAll *
  * Previous Topic: ISubscriptionMgr::ShowSubscriptionProperties
  * Next Topic: ISubscriptionMgr::UpdateSubscription

ISubscriptionMgr::UpdateAll

HRESULT UpdateAll()

Updates all subscriptions immediately.


ISubscriptionMgr::UpdateSubscription

HRESULT UpdateSubscription(
    [in] LPCWSTR pwszURL
);

Updates the specified subscription immediately.

pwszURL
String containing the URL of the subscription to update.


Structures Structures *
  * Previous Topic: ISubscriptionMgr::UpdateSubscription
  * Next Topic: CHANNELCATEGORYINFO

Structures

This section describes the structures used with the Information Delivery API.


CHANNELCATEGORYINFO

typedef _tagChannelCategoryInfo {
    DWORD cbSize;
    LPWSTR pszTitle;
    LPWSTR pszURL;
    LPWSTR pszLogo;
    LPWSTR pszIcon;
    LPWSTR pszWideLogo;
} CHANNELSHORTCUTINFO;

Contains the information associated with a category on the channel bar.

cbSize
Required. Double word value that contains the size of the structure. This value must be specified.
pszTitle
Required. String value that contains the title of the category.
pszURL
Optional. String value that contains the URL to an HTML page for the category.
pszLogo
Optional. String value that contains the URL of the logo associated with the category.
pszIcon
Optional. String value that contains the URL of the icon associated with the category.
pszWideLogo
Optional. String value that contains the URL of the wide logo associated with the channel.


CHANNELENUMINFO

typedef struct _tagChannelInfo{
    LPOLESTR pszTitle;
    LPOLESTR pszPath;
    LPOLESTR pszURL;
    SUBSCRIPTIONSTATE stSubscriptionState;
} CHANNELENUMINFO;

Contains the information on a channel in an enumeration.

pszTitle
String value that contains the channel title. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
pszPath
String value that contains the path to the channel shortcut. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
pszURL
String value that contains the URL of the CDF file for the given channel. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
stSubscriptionState
SUBSCRIPTIONSTATE value that indicates the current state of the subscription.


CHANNELSHORTCUTINFO

typedef _tagChannelShortcutInfo {
    DWORD cbSize;
    LPWSTR pszTitle;
    LPWSTR pszURL;
    LPWSTR pszLogo;
    LPWSTR pszIcon;
    LPWSTR pszWideLogo;
    BOOL bIsSoftware;
} CHANNELSHORTCUTINFO;

Contains the information associated with a channel entry in the channel bar.

cbSize
Required. Double word value that contains the size of the structure. This value must be specified.
pszTitle
Required. String value that contains the channel title. To add the channel to an existing category on the channel bar, the category title should be included in the channel title using the following format:

<category title>\\<channel title>

pszURL
Required. String value that contains the URL of the channel's CDF file.
pszLogo
Optional. String value that contains the URL of the logo associated with the channel.
pszIcon
Optional. String value that contains the URL of the icon associated with the channel.
pszWideLogo
Optional. String value that contains the URL of the wide logo associated with the channel.
bIsSoftware
Boolean value that indicates whether or not this shortcut is a software update.


SUBSCRIPTIONINFO

typedef struct _tagSubscriptionInfo {
    DWORD cbSize;
    DWORD fUpdateFlags;
    SUBSCRIPTIONSCHEDULE schedule;
    CLSID customGroupCookie;
    LPVOID pTrigger;
    DWORD dwRecurseLevels;
    DWORD fWebcrawlerFlags;
    BOOL bMailNotification;
    BOOL bGleam;
    BOOL bChangesOnly;
    BOOL bNeedPassword;
    DWORD fChannelFlags;
    BSTR bstrUserName;
    BSTR bstrPassword;
    BSTR bstrFriendlyName;
    DWORD dwMaxSizeKB;
    SUBSCRIPTIONTYPE subType;
    DWORD fTaskFlags;
    DWORD dwReserved;
} SUBSCRIPTIONINFO, *LPSUBSCRIPTIONINFO, *PSUBSCRIPTIONINFO;

Contains the details of a subscription.

cbSize
Unsigned long integer value that contains the size of the structure.
fUpdateFlags
Unsigned long integer value that contains the update flags. Can be a combination of the SUBSCRIPTIONINFOFLAGS. Can also be set to SUBSINFO_ALLFLAGS to set all of the flags.
schedule
SUBSCRIPTIONSCHEDULE value that indicates how often the subscription is updated.
customGroupCookie
CLSID value that contains the cookie associated with the group.
pTrigger
Addresss of a pointer to the TASK_TRIGGER structure.
dwRecurseLevels
Unsigned long integer value that contains the number of levels to recurse.
fWebcrawlerFlags
Unsigned long integer value that contains the flags to control what resources are downloaded by the link crawler. Can be a combination of the WEBCRAWL_RECURSEFLAGS values.
bMailNotification
Boolean value that indicates whether to notify the user through e-mail when the subscribed site has been updated.
bGleam
Boolean value that indicates whether a gleam is displayed when the subscribed site has been updated.
bChangesOnly
Boolean value that indicates whether to only check for changes, or check for changes and download content.
bNeedPassword
Boolean value that indicates whether authentication is required for the subscribed site.
fChannelFlags
Unsigned long integer value containing the flags that control the channel agent. Can be one of the CHANNEL_AGENT_FLAGS.
bstrUserName
String value containing the user name used for authentication.
bstrPassword
String value containing the password used for authentication.
bstrFriendlyName
String value that contains the friendly name for the subscription.
dwMaxSizeKB
Unsigned long integer value that contains the maximum download size (in kilobytes) for this subscripton.
subType
SUBSCRIPTIONTYPE value that indicates the type of subscription.
fTaskFlags
Unsigned long integer value that contains the task flags. Can be one of the TASK_FLAG_* values defined in the Task Scheduler Reference.
dwReserved
Reserved. Must be set to zero.


Enumerated Types

This section defines the enumerated types in the Information Delivery API.

CHANNEL_AGENT_FLAGS
CHANNELENUMFLAGS
CREATESUBSCRIPTIONFLAGS
SUBSCRIPTIONINFOFLAGS
SUBSCRIPTIONSCHEDULE
SUBSCRIPTIONSTATE
SUBSCRIPTIONTYPE
WEBCRAWL_RECURSEFLAGS


CHANNEL_AGENT_FLAGS

typedef enum CHANNEL_AGENT_FLAGS {
    CHANNEL_AGENT_DYNAMIC_SCHEDULE = 0x0001,
    CHANNEL_AGENT_PRECACHE_SOME = 0x0002,
    CHANNEL_AGENT_PRECACHE_ALL = 0x0004,
    CHANNEL_AGENT_PRECACHE_SCRNSAVER = 0x0008
} CHANNEL_AGENT_FLAGS;

Contains the flags that control the channel agent.

CHANNEL_AGENT_DYNAMIC_SCHEDULE
Use the information in the CDF file to create a schedule.
CHANNEL_AGENT_PRECACHE_SOME
Store any item that has an ITEM tag with the value PRECACHE=YES in the cache.
CHANNEL_AGENT_PRECACHE_ALL
Store all items in the cache that don't have an ITEM tag with the value PRECACHE=NO.
CHANNEL_AGENT_PRECACHE_SCRNSAVER
Store any item that has a USAGE tag with value equal to "ScreenSaver".


CHANNELENUMFLAGS

typedef enum _tagChannelEnumFlags{
    CHANENUM_CHANNELFOLDER = 0x00000001,
    CHANENUM_SOFTUPDATEFOLDER = 0x00000002,
    CHANENUM_DESKTOPFOLDER = 0x0000004,
    CHANENUM_TITLE = 0x00010000,
    CHANENUM_PATH = 0x00020000,
    CHANENUM_URL = 0x00040000,
    CHANENUM_SUBSCRIBESTATE = 0X00080000
} CHANNELENUMFLAGS;

Enumerated type that contains the channel enumerator flags that define what cahnnels are returned and what information will be returned for each channel enumerated.

CHANENUM_CHANNELFOLDER
Retrieve all channels in the channel folder.
CHANENUM_SOFTUPDATEFOLDER
Retrieve all channels in the software update folder.
CHANENUM_DESKTOPFOLDER
Retrieve all channels on the desktop.
CHANENUM_TITLE
Return the title of each channel enumerated.
CHANENUM_PATH
Return the path to the channel shortcut for each channel enumerated.
CHANENUM_URL
Return the URL of the CDF file for each channel enumerated.
CHANENUM_SUBSCRIBESTATE
Return the subscription state of each channel enumerated.


CREATESUBSCRIPTIONFLAGS

typedef enum CREATESUBSCRIPTIONFLAGS{
    CREATESUBS_ADDTOFAVORITES = 0x0001,
    CREATESUBS_FROMFAVORITES = 0x0002,
    CREATESUBS_NOUI = 0x0004,
    CREATESUBS_NOSAVE = 0x0008,
    CREATESUBS_SOFTWAREUPDATE = 0x0010,
} CREATESUBSCRIPTIONFLAGS;

Contains the flags used when creating a subscription.

CREATESUBS_ADDTOFAVORITES
Add subscription to Favorites menu.
CREATESUBS_FROMFAVORITES
Create the subscription for a site that already has a listing in the Favorites menu. Used in conjunction with the CREATESUBS_ADDTOFAVORITES value. This value will skip the section of the user interface that is used to add a Favorite and display the subscription options only.
CREATESUBS_NOUI
Create the subscription without displaying any user interface.
CREATESUBS_NOSAVE
Creates the subscription in the Subscriptions folder and then copies the information back to the SUBSCRIPTIONINFO structure that was passed in. Normally, the information is saved to the disk and the structure is not updated.
CREATESUBS_SOFTWAREUPDATE
Create a subscription for a Software Update Channel. Used in conjunction SUBSTYPE_CHANNEL value. If used with the CREATESUBS_ADDTOFAVORITES value, the method will display a different user inteface and add the listing to the software updates folder.


SUBSCRIPTIONINFOFLAGS

typedef enum SUBSCRIPTIONINFOFLAGS {
    SUBSINFO_SCHEDULE = 0x0001,
    SUBSINFO_RECURSE = 0x0002,
    SUBSINFO_WEBCRAWL = 0x0004,
    SUBSINFO_MAILNOT = 0x0008,
    SUBSINFO_MAXSIZEKB = 0x0010,
    SUBSINFO_USER = 0x0020,
    SUBSINFO_PASSWORD = 0x0040,
    SUBSINFO_GLEAM = 0x0200,
    SUBSINFO_CHANGESONLY = 0x0400,
    SUBSINFO_CHANNELFLAGS = 0x0800,
    SUBSINFO_FRIENDLYNAME = 0x2000,
    SUBSINFO_NEEDPASSWORD = 0x4000,
    SUBSINFO_TYPE = 0x8000
} SUBSCRIPTIONINFOFLAGS;

Contains the type information about subscriptions.

SUBSINFO_SCHEDULE
Update schedule the subscription is on.
SUBSINFO_RECURSE
Number of levels to recurse.
SUBSINFO_WEBCRAWL
Flags for the link crawling agent.
SUBSINFO_MAILNOT
User should be notified through e-mail.
SUBSINFO_MAXSIZEKB
Maximum download size in kilobytes.
SUBSINFO_USER
User name for authentication.
SUBSINFO_PASSWORD
Password for authentication.
SUBSINFO_GLEAM
Add a gleam to notify the user of an update to the site.
SUBSINFO_CHANGESONLY
Notify the user of changes only.
SUBSINFO_CHANNELFLAGS
Channel flags.
SUBSINFO_FRIENDLYNAME
Friendly name for the subscription.
SUBSINFO_NEEDPASSWORD
Subscription requires a password.
SUBSINFO_TYPE
Type of subscription.


SUBSCRIPTIONSCHEDULE

typedef enum SUBSCRIPTIONSCHEDULE {
    SUBSSCHED_AUTO = 0,
    SUBSSCHED_DAILY = 1,
    SUBSSCHED_WEEKLY = 2,
    SUBSSCHED_CUSTOM = 3,
    SUBSSCHED_MANUAL = 4
} SUBSCRIPTIONSCHEDULE;

Contains the values that indicate the update frequency.

SUBSSCHED_AUTO
Automatically schedule updates.
SUBSSCHED_DAILY
Update the subscription daily.
SUBSSCHED_WEEKLY
Update the subscription weekly.
SUBSSCHED_CUSTOM
Update the subscription using a custom schedule.
SUBSSCHED_MANUAL
Update the subscription manually.


SUBSCRIPTIONSTATE

typedef enum _tagSubscriptionState{
    SUBSTATE_NOTSUBSCRIBED,
    SUBSTATE_PARTIAL_SUBSCRIPTION,
    SUBSTATE_FULLSUBSCRIPTION
} SUBSCRIPTIONSTATE;

Contains the different subscription states.

SUBSTATE_NOTSUBSCRIBED
Not subscribed to the channel.
SUBSTATE_PARTIALSUBSCRIPTION
Partially subscribed to the channel.
SUBSTATE_FULLSUBSCRIPTION
Subscribed to the channel.


SUBSCRIPTIONTYPE

typedef enum SUBSCRIPTIONTYPE {
    SUBSTYPE_URL = 0,
    SUBSTYPE_CHANNEL = 1,
    SUBSTYPE_DESKTOPCOMPONENT = 2
} SUBSCRIPTIONTYPE;

Contains the different types of subscriptions.

SUBSTYPE_URL
Subscription is an Internet resource.
SUBSTYPE_CHANNEL
Subscription is a channel.
SUBSTYPE_DESKTOPCOMPONENT
Subscription is a desktop component.


WEBCRAWL_RECURSEFLAGS

typedef enum WEBCRAWL_RECURSEFLAGS {
    WEBCRAWL_DONT_MAKE_STICKY = 0x0001,
    WEBCRAWL_GET_IMAGES = 0x0002,
    WEBCRAWL_GET_VIDEOS = 0x0004,
    WEBCRAWL_GET_BGSOUNDS = 0x0008,
    WEBCRAWL_GET_CONTROLS = 0x0010,
    WEBCRAWL_LINKS_ELSEWHERE = 0x0020,
    WEBCRAWL_IGNORE_ROBOTSTXT = 0x0080
} WEBCRAWL_RECURSEFLAGS;

Contains the flags for the default link crawling agent included with the Information Delivery API.

WEBCRAWL_DONT_MAKE_STICKY
Instructs the agent to cache the downloaded resources normally. If this value is not set, the agent makes the entries sticky, which prevents the entry from being removed during a normal clean-up operation.
WEBCRAWL_GET_IMAGES
Instructs the agent to download any images associated with the resource.
WEBCRAWL_GET_VIDEOS
Instructs the agent to download any videos associated with the resource.
WEBCRAWL_GET_BGSOUNDS
Instructs the agent to download any background sounds associated with the resource.
WEBCRAWL_GET_CONTROLS
Instructs the agent to download any controls associated with the resource.
WEBCRAWL_LINKS_ELSEWHERE
Instructs the agent to follow links that go to sites outside the site that the resource resides on.
WEBCRAWL_IGNORE_ROBOTSTXT
Instructs the agent to ignore any robot scripts.


Return Values

The following list contains possible return values for the Information Delivery API.

INET_E_AGENT_CACHE_SIZE_EXCEEDED
Maximum cache limit has been reached.
INET_E_AGENT_CONNECTION_FAILED
Failed to connect to the Internet.
INET_E_AGENT_MAX_SIZE_EXCEEDED
Subscription size limit has been reached.
INET_S_AGENT_PART_FAIL
Agent has completed the operation after encountering a few errors.


Internet Component Download

Internet Component Download is a mechanism for downloading and installing code from the Internet.

Microsoft Internet Component Download Overview
Microsoft Internet Component Download Reference


Microsoft Internet Component Download Overview

Internet Component Download is a system service for downloading and installing code from the Internet, and for certificate checking. This service is used by Microsoft® Internet Exporer to automatically download and install software from code repositories on the Internet. This section explains how code authors should prepare their software for automatic download. It then describes the interface for the component download mechanism, and finally provides some additional implementation details, including a description of the Internet Search Path service, which allows searching for code that can be downloaded.

The following topics are covered in this section:

Microsoft Internet Component Download Using INF
Extending Internet Component Download Using OSD


Internet Component Download Using INF

Microsoft Internet Explorer 4.0 introduces the concept of a software package. The packaging mechanism for this software package is a cabinet (CAB) file referenced by the CODEBASE element. A software package typically describes the smallest installable component, an ActiveX™ control, or a Java class library. The software package is addressed by its unique name/identifier and a version number. Legacy CABs that contain an INF file referenced by a CODEBASE attribute in the OBJECT element are automatically treated as a software package, with the unique name or identifier being the same as the GUID in the CLASSID attribute—for example, CLASSID=clsid:{9dba....}.

Software packages are described in the Open Software Description (OSD) vocabulary at http://www.microsoft.com/standards/osd. A software package CAB typically contains an OSD file. For compatibility and ease of use, it is possible to have the OSD reference a Microsoft Internet Explorer 3.0-style code download INF file inside the same CAB.

Packaging Component Code for Automatic Download

Independent software vendors and authors of COM objects for the Internet should package their implementations so they can be downloaded automatically by Web browsers such as Microsoft Internet Explorer. Such objects will be downloaded, for instance, when parsing the OBJECT tag in HTML.

Starting with Internet Explorer 4.0, an Internet Component Download CAB can contain a software package that represents a Java class library to be submitted to the Microsoft Internet Explorer Java Package Manager. Java class libraries are referenced by HTML in the APPLET and OBJECT element with PARAM NAME="useslibrary". When Internet Component Download is handed a CODEBASE that happens to be a CAB file, the following happens:

  • The CAB is inspected to see if it contains an OSD file first. OSD files are basically Extensible Markup Language (XML) files with OSD vocabulary. The OSD specification is located at http://www.microsoft.com/standards/osd/; details on usage of OSD to install Java packages with the Microsoft Java Virtual Machine Package Manager or installing simple ActiveX Controls with OSD syntax can be found in the Extending Internet Component Download Using OSD article.
  • If the CAB contains an OSD, it is processed for native code or Java packages to be installed as part of this software package. An OSD can also point to an INF file in the same CAB file.
  • If the CAB does not contain an OSD file, a search is made for an INF file. If found, it is processed with the Component Download INF grammar detailed in INF setup-script format.

Interpreting the CODEBASE URL

The CODEBASE attribute in an OBJECT element contains a URL pointing to the implementation of a given COM object. This URL is of critical importance for component download, because it must specify all files necessary to implement a particular COM object. HTML authors can author the CODEBASE URL to point to one of two file types in the general case, and a third file type in a special case. Component developers should choose one of the following packaging schemes for their COM objects:

  • A single PE (portable executable, for example, an .ocx, a .dll, or an .exe file): This single executable is downloaded, installed, and registered in one step. This is the simplest way to package a single-file OLE control, but it will not use file compression, and it will not be platform independent except with HTTP.
  • A CAB (cabinet) file: This file contains one or more files, all of which are downloaded together in a compressed cabinet. Exactly one file in the cabinet is an INF file providing further installation information. This INF file can refer to files in the CAB as well as to files at other URLs. This mechanism requires authoring of an INF file and packaging of a CAB file, but in return it provides file compression. It will not be platform independent, however, except with HTTP format negotiation.
  • (Special case) A stand-alone INF file: The stand-alone INF can be used only when browser security is set to low or medium. This will not work in high browser security because a flat INF file cannot be signed, thus making it incompatible with Authenticode™. This file specifies various files that need to be downloaded and set up for the OCX to run. The syntax of the INF file allows URLs pointing to files to download, and platform independence (by enumerating files for various platforms). This mechanism provides platform independence for non-HTTP servers.

Registry settings and self-extracting EXE files

It's best to use self-registering code for Internet Component Download. For OCX, DLL, and EXE files marked as "OleSelfRegister" in the version resource, Internet Component Download will try to run self-registration. For DLLs, this means loading the DLL library and calling the DllRegisterServer entry point, if available. For EXEs, this means running the EXE file with the run-time parameter of "/RegServer". This ensures that COM objects implemented as local servers (for example, Winword.exe) are registered correctly. If an object is not marked as "OleSelfRegister" but registration is necessary, or if it is necessary to override the "OleSelfRegister" flag, one can add the following to an INF file (see the INF setup-script format below):

[foo.ocx]
RegisterServer=no 	; don't register even if marked OleSelfRegister

or

[foo.ocx]
RegisterServer=yes 	; register this even if not marked OleSelfRegister.
                ; This is the typical workaround for getting old
                ; controls to register

Code that is downloaded through Internet Component Download can be a self-extracting EXE because Internet Component Download ignores the "OleSelfRegister" flag if the main URL for code download points directly to an EXE file. In this case it is assumed that this is a self-registering EXE, and this enables self-extracting EXEs to work correctly as long as they ignore the /regsvr command-line parameter. Supporting self-extracting EXEs enables very complex setup mechanisms to be launched automatically through Internet Component Download. For details on how to package your self-extracting EXE as a hook instead of pointing your CODEBASE at it, see the "When and How to Use Hooks" section. However, if a self-extracting EXE is called through this mechanism, any components it installs will not be automatically tracked by Internet Component Download. Such components are permanently installed and are not marked by Internet Component Download for future cleanup.

Including the version number in the CODEBASE URL

In addition to the actual code address, the CODEBASE URL can also include an optional version number by using the following syntax:

"CODEBASE=http://www.foo.com/bar.ocx#Version=a,b,c,d"

The Internet Component Download mechanism downloads and installs the file only if the specified version number is more recent than any existing version of the same file currently installed in the system. If a version number is not specified with a file, it is assumed that any version installed on the system is recent enough.

If the version number specified in the CODEBASE attribute is "-1,-1,-1,-1", Internet Component Download will always try to download the latest version of the desired component. Note that this can be a costly effort involving many network transactions, especially if the Internet search path is searched for the newest version of an object. Note also that because of the Internet search path, it is possible for the Component Download service to try to download code in the absence of a CODEBASE attribute. In fact, if the CODEBASE attribute is the URL fragment "#Version=-1,-1,-1,-1", there is no specific location to download code from, but the Internet search path will still be searched to find the latest version of an object.

Platform independence and HTTP

When code to be downloaded is on an HTTP server, the HTTP Accept header MIME request type can be used to specify which platform the code is to run on, thus allowing platform independence of the CODEBASE URL.

The following MIME types are used to describe PE files (.exe, .dll, .ocx), cabinet files (.cab), and setup scripts (.inf).
File description | MIME type
PE (portable executable) - .exe, .dll, .ocx | application/x-pe-%opersys%-%cpu%
Cabinet files - .cab | application/x-cabinet-%opersys%-%cpu%
Setup scripts - .inf (platform independent) | application/x-setupscript
Macintosh® Binhex files | application/mac-binhex-40

%opersys% and %cpu% specify the operating system and CPU for the platform on which downloaded components will be executed. For example, the MIME type for a Win32® cabinet file running on an Intel® x86-architecture processor would be:

application/x-cabinet-win32-x86

The following are valid values for %opersys% and %cpu%.
Valid values for %opersys% | Meaning
win32 | 32-bit Windows® operating systems (Windows 95 or Windows NT®)
mac | Macintosh® operating system
<other> | will be defined as necessary
Valid values for %cpu% | Meaning
x86 | Intel® x86 family of processors
ppc | Motorola® PowerPC architecture
mips | MIPS® architecture processors
alpha | DEC® Alpha architecture
68k | Motorola® 68k CPU

When the code is on a non-HTTP server (for example, at a local LAN location), an INF file can be used to achieve platform independence by specifying different URLs for files to be downloaded for different platforms.

CAB format

The CAB format used for Internet Component Download is a nonproprietary format based on Lempel-Ziv compression. The Microsoft Internet Client SDK includes a free tool called DIAMOND.EXE that will package cabinet files into this nonproprietary format.

Using the DIAMOND.EXE tool for creating CAB files

The DIAMOND.EXE tool takes a DDF "directive file" specifying which files to combine into a cabinet. The syntax for using this tool from the command line is:

DIAMOND.EXE /f <directive file.ddf>

The following example directive file, Circ3z.dff, would be used for creating a cabinet file containing two files: Circ3.inf and Circ3.ocx. It should be straightforward to add to this list of files.

; DIAMOND directive file for CIRC3.OCX+CIRC3.INF
.OPTION EXPLICIT				; Generate errors on variable typos
.Set CabinetNameTemplate=CIRC3Z.CAB
;** The files specified below are stored, compressed, in cabinet files
.Set Cabinet=on
.Set Compress=on
circ3.INF
circ3.OCX

Note It is possible to use the "code-signing" utilities to sign entire cabinet files using a digital certificate. However, to do this, it is necessary to add the following lines to the DDF file before the list of files for inclusion in the cabinet.

;Reserve space for PKS#7 Code Signature
.Set ReservePerCabinetSize=2048

If a cabinet file is signed, it is assumed that every file inside the cabinet is trusted, including .inf and .ini files. This has two advantages:

  • It is now possible to include powerful INF files inside a trusted cabinet.
  • By signing an entire cabinet, the time for verifying digital certificates can be accelerated due to the cabinet compression.

INF setup-script format

INF syntax understood by Internet Component Download

All URLs in the INF are to be encoded for handling of special characters—for example, 'space' should be encoded as "http://foo/foo%20bar.ocx". Friendly file names are created using the decoded base names of these URLs. URLs, if relative, are based of the context of the main CODEBASE=<url>, unless redirected by the object index, in which case the context is set to that of the redirected URL.

Code downloader-understood main sections

The code downloader looks for and understands the [Add.Code] and [Setup Hooks] sections in the INF file. If both these sections are missing, the INF is assumed to be a standard Win32 INF without code downloader extensions, and a hook is created to have the system process the INF's DefaultInstall section.

The Add.Code section lists all the files to be installed, including optional files.

[Add.Code]
filename1=section-name1
filename2=section-name2

Each file section is identified by the section name in brackets, followed by all the key values, as in an .ini file.

[section-name1]
key1=value1
key2=value2

The following keys are valid in a file section:

File-%opersys%-%cpu%=[url | ignore | thiscab]
%opersys% can be one of [win32 | mac] currently. %cpu% can be one of [x86 | ppc | mips | alpha].

A URL can be specified to indicate the correct file for the target operating system and CPU, or the special value "ignore", which indicates the file is not required for the specified platform. This key is always looked for before the platform-independent description key File= as described below.

File=[url | thiscab]
The value of the file key indicates where the file can be downloaded from. It can be a URL or the special value "thiscab", which indicates that the file is located in the CAB file where the INF file came from. If no value is specified, component download fails if the file is not already installed on the user's computer. If this URL points to a non-HTTP protocol or to an HTTP server that does not support/understand the special Accept Types sent out by the code downloader as discussed in the Platform Independence and HTTP section above, you must use the file-%opersys%-%cpu%= key described in the previous paragraph.
FileVersion=a,b,c,d
The FileVersion key specifies the minimum required version of the file specified by the File key. If no value is specified, any version is acceptable.
Clsid={nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
The value of the clsid key is the string representation of the component CLSID, enclosed in braces {}.
DestDir=[10 | 11]
DestDir can be set to 10 to place the file into the \windows directory or to 11 to place the file into the \windows\system directory. If no value is specified, the file is placed in the \cache directory.
RegisterServer=[yes | no]
This is an override to the policy on whether to try to self-register this file. Section "Registry settings and self-extracting .exes" above in this document contain details on the registration policy.
Hook=section-name3
This is the way to specify conditional hooks. If the clsid or file of at least the version specified in this section is not sufficient and no File= or File-%opersys%-%cpu%= values are specified, this key hook is looked for by the component downloader to look for a custom setup hook to install the required file or component. The Hook section looks like the following:
[section-name3]
key1=value1
key2=value2

It is valid for several different file section hooks to point to the same hook section. This is a way to have one hook install one or more components/files. The hook is executed only once if one or more pieces are missing.

with the following valid keys:

File-%opersys%-%cpu%=[url | ignore]
%opersys% can be one of [win32 | mac] currently. %cpu% can be one of [x86 | ppc | mips | alpha].

A URL can be specified to indicate the correct file for the target operating system and CPU, or the special value "ignore", which indicates the file is not required for the specified platform. This is identical to the way you would specify the location of a file name in a section describing the piece in [add.code] except that this has to point to a CAB file and the keyword 'thiscab' is not applicable with this key. This value if absent would cause us to set our context to the CAB that this INF file was located in. This key is always looked for before the platform independent description key File= as described below.

File=[url]
This is a URL to a CAB file that contains one or more files that are needed for the hook. The component download downloads the CAB file and expands it into a unique temporary directory and then executes the hook. This is identical to the way you would specify the location of a file name in a section describing the piece in [add.code], except that this has to point to a CAB file, and the keyword 'thiscab' is not applicable with this key. This value, if absent, would cause us to set our context to the CAB that this INF file was located in.
Run=[cmd-line]
This is the command line to be run in the temporary directory with the extracted files in the CAB file pointed to by the above File= key. The command line can contain some component downloader variables that are expanded before execution. It can also contain translations of Win32 INF syntax based on registry key values on the client. Look for examples and details in the Appendix. If this key is absent, the component downloader looks for InfFile= and InfSection= keys to run a Win32 INF hook.
InfFile=[name of win32 INF file inside the CAB]
This is an optional key that, if absent, sets it to the current INF (the main INF pointed to or found in the CAB pointed to by CODEBASE=). This is a way to use standard Win32 INF syntax for installation of a file or component. Please look for samples and syntax of Win32 INF in the Appendix.
InfSection=[section name in the InfFile mentioned in above key]
This is an optional key that, if absent, sets it to the DefaultInstall section of the INF file specified in the InfFile= key above.

The Setup Hooks section lists all unconditional hooks to be executed before setup of files in the Add.Code section.

[Setup Hooks]
hookname1=section-name4
hookname2=section-name5

Just as within a section describing a file to be installed listed in Add.Code section, you could execute a hook to install/set up that file with the hook= key, you can also list a set unconditional hooks to be always executed before setup of files in Add.Code. This is done by listing all the hooks in order of preferred execution in the Setup Hooks section.

Note When using hooks, it is important to add the following lines to your INF file for compatibility.

[Version]
Signature="$CHICAGO$"
AdvancedINF=2.0

The following is a sample INF file that demonstrates the syntax understood by the Component Download service.

;Sample INF file for CIRC3.OCX
[Add.Code]
circ3.ocx=circ3.ocx
random.dll=random.dll
mfc40.dll=mfc40.dll
foo.ocx=foo.ocx

[circ3.ocx]
; Lines below specify that the specified circ3.ocx (clsid, version) needs to be
; installed on the system. If it doesn't exist already, it can be downloaded from
; the given location (a .CAB).
; Note: if "thiscab" is specified instead of the file location, it is assumed that
; the desired file is present in the same .CAB cabinet that the INF originated from.
; Otherwise, if the location pointed to is a different .CAB, the new cabinet
; is also downloaded and unpacked in order to extract the desired file.
file=http://www.code.com/circ3/circ3.cab
clsid={9DBAFCCF-592F-101B-85CE-00608CEC297B}
; Note that the {}s are required when entering a CLSID in the INF file.
; This is slightly different from the HTML
; syntax for inserting CLSIDs in an <OBJECT> tag.
FileVersion=1,0,0,143

[random.dll]
; Lines below specify that the random.dll needs to be installed in the system.
; If this doesn't exist already, it can be downloaded from the given location.
file=http:// www.code.com/circ3/random.dll
; Note that the FileVersion is optional, and it can also be left empty,
; meaning that any version is ok.
FileVersion=
DestDir=10

; DestDir can be set to 10 or 11 ( LDID_WIN or LDID_SYS by INF convention).
; This places files in \windows or \windows\system, respectively.
; If no dest dir is specified (typical case), code is installed in the occache
; directory.

[mfc40.dll]
; Leaving the file location empty specifies that the installation
; needs mfc40 (version 4,0,0,5), but it should not be downloaded.
; If this file is not already present on the client machine, component download fails.
file=
FileVersion=4,0,0,5

[foo.ocx]
; Leaving the file location empty specifies that the installation
; needs the specified foo.ocx (clsid, version), but it should not be downloaded.
; If this file is not already present on the client machine, component download fails.
file=
clsid={DEADBEEF-592F-101B-85CE-00608CEC297B}
FileVersion=1,0,0,143

Platform independence in .INF files

It is possible to create platform-independent setup scripts that pull files from different locations depending on the desired platform. Internet Component Download INF files use a scheme similar to the one described under "Platform Independence and HTTP" earlier in this section. Specifically, a sample platform-independent INF file would include text such as the following:

[circ3.ocx]
; Lines below specify that the specified circ3.ocx (clsid, version) needs to be
; installed on the system. If it doesn't exist already, can be downloaded from
; the given location (a .CAB).
file-win32-x86=file://products/release/circ3/x86/circ3.cab
file-win32-mips=file://products/release/circ3/mips/circ3.cab
file-mac-ppc=ignore
; The 'ignore' keyword means that this file is not needed for this platform.

clsid={9DBAFCCF-592F-101B-85CE-00608CEC297B}
FileVersion=1,0,0,143

Thus the "file=" syntax used in the INF file is expanded to "file-%opersys%-%cpu =", allowing the INF file to specify multiple locations where various platform-dependent modules can be found and downloaded. See the section above for valid values for %opersys% and %cpu%.

The Internet Component Download Service

The Internet Component Download service is exposed through a single function, CoGetClassObjectFromURL. This system function is called by an application to download, verify, and install code for an OLE component. The function is used in the implementation of Microsoft Internet Explorer.

The CoGetClassObjectFromURL function returns a factory object for a given rclsid. If no CLSID is specified (CLSID_NULL), this function chooses the appropriate CLSID for interpreting the Internet MIME type specified in szContentType. If the desired object is installed on the system, it is instantiated. Otherwise, the necessary code is downloaded and installed from the location specified in szCodeURL or from an object store on the Internet search path (see below).

This "download and install" process involves the following steps:

  1. Download the necessary file(s) (.cab, .inf, or .exe) using URL Moniker(s).
  2. Call WinVerifyTrust to ensure that all downloaded files are safe to install.
  3. Complete self-registration of all COM components.
  4. Add registry entries to keep track of downloaded code (see Appendix on Registry Details).
  5. Call CoGetClassObject for the desired rclsid.

In the common Web-browser scenario, the values for parameters passed to this function are read directly from an HTML OBJECT element. For example, the szCodeURL, dwFileVersionMS, and dwFileVersionLS parameters are specified inside an <OBJECT> tag as "CODEBASE=http://www.foo.com/bar.ocx#Version=a,b,c,d", where szCodeURL is "http://www.foo.com/bar.ocx", dwFileVersionMS is MAKELONG(b, a), and dwFileVersionLS is MAKELONG(d, c).

Because downloading and installation of code occurs asynchronously, CoGetClassObjectFromURL often returns immediately with a return value of E_PENDING. At this point, the IBindStatusCallBack interface is used to communicate the status of the download operation to the client. To participate in this communication, the client must implement IBindStatusCallback and register this interface in the pBindCtx parameter passed into CoGetClassObjectFromURL using RegisterBindStatusCallback. The client can expect to be called with callback notifications for IBindStatusCallback::OnStartBinding (providing an IBinding for controlling the download), IBindStatusCallback::OnProgress (reporting progress), IBindStatusCallback::OnObjectAvailable (which returns the desired object interface pointer), and IBindStatusCallback::OnStopBinding (which returns error codes in case of an error).

Storing/Caching Downloaded Code

Component Download installs most new code in a permanent store in windows\occache. The cache location can be overridden by a registry setting of HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Internet Settings\ActiveXCache. Some components (helper DLLs that need to be on the system PATH but currently are not) will also be installed in \windows and \windows\system. All downloaded code is registered using a new "Module Usage" registry section that keeps track of such code. Downloaded code is not removed automatically, but it is possible in the future to add a user interface to the Control Panel (or elsewhere) allowing a user to clean up this directory.

Internet Search Path

When Internet Component Download is called to download code, it traverses the Internet search path to look for the desired component. This path is a list of object store servers that will be queried every time components are downloaded using CoGetClassObjectFromURL. This way, even if an <OBJECT> tag in an HTML document does not specify a CODEBASE location to download code for an embedded OLE control, the Internet Component Download will still use the Internet search path to find the necessary code.

Internet search path syntax

The search path is specified in a string in the registry, under the key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Internet Settings\CodeBaseSearchPath. The value for this key is a string in the following format:
CodeBaseSearchPath = <URL1>; <URL2>; ... <URLm>; CODEBASE; <URLm+1>;
    ... <URLn-1>; <URLn>

In this format, each of URL1 through URLn is an absolute URL pointing to HTTP servers acting as "object stores". When processing a call to CoGetClassObjectFromURL, the Internet Component Download service will first try downloading the desired code from the locations URL1 through URLm, then try the location specified in the szCodeURL parameter (corresponding to the CODEBASE attribute in the <OBJECT> tag), and will finally try the locations specified in locations URLm+1 through URLn.

Note that if the CODEBASE keyword is not included in the CodeBaseSearchPath key, calls to CoGetClassObjectFromURL will never check the szCodeURL location for downloading code. By removing the CODEBASE keyword from the CodeBaseSearchPath key, corporate intranet administrators can effectively disable Internet Component Download for corporate users.

Object stores

An object store on the Internet search path is an HTTP server that services requests for downloadable code. During a call to CoGetClassObjectFromURL, Internet Component Download will try to download code from the various object stores on the search path. Specifically, an object store will receive an HTTP POST request with data in the following format:

CLSID={class id}
Version=a,b,c,d
MIMETYPE=mimetype

All the values above are optional, although one of CLSID or MIMETYPE must be present. The object store should parse this information, check an internal database, and either fail the call or redirect the HTTP request to the downloadable code cabinet file (.cab), setup script (.inf), or portable executable (.exe, .dll, .ocx).

The POST parameters should be processed by the object store as follows:

  • If CLSID is provided with no version number, the most recent object matching the CLSID will be returned. If the CLSID is provided with a Version, the object matching the CLSID and with the largest version number greater than or equal to Version will be provided. If no object is available that matches the CLSID with a large enough version number, the 404 error will be returned. MIMETYPE will be ignored when CLSID is provided.
  • If no CLSID is provided but MIMETYPE is provided, the first object found in the database that matches the MIMETYPE will be returned. Version, if provided, is treated exactly as above. If neither CLSID or MIMETYPE is provided, the error return code 400 Bad Request will be returned.

In addition to the POST data described above, queries to object stores will also include HTTP headers for Accept (MIME type) and Accept-Language, thus specifying the desired platforms (see above for Platform Independence and HTTP) and language-localized implementation for a component. Note that these HTTP headers are added to all HTTP requests made by Internet Component Download. This allows object stores to serve different code implementations for differing platforms or even different languages.

Note Internet Component Download uses the first successful response from a server on the Internet search path. Component Download will not continue searching for newer versions of components.

Uses for the Internet search path

The Internet search path can be used in two ways:

  • Object store servers at the beginning of the path will be asked for code before checking the location specified in the szCodeURL parameter for CoGetClassObjectFromURL. Servers at the beginning of the search path will thus be checked before trying the location specified in the CODEBASE attribute of an <OBJECT> tag. This is a useful feature for corporate intranets, because it allows intranet administrators to set up a local object store that is used to serve code for download by employees. In fact, it is possible to disable the CODEBASE attribute for <OBJECT> tags by removing the CODEBASE keyword from the search path.
  • Object store servers at the end of the search path will be asked for code after trying the location specified in the szCodeURL parameter for CoGetClassObjectFromURL, and thus after trying the location specified in the CODEBASE attribute. This allows registration of default object store locations on the World Wide Web, where browsers can find code when no CODEBASE location is explicitly specified.

Registry Details

The Internet Component Download service keeps registry entries for every new downloaded component. These registry entries will be useful for writing a utility for cleaning up the code storage, or for migrating the Component Download service to use a code cache rather than a permanent store.

Why the existing "SharedDLL" mechanism is inadequate

To do correct code caching, the existing shared DLL reference counting scheme will not suffice, because reference counts are easily inflated. Specifically, any application that is reinstalled increases the reference count on a shared DLL even though that DLL already has a reference count belonging to the particular application. This is already broken for current reference counting, but it will especially fail for code download, in which OCXes are used by multiple pages quite regularly and there is no way of knowing which OCXes need reference counts.

New "ModuleUsage" registry mechanism for tracking usage of shared components

To do ref. counting correctly, Component Download maintains a ModuleUsage section in the registry that holds a list of "owners" and "clients" for each shared module. Thus the registry can keep track of who is using a shared module, not just how many clients that module has. The registry entries use the following syntax:

[ModuleUsage]
    [<Fully Qualified Path&File Name>]
        .FileVersion=a,b,c,d
        .Owner = Friendly Name/ID of Owner
        <Client ID > = <info peculiar to this client>
        <Client ID > = <info peculiar to this client>

A ModuleUsage section in a sample registry would look something like the following:

Under My Computer\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion:

[ModuleUsage]
    [c:/windows/system/mfc40.dll]
        .FileVersion=0,4,0,0
        .Owner ={CLSID of main object rclsid passed to CoGetClassObjectFromURL}
        {CLSID of main object rclsid passed to CoGetClassObjectFromURL}= <any info,
            or default>
        AnotherAppID= <any info, or default>
Key name | Description
<Fully Qualified Path&File Name> | This is the full path of the shared module. This name has to use "/"s instead of "\"s because the "\" is an invalid character in a key name.
.Owner | The application that installs the shared module and creates the original ModuleUsage section will put some identifier in the Owner key section. If the DLL already existed on the system and this Module Usage key did not exist, the .Owner key should be set to "Unknown" and the DLL should not be removed on uninstall. The owner should always also enlist itself as a client.
.File Version | The version number for the shared module. This is unimplemented by Component Download at this time.
<Client ID> | Identifier of a client who is using the shared module. The value corresponding to each client key contains client-specific information. When the client is Internet Component Download, the <Client ID> is {CLSID of main object rclsid passed to CoGetClassObjectFromURL}. For other clients, the client-specific information should be the full path of the client, so that if the client is accidentally deleted it is possible to do garbage collection.

Every client of this module is expected to increment and decrement the existing SharedDLLs section in the registry as well (a client only increments this value once when it adds itself as a client under [ModuleUsage]). This is to allow a migration path for applications currently implementing only a SharedDLLs scheme.

This registry information complements the reference counts in the SharedDLLs section by remembering which clients are actually using a shared module. This counting scheme will work correctly and allow caching of downloaded code. Furthermore, when downloading files, Internet Component Download can use this registry information as an efficient shortcut for verifying whether a file needs to be overwritten because it is an out-of-date version.

Win32 INF Syntax and Variable Substitutions

EXTRACT_DIR
Expands to the directory that the files in the CAB pointed to by the hook section were extracted to. For example, the following line in the Hook section will run the command mysetup.exe in the extracted directory.
run=%EXTRACT_DIR%/mysetup.exe
OBJECT_DIR
Expands to the default destination directory for controls. In Internet Explorer 4.0, this is the Downloaded Program Files folder under the \windows directory. If there is a file name conflict with a previously existing file in this directory, CONFLICT.<n> folders are created under the default destination directory, when n is a monotonically increasing number. OBJECT_DIR reflects the final destination directory including such name conflict resolutions.

Version Number Format and Other Details

Version is a 64-bit number that you could break up as a,b,c,d, with most significant to least significant left to right. Typically the printed version numbers are represented as a.b.d (skipping c = 0), where:

  • a - major version
  • b - minor version
  • c - custom number
  • d - build number

For example, 4.1.6130 is really 4,1,0,6130.

Determining the local version number of a file

If a recent enough version of a file listed in either the CODEBASE attribute in the OBJECT tag or in the FileVersion= key in the section of the INF file is already available on the local computer, no download happens. When deciding if the version of an available local file is good enough, the following algorithm is applied:

  • If the file in question has an associated CLSID (either by the CLASSID attribute in the OBJECT tag for the main object to be instantiated, or specified by the clsid= key in the INF file), the following key is looked for on the client registry:
    HKEY_CLASSES_ROOT:\\CLSID\{... clsid ...}\Installed version\

    The default value of this key if of the format a,b,c,d (as described in the previous section) is assumed to be the available local version of the clsid. This support is for extending version support to non-PE files such as Java class files. To make the version check more robust, the code downloader will also look for an optional named value "path" under the Installed Version key, which if present is validated to be present on the file system on the local computer. This is to ensure that a download takes place when the registry information is intact, but the actual file that implements the classid has been removed from the hard disk.

  • The file version number is retrieved from the version resource and checked for sufficiency. If the file version cannot be retrieved, the version of the file is deemed insufficient and a download is initiated for that file. A trick to always download a non-PE file is to mark its FileVersion=1,0,0,0 or some non-zero version in the INF section.

Order of Processing and Execution of INF

The [Add.Code] section is processed in the order listed, but the files are installed and set up in reverse order. This means that typically you would list the main OCX file first in the INF file, followed by dependent DLLs. The dependent DLLs are guaranteed to be installed and available at registration time of the main OCX.

Unconditional hooks, those hooks in the [Setup Hooks] section in the INF file, are executed in the order listed in that section (Hook1 executed before hook2). Conditional hooks, those hooks in the file sections referenced by file names in the [Add.Code] section, are executed in the order of the [Add.Code] section. Between conditional hooks and file section installation/setup, conditional hooks always get executed before file section installations/setups in the same CAB. Between two file section installations/setups, the order of file installation and setup is the reverse of the listing in the [Add.Code] section. Between two conditional hooks, the order is the same as that listed in the [Add.Code] section. Note this different ordering rule between conditional hooks and file section installation and setup.

When and How to Use Hooks

A hook is a way to override or customize the installation process of one or more pieces required for a component. There are two types of hooks, unconditional and conditional.

Unconditional hooks are hooks that always get executed. These are hooks mentioned in the [Setup Hooks] section of the Internet Component Download INF file. A good example of an unconditional hook is a setup program. The following is an example of a case using a custom setup program to install the component. Its packaging is as follows:

  1. CODEBASE= points to a foo.cab that contains a foosetup.exe, foo.ocx, and foo.inf file. foosetup.exe, when run with the /q parameter, will install foo.ocx silently in the windows\occache directory.
  2. foo.inf has:
    [Setup Hooks]
    hook1=hook1

    [hook1]
    run=%EXTRACT_DIR%\foosetup.exe /q

    [Version]
    ; This section is required for compatibility on both Windows 95 and Windows NT.
    Signature="$CHICAGO$"
    AdvancedInf=2.0

When the Code Downloader pulls down foo.cab, it trust verifies the cabinet and then processes the INF. Seeing that it has no [Add.Code], it processes the [Setup Hooks] section. It extracts all the files in foo.cab in a unique temporary directory and then runs the command line listed in the run= key. All the files left in the temporary directory after the completion of foosetup.exe including foosetup.exe are discarded. See section on "Component Downloader Variables" for details on the use of %EXTRACT_DIR% variable in the run= key.

Conditional hooks are run only when a certain condition evaluates as TRUE. This is typically when the [Add.Code] section points to a certain piece, and that piece is not available on the client's computer. The above example of foo.ocx could be rewritten using conditional hooks as follows:

  1. CODEBASE= points to a foo.cab that contains a foosetup.exe, foo.ocx, and foo.inf file. foosetup.exe, when run with the /q parameter, will install foo.ocx silently in the windows\occache directory.
  2. foo.inf has:
    [Add.Code]
    foo.ocx=foo.ocx

    [foo.ocx]
    Clsid={...}
    hook=hook1

    [hook1]
    run=%EXTRACT_DIR%\foosetup.exe /q

    [Version]
    ; This section is required for compatibility on both Windows 95 and Windows NT.
    Signature="$CHICAGO$"
    AdvancedInf=2.0

    When the Code Downloader sees the above INF, it processes the [Add.Code] section. When processing the foo.ocx section, it sees that the clsid (foo.ocx) is not registered/available on the client computer and so proceeds to execute the hook mentioned in the hook= key when it is hook1. Execution of hook1 is identical to the previous description of the hook as an unconditional hook. When only one component is in question, it doesn't make any difference whether marked conditional or unconditional as the whole code download was triggered because the CLASSID attribute in the OBJECT tag could not be found on the client computer. However, when installing a component that relies on some dependency that is separately installable by itself (such as MFC DLLs), it is good to use conditional hooks to install them.

    When mixing hooks and regular code download setups, read the section on "Order of processing and execution of INF".


Extending Internet Component Download Using OSD

Microsoft® Internet Explorer 3.0 introduced the Internet Component Download (ICD) mechanism. When visiting a Web page, ICD lets your browser pull down and install programs from the Internet automatically. This gave any software author or vendor the ability to package an application and place it on a server for download. But Internet Component Download, as implemented in Internet Explorer 3.0, was limited for the following reasons:

  • No support for Java class libraries
  • No support for stand-alone Java applications
  • INF files are not written according to any standard syntax or grammar
  • Old distribution units are limited in flexibility because they cannot adequately express software dependencies

Open Software Description (OSD) provides the Internet Component Download mechanism with the ability to download Java applications, Java packages, and ActiveX™ Controls. OSD also provides the ability to handle complex file dependencies that might be spread out over multiple distribution units on the Internet, and provides automatic installation of missing components.

For more information on Internet Component Download, see the Microsoft Internet Component Download documentation.

Supporting the Extended Functionality

Each distribution unit requires a single OSD file that contains the installation instructions for the application, just as an INF file does. The advantages of OSD are that it is more expressive than INF and it is being written in a standardized form.

An OSD file is supported in the following cases:

  • Inclusion in cabinet (CAB) files

    Exactly one file in the CAB can be an OSD file. The inclusion of an INF file in CAB is still supported for compatibility. Therefore, a CAB file should contain one OSD file, one INF file, or both an INF file and an OSD file. If both file types are present and your browser (for example, Microsoft Internet Explorer 4.0) knows about OSD files, the CAB is processed according to the following priorities:

    1. The parser looks inside the current CAB for the OSD file. If found, it is processed. It is also legal for the OSD file to reference the INF file. In this case, both files are processed, but notice that the OSD file is really in control here.
    2. If there is no OSD file present, the parser looks for an INF file to process.

    If your browser (for example, Internet Explorer 3.0) does not know about Open Software Description, the INF file is processed first because that is the only option.

  • In the CODEBASE attribute of the OBJECT element

    The CODEBASE attribute can now point to a stand-alone OSD file, which presents the same security/trust issue as having it point to a stand-alone INF file. Both of these are flat text and are not signable with Authenticode™ tools today, so component download will treat them as unsigned. Microsoft Internet Explorer will decline trust in the default browser security modes. One solution is to package the OSD file as the only file in a single CAB file and sign the CAB file.

OSD skeleton

All OSD files use the same basic skeleton. Each OSD file starts out with the Extensible Markup Language (XML) version identification and the documentation type declaration. The documentation type declaration includes the path to the OSD document type declaration (DTD) file, which describes all the elements that are supported by OSD.

The following example shows the XML version identification and documentation type declaration (with the actual location of the OSD DTD file).

<?XML version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd">

In many instances, the OSD file requires a richer vocabulary to describe the software or its dependencies. For example, describing native code or Java applications requires the elements defined in the Microsoft Internet Component Download DTD file. To include the Internet Component Download DTD file, an XML name space can be created that references that DTD file.

The following example shows how to create the XML name space msicd for the Internet Component Download DTD file.

<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

The XML name space allows any of the elements defined in the Microsoft Internet Component Download Reference to be used in the following format:

msicd::<element>

where <element> is an element described in the reference.

The main section of an OSD file begins and ends with the SOFTPKG tag. The three major sections enclosed inside SOFTPKG are used to express installation instructions for Java code, native code (meaning that the files are platform-dependent), and dependency code (one program is used by another). The basic OSD skeleton looks like this:

<?XML version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd">
<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

<SOFTPKG NAME="unique name of distribution" VERSION="4,0,5,0" STYLE="MSICD">
    <MSICD::JAVA> ... </MSICD::JAVA>
    <MSICD::NATIVECODE> ... </MSICD::NATIVECODE>
    <DEPENDENCY> ... </DEPENDENCY>
</SOFTPKG>

Integration with Java

Unlike INF files, OSD files support the inclusion of Java packages and stand-alone Java applications in a distribution unit. Specifically, this is done with the JAVA and PACKAGE tags.

<MSICD::JAVA>
    <PACKAGE NAME="com.ms.package.basic" VERSION="1,1,0,0">
    .
    .
    .
    </PACKAGE>
</MSICD::JAVA>

Relationship between OSD and INF

As mentioned previously, an OSD file is a markup tag file written according to XML syntax and grammar. An INF file is a file containing name-value pairs. Both serve the same purpose of specifying file dependency, program version number, and computer configuration information.

Using OSD to describe distribution units allows a cascading model, where one distribution unit can be dependent on others, which in turn can be dependent on others, and so on. In contrast, INF can express only one level of dependency. Allowing a component to specify dependencies at a high level allows installation details of dependencies to stay within their CABs versus cluttering the main OSD.

Pointing to an INF from the OSD

One can point to an INF in the same CAB as the OSD, for further processing of a subset of setup in the following manner. Setup capability, such as adding/modifying registry entries, advanced setup functionality in custom destination directories, and so on, is not available in the OSD syntax and so would require being pointed to by an accompanying INF file in the CAB.

<MSICD::NATIVECODE>
    <CODE NAME="Adventure Works Goodbye World"
    CLASSID="84D8E454-1000-1000-1000-45EA43332000"
    VERSION="1,0,0,0">
        <IMPLEMENTATION>
            <OS VALUE="win95" / >
            <CODEBASE FILENAME="goodby.inf" />
        </IMPLEMENTATION>
    </CODE>
</MSICD::NATIVECODE>

Sample OSD file sections

Building on the OSD Skeleton and Integration with Java sections, which contained small samples of what an OSD file looks like, this section will show examples of OSD usage.

Introducing the distribution

As previously mentioned, <SOFTPKG> and </SOFTPKG> are the opening and closing tags in the main section of an OSD file. This is analogous to the roles that <HTML> and </HTML> play in an HTML file. After the opening SOFTPKG, the TITLE and ABSTRACT elements are used to give a more verbose description of the distribution.

<?XML version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd">
<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

<SOFTPKG NAME="unique name or GUID" VERSION="1,0,0,0" STYLE="MSICD">
    <TITLE>My Very First Distribution!</TITLE>
    <ABSTRACT>This software distribution will install
        my Hello World program written in C++</ABSTRACT>
    .
    .
    .
</SOFTPKG>

Setting the file location

Use the CODEBASE element to tell the client browser where the files are located. The simplest case is if the files are already in the same CAB as the OSD file. If this is the case, don't use CODEBASE at all. Your browser will automatically look in the current CAB.

If the files are somewhere on the Internet, make CODEBASE point to that URL.

<CODEBASE HREF=<A HREF="http://www.server1.com/install-me.cab">
    http://www.server1.com/install-me.cab</A> / >

Handling different computer setups

Use the IMPLEMENTATION element to indicate what type of hardware your code requires. The following example shows that the program "Adventure Works Hello World" version 1.1 is available for three types of computer setups: a PC running Microsoft Windows® 95, a PC running Microsoft Windows NT®, and a Macintosh® running MacOS.

<MSICD::NATIVECODE>
    <CODE NAME="Adventure Works Hello World"
    CLASSID="84D8E454-0001-0001-0001-45EA43332000"
    VERSION="1,1,0,0" >

        <IMPLEMENTATION>
            <OS VALUE="win95" />
            <CODEBASE HREF="<A HREF="http://www.programs-r-us/hello-
                95.cab">http://www.programs-r-us/hello-95.cab</A>" />
        </IMPLEMENTATION>

        <IMPLEMENTATION>
            <OS VALUE="winnt" />
            <CODEBASE HREF="<A HREF="http://www.programs-r-us/hello-
                95.cab">http://www.programs-r-us/hello-nt.cab</A>" />
        </IMPLEMENTATION>

        <IMPLEMENTATION>
            <OS VALUE="mac" />
            <CODEBASE HREF="<A HREF="http://www.programs-r-us/hello-
                95.cab">http://www.programs-r-us/hello-mac.cab</A>" />
        </IMPLEMENTATION>
    </CODE>
</MSICD::NATIVECODE>

Notice that the CODEBASE in each IMPLEMENTATION grouping actually points to different files on the server.

Setting dependencies

Following the example above, what if Adventure Works comes out with a new program called "Adventure Works Goodbye World." However, Goodbye World is really an extension of Hello World, so you have to have Hello World on your computer before Goodbye World works properly.

The following sample instructs your computer to get Hello World from the location indicated, and then get Goodbye World.

<SOFTPKG NAME="Adventure Works Goodbye World" VERSION="1,0,0,0" STYLE="MSICD">
    <MSICD::NATIVECODE>
        <CODE NAME="Adventure Works Goodbye World"
        CLASSID="84D8E454-1000-1000-1000-45EA43332000"
        VERSION="1,0,0,0">

        <IMPLEMENTATION>
            <OS VALUE="win95" / >
            <CODEBASE HREF="<A HREF="http://www.programs-r-us/hello-
                95.cab">http://www.programs-r-us/goodbye-95.cab</A>" />
        </IMPLEMENTATION>
        </CODE>
    </MSICD::NATIVECODE>

    <DEPENDENCY ACTION="install">
        <SOFTPKG NAME="Adventure Works Hello World" VERSION="1,1,0,0">
            <IMPLEMENTATION>
                <OS VALUE="win95" />
            <CODEBASE HREF="<A HREF="http://www.programs-r-us/hello-
               95.cab">http://www.programs-r-us/hello-95.cab</A>" />
            </IMPLEMENTATION>
        </SOFTPKG>
    </DEPENDENCY>
</SOFTPKG>

Letting OSD worry about all the dependencies means that users don't have to. They only know that they want the Adventure Works Goodbye World application. If there's anything that Goodbye World needs, it will be installed in the fly.

There are two types of dependencies. Notice that the above example has ACTION="install" as an attribute-value of DEPENDENCY. The other type is ACTION="assert".

For example, a user might be running Goodbye World version 1.0 and like it. When version 1.1 comes out, the user decides not to install it and stays with version 1.0. When patches or updates come out specifically for version 1.1 (which the user doesn't have), how does OSD know not to bother the user with these advertisements that don't pertain to him or her? By using ACTION="assert". The following code section shows how OSD can make an advertisement of a version 1.1 patch only to those people running that version.

<SOFTPKG NAME="Vocabulary Patch for Goodbye World version 1.1 only" VERSION="1,0,0,0">

<!-- put the MSICD::NATIVECODE/CODE/IMPLEMENTATION/CODEBASE here for the Vocabulary Patch -->

<DEPENDENCY ACTION="assert">
    <SOFTPKG NAME="Adventure Works Goodbye World" VERSION="1,1,0,0">
        <IMPLEMENTATION>
            <OS VALUE="win95" />
        </IMPLEMENTATION>
    </SOFTPKG>
</DEPENDENCY>
</SOFTPKG>

Therefore, if a computer does not satisfy the prerequisites (having Microsoft Windows 95 and Goodbye World v1.1) indicated in the DEPENDENCY section, it completely ignores this SOFTPKG. Thus the user is not unnecessarily bothered.

More on general OSD structure

The OSD Skeleton section mentions that the OSD file has three main sections: Java, Nativecode, and Dependency. Not all three sections need to appear in an OSD file; only the sections that are used need to be included. For example, if a software author is distributing a stand-alone Java application, the Nativecode and Dependency sections probably won't appear in the OSD.

Notice that the Java, Nativecode, and Dependency items share a similar structure when used in OSD.

<MSICD::JAVA>

<PACKAGE ...>

<IMPLEMENTATION>

<CODEBASE .../>

</IMPLEMENTATION>

</PACKAGE>

</MSICD::JAVA>

<MSICD::NATIVECODE>

<CODE ...>

<IMPLEMENTATION>

<CODEBASE .../>

</IMPLEMENTATION>

</CODE>

</MSICD::NATIVECODE>

<DEPENDENCY>

<SOFTPKG ...>

<IMPLEMENTATION>

<CODEBASE ... />

</IMPLEMENTATION>

</SOFTPKG>

</DEPENDENCY>

Processing order

The DEPENDENCY items to be installed are triggered in the order in which they appear in the OSD file, and they come with no guarantee on the order in which they will actually get installed. The only guarantee is that the dependencies will be installed before the main component in the SOFTPKG tag gets installed. If specific ordering dependencies are necessary, the components should be arranged in a tree fashion as dependency nodes where one can be assured that nodes deepest in the tree will get installed first.

CODE items under NATIVECODE get processed in the order in which they appear in the OSD, but they get installed and registered in the reverse of their order in the OSD. Thus dependent files should be placed below the CODE items that depend on them being available/installed. When the OSD is mixed with an INF (see Internet Component Download INF document for details), the order of processing between CODE items and items in the [Add.Code] section in the INF is as if the CODE items appeared before items in [Add.Code]. Packages under JAVA are installed before CODE items under NATIVECODE.


Microsoft Internet Component Download Reference

This Internet Component Download reference contains all the elements defined by the Msicd.dtd file. These elements are used to describe distribution units in Open Software Description (OSD) files.

To use these elements in OSD files, an XML (Extensible Markup Language) name space must be created using the following line in the OSD file:

<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

To use the tags in the XML name space, prefix the tag with the name space name and two colons. For the JAVA tag, it would be used as follows:

<MSICD::JAVA>

All tags within name-space-defined tags must be defined in the name space and do not need to be prefixed with the name of the name space. Some of the elements defined in the Msicd.dtd file redefine elements that are defined in the Open Software Description Reference, so they can be used within the name space. For more information on OSD, see the Open Software Description (OSD) documentation.

MSICD Elements
CLASS CODE ICON ISBEAN
JAVA NAMESPACE NATIVECODE NEEDSTRUSTEDSOURCE
PACKAGE SYSTEM TYPELIB

MSICD Elements Also Defined in the Osd.dtd File
CODEBASE IMPLEMENTATION LANGUAGE OS
OSVERSION PROCESSOR SOFTPKG

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


CLASS

<CLASS
 CLASSID="{id}"
 NAME="classname"
>

Specifies a class within a Java package.

CLASSID="{id}"
Unique identifier for the class file. For Microsoft® Internet Explorer, this value must be in GUID format {hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}, where "h" is a hexadecimal digit.
NAME="classname"
Required. Name of the class file. The ".class" file extension is required.

Number of allowed occurrences: Any number
Parent elements Child elements
PACKAGE ICON
ISBEAN
TYPELIB

Example

<CLASS NAME="Browserbean" CLASSID="{01234567-89AB-CDEF-0123-456789ABCDEF}">
    <ISBEAN />
    <ICON FILENAME="Browser.ico" />
    <TYPELIB CLASSID="{01234567-89AB-CDEF-0123-456789ABCDEF}" />
</CLASS>

The end tag </CLASS> is required.

Applies To

OSD


CODE

<CODE
 CLASSID="{id}"
 NAME="classname"
 VERSION="a,b,c,d"
>

Describes a specific instance of platform native code.

CLASSID="{id}"
Unique identifier for the component. For Microsoft® Internet Explorer, this value must be in GUID format {hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}, where "h" is a hexadecimal digit.
NAME="classname"
Required. File name containing the native code. The file name, usually a *.ocx or *.dll file, should be specified without the full path.
VERSION="a,b,c,d"
Major, minor, custom, and build version numbers. The default value is "0,0,0,0".

Number of allowed occurrences: Any number
Parent elements Child elements
NATIVECODE IMPLEMENTATION

Example

<CODE NAME="mycontrol.ocx"
CLASSID="{01234567-89AB-CDEF-0123-456789ABCDEF}"
    VERSION="1,1,1,0">
    .
    .
    .
</CODE>

The end tag </CODE> is required.

Applies To

OSD


ICON

<ICON
 FILENAME="file"
/>

Specifies an icon to be associated with a particular JavaBean.

FILENAME="file"
Name of an icon file to be associated with a particular JavaBean.

Number of allowed occurrences: None or one
Parent elements | Child elements
CLASS | None

Example

<ICON FILENAME="Browser.ico"/>

Applies To

OSD


ISBEAN

<ISBEAN/>

Indicates that a particular class is a JavaBean rather than a regular Java class.

Number of allowed occurrences: None or one
Parent elements | Child elements
CLASS | None

Example

<ISBEAN />

Applies To

OSD


JAVA

<JAVA>

Specifies either a Java PACKAGE or application.

Number of allowed occurrences: Any number
Parent elements Child elements
SOFTPKG PACKAGE

The end tag </JAVA> is required.

Applies To

OSD


NAMESPACE

<NAMESPACE>

Defines a private name space for stand-alone Java applications.

Number of allowed occurrences: None or one
Parent elements | Child elements
JAVA | None

Example

<NAMESPACE>string</NAMESPACE>

The end tag </NAMESPACE> is required.

Applies To

OSD


NATIVECODE

<NATIVECODE>

Specifies one or more platform native code distributions.

Number of allowed occurrences: None or one
Parent elements Child elements
SOFTPKG CODE

The end tag </NATIVECODE> is required.

Applies To

OSD


NEEDSTRUSTEDSOURCE

<NEEDSTRUSTEDSOURCE/ >

Indicates that the immediate caller of classes in this package needs to be fully trusted.

Number of allowed occurrences: None or one
Parent elements | Child elements
PACKAGE | None

Applies To

OSD


PACKAGE

<PACKAGE
 NAME="name"
 VERSION="a,b,c,d"
>

Specifies a Java package or Java application.

NAME="name"
Required. Name of the Java package.
VERSION="a,b,c,d"
Major, minor, custom, and build version numbers.

Number of allowed occurrences: Any number
Parent elements Child elements
JAVA IMPLEMENTATION
CLASS

The end tag </PACKAGE> is required.

Applies To

OSD


SYSTEM

<SYSTEM />

When used as a child element of PACKAGE, indicates that the package contains system classes. System classes are fully trusted and have a single global instance per Java VM. Nonsystem classes have applet-level sandboxed security but may request other permissions if the distribution unit is signed.

When used as a child element of CODE, indicates that all files described by the CODE section should be installed in the designated system directory.

Number of allowed occurrences: None or one
Parent elements | Child elements
CODE | None
PACKAGE

Applies To

OSD


TYPELIB

<TYPELIB
 CLASSID="{id}"
/>

Specifies the type library file (*.tlb) for a particular JavaBean.

CLASSID="{id}"
Required. Unique identifier for the type library file associated with a particular JavaBean. For Microsoft® Internet Explorer, this file must be specified in GUID format {hhhhhhhh-hhhh-hhhh-hhhh-hhhhhhhhhhhh}, where "h" is a hexadecimal digit.

Number of allowed occurrences: None or one
Parent elements | Child elements
CLASS | None

Example

<TYPELIB CLASSID="{01234567-89AB-CDEF-0123-456789ABCDEF}" />

Applies To

OSD


Internet Explorer Address Book

Microsoft® Internet Explorer Address Book is an application and service that helps users keep track of people. It has a local database and a user interface for finding and editing information about people, and it can perform queries against network directory servers using the Internet-standard (LDAP) protocol. There are two ways users can access the Address Book from the Start Menu. They can select Programs, select Internet Explorer, and then select Address Book, or they can select Find and then select People. Other applications can also use Internet Explorer Address Book. For example, Microsoft Outlook Express uses Internet Explorer Address Book as its e-mail address book. Internet Explorer Address Book offers interfaces that enable other applications to directly use its database and its user interface services.

For more information on Internet Explorer Address Book, please see:

Internet Explorer Address Book File Location

Interfaces

Functions

Structures

Internet Explorer Address Book Files and Locations

The collection of interfaces available to the developer from Internet Explorer Address Book represents the programmatic techniques necessary to implement the functionality of Internet Explorer Address Book.

  • Registering Internet Explorer Address Book
  • Creating an Instance of Internet Explorer Address Book
  • Loading Wab32.dll at Run Time
  • Using Internet Explorer Address Book Files Under Internet Explorer 3.0x

Registering Internet Explorer Address Book

If you plan to have your application use Internet Explorer Address Book, your application must register itself for using the Wab32.dll as a shared DLL. This will prevent the Wab32.dll from being inadvertently uninstalled while your application is still using it. To do this, you need to increment the reference count of the Wab32.dll in the SharedDLLs section in the registry under HKLM\Software\Microsoft\Windows\CurrentVersion\SharedDLLs.

First get the full path of the installed Wab32.dll from:

HKLM\Software\Microsoft\WAB\DLLPath

The default value under this key gives the path of any WAB DLL installed on the computer. (This DLL path is defined in Wabapi.h as WAB_DLL_PATH_KEY; if you are including Wabapi.h in your application, just use the defined WAB_DLL_PATH_KEY symbol as the name of the key to open.) If this key does not exist, the system has a pre-Internet Explorer 4.0 version of Internet Explorer Address Book and you do not need to do any reference counting on the DLL.

If the above key exists, look under:

HKLM\Software\Microsoft\Windows\CurrentVersion\SharedDLLs

Look for the value of <Full WAB32 Path>. If this value doesn't exist, create it using the registry API. This is a DWORD value. The content of this value is a reference count representing the number of clients registered to use Internet Explorer Address Book. You should read the reference count from the value, increment it by one, and then save the incremented value back to the registry.

Loading Wab32.dll at Run Time

On systems that have Internet Explorer 3.0x or earlier, the Wab32.dll file exists in the windows\system directory. However, on Internet Explorer 4.0 and later platforms, Wab32.dll exists elsewhere, and your application cannot assume it will be able to load the DLL by just using LoadLibrary("wab32.dll"). You should also not statically link your application to Wab32.dll because it might not necessarily be on the path.

Under Internet Explorer 4.0, Wab32.dll is set in the registry in the following location:

HKLM\Software\Microsoft\WAB\DLLPath

The only reason to call LoadLibrary("wab32.dll") is if this key does not exist or if the path set in this key is invalid.

The following sample code shows how to run LoadLibrary on Internet Explorer Address Book.

const static TCHAR lpszWABRegPathKey[] = TEXT("Software\\Microsoft\\WAB\\DLLPath");
const static TCHAR lpszWABDll[] = TEXT("WAB32.dll");

// GetWABDllPath - loads the WAB DLL path from the registry
// szPath - ptr to buffer
// cb - sizeof buffer
//
void GetWABDllPath(LPTSTR szPath, ULONG cb)
{
    DWORD  dwType = 0;
    ULONG  cbData = cb;
    HKEY hKey = NULL;
    if(szPath)
    {
        *szPath = '\0';
        if (ERROR_SUCCESS == RegOpenKeyEx( HKEY_LOCAL_MACHINE,
            lpszWABRegPathKey, 0, KEY_READ, &hKey))
            RegQueryValueEx( hKey, "", NULL, &dwType, (LPBYTE) szPath, &cbData);
    }
    if(hKey) RegCloseKey(hKey);
    return;
}

// LoadLibrary_WABDll() - Load the WAB library based on the WAB DLL path
//
HINSTANCE LoadLibrary_WABDll()
{
    TCHAR  szWABDllPath[MAX_PATH];
    HINSTANCE hinst = NULL;

    GetWABDllPath(szWABDllPath, sizeof(szWABDllPath));

    return(hinst = LoadLibrary( (lstrlen(szWABDllPath)) ? szWABDllPath : lpszWABDll ));
}

Creating an Instance of Internet Explorer Address Book

To create and initialize the first instance of Internet Explorer Address Book, use the following sample code as a guide.

LPWABOPEN lpfnWABOpen = NULL;   // defined in WABAPI.H
HINSTANCE hinstWAB = NULL;
//
// Initialize Internet Explorer Address Book and get an instance of IWABObject and IAddrBook
//
HRESULT InitWAB(LPWABOBJECT * lppWABObject,
   LPADRBOOK * lppAdrBook)
{
    HRESULT hr = E_FAIL;
    hinstWAB = LoadLibrary_WABDll();
  if(hinstWAB)
    {
    lpfnWABOpen = (LPWABOPEN) GetProcAddress(hinstWAB, "WABOpen");
  if(lpfnWABOpen)
    hr = lpfnWABOpen(lppAdrBook, lppWABObject, NULL, 0);
    }
 return hr;
}

Using Internet Explorer Address Book Files Under Internet Explorer 3.0x

In Internet Explorer 3.0x installations, the default location of Wab32.dll is in the Windows system directory.

<Windows System Directory>\WAB32.dll

When Internet Explorer 4.0 is installed, the file Wab32.dll is renamed Wab32.ie3 so the old version of the file will not conflict with the newer versions installed by Internet Explorer 4.0 setup. Should it become necessary to uninstall, the old files are given back their original names so that users can revert back to their exact pre-Internet Explorer 4.0 settings.

An application that will be working with Wab32.dll under both Internet Explorer 4.0 and Internet Explorer 3.0x should not rely on being able to find Wab32.dll on the path. To see how you can write a single piece of code that can load the WAB32.dll library under both Internet Explorer 4.0 and Internet Explorer 3.0, refer to the sample code from the previous section, Loading Wab32.dll at Run Time.


Internet Explorer Address Book Interfaces

Internet Explorer Address Book exports one API, WABOpen. This API gives access to the address book through a number of object interfaces. The root interface is IAddrBook, which is a subset of the MAPI implementation of IAddrBook.

These interfaces are based on the address book interface exposed by Extended MAPI 1.0, but Internet Explorer Address Book does not use or require MAPI in any way. OLE is used only for its user interface functionality, such as drag and drop and shell integration. Nothing in OLE is loaded until it is needed.

The IUnknown interface allows clients to get pointers to other interfaces on a given object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other COM interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.

In a future release, these objects may be exposed to applications that want an OLE Automation interface. For additional information on the IUnknown interface methods, see the Platform SDK.

The following sections describe the Internet Explorer Address Book interfaces and methods.

  • IABContainer
  • IABTable
  • IAddrBook
  • IDistList
  • IMailUser
  • IWABObject


IABContainer

The methods that are included within the IABContainer interface provide the mechanisms for creating, deleting, searching, and modifying address book entries. The organization of the method list for IABContainer is arranged in v-table order.
IABContainer methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames
GetContentsTable
GetHierarchyTable
OpenEntry
SetSearchCriteria
GetSearchCriteria
CreateEntry
CopyEntries
DeleteEntries
ResolveNames


IABContainer::CopyEntries IABContainer::CopyEntries *
  * Previous Topic: IABContainer
  * Next Topic: IABContainer::CopyProps

IABContainer::CopyEntries

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::CopyProps IABContainer::CopyProps *
  * Previous Topic: IABContainer::CopyEntries
  * Next Topic: IABContainer::CopyTo

IABContainer::CopyProps

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::CopyTo IABContainer::CopyTo *
  * Previous Topic: IABContainer::CopyProps
  * Next Topic: IABContainer::CreateEntry

IABContainer::CopyTo

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::CreateEntry

HRESULT CreateEntry(
    ULONG       cbEntryID,
    LPENTRYID   lpEntryID,
    ULONG       ulCreateFlags,
    LPMAPIPROP  lppMAPIPropEntry
);

Creates a new entry in the address book container. Internet Explorer Address Book supports creating new address book objects IDistList for a distribution list and IMailUser for a messaging user. Internet Explorer Address Book might support creation of subcontainers in a future version.

  • Returns S_OK if successful.
cbEntryID
Size, in bytes, of the existing entry identifier to copy from, in the lpEntryID parameter.
lpEntryID
Entry identifier of the object to copy from.
ulCreateFlags
Bitmask of flags that control how entry creation is performed. The following flags can be set:
CREATE_CHECK_DUP_LOOSE
Indicates a loose level should be used for duplicate entry checking, which returns more matches than setting a strict level with the CREATE_CHECK_DUP_STRICT flag. For example, a provider can define a loose match as any two entries having the same display name.
CREATE_CHECK_DUP_STRICT
Indicates a strict level should be used for duplicate entry checking, which returns fewer matches than setting a loose level with the CREATE_CHECK_DUP_LOOSE flag. For example, a provider can define a strict match as any two entries having the same display name and messaging address.
CREATE_REPLACE
Indicates that duplicate entries replace existing entries within a container.
lppMAPIPropEntry
Returned property interface to a new object.

These flags are valid only for the instance of the object returned by CreateEntry. There is no way in the API to get the SetProps or the SaveChanges method to check for duplicates on an object returned by OpenEntry. To do duplicate checking on SaveChanges of an object returned by OpenEntry, the caller would have to do the following:

  1. Modify any of the name fields in the user interface: PR_SURNAME, PR_GIVEN_NAME, PR_COMPANY_NAME, or PR_DISPLAYNAME.
  2. Delete the old contact.
  3. Use CreateEntry to create a new entry with the CREATE_CHECK_DUP_LOOSE flag, set the properties, and save the changes. On failure, restore the original entry.

Back to top


IABContainer::DeleteEntries

HRESULT DeleteEntries(
    LPENTRYLIST   lpEntries,
    ULONG         ulFlags
);

Removes one or more entries from the address book container.

  • Returns S_OK if successful.
lpEntries
ENTRYLIST structure containing identifiers of entries to be deleted.
ulFlags
Reserved; must be zero.

Back to top


IABContainer::DeleteProps IABContainer::DeleteProps *
  * Previous Topic: IABContainer::DeleteEntries
  * Next Topic: IABContainer::GetContentsTable

IABContainer::DeleteProps

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetContentsTable

HRESULT GetContentsTable(
    ULONG    ulFlags,
    LPMAPITABLE FAR *  lppTable
);

Returns a pointer to the contents table of the container.

  • Returns one of the following values:
    S_OK | The contents table was successfully retrieved.
    MAPI_E_BAD_CHARWIDTH | Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
    MAPI_E_NO_SUPPORT | The container has no contents and cannot provide a contents table.
ulFlags
Bitmask of flags that provide the ability to specify the returned text type. Can be one of the following:
MAPI_DEFERRED_ERRORS | Not supported by Internet Explorer Address Book.
MAPI_UNICODE | Indicates the returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format. Not supported in the first version of Internet Explorer Address Book.
lppTable
Address of the table object containing the contents table.

Back to top


IABContainer::GetHierarchyTable IABContainer::GetHierarchyTable *
  * Previous Topic: IABContainer::GetContentsTable
  * Next Topic: IABContainer::GetIDsFromNames

IABContainer::GetHierarchyTable

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetIDsFromNames IABContainer::GetIDsFromNames *
  * Previous Topic: IABContainer::GetHierarchyTable
  * Next Topic: IABContainer::GetLastError

IABContainer::GetIDsFromNames

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetLastError IABContainer::GetLastError *
  * Previous Topic: IABContainer::GetIDsFromNames
  * Next Topic: IABContainer::GetNamesFromIDs

IABContainer::GetLastError

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetNamesFromIDs IABContainer::GetNamesFromIDs *
  * Previous Topic: IABContainer::GetLastError
  * Next Topic: IABContainer::GetPropList

IABContainer::GetNamesFromIDs

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetPropList IABContainer::GetPropList *
  * Previous Topic: IABContainer::GetNamesFromIDs
  * Next Topic: IABContainer::GetProps

IABContainer::GetPropList

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetProps IABContainer::GetProps *
  * Previous Topic: IABContainer::GetPropList
  * Next Topic: IABContainer::GetSearchCriteria

IABContainer::GetProps

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::GetSearchCriteria IABContainer::GetSearchCriteria *
  * Previous Topic: IABContainer::GetProps
  * Next Topic: IABContainer::OpenEntry

IABContainer::GetSearchCriteria

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::OpenEntry

HRESULT OpenEntry(
    ULONG         cbEntryID,
    LPENTRYID     lpEntryID,
    LPCIID        lpInterface,
    ULONG         ulFlags,
    ULONG FAR     *lpulObjType,
    LPUNKNOWN FAR *lppUnk
);

Opens a child container object contained in the open container and returns a pointer to the object to provide further access.

  • Returns S_OK if successful.
cbEntryID
Count of bytes in the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
Address of the entry identifier of the object to open. If lpEntryID is set to NULL, the top-level container in the container's hierarchy is opened.
lpInterface
Address of the interface identifier (IID) representing the interface to be used to access the object. Passing NULL results in the identifier for the object's standard interface being returned. For messages, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.
ulFlags
Bitmask of flags that control how the object is opened. The following flags can be used:
MAPI_BEST_ACCESS | Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.
MAPI_DEFERRED_ERRORS | Not supported by Internet Explorer Address Book at this time.
MAPI_MODIFY | Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.
lpulObjType
Address of the opened object's type.
lppUnk
Address of a pointer to the interface implementation to use to access the open object.

Back to top


IABContainer::OpenProperty IABContainer::OpenProperty *
  * Previous Topic: IABContainer::OpenEntry
  * Next Topic: IABContainer::ResolveNames

IABContainer::OpenProperty

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::ResolveNames

HRESULT ResolveNames(
    LPSPropTagArray    lpPropTagArray,
    ULONG              ulFlags,
    LPADRLIST          lpAdrList,
    LPFlagList         lpFlagList
);

Resolves entries against the address book container.

  • Returns S_OK if successful.
lpPropTagArray
SPropTagArray structure that specifies the set of properties to be included in the returned ADRLIST structure. Pass NULL to return the default columns.
ulFlags
MAPI_UNICODE flag, which indicates the returned strings of the default column set are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Note Must be zero in the first version of Internet Explorer Address Book.

lpAdrList
Input-output parameter that on input points to an ADRLIST structure containing the address list of entries whose names need to be resolved. On output, this parameter returns the list of resolved names.
lpFlagList
Input-output parameter containing an array of flags; each flag corresponds to an entry in lpAdrList and provides the name-resolution status for that particular entry. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:
MAPI_AMBIGUOUS | Indicates that the corresponding entry is resolved, but that it did not resolve to a unique entry identifier. If this flag is returned, other containers should ignore this entry when the lpAdrList is passed to them for further name resolution.
MAPI_RESOLVED | Indicates that the corresponding entry has been resolved to a unique entry identifier. If this flag is returned, other containers should ignore this entry in further resolution.
MAPI_UNRESOLVED | Indicates that the corresponding entry is unresolved. Another container can attempt to resolve this entry.

This method takes the address list passed in lpAdrList and tries to resolve all the entries that have their corresponding MAPI_UNRESOLVED flag set in lpFlagList. Entries in lpAdrList that lack the PR_ENTRYID property are considered unresolved.

The array of flags this method returns in lpFlagList is used to track the results of the name resolution operation; the array shows for each entry name whether it is resolved or unresolved or matches more than one entry. If, after looking at an unresolved entry, a container can match that entry uniquely, ResolveNames sets the flag for that entry in lpFlagList to MAPI_RESOLVED and adds the PR_ENTRYID property for that entry to that entry's ADRENTRY structure in the address list in lpAdrList. If a container contains more than one entry that matches a given unresolved entry, ResolveNames sets the flag for the unresolved entry in lpFlagList to MAPI_AMBIGUOUS and leaves that entry's ADRENTRY alone.

If the ResolveNames method is unable to return all the properties requested for an unresolved entry, and these properties don't exist in the ADRENTRY structure passed in, it sets the property type of each property not returned to PT_ERROR. Any property columns that are already included for an entry are retained if that entry is resolved.

Note The ADRENTRY items in ADRLIST should be separately allocated, not allocated with AllocateMore. When ResolveNames replaces an entry, it expects to free the ADRENTRY structure by using FreeBuffer and allocate a new one by using AllocateBuffer.

Back to top


IABContainer::SaveChanges IABContainer::SaveChanges *
  * Previous Topic: IABContainer::ResolveNames
  * Next Topic: IABContainer::SetProps

IABContainer::SaveChanges

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::SetProps IABContainer::SetProps *
  * Previous Topic: IABContainer::SaveChanges
  * Next Topic: IABContainer::SetSearchCriteria

IABContainer::SetProps

Currently not implemented in Internet Explorer Address Book.

Back to top


IABContainer::SetSearchCriteria IABContainer::SetSearchCriteria *
  * Previous Topic: IABContainer::SetProps
  * Next Topic: IABTable

IABContainer::SetSearchCriteria

Currently not implemented in Internet Explorer Address Book.

Back to top


IABTable

This interface is based upon the IMAPITable interface. This interface is used for contents tables of Internet Explorer Address Book containers and distribution lists. The organization of the method list for IABTable is arranged in v-table order.
IABTable methods
GetLastError
Advise
Unadvise
GetStatus
SetColumns
QueryColumns
GetRowCount
SeekRow
SeekRowApprox
QueryPosition
FindRow
Restrict
CreateBookmark
FreeBookmark
SortTable
QuerySortOrder
QueryRows
Abort
ExpandRow
CollapseRow
WaitForCompletion
GetCollapseState
SetCollapseState


IABTable::Abort IABTable::Abort *
  * Previous Topic: IABTable
  * Next Topic: IABTable::Advise

IABTable::Abort

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::Advise IABTable::Advise *
  * Previous Topic: IABTable::Abort
  * Next Topic: IABTable::CollapseRow

IABTable::Advise

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::CollapseRow IABTable::CollapseRow *
  * Previous Topic: IABTable::Advise
  * Next Topic: IABTable::CreateBookmark

IABTable::CollapseRow

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::CreateBookmark

HRESULT CreateBookmark(
    BOOKMARK FAR * lpbkPosition
);

Creates the address of the current position of the table cursor so a client can return to that position even when the table is updated. The method that calls this method must clean up by freeing the bookmark with FreeBookmark.

  • Returns S_OK if successful, or MAPI_E_UNABLE_TO_COMPLETE if the requested operation could not be completed.
lpbkPosition
Address of the returned bookmark's 32-bit bookmark value.

Back to top


IABTable::ExpandRow IABTable::ExpandRow *
  * Previous Topic: IABTable::CreateBookmark
  * Next Topic: IABTable::FindRow

IABTable::ExpandRow

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::FindRow

HRESULT FindRow(
    LPSRestriction  lpRestriction,
    BOOKMARK  BkOrigin,
    ULONG     ulFlags
);

Find the next row in a table that contains a property matching the specified criteria.

  • Returns one of the following values:
    S_OK | The find operation was successful.
    MAPI_E_INVALID_BOOKMARK | The bookmark in the BkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.
    MAPI_E_NOT_FOUND | No rows were found that matched the restriction.
    MAPI_W_POSITION_CHANGED | The call succeeded, but the bookmark used in the operation is no longer set at the same row as when it was last used; if the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro.
lpRestriction
Address of an SRestriction structure that describes the search criteria.
BkOrigin
Bookmark identifying the row where FindRow should begin its search. A bookmark can be created using the CreateBookmark method, or one of the following predefined values can be passed:
BOOKMARK_BEGINNING | Searches from the beginning of the table
BOOKMARK_CURRENT | Searches from the row in the table where the cursor is located.
BOOKMARK_END | Searches from the end of the table.
ulFlags
Bitmask of flags that control the direction of the search. The following flag can be set:
DIR_BACKWARD Searches backward from the row identified by the bookmark.

Back to top


IABTable::FreeBookmark

HRESULT FreeBookmark(
    BOOKMARK bkPosition
);

Provides the ability to free a bookmark that was created by CreateBookmark.

  • Returns S_OK if successful, or MAPI_E_INVALID_BOOKMARK if the specified bookmark does not exist.
bkPosition
Address of the bookmark to free.

Back to top


IABTable::GetCollapseState IABTable::GetCollapseState *
  * Previous Topic: IABTable::FreeBookmark
  * Next Topic: IABTable::GetLastError

IABTable::GetCollapseState

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::GetLastError IABTable::GetLastError *
  * Previous Topic: IABTable::GetCollapseState
  * Next Topic: IABTable::GetRowCount

IABTable::GetLastError

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::GetRowCount

HRESULT GetRowCount(
    ULONG  ulFlags,
    ULONG  FAR *lpulCount
);

Returns the total number of rows in a table view.

  • Returns one of the following values:
    S_OK | The row count was successfully returned.
    MAPI_E_BUSY | Another operation is in progress that prevents the row count retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
    MAPI_E_NO_SUPPORT | The table cannot calculate the number of rows.
    MAPI_W_APPROX_COUNT | The call succeeded, but an approximate row count was returned because the exact row count could not be determined, possibly due to memory constraints. To test for this warning, use the FAILED macro.
ulFlags
Reserved; must be zero.
lpulCount
Address of the number of rows in the table.

Back to top


IABTable::GetStatus IABTable::GetStatus *
  * Previous Topic: IABTable::GetRowCount
  * Next Topic: IABTable::QueryColumns

IABTable::GetStatus

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::QueryColumns

HRESULT QueryColumns(
    ULONG  ulFlags,
    LPSPropTagArray  FAR * lpPropTagArray
);

Returns a list of columns for the table.

  • Returns one of the following values:
    S_OK | The column set was successfully returned.
    MAPI_E_BUSY | Another operation is in progress that prevents the column set retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
ulFlags
Bitmask of flags that indicate which column set should be returned. The following flag can be set:
TBL_ALL_COLUMNS Returns all available columns.
lpPropTagArray
Address of an SPropTagArray structure containing the property tags for the column set.

Back to top


IABTable::QueryPosition

HRESULT QueryPosition(
    ULONG FAR * lpulRow,
    ULONG FAR * lpulNumerator,
    ULONG FAR * lpulDenominator
);

Gets the current table cursor position, based on a fractional value.

  • Returns S_OK if the method returned valid values in lpulRow, lpulNumerator, and lpulDenominator.
lpulRow
Address of the value that contains the current row number. The row numbers are zero-based in position; row zero is the first row.
lpulNumerator
Address of the value that contains the fractional numerator part of the table position.
lpulDenominator
Address of the value that contains the fractional denominator part of the table position. The lpulDenominator parameter cannot be zero.

Back to top


IABTable::QueryRows

HRESULT QueryRows(
    LONG lRowCount,
    ULONG ulFlags,
    LPSRowSet FAR * lppRows
);

Gets rows of data from a table.

  • Returns one of the following values:
    S_OK | The rows were successfully returned.
    MAPI_E_BUSY | Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
    MAPI_E_INVALID_PARAMETER | The lRowCount parameter is set to zero.
lRowCount
Number of rows requested. If positive, rows are read starting at the current position and reading forward. If negative, the cursor position moves backward the indicated number of rows, then reads in forward order.
ulFlags
Flags specifying advancement of the cursor operation. TBL_NOADVANCE prevents the cursor from advancing. Default is that the cursor will advance past the last returned row.
lppRows
Returned SRowSet structure. This buffer must be freed by the caller according to the rules specified in the following comments.

The cRows member in the SRowSet structure returned in lppRows indicates the number of rows returned. If zero rows are returned, there are no more rows to return.

Freeing of the SRowSet structure returned by QueryRows is unusual in that each row must be freed independently; the rows are not allocated with AllocateMore. Memory used for the properties held in the SRow structures that make up the SRowSet in the lppRows parameter and for the rgPropVals members of the ADRENTRY structure is separately allocated for each row, and memory for each row must be separately freed by a call to MAPIFreeBuffer. The SRowSet structure itself must also be freed. Thus, to free all the memory returned for 10 rows requires 11 calls to FreeBuffer. This process might seem complex, but freeing memory for each row separately enables implementations to free different rows at different times. However, when a call to QueryRows returns zero, indicating the beginning or end of the table, only the SRowSet structure itself needs to be freed.

Back to top


IABTable::QuerySortOrder

HRESULT QuerySortOrder(
    LPSSortOrderSet FAR * lppSortCriteria
);

Retrieves the current sort order for the table.

  • Returns one of the following values:
    S_OK | The current sort order was successfully returned.
    MAPI_E_BUSY | Another operation is in progress that prevents the sort order retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
lppSortCriteria
Address of the SSortOrderSet structure holding the current sort order.

Back to top


IABTable::Restrict

HRESULT Restrict(
    lpRestriction,
    ulFlags
);

Applies a restriction to a table, reducing the rows visible to only those matching the restriction criteria.

  • Returns one of the following values:
    S_OK | The filter was successfully applied.
    MAPI_E_BUSY | Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
    MAPI_E_TOO_COMPLEX | The table cannot perform the operation because the particular filter pointed to by the lpRestriction parameter is too complicated.
lpRestriction
Address of an SRestriction structure defining the conditions of the restriction. Passing NULL removes the current restriction.
ulFlags
Flags specifying asynchronous operation. For Internet Explorer Address Book, this value must be zero.

Back to top


IABTable::SeekRow

HRESULT SeekRow(
    BOOKMARK bkOrigin,
    LONG lRowCount,
    LONG FAR * lplRowsSought
);

Moves the table cursor to a specific position.

  • Returns one of the following values:
    S_OK | The seek operation was successful.
    MAPI_E_BUSY | Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
    MAPI_E_INVALID_BOOKMARK | The bookmark specified in the bkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested.
    MAPI_W_POSITION_CHANGED | The call succeeded, but the bookmark specified in the bkOrigin parameter is no longer set at the same row as when it was last used. If the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro.
bkOrigin
Bookmark identifying the starting position for the seek operation. A bookmark can be created using the CreateBookmark method, or one of the following predefined values can be passed:
BOOKMARK_BEGINNING | Starts the seek operation from the beginning of the table.
BOOKMARK_CURRENT | Starts the seek operation from the row in the table where the cursor is located.
BOOKMARK_END | Starts the seek operation from the end of the table.
lRowCount
Signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.
lplRowsSought
If lplRowsSought is a valid pointer on input, on output it points to the number of rows that were processed in the seek operation. If lplRowsSought is NULL on input, the indication is the caller is not interested in the number of rows processed, and nothing is returned on output.

Back to top


IABTable::SeekRowApprox

HRESULT SeekRowApprox(
    ULONG ulNumerator,
    ULONG ulDenominator
);

Moves the cursor to an approximate fractional position in a table.

  • Returns one of the following values:
    S_OK | The seek operation was successful.
    MAPI_E_BUSY | Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
ulNumerator
Numerator of the fraction representing the table position. If the ulNumerator parameter is zero, it points to the beginning of the table regardless of the denominator value. If ulNumerator is equal to the ulDenominator parameter, the cursor is positioned after the last table row.
ulDenominator
Denominator of the fraction representing the table position. The ulDenominator parameter cannot be zero.

Back to top


IABTable::SetCollapseState IABTable::SetCollapseState *
  * Previous Topic: IABTable::SeekRowApprox
  * Next Topic: IABTable::SetColumns

IABTable::SetCollapseState

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::SetColumns

HRESULT SetColumns(
    LPSPropTagArray lpPropTagArray,
    ULONG ulFlags
);

Defines the order of property values, and the order of properties to appear as columns in a table.

  • Returns one of the following values:
    S_OK | The column setting operation was successful.
    MAPI_E_BUSY | Another operation is in progress that prevents the column setting operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
lpPropTagArray
Address of an SPropTagArray structure containing a counted array of property tags corresponding to the desired table columns. The lpPropTagArray parameter cannot be set to NULL; every table must have one column as a minimum.
ulFlags
Flags specifying asynchronous operation. For Internet Explorer Address Book, this value must be zero.

Back to top


IABTable::SortTable

HRESULT SortTable(
    LPSSortOrderSet lpSortCriteria,
    ULONG ulFlags
);

Sorts the table rows based on the sort criteria provided.

  • Returns one of the following values:
    S_OK | The sort operation was successful.
    MAPI_E_BUSY | Another operation is in progress that prevents the sort operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
    MAPI_E_NO_SUPPORT | The table does not support the type of sorting requested.
    MAPI_E_TOO_COMPLEX | The table cannot perform the operation because the particular sort criteria pointed to by the lpSortCriteria parameter is too complicated.
lpSortCriteria
Address of an SSortOrderSet structure that contains the sort criteria. Passing an SSortOrderSet structure containing zero columns indicates that sorting the table is not desired.
ulFlags
Must be zero in Internet Explorer Address Book.

Back to top


IABTable::Unadvise IABTable::Unadvise *
  * Previous Topic: IABTable::SortTable
  * Next Topic: IABTable::WaitForCompletion

IABTable::Unadvise

Currently not implemented by Internet Explorer Address Book.

Back to top


IABTable::WaitForCompletion IABTable::WaitForCompletion *
  * Previous Topic: IABTable::Unadvise
  * Next Topic: IAddrBook

IABTable::WaitForCompletion

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook

The IAddrBook interface supports access to the Internet Explorer Address Book and includes operations such as displaying common dialog boxes, opening containers, messaging users (contacts) and distribution lists (groups) in the address book, and performing name resolution. The organization of the method list for IAddrBook is arranged in v-table order.

IAddrBook methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames
OpenEntry
CompareEntryIDs
Advise
Unadvise
CreateOneOff
NewEntry
ResolveName
Address
Details
RecipOptions
QueryDefaultRecipOpt
GetPAB
SetPAB
GetDefaultDir
SetDefaultDir
GetSearchPath
SetSearchPath
PrepareRecips


IAddrBook::Address

HRESULT Address(
    ULONG FAR * lpulUIParam
    LPADRPARM lpAdrParms,
    LPADRLIST FAR * lppAdrList
);

Displays user interface to browse the address book contents and to select recipients from the address book. The UI behavior is specified by a number of flags and parameters in lpAdrParms. Internet Explorer Address Book will not support some of the customization features of the MAPI IAddrBook::Address method. Internet Explorer Address Book will also not support the MAPI Send Options dialog button.

  • Returns S_OK if successful.
lpulUIParam
Input-output parameter containing the handle of the parent window of the dialog box. On input, a window handle must always be passed. On output, if the DIALOG_SDI flag is set in the lpAdrParms parameter's ADRPARM structure, the window handle of the modeless dialog box is returned.
lpAdrParms
Input-output parameter pointing to an ADRPARM structure that controls the presentation and behavior of the addressing dialog box.
lppAdrList
Input-output parameter that on input points to a variable holding a pointer to an ADRLIST structure holding the current recipient list. On output, the lppAdrList parameter points to a variable where the pointer to an ADRPARM structure updated by IAddrBook::Address is stored. lppAdrList can be NULL on input.

Back to top


IAddrBook::Advise IAddrBook::Advise *
  * Previous Topic: IAddrBook::Address
  * Next Topic: IAddrBook::CompareEntryIDs

IAddrBook::Advise

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::CompareEntryIDs IAddrBook::CompareEntryIDs *
  * Previous Topic: IAddrBook::Advise
  * Next Topic: IAddrBook::CopyProps

IAddrBook::CompareEntryIDs

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::CopyProps IAddrBook::CopyProps *
  * Previous Topic: IAddrBook::CompareEntryIDs
  * Next Topic: IAddrBook::CopyTo

IAddrBook::CopyProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::CopyTo IAddrBook::CopyTo *
  * Previous Topic: IAddrBook::CopyProps
  * Next Topic: IAddrBook::CreateOneOff

IAddrBook::CopyTo

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::CreateOneOff

HRESULT CreateOneOff(
    LPTSTR lpszName,
    LPTSTR lpszAdrType,
    LPTSTR lpszAddress,
    ULONG ulFlags,
    ULONG FAR * lpcbEntryID,
    LPENTRYID FAR * lppEntryID
);

Creates an entry identifier for a one-off address.

  • Returns S_OK if the one-off entry identifier was created successfully.
lpszName
Pointer to the display name of the recipient. The lpszName parameter can be NULL. the PR_DISPLAY_NAME property. The lpszName parameter can be NULL.
lpszAdrType
Pointer to the address type of the recipient, such as FAX or SMTP. The lpszAdrType parameter cannot be NULL.
lpszAddress
Pointer to the address of the recipient. The lpszAddress parameter cannot be NULL.
ulFlags
Bitmask of flags that affect the one-off recipient. The following flags can be set:
MAPI_SEND_NO_RICH_INFO | Indicates the recipient cannot handle formatted message content. If MAPI_SEND_NO_RICH_INFO is set, MAPI sets the recipient's PR_SEND_RICH_INFO property to FALSE. If MAPI_SEND_NO_RICH_INFO is not set, MAPI sets this property to TRUE unless the recipient's messaging address pointed to by lpszAddress is interpreted to be an Internet address. In this case, MAPI sets PR_SEND_RICH_INFO to FALSE.
MAPI_UNICODE | Displays the name, address type, and address are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.
lpcbEntryID
Address of the count of bytes in the entry identifier pointed to by the lppEntryID parameter.
lppEntryID
Address of a pointer to the entry identifier for the one-off recipient.

Back to top


IAddrBook::DeleteProps IAddrBook::DeleteProps *
  * Previous Topic: IAddrBook::CreateOneOff
  * Next Topic: IAddrBook::Details

IAddrBook::DeleteProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::Details

HRESULT Details(
    ULONG FAR * lpulUIParam,
    LPFNDISMISS lpfnDismiss,
    LPVOID lpvDismissContext,
    ULONG cbEntryID,
    LPENTRYID lpEntryID,
    LPFNBUTTON lpfButtonCallback,
    LPVOID lpvButtonContext,
    LPTSTR lpszButtonText,
    ULONG ulFlags
);

Displays a dialog box showing details for, and allowing editing of, a particular entry in Internet Explorer Address Book. Internet Explorer Address Book does not support the passing in a callback function for buttons through the lpfButtonCallback parameter.

  • Returns S_OK if the dialog box was successfully displayed for the address book entry.
lpulUIParam
Returned HWND of the parent window of the returned dialog box.
lpfnDismiss
DISMISSMODELESS function pointer. This function is called when the modeless dialog box is dismissed. (Not implemented at this time.)
lpvDismissContext
Data passed to lpfnDismiss.
cbEntryID
Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
Address of an entry identifier for the entry for which details are displayed.
lpfButtonCallback
Not supported by Internet Explorer Address Book; must be NULL.
lpvButtonContext
Not supported by Internet Explorer Address Book; must be NULL.
lpszButtonText
Not supported by Internet Explorer Address Book; must be NULL.
ulFlags
Not supported by Internet Explorer Address Book; must be zero.

Back to top


IAddrBook::GetDefaultDir IAddrBook::GetDefaultDir *
  * Previous Topic: IAddrBook::Details
  * Next Topic: IAddrBook::GetIDsFromNames

IAddrBook::GetDefaultDir

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetIDsFromNames IAddrBook::GetIDsFromNames *
  * Previous Topic: IAddrBook::GetDefaultDir
  * Next Topic: IAddrBook::GetLastError

IAddrBook::GetIDsFromNames

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetLastError IAddrBook::GetLastError *
  * Previous Topic: IAddrBook::GetIDsFromNames
  * Next Topic: IAddrBook::GetNamesFromIDs

IAddrBook::GetLastError

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetNamesFromIDs IAddrBook::GetNamesFromIDs *
  * Previous Topic: IAddrBook::GetLastError
  * Next Topic: IAddrBook::GetPAB

IAddrBook::GetNamesFromIDs

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetPAB

HRESULT GetPAB(
    ULONG FAR * lpcbEntryID,
    LPENTRYID FAR * lppEntryID
);

Returns the ENTRYID of the default address book container.

  • Returns S_OK if successful.
lpcbEntryID
Address of the value that contains the size, in bytes, for the identifier pointed to by the lppEntryID parameter.
lppEntryID
Returned ENTRYID of the default address book container.

Back to top


IAddrBook::GetPropList IAddrBook::GetPropList *
  * Previous Topic: IAddrBook::GetPAB
  * Next Topic: IAddrBook::GetProps

IAddrBook::GetPropList

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetProps IAddrBook::GetProps *
  * Previous Topic: IAddrBook::GetPropList
  * Next Topic: IAddrBook::GetSearchPath

IAddrBook::GetProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::GetSearchPath

HRESULT GetSearchPath(
    ULONG ulFlags,
    LPSRowSet FAR * lppSearchPath
);

Returns an ordered list of entry identifiers of containers to be included in the name resolution process initiated by the ResolveName method.

  • Returns S_OK if the search path was successfully retrieved.
ulFlags
Bitmask of flags that control the type of the strings returned in the search path. The following flag can be set:
MAPI_UNICODE Specifies returned strings are in Unicode format. If this flag is not set, the strings are in ANSI format.
lppSearchPath
Address of a pointer to an ordered list of container entry identifiers. GetSearchPath stores the ordered list in an SRowSet structure. If there are no containers in the address book hierarchy, zero is returned in the SRowSet structure.

Back to top


IAddrBook::NewEntry

HRESULT NewEntry(
    ULONG ulUIParam,
    ULONG ulFlags,
    ULONG cbEIDContainer,
    LPENTRYID lpEIDContainer,
    ULONG cbEIDNewEntryTpl,
    LPENTRYID lpEIDNewEntryTpl,
    ULONG FAR * lpcbEIDNewEntry,
    LPENTRYID FAR * lppEIDNewEntry
);

Adds a new entry to the address book.

  • Returns S_OK if the new address book entry was successfully created.
ulUIParam
Handle of the parent window for the dialog box.
ulFlags
Reserved; must be zero.
cbEIDContainer
Size, in bytes, for the entry identifier pointed to by the lpEIDContainer parameter.
lpEIDContainer
Entry identifier of the container where the new address is to be created. If NULL, creates the entry in the root container. This is different than the MAPI IAddrBook::NewEntry method.
cbEIDNewEntryTpl
Not supported by Internet Explorer Address Book; must be zero.
lpEIDNewEntryTpl
Not supported by Internet Explorer Address Book; must be NULL.
lpcbEIDNewEntry
Address for the value indicating the size, in bytes, for the entry identifier pointed to by the lppEIDNewEntry parameter.
lppEIDNewEntry
Returned entry identifier of the new entry.

Back to top


IAddrBook::OpenEntry

HRESULT OpenEntry(
    ULONG cbEntryID,
    LPENTRYID lpEntryID,
    LPCIID lpInterface,
    ULONG ulFlags,
    ULONG FAR * lpulObjType,
    LPUNKNOWN FAR * lppUnk
);

Opens a container or mail user object and returns a pointer to the object.

  • Returns one of the following values:
    S_OK | The entry was successfully opened.
    MAPI_E_NO_ACCESS | An attempt was made to open an entry for which the user has insufficient permissions.
    MAPI_E_NOT_FOUND | The entry represented by lpEntryID does not exist.
    MAPI_E_UNKNOWN_ENTRYID | The entry identifier specified in lpEntryID is not recognized. This value is typically returned if the address book provider responsible for the corresponding entry is not open.
cbEntryID
Size, in bytes, for the entry identifier to open.
lpEntryID
Entry identifier of the object to open (NULL for the root address book container).
lpInterface
Address of the interface identifier (IID) for the object to open. Pass NULL to specify the standard interface for the object.
ulFlags
Bitmask containing the object access flags. Default is read access only. The following flags can be used for modifications:
MAPI_BEST_ACCESS | Specifies to open with best available access rights.
MAPI_MODIFY | Requests read/write access.
MAPI_DEFERRED_ERRORS | Currently not supported by Internet Explorer Address Book.
lpulObjType
Returned object type.
lppUnk
Returned object pointer.

Back to top


IAddrBook::OpenProperty IAddrBook::OpenProperty *
  * Previous Topic: IAddrBook::OpenEntry
  * Next Topic: IAddrBook::PrepareRecips

IAddrBook::OpenProperty

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::PrepareRecips

HRESULT PrepareRecips(
    ULONG ulFlags,
    LPSPropTagArray lpSPropTagArray,
    LPADRLIST lpRecipList
);

Prepares a recipient list for later use by the messaging system.

  • Returns S_OK if the recipient list was successfully prepared.
ulFlags
Reserved; must be zero.
lpSPropTagArray
Address of an SPropTagArray structure containing an array of property tags indicating properties that require updating, if any. The lpSPropTagArray parameter can be NULL.
lpRecipList
Address of an ADRLIST structure holding the list of recipients.

Back to top


IAddrBook::QueryDefaultRecipOpt IAddrBook::QueryDefaultRecipOpt *
  * Previous Topic: IAddrBook::PrepareRecips
  * Next Topic: IAddrBook::RecipOptions

IAddrBook::QueryDefaultRecipOpt

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::RecipOptions IAddrBook::RecipOptions *
  * Previous Topic: IAddrBook::QueryDefaultRecipOpt
  * Next Topic: IAddrBook::ResolveName

IAddrBook::RecipOptions

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::ResolveName

HRESULT ResolveName(
    ULONG ulUIParam,
    ULONG ulFlags,
    LPTSTR lpszNewEntryTitle,
    LPADRLIST lpAdrList
);

Resolves a partial recipient list to full addresses.

  • Returns one of the following values:
    S_OK | The name resolution process succeeded.
    MAPI_E_AMBIGUOUS_RECIP | At least one recipient in the lpAdrList parameter matched more than one entry in the address book. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.
    MAPI_E_NOT_FOUND | At least one recipient in the lpAdrList parameter cannot be resolved. Usually, this value is returned when the MAPI_DIALOG flag is set, prohibiting the display of a dialog box.
ulUIParam
Handle of the parent window.
ulFlags
MAPI_DIALOG flag. Displays a dialog box to prompt the user for additional name-resolution information. If this flag is not set, no dialog box is displayed.
lpszNewEntryTitle
Pointer to text for the title of the control in the dialog box that prompts the user to enter a recipient. The lpszNewEntryTitle parameter can be NULL.
lpAdrList
On input, the address list the list of recipients to resolve. On output, contains the list of resolved recipients.

This method optionally displays a dialog box if ambiguous matches are found. ResolveName goes through the address list passed in the lpAdrList parameter, finds all the names not yet resolved, resolves them, and returns the appropriately modified address list. The address list passed in can be one created using the Address method. If a recipient is ambiguous and the MAPI_DIALOG flag is not specified, ResolveName returns MAPI_E_AMBIGUOUS_RECIP.

Note The ADRENTRY items in ADRLIST should be separately allocated, not allocated with AllocateMore. When ResolveNames replaces an entry, it expects to free the ADRENTRY structure by using FreeBuffer and allocate a new one by using AllocateBuffer.

Back to top


IAddrBook::SaveChanges IAddrBook::SaveChanges *
  * Previous Topic: IAddrBook::ResolveName
  * Next Topic: IAddrBook::SetDefaultDir

IAddrBook::SaveChanges

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::SetDefaultDir IAddrBook::SetDefaultDir *
  * Previous Topic: IAddrBook::SaveChanges
  * Next Topic: IAddrBook::SetPAB

IAddrBook::SetDefaultDir

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::SetPAB IAddrBook::SetPAB *
  * Previous Topic: IAddrBook::SetDefaultDir
  * Next Topic: IAddrBook::SetProps

IAddrBook::SetPAB

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::SetProps IAddrBook::SetProps *
  * Previous Topic: IAddrBook::SetPAB
  * Next Topic: IAddrBook::SetSearchPath

IAddrBook::SetProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::SetSearchPath IAddrBook::SetSearchPath *
  * Previous Topic: IAddrBook::SetProps
  * Next Topic: IAddrBook::Unadvise

IAddrBook::SetSearchPath

Currently not implemented by Internet Explorer Address Book.

Back to top


IAddrBook::Unadvise IAddrBook::Unadvise *
  * Previous Topic: IAddrBook::SetSearchPath
  * Next Topic: IDistList

IAddrBook::Unadvise

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList

The IDistList interface is used to provide access to distribution lists in modifiable address book containers. This interface can create, copy, and delete distribution lists, in addition to performing name resolution. The organization of the method list for IDistList is arranged in v-table order.

IDistList methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames
GetContentsTable
GetHierarchyTable
OpenEntry
SetSearchCriteria
GetSearchCriteria
CreateEntry
CopyEntries
DeleteEntries
ResolveNames


IDistList::CopyEntries IDistList::CopyEntries *
  * Previous Topic: IDistList
  * Next Topic: IDistList::CopyProps

IDistList::CopyEntries

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::CopyProps IDistList::CopyProps *
  * Previous Topic: IDistList::CopyEntries
  * Next Topic: IDistList::CopyTo

IDistList::CopyProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::CopyTo IDistList::CopyTo *
  * Previous Topic: IDistList::CopyProps
  * Next Topic: IDistList::CreateEntry

IDistList::CopyTo

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::CreateEntry

HRESULT CreateEntry(
    ULONG   cbEntryID,
    LPENTRYID   lpEntryID,
    ULONG   ulCreateFlags,
    LPMAPIPROP FAR  * lppMAPIPropEntry
);

Creates a new entry in the distribution list container. Internet Explorer Address Book supports creation of both IMailUser and IDistList objects.

  • Returns S_OK if the entry was successfully created.
cbEntryID
Size of the existing entry identifier to copy from, stored in the lpEntryID parameter. lpEntryID parameter.
lpEntryID
Entry identifier of the object to copy from.
ulCreateFlags
Bitmask that controls the level of duplicate entries. Can be one of the following values:
CREATE_CHECK_DUP_LOOSE | Indicates a loose level should be used for duplicate entry checking, which returns more matches than setting a strict level with the CREATE_CHECK_DUP_STRICT flag. For example, a provider can define a loose match as any two entries having the same display name, while defining a strict match as any two entries having the same display name and messaging address.
CREATE_CHECK_DUP_STRICT | Indicates a strict level should be used for duplicate entry checking, which returns fewer matches than setting a loose level with the CREATE_CHECK_DUP_LOOSE flag.
CREATE_REPLACE | Indicates that duplicate entries replace existing entries within a container.
lppMAPIPropEntry
Returned property interface to the new object.

Back to top


IDistList::DeleteEntries

HRESULT DeleteEntries(
    LPENTRYLIST  lpEntries,
    ULONG  ulFlags
);

Removes one or more entries from the distribution list.

  • Returns one of the following values:
    S_OK | The specified entries have been successfully deleted.
    MAPI_W_PARTIAL_COMPLETION | The call succeeded, but one or more of the entries could not be deleted. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro.
lpEntries
Address of an array of ENTRYLIST structures containing entry identifiers representing the entries being deleted from the distribution list.
ulFlags
Reserved; must be zero.

Back to top


IDistList::DeleteProps

HRESULT DeleteProps(
    LPSPropTagArray  lpPropTagArray,
    LPSPropProblemArray FAR *  lppProblems
);

Deletes property values from a distribution list object.

  • Returns S_OK if the properties were successfully deleted, or MAPI_E_NO_ACCESS if the method that called this method has insufficient permissions to delete properties.
lpPropTagArray
Returned property tag array to be deleted.
lppProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IDistList::GetContentsTable

HRESULT GetContentsTable(
    ULONG   ulFlags,
    LPMAPITABLE FAR *  lppTable
);

Returns the address to the contents table of the distribution list.

  • Returns one of the following values:
    S_OK | The contents table was successfully retrieved.
    MAPI_E_BAD_CHARWIDTH | Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
    MAPI_E_NO_SUPPORT | The container has no contents and cannot provide a contents table.
ulFlags
Bitmask of flags that control how the contents table is returned. The following flags can be set:
MAPI_DEFERRED_ERRORS | Currently not supported by Internet Explorer Address Book.
MAPI_UNICODE | Indicates the returned strings are in Unicode format. If this flag is not set, the strings are in ANSI format. Not supported in the first version of Internet Explorer Address Book.
lppTable
Returned table object containing the contents table.

Back to top


IDistList::GetHierarchyTable IDistList::GetHierarchyTable *
  * Previous Topic: IDistList::GetContentsTable
  * Next Topic: IDistList::GetIDsFromNames

IDistList::GetHierarchyTable

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::GetIDsFromNames

HRESULT GetIDsFromNames(
    ULONG cPropNames,
    LPMAPINAMEID FAR * lppPropNames,
    ULONG ulFlags,
    LPSPropTagArray FAR * lppPropTags
);

Provides the property identifiers that correspond to one or more property names.

  • Returns one of the following values:
    S_OK | The identifiers for the specified property names were successfully returned.
    MAPI_E_NO_SUPPORT | The object does not support named properties.
    MAPI_E_NOT_ENOUGH_MEMORY | Insufficient memory was available to retrieve the identifiers.
    MAPI_E_TOO_BIG | The operation cannot be performed because it requires too many property tags be returned.
    MAPI_W_ERRORS_RETURNED | The call succeeded overall, but one or more property identifiers could not be returned. The corresponding property type for each inaccessible property is set to PT_ERROR and its identifier to zero. When this warning is returned, handle the call as successful. To test for this warning, use the FAILED macro.
cPropNames
Value that represents the number of property names pointed to by the lppPropNames parameter. If lppPropNames is NULL, the cPropNames parameter must be zero.
lppPropNames
Address of an array of property names, or NULL. Passing NULL requests property identifiers for all property names in all property sets about which the object has information. The lppPropNames parameter must not be NULL if the MAPI_CREATE flag is set in the ulFlags parameter.
ulFlags
Bitmask of flags that indicate how the property identifiers should be returned. The following flag can be set:
MAPI_CREATE Assigns a property identifier to one or more of the names included in the property name array pointed to by lppPropNames if one has not yet been assigned. Internally registers the identifier in the name-to-identifier mapping table.
lppPropTags
Returned array structure of property tags containing existing or newly assigned property identifiers. The property types for the property tags in this array are set to PT_UNSPECIFIED.

Back to top


IDistList::GetLastError IDistList::GetLastError *
  * Previous Topic: IDistList::GetIDsFromNames
  * Next Topic: IDistList::GetNamesFromIDs

IDistList::GetLastError

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::GetNamesFromIDs IDistList::GetNamesFromIDs *
  * Previous Topic: IDistList::GetLastError
  * Next Topic: IDistList::GetPropList

IDistList::GetNamesFromIDs

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::GetPropList

HRESULT GetPropList(
    ULONG  ulFlags,
    LPSPropTagArray FAR *  lppPropTagArray
);

Retrieves a list of the property tags on the object.

  • Returns one of the following values:
    S_OK | All of the property tags were returned successfully.
    MAPI_E_BAD_CHARWIDTH | Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
ulFlags
Must be zero for Internet Explorer Address Book.
lppPropTagArray
Returned property tag array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IDistList::GetProps

HRESULT GetProps(
    LPSPropTagArray lpPropTagArray,
    ULONG ulFlags,
    ULONG FAR * lpcValues,
    LPSPropValue FAR * lppPropArray
);

Retrieves the property tag information for the distribution list items.

  • Returns one of the following values:
    S_OK | The property values were successfully retrieved.
    MAPI_W_ERRORS_RETURNED | The call succeeded overall, but one or more properties could not be accessed. The ulPropTag member of the property value for each inaccessible property in the lppPropArray parameter has a property type of PT_ERROR and an identifier of zero. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro.
    MAPI_E_INVALID_PARAMETER | Zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray.
lpPropTagArray
Address of an SPropTagArray structure of properties whose values are to be retrieved. A NULL value specifies that all properties should be retrieved.
ulFlags
MAPI_UNICODE flag. Not supported by Internet Explorer Address Book.
lpcValues
Returned value that represents the number of property values returned. If lppPropArray is NULL, the contents of the lpcValues parameter is zero.
lppPropArray
Returned SPropValue array. Must be freed by the caller.

Back to top


IDistList::GetSearchCriteria IDistList::GetSearchCriteria *
  * Previous Topic: IDistList::GetProps
  * Next Topic: IDistList::OpenEntry

IDistList::GetSearchCriteria

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::OpenEntry

HRESULT OpenEntry(
    ULONG cbEntryID,
    LPENTRYID lpEntryID,
    LPCIID lpInterface,
    ULONG ulFlags,
    ULONG FAR * lpulObjType,
    LPUNKNOWN FAR * lppUnk
);

Opens an entry contained in the distribution list and returns a pointer to the object to provide further access.

  • Returns one of the following values:
    S_OK | The entry was successfully opened.
    MAPI_E_NO_ACCESS | An attempt was made to open an entry for which the user has insufficient permissions.
    MAPI_E_NOT_FOUND | The entry represented by lpEntryID does not exist.
    MAPI_E_UNKNOWN_ENTRYID | The entry identifier specified in lpEntryID is not recognized. This value is typically returned if the address book provider responsible for the corresponding entry is not open.
cbEntryID
Value that represents the number of bytes contained in the entry identifier to open.
lpEntryID
Address of an entry identifier of the object to open.
lpInterface
Address of an interface identifier (IID) for the object to open. Pass NULL to specify the standard interface for the object.
ulFlags
Bitmask containing object access flags. The default is read access only. The following flags can be used for modifications:
MAPI_BEST_ACCESS | Specifies to open with best available access rights.
MAPI_MODIFY | Requests read/write access.
MAPI_DEFERRED_ERRORS | Currently not supported by Internet Explorer Address Book.
lpulObjType
Address of the object type of the opened entry.
lppUnk
Returned object pointer to the opened entry.

Back to top


IDistList::OpenProperty IDistList::OpenProperty *
  * Previous Topic: IDistList::OpenEntry
  * Next Topic: IDistList::ResolveNames

IDistList::OpenProperty

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::ResolveNames IDistList::ResolveNames *
  * Previous Topic: IDistList::OpenProperty
  * Next Topic: IDistList::SaveChanges

IDistList::ResolveNames

Currently not implemented by Internet Explorer Address Book.

Back to top


IDistList::SaveChanges

HRESULT SaveChanges(
    ULONG ulFlags
);

Provides the ability to save changes to the open distribution list object.

  • Returns one of the following values:
    S_OK | The commitment of changes has been successful.
    MAPI_E_NO_ACCESS | SaveChanges cannot keep the object open for read-only access if KEEP_OPEN_READONLY is set, or read/write access if KEEP_OPEN_READWRITE is set. No changes are committed.
    MAPI_E_OBJECT_CHANGED | The object has changed since it was opened.
    MAPI_E_OBJECT_DELETED | The object has been deleted since it was opened.
ulFlags
Bitmask of flags that control what happens to the object when the SaveChanges method is called. The following flags can be set:
FORCE_SAVE | Writes changes to the object and closes it. Read-write access must have been set for the operation to succeed. This flag forces saving only if MAPI_E_OBJECT_CHANGED was returned from a preceding SaveChanges call. FORCE_SAVE overrides the previous changes made to the object.
KEEP_OPEN_READONLY | Indicates the client requests changes be committed and the object be kept open for reading. This flag informs the provider that the object should not be modified and that the calling implementation will not call SaveChanges again. If the provider cannot keep the object open for read-only access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
KEEP_OPEN_READWRITE | Indicates the client requests changes be committed and the object be kept open for read-write access. This flag is usually set when the object was initially opened for read-write access. After calling SaveChanges, the client can make further changes to the object if this flag is passed. If the provider cannot keep the object open for read-write access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
MAPI_DEFERRED_ERRORS | Not supported by Internet Explorer Address Book.

Back to top


IDistList::SetProps

HRESULT SetProps(
    ULONG cValues,
    LPSPropValue lpPropArray,
    LPSPropProblemArray FAR * lppProblems
);

Sets property values on a distribution list object.

  • Returns one of the following values:
    S_OK | The properties were successfully updated. The following values can be returned in the SPropProblemArray structure, but not as return values for SetProps.
    MAPI_E_BAD_CHARWIDTH | Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.
    MAPI_E_COMPUTED | The property cannot be updated because it is read-only, computed by the service provider responsible for the object.
    MAPI_E_INVALID_TYPE | The property type is invalid.
    MAPI_E_NO_ACCESS | An attempt was made to modify a read-only object or to access an object for which the user has insufficient permissions.
    MAPI_E_NOT_ENOUGH_MEMORY | The property cannot be updated because it is larger than the remote procedure call "RPC" buffer size.
    MAPI_E_UNEXPECTED_TYPE | The property type is not the type expected by the calling implementation.
cValues
Count of property values to be set. This parameter must not be zero.
lpPropArray
Address of an array of SPropValue structures containing the properties to set.
lppProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IDistList::SetSearchCriteria IDistList::SetSearchCriteria *
  * Previous Topic: IDistList::SetProps
  * Next Topic: IMailUser

IDistList::SetSearchCriteria

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser

The IMailUser interface is implemented by messaging user objects. IMailUser inherits from the IMAPIProp interface and has no unique methods of its own. The IMailUser interface provides access to the many properties that are associated with messaging users. The organization of the method list for IMailUser is arranged in v-table order.

IMailUser methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames


IMailUser::CopyProps IMailUser::CopyProps *
  * Previous Topic: IMailUser
  * Next Topic: IMailUser::CopyTo

IMailUser::CopyProps

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser::CopyTo IMailUser::CopyTo *
  * Previous Topic: IMailUser::CopyProps
  * Next Topic: IMailUser::DeleteProps

IMailUser::CopyTo

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser::DeleteProps

HRESULT DeleteProps(
    LPSPropTagArray  lpPropTagArray,
    LPSPropProblemArray FAR *  lppProblems
);

Deletes property values from a mail user object.

  • Returns S_OK if properties were successfully deleted, or MAPI_E_NO_ACCESS if the caller has insufficient permissions to delete properties.
lpPropTagArray
Address of an array of property tags indicating the properties to delete. The cValues member of the SPropTagArray structure pointed to by lpPropTagArray must not be zero, and the lpPropTagArray parameter itself must not be NULL.
lppProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IMailUser::GetIDsFromNames

HRESULT GetIDsFromNames(
    ULONG  cPropNames,
    LPMAPINAMEID FAR *  lppPropNames,
    ULONG  ulFlags,
    LPSPropTagArray FAR *  lppPropTags
);

Registers named properties with the mail user object.

  • Returns one of the following values:
    S_OK | The identifiers for the specified property names were successfully returned.
    MAPI_E_NO_SUPPORT | The object does not support named properties.
    MAPI_E_NOT_ENOUGH_MEMORY | Insufficient memory was available to retrieve the identifiers.
    MAPI_E_TOO_BIG | The operation cannot be performed because it requires too many property tags be returned.
    MAPI_W_ERRORS_RETURNED | The call succeeded overall, but one or more property identifiers could not be returned. The corresponding property type for each inaccessible property is set to PT_ERROR and its identifier to zero. When this warning is returned, handle the call as successful. To test for this warning, use the FAILED macro.
cPropNames
Count of names to register. If lppPropNames is NULL, the cPropNames parameter must be zero.
lppPropNames
MAPINAMEID structure containing the names and their globally unique identifiers (GUIDs).
ulFlags
Bitmask of flags that indicate how the property identifiers should be returned. The following flag can be set:
MAPI_CREATE Creates a property identifier for any name not already mapped. The default is to fail those non-existent property names.
lppPropTags
Returned SPropTagArray of property tags. Must be freed by the caller.

Back to top


IMailUser::GetLastError IMailUser::GetLastError *
  * Previous Topic: IMailUser::GetIDsFromNames
  * Next Topic: IMailUser::GetNamesFromIDs

IMailUser::GetLastError

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser::GetNamesFromIDs IMailUser::GetNamesFromIDs *
  * Previous Topic: IMailUser::GetLastError
  * Next Topic: IMailUser::GetPropList

IMailUser::GetNamesFromIDs

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser::GetPropList

HRESULT GetPropList(
    ULONG   ulFlags,
    LPSPropTagArray FAR *  lppPropTagArray
);

Gets a list of the property tags on the object.

  • Returns S_OK if all property tags were returned successfully.
ulFlags
Must be zero for Internet Explorer Address Book.
lppPropTagArray
Returned property tag array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IMailUser::GetProps

HRESULT GetProps(
    LPSPropTagArray lpPropTagArray,
    ULONG ulFlags,
    ULONG FAR * lpcValues,
    LPSPropValue FAR * lppPropArray
);

Gets property values from a mail user object.

  • Returns S_OK if the property values were successfully retrieved, or MAPI_E_INVALID_PARAMETER if zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray.
lpPropTagArray
SPropTagArray of properties to be retrieved. A NULL value specifies that all properties should be retrieved.
ulFlags
MAPI_UNICODE flag. Currently not supported by Internet Explorer Address Book.
lpcValues
Returned count of property values returned. This pointer can be NULL if the caller does not want the count of the returned property values.
lppPropArray
Returned SPropValue array. Must be freed by the caller.

Back to top


IMailUser::OpenProperty IMailUser::OpenProperty *
  * Previous Topic: IMailUser::GetProps
  * Next Topic: IMailUser::SaveChanges

IMailUser::OpenProperty

Currently not implemented by Internet Explorer Address Book.

Back to top


IMailUser::SaveChanges

HRESULT SaveChanges(
    ULONG  ulFlags
);

Saves changes to the open mail user object. Note that the following properties may be calculated and changed at SaveChanges:
PR_DISPLAY_NAME
PR_GIVEN_NAME
PR_SURNAME
PR_LAST_MODIFICATION_TIME

  • Returns one of the following values:
    S_OK | The commitment of changes has been successful.
    MAPI_E_NO_ACCESS | SaveChanges cannot keep the object open for read-only access if KEEP_OPEN_READONLY is set, or read/write access if KEEP_OPEN_READWRITE is set. No changes are committed.
    MAPI_E_OBJECT_CHANGED | The object has changed since it was opened.
    MAPI_E_OBJECT_DELETED | The object has been deleted since it was opened.
ulFlags
Bitmask of flags that control what happens to the object when the SaveChanges method is called. The following flags can be set:
FORCE_SAVE | Writes changes to the object and closes it. Read-write access must have been set for the operation to succeed. This flag forces saving only if MAPI_E_OBJECT_CHANGED was returned from a preceding SaveChanges call. FORCE_SAVE overrides the previous changes made to the object.
KEEP_OPEN_READONLY | Indicates the client requests changes be committed and the object be kept open for reading. This flag informs the provider that the object should not be modified and that the calling implementation will not call SaveChanges again. If the provider cannot keep the object open for read-only access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
KEEP_OPEN_READWRITE | Indicates the client requests changes be committed and the object be kept open for read-write access. This flag is usually set when the object was initially opened for read-write access. After calling SaveChanges, the client can make further changes to the object if this flag is passed. If the provider cannot keep the object open for read-write access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
MAPI_DEFERRED_ERRORS | Currently not supported by Internet Explorer Address Book.

Back to top


IMailUser::SetProps

HRESULT SetProps(
    ULONG  cValues,
    LPSPropValue  lpPropArray,
    LPSPropProblemArray FAR *   pProblems
);

Sets the property values on a mail user object.

  • Returns S_OK if the properties were successfully updated.
cValues
Count of property values to be set.
lpPropArray
Array of SPropValue structures containing the properties to set.
pProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

Back to top


IWABObject

The Internet Explorer Address Book object contains function pointers to memory allocation functions and database maintenance functions. The organization of the method list for IWABObject is arranged in v-table order.

IWABObject methods
GetLastError
AllocateBuffer
AllocateMore
FreeBuffer
Backup
Import
Find
VCardDisplay
LDAPUrl
VCardCreate
VCardRetrieve
GetMe
SetMe


IWABObject::AllocateBuffer

HRESULT AllocateBuffer(
    ULONG  cbSize,
    LPVOID FAR *  lppBuffer
);

Allocates a memory for a buffer. This is the allocation routine that should be used for buffers passed to Internet Explorer Address Book methods. The buffer should be freed with FreeBuffer and can be reallocated with AllocateMore.

  • Returns S_OK if the requested buffer was successfully allocated.
cbSize
Specified size, in bytes, of the buffer to be allocated.
lppBuffer
Returned buffer pointer.

Back to top


IWABObject::AllocateMore

HRESULT AllocateMore(
    ULONG           cbSize,
    LPVOID          lpObject,
    LPVOID FAR *    lppBuffer
);

Allocates a memory buffer that is linked to another buffer previously allocated with the AllocateBuffer function.

  • Returns S_OK if the requested AllocateMore method was successful.
cbSize
Size, in bytes, of the buffer to be allocated.
lpObject
Existing buffer object allocated using AllocateBuffer.
lppBuffer
Returned buffer pointer; this buffer is linked to lpObject.

The only way to release a buffer allocated with AllocateMore is to pass the buffer pointer specified in the lpObject parameter to the FreeBuffer function. The link between the memory buffers allocated with AllocateBuffer and AllocateMore enables FreeBuffer to release both buffers with a single call.

Back to top


IWABObject::Backup IWABObject::Backup *
  * Previous Topic: IWABObject::AllocateMore
  * Next Topic: IWABObject::Find

IWABObject::Backup

Currently not implemented in Internet Explorer Address Book.

Back to top


IWABObject::Find

HRESULT Find(
    HWnd
);

Launches the address book's Find dialog box. (Internet Explorer 4.0 only)

  • Returns S_OK if successful.
HWnd
HWND of the parent for the Find dialog box. Can be NULL.

Back to top


IWABObject::FreeBuffer

HRESULT FreeBuffer(
    LPVOID lpBuffer
);

Frees memory allocated with AllocateBuffer or any of the Internet Explorer Address Book methods.

  • Returns S_OK if the call succeeded and freed the memory requested.
lpBuffer
Address of the buffer to free.

Back to top


IWABObject::GetLastError IWABObject::GetLastError *
  * Previous Topic: IWABObject::FreeBuffer
  * Next Topic: IWABObject::GetMe

IWABObject::GetLastError

Currently not implemented in Internet Explorer Address Book.

Back to top


IWABObject::GetMe IWABObject::GetMe *
  * Previous Topic: IWABObject::GetLastError
  * Next Topic: IWABObject::Import

IWABObject::GetMe

Currently not implemented in Internet Explorer Address Book.

Back to top


IWABObject::Import IWABObject::Import *
  * Previous Topic: IWABObject::GetMe
  * Next Topic: IWABObject::LDAPUrl

IWABObject::Import

Currently not implemented in Internet Explorer Address Book.

Back to top


IWABObject::LDAPUrl

HRESULT IWABObject::LDAPUrl (
    HWND  hWnd,
    ULONG ulFlags,
    LPTSTR  lpszLDAPURL,
    LPMailUser * lppMailUser
);

This method processes a given LDAP Url and displays corresponding results. If the URL only contains a server name, the method will display the WAB Find dialog with the server name filled in, enabling the user to manually search the server. If the URL contains an explicit LDAP query, this method performs a search based on the query. If the query produces a single result, the method shows details on the single result, else if the query has multiple results, the method shows the WAB Find dialog with multiple search results filled in. If WABOBJECT_LDAPURL_RETURN_MAILUSER is specified in the ulFlags parameter, the method returns a IMailUser object, if the query returns a single specific result, else returns a MAPI_E_AMBIGUOUS_RECIP if the query returns multiple hits.

  • Returns S_OK if successful.
hWnd
HWND of the parent for displayed dialogs.
ulFlags
Flags specifying behavior. Can be zero, or WABOBJECT_LDAPURL_RETURN_MAILUSER.
lpszLDAPUrl
URL string, starting with ldap://. (Format for LDAP URLs is specified in RFC-1959)
lppMailUser
Returned IMailUser object, if requested. Null otherwise.

Back to top


IWABObject::SetMe IWABObject::SetMe *
  * Previous Topic: IWABObject::LDAPUrl
  * Next Topic: IWABObject::VCardCreate

IWABObject::SetMe

Currently not implemented in Internet Explorer Address Book.

Back to top


IWABObject::VCardCreate

HRESULT VCardCreate(
    lpAdrBook,
    lpFileName,
    lpMailUser
);

Translates the properties of an IMailUser object into a business card (vCard) file. (The vCard file format is an Internet standard for exchanging contact information through text based files).

The complete file name must be specified. If the file already exists, it will be overwritten.

Warning! This API is in development at this time, and is subject to change.

  • Returns S_OK if successful.
lpAdrBook
Address of an IAddrBook object.
lpFileName
Address of a string containing the complete path of the file to create.
lpMailUser
Address of a IMailUser object whose properties will be written into the file.

Back to top


IWABObject::VCardDisplay

HRESULT VCardDisplay(
    lpAdrBook,
    hWnd,
    lpFileName
);

Displays the contents of a business card (vCard) file. The complete file name must be specified.

Warning! This API is in development at this time, and is subject to change.

  • Returns S_OK if successful.
lpAdrBook
Address of an IADRBOOK object.
hWnd
HWND of the parent for displayed dialog boxes.
lpFileName
Full path of vCard file to display. Fails if the file does not exist.

Back to top


IWABObject::VCardRetrieve

HRESULT VCardRetrieve(
    lpAdrBook,
    lpFileName,
    lppMailUser
);

Reads a vCard file and creates a MailUser object containing the vCard properties.

  • Returns S_OK if successful.
lpAdrBook
Address of an IADRBOOK object.
lpFileName
Address of a string containing the complete path of the file to read. Fails if the file is not found.
lppMailUser
Returned MailUser object created containing the properties in the vCard file.

Back to top


Internet Explorer Address Book Functions

This section describes the functions implemented by the Internet Explorer Address Book.

The Internet Explorer Address Book implements the WABOpen and WabOpenEx functions, that are used to access the interfaces included in the address book.

  • WABOpen
  • WABOpenEx


WABOpen

HRESULT WABOpen(
    LPADRBOOK   * lppAdrBook,
    LPWABOBJECT * lppWABObject,
    LPWAB_PARM    lpWP,          // Can be null
    DWORD         Reserved2
);

Gives access to the address book through a number of object interfaces. The root interface is IAddrBook, which is a subset of the MAPI implementation of IAddrBook.

  • Returns S_OK if successful.
lppAdrBook
Returned IAddrBook interface.
lppWABObject
Returned IWABObject interface.
lpWP
Address of a WAB_PARAM structure. (This value can be null.)
Reserved2
Reserved; must be zero.

Back to top


WABOpenEx

HRESULT WABOpenEx(
    LPADRBOOK      * lppAdrBook,
    LPWABOBJECT    * lppWABObject,
    LPWAB_PARM       lpWP,          // Can be null
    DWORD            Reserved2,
    ALLOCATEBUFFER * lpfnAllocateBuffer,
    ALLOCATEMORE   * lpfnAllocateMore,
    FREEBUFFER     * lpfnFreeBuffer
    );

Gives access to the address book through a number of object interfaces. The root interface is IAddrBook, which is a subset of the MAPI implementation of IAddrBook. This function also specifies the memory allocation functions that Internet Explorer Address Book uses to allocate all buffers returned to the client. If you pass in one allocation routine, you must pass them all.

Note When WABOpenEx has been called specifying memory allocation routines, these routines globally replace Internet Explorer Address Book internal routines for this process. Other threads can still call WABOpen, but the memory will still be allocated with those routines previously passed to WABOpenEx. Unless you really need the additional functionality, use WABOpen.

  • Returns S_OK if successful.
lppAdrBook
Returned IAddrBook interface.
lppWABObject
Returned IWABObject interface.
lpWP
Address of a WAB_PARAM structure. (This value can be null.)
Reserved2
Reserved; must be zero.
lpfnAllocateBuffer
Allocation function in the style of MAPIAllocateBuffer. Can be NULL to use Internet Explorer Address Book internal routines.
lpfnAllocateMore
Allocation function in the style of MAPIAllocateMore. Can be NULL to use Internet Explorer Address Book internal routines.
lpfnFreeBuffer
Buffer function in the style of MAPIFreeBuffer. Can be NULL to use Internet Explorer Address Book internal routines.

Back to top


Internet Explorer Address Book Structures

This section contains the data structures and related information that are used by the Internet Explorer Address Book programming interfaces.

  • ADRENTRY
  • ADRLIST
  • ADRPARM
  • ENTRYID
  • ENTRYLIST
  • MAPI_PAB_Schema
  • SPropProblem
  • SPropProblemArray
  • SPropTagArray
  • SPropValue
  • SRestriction
  • SRow
  • SRowSet
  • SSortOrder
  • SSortOrderSet
  • WAB_PARAM


ADRENTRY

typedef struct _ADRENTRY {
    ULONG          ulReserved1;
    ULONG          cValues;
    LPSPropValue   rgPropVals;
} ADRENTRY;

Describes zero or more properties belonging to a recipient.

ulReserved1
Reserved; must be zero.
cValues
Count of properties in the property value array pointed to by the rgPropVals member. The cValues member can be zero.
rgPropVals
Address of a property value array describing the properties for the recipient. The rgPropVals member can be NULL.

Back to top


ADRLIST

typedef struct _ADRLIST {
    ULONG          cEntries;
    ADRENTRY       aEntries[MAPI_DIM];
    } ADRLIST;

Describes zero or more properties belonging to one or more recipients.

cEntries
Count of entries in the array specified by the aEntries member.
aEntries[MAPI_DIM]
Array of ADRENTRY structures, one structure for each recipient.

Back to top


ADRPARM

typedef struct _ADRPARM
{
    ULONG            cbABContEntryID;
    LPENTRYID        lpABContEntryID;
    ULONG            ulFlags;
    LPVOID           lpReserved;
    ULONG            ulHelpContext;
    LPTSTR           lpszHelpFileName;
    LPFNABSDI        lpfnABSDI;
    LPFNDISMISS      lpfnDismiss;
    LPVOID           lpvDismissContext;
    LPTSTR           lpszCaption;
    LPTSTR           lpszNewEntryTitle;
    LPTSTR           lpszDestWellsTitle;
    ULONG            cDestFields;
    ULONG            nDestFieldFocus;
    LPTSTR FAR      *lppszDestTitles;
    ULONG FAR       *lpulDestComps;
    LPSRestriction   lpContRestriction;
    LPSRestriction   lpHierRestriction;
} ADRPARM, FAR *LPADRPARM;

Describes the display and behavior of the common address dialog box.

cbABContEntryID
List of entries that can be added to the recipient wells.
lpABContEntryID
Address of an ENTRYID of a container that will supply the list of one-offs that can be added to the recipient wells of the address book common dialog box. The address book container that lpABContEntryID points to determines what is listed in the edit box within the dialog box that holds possible recipient names. Usually, lpABContEntryID is NULL, indicating the use of a custom recipient provider.
ulFlags
Bitmask of flags associated with various address dialog box options. The following flags can be set:
AB_RESOLVE | Causes all names to be resolved after the address book dialog box is closed. The Resolve Name dialog box is displayed if there are ambiguous entries in the recipient list.
AB_SELECTONLY | Disables the creation of custom recipient addresses and direct type-in entries for a recipient list. This flag is used only if the dialog box is modal.
ADDRESS_ONE | Indicates that the user of the dialog box can select exactly one message recipient, instead of a number of recipients from a recipient list. This flag is valid only when cDestFields is zero. This flag is used only if the dialog box is modal.
DIALOG_MODAL | Causes a modal dialog box to be displayed. The client must set either this flag or DIALOG_SDI, but not both.
DIALOG_OPTIONS | Not supported by Internet Explorer Address Book.
DIALOG_SDI | Causes a modeless dialog box to be displayed. This call returns immediately and thus does not modify the ADRLIST structure passed in. The caller must set either this flag or DIALOG_MODAL, but not both.
lpReserved
Reserved; must be zero.
ulHelpContext
Not supported by Internet Explorer Address Book. Should be zero.
lpszHelpFileName
Not supported by Internet Explorer Address Book. Should be NULL.
lpfnABSDI
Address of an Internet Explorer Address Book function based on the ACCELERATEABSDI (see MAPI documentation) prototype, or NULL. This member applies to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set.

Clients building an ADRPARM structure to pass to IAddrBook::Address must always set the lpfnABSDI member to NULL. If the DIALOG_SDI flag is set, Internet Explorer Address Book then sets it to a valid function before returning. Clients call this function from within their message loop to ensure that accelerators in the address book dialog box work. When the dialog box is dismissed and Internet Explorer Address Book calls the function pointed to by the lpfnDismiss member, clients should unhook the ACCELERATEABSDI function from their message loop.

lpfnDismiss
Address of a function based on the DISMISSMODELESS (see MAPI documentation) prototype, or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set. Internet Explorer Address Book calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client calling IAddrBook::Address that the dialog box is no longer active.
lpvDismissContext
Address of the context information to be passed to the DISMISSMODELESS function pointed to by the lpfnDismiss member. This member applies to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set.
lpszCaption
Address of the text to be used as a caption for the address book dialog box.
lpszNewEntryTitle
Address of the text to be used as a new-entry prompt for an edit box in an address book dialog box.
lpszDestWellsTitle
Address of text to be used as a title for the set of recipient-name edit boxes that appears in the dialog box. This member is used only if the address book dialog box is modal.
cDestFields
Number of recipient-name edit boxes (that is, destination fields) in the address book dialog box. A number from 0 through 3 is typical. If the cDestFields member is zero and the ADDRESS_ONE flag is not set in ulFlags, the address book is open for browsing only.
nDestFieldFocus
Field in the address book dialog box that should have the initial focus when the dialog box appears. This value must be between 0 and the value of cDestFields minus 1.
lppszDestTitles
Address of an array of text titles to be displayed in the recipient-name edit boxes of the address book dialog box. The size of the array is the value of cDestFields. If the lppszDestTitles member is NULL, the IAddrBook::Address method chooses default titles.
lpulDestComps
Address of an array of recipient types, such as MAPI_TO, MAPI_CC, and MAPI_BCC, associated with each recipient-name edit box. The size of the array is the value of cDestFields. If the lpulDestComps member is NULL, the IAddrBook::Address method chooses default recipient types.
lpContRestriction
Not supported by Internet Explorer Address Book. Should be NULL.
lpHierRestriction
Not supported by Internet Explorer Address Book. Should be NULL.

Back to top


ENTRYID

typedef struct _ENTRYID
{
    BYTE    abFlags[4];
    BYTE    ab[MAPI_DIM];
} ENTRYID, FAR *LPENTRYID;

Contains the entry identifier information for a MAPI object.

abFlags
Bitmask of flags that provide information describing the object.
ab[MAPI_DIM]
Indicates an array of binary data used by service providers. Client applications cannot use this array.

Back to top


ENTRYLIST

typedef
    SBinaryArray ENTRYLIST,
    FAR *LPENTRYLIST;

The ENTRYLIST structure is an array of entry identifiers representing MAPI objects.

Back to top


MAPI_PAB_Schema

The Internet Explorer Address Book schema is based upon the MAPI Personal Address Book, or (PAB) schema. The following properties are defined in table form. Additional properties can be added by client applications by using the named property methods: GetNamesFromIDs and GetIDsFromNames.

MAPI PAB Schema
Property name | Property type | Property identifier
PR_7BIT_DISPLAY_NAME | PT_STRING8 | 0x39FF
PR_ACCOUNT | PT_TSTRING | 0x39FF
PR_ALTERNATE_RECIPIENT | PT_BINARY | 0x3A01
PR_ASSISTANT | PT_TSTRING | 0x3A30
PR_ASSISTANT_TELEPHONE_NUMBER | PT_TSTRING | 0x3A2E
PR_BEEPER_TELEPHONE_NUMBER | PT_TSTRING | PR_PAGER_TELEPHONE_NUMBER
PR_BIRTHDAY | PT_SYSTIME | 0x3A42
PR_BUSINESS_ADDRESS_CITY | PT_TSTRING | PR_LOCALITY
PR_BUSINESS_ADDRESS_COUNTRY | PT_TSTRING | PR_COUNTRY
PR_BUSINESS_ADDRESS_POST_OFFICE_BOX | PT_TSTRING | PR_POST_OFFICE_BOX
PR_BUSINESS_ADDRESS_POSTAL_CODE | PT_TSTRING | PR_POSTAL_CODE
PR_BUSINESS_ADDRESS_STATE_OR_PROVINCE | PT_TSTRING | PR_STATE_OR_PROVINCE
PR_BUSINESS_ADDRESS_STREET | PT_TSTRING | PR_STREET_ADDRESS
PR_BUSINESS_FAX_NUMBER | PT_TSTRING | 0x3A24
PR_BUSINESS_HOME_PAGE | PT_TSTRING | 0x3A51
PR_BUSINESS_TELEPHONE_NUMBER | PT_TSTRING | 0x3A08
PR_BUSINESS_HOME_PAGE | PT_TSTRING | 0x3A51
PR_BUSINESS_TELEPHONE_NUMBER | PT_TSTRING | 0x3A08
PR_BUSINESS2_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1B
PR_CALLBACK_TELEPHONE_NUMBER | PT_TSTRING | 0x3A02
PR_CAR_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1E
PR_CELLULAR_TELEPHONE_NUMBER | PT_TSTRING | PR_MOBILE_TELEPHONE_NUMBER
PR_CHILDRENS_NAMES | PT_MV_TSTRING | 0x3A58
PR_COMMENT | PT_TSTRING | 0x3004
PR_COMPANY_MAIN_PHONE_NUMBER | PT_TSTRING | 0x3A57
PR_COMPANY_NAME | PT_TSTRING | 0x3A16
PR_COMPUTER_NETWORK_NAME | PT_TSTRING | 0x3A49
PR_CONTACT_ADDRTYPES | PT_MV_TSTRING | 0x3A54
PR_CONTACT_DEFAULT_ADDRESS_INDEX | PT_LONG | 0x3A55
PR_CONTACT_EMAIL_ADDRESSES | PT_MV_TSTRING | 0x3A56
PR_CONTACT_ENTRYIDS | PT_MV_BINARY | 0x3A53
PR_CONTACT_VERSION | PT_CLSID | 0x3A03
PR_CONVERSION_PROHIBITED | PT_BOOLEAN | 0x3A03
PR_COUNTRY | PT_TSTRING | 0x3A26
PR_CUSTOMER_ID | PT_TSTRING | 0x3A4A
PR_DEPARTMENT_NAME | PT_TSTRING | 0x3A18
PR_DISCLOSE_RECIPIENTS | PT_BOOLEAN | 0x3A04
PR_DISPLAY_NAME | PT_TSTRING | 0x3001
PR_DISPLAY_NAME_PREFIX | PT_TSTRING | 0x3A45
PR_EMAIL_ADDRESS | PT_TSTRING | 0x3003
PR_ENTRYID | PT_BINARY | 0x0FFF
PR_FTP_SITE | PT_TSTRING | 0x3A4C
PR_GENDER | PT_SHORT | 0x3A4D
PR_GENERATION | PT_TSTRING | 0x3A05
PR_GIVEN_NAME | PT_TSTRING | 0x3A06
PR_GOVERNMENT_ID_NUMBER | PT_TSTRING | 0x3A07
PR_HOBBIES | PT_TSTRING | 0x3A43
PR_HOME_ADDRESS_CITY | PT_TSTRING | 0x3A59
PR_HOME_ADDRESS_COUNTRY | PT_TSTRING | 0x3A5A
PR_HOME_ADDRESS_POST_OFFICE_BOX | PT_TSTRING | 0x3A5E
PR_HOME_ADDRESS_POSTAL_CODE | PT_TSTRING | 0x3A5B
PR_HOME_ADDRESS_STATE_OR_PROVINCE | PT_TSTRING | 0x3A5C
PR_HOME_ADDRESS_STREET | PT_TSTRING | 0x3A5D
PR_HOME_FAX_NUMBER | PT_TSTRING | 0x3A25
PR_HOME_TELEPHONE_NUMBER | PT_TSTRING | 0x3A09
PR_HOME2_TELEPHONE_NUMBER | PT_TSTRING | 0x3A2F
PR_INITIALS | PT_TSTRING | 0x3A0A
PR_ISDN_NUMBER | PT_TSTRING | 0x3A2D
PR_KEYWORD | PT_TSTRING | 0x3A0B
PR_LANGUAGE | PT_TSTRING | 0x3A0C
PR_LOCALITY | PT_TSTRING | 0x3A27
PR_LOCATION | PT_TSTRING | 0x3A0D
PR_MAIL_PERMISSION | PT_BOOLEAN | 0x3A0E
PR_MANAGER_NAME | PT_TSTRING | 0x3A4E
PR_MHS_COMMON_NAME | PT_TSTRING | 0x3A0F
PR_MIDDLE_NAME | PT_TSTRING | 0x3A44
PR_MOBILE_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1C
PR_NICKNAME | PT_TSTRING | 0x3A4F
PR_OBJECT_TYPE | PT_LONG | 0xFFE
PR_OFFICE_LOCATION | PT_TSTRING | 0x3A19
PR_OFFICE_TELEPHONE_NUMBER | PT_TSTRING | PR_BUSINESS_TELEPHONE_NUMBER
PR_OFFICE2_TELEPHONE_NUMBER | PT_TSTRING | PR_BUSINESS2_TELEPHONE_NUMBER
PR_ORGANIZATIONAL_ID_NUMBER | PT_TSTRING | 0x3A10
PR_ORIGINAL_DISPLAY_NAME | PT_TSTRING | 0x3A13
PR_ORIGINAL_ENTRYID | PT_BINARY | 0x3A12
PR_ORIGINAL_SEARCH_KEY | PT_BINARY | 0x3A14
PR_OTHER_ADDRESS_CITY | PT_TSTRING | 0x3A5F
PR_OTHER_ADDRESS_COUNTRY | PT_TSTRING | 0x3A60
PR_OTHER_ADDRESS_POST_OFFICE_BOX | PT_TSTRING | 0x3A64
PR_OTHER_ADDRESS_POSTAL_CODE | PT_TSTRING | 0x3A61
PR_OTHER_ADDRESS_STATE_OR_PROVINCE | PT_TSTRING | 0x3A62
PR_OTHER_ADDRESS_STREET | PT_TSTRING | 0x3A63
PR_OTHER_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1F
PR_PAGER_TELEPHONE_NUMBER | PT_TSTRING | 0x3A21
PR_PERSONAL_HOME_PAGE | PT_TSTRING | 0x3A50
PR_POST_OFFICE_BOX | PT_TSTRING | 0x3A2B
PR_POSTAL_ADDRESS | PT_TSTRING | 0x3A15
PR_POSTAL_CODE | PT_TSTRING | 0x3A2A
PR_PREFERRED_BY_NAME | PT_TSTRING | 0x3A47
PR_PRIMARY_FAX_NUMBER | PT_TSTRING | 0x3A23
PR_PRIMARY_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1A
PR_PROFESSION | PT_TSTRING | 0x3A46
PR_RADIO_TELEPHONE_NUMBER | PT_TSTRING | 0x3A1D
PR_SEND_INTERNET_ENCODING | PT_LONG | 0x3A71
PR_SEND_RICH_INFO | PT_BOOLEAN | 0x3A40
PR_SPOUSE_NAME | PT_TSTRING | 0x3A48
PR_STATE_OR_PROVINCE | PT_TSTRING | 0x3A28
PR_STREET_ADDRESS | PT_TSTRING | 0x3A29
PR_SURNAME | PT_TSTRING | 0x3A11
PR_TELEX_NUMBER | PT_TSTRING | 0x3A2C
PR_TITLE | PT_TSTRING | 0x3A17
PR_TRANSMITABLE_DISPLAY_NAME | PT_TSTRING | 0x3A20
PR_TTYTDD_PHONE_NUMBER | PT_TSTRING | 0x3A4B
PR_USER_CERTIFICATE | PT_BINARY | 0x3A22
PR_USER_X509_CERTIFICATE | PT_MV_BINARY | 0x3A70
PR_WEDDING_ANNIVERSARY | PT_SYSTIME | 0x3A41


SPropProblem

typedef struct _SPropProblem {
    ULONG     ulIndex;
    ULONG     ulPropTag;
    SCODE     scode;
} SPropProblem;

Describes an error relating to an operation involving a property.

ulIndex
Index value into an array of property tags.
ulPropTag
Property tag for the property with the error.
scode
Error value describing the problem with the property.

Back to top


SPropProblemArray

typedef struct _SPropProblemArray {
    ULONG           cProblem;
    SPropProblem    aProblem[MAPI_DIM];
    } SPropProblemArray;

Contains an array of one or more SPropProblem structures.

cProblem
Count of SPropProblem structures in the array indicated by the aProblem member.
aProblem[MAPI_DIM]
Array of SPropProblem structures, each describing a property error.

Back to top


SPropTagArray

typedef struct _SPropTagArray{
    ULONG   cValues;
    ULONG   aulPropTag[MAPI_DIM];
} SPropTagArray;

Contains an array of property tags.

cValues
Count of property tags in the array indicated by the aulPropTag member.
aulPropTag[MAPI_DIM]
Array of property tags.

Back to top


SPropValue

typedef struct _SPropValue {
    ULONG       ulPropTag;
    ULONG       dwAlignPad;
    union _PV   Value;
    } SPropValue;

Contains the property tag values.

ulPropTag
Property tag for the property. Property tags are 32-bit unsigned integers consisting of the property's unique identifier in the high-order 16 bits and the property's type in the low-order 16 bits.
dwAlignPad
Reserved; do not use.
Value
Union of data values, the specific value dictated by the property type. The following table lists, for each property type, the member of the union that should be used and its associated data type.

Table of Property Types
Property type | Value | Data type of Value
PT_I2 or PT_SHORT | i | short int
PT_I4 or PT_LONG (signed) | i | LONG
PT_R4 or PT_FLOAT | flt | FLOAT
PT_R8 or PT_DOUBLE | dbl | double
PT_BOOLEAN | b | unsigned short int
PT_CURRENCY | cur | CURRENCY
PT_APPTIME | at | double
PT_SYSTIME | ft | FILETIME
PT_STRING8 | lpszA | LPSTR
PT_BINARY | bin | BYTE [array]
PT_UNICODE | lpszW | LPWSTR
PT_CLSID | lpguid | LPGUID
PT_I8 or PT_LONGLONG | li | LARGE_INTEGER
PT_MV_I2 | MVi | SShortArray
PT_MV_LONG | MVI | SLongArray
PT_MV_R4 | MVflt | SRealArray
PT_MV_DOUBLE | MVdbl | SDoubleArray
PT_MV_CURRENCY | MVcur | SCurrencyArray
PT_MV_APPTIME | MVat | SAppTimeArray
PT_MV_SYSTIME | MVft | SDateTimeArray
PT_MV_BINARY | MVbin | SBinaryArray
PT_MV_STRING8 | MVszA | SLPSTRArray
PT_MV_UNICODE | MVszW | SLPSTRArray
PT_MV_CLSID | MVguid | SGuidArray
PT_MV_I8 | MVli | SLargeIntegerArray
PT_ERROR | err | SCODE
PT_NULL or PT_OBJECT | x | LONG

Back to top


SRestriction

typedef struct _SRestriction
{
    ULONG   rt;
    union
    {
        SComparePropsRestriction    resCompareProps;
        SAndRestriction             resAnd;
        SOrRestriction              resOr;
        SNotRestriction             resNot;
        SContentRestriction         resContent;
        SPropertyRestriction        resProperty;
        SBitMaskRestriction         resBitMask;
        SSizeRestriction            resSize;
        SExistRestriction           resExist;
        SSubRestriction             resSub;
        SCommentRestriction         resComment;
    } res;
} SRestriction;

Describes a filter for limiting the view of a table to particular rows.

rt
Restriction type. Possible values are:
RES_AND | SRestriction structure describes an AND restriction, which applies a bitwise AND operation to a restriction.
RES_BITMASK | SRestriction structure describes a bitmask restriction, which applies a bitmask to a property value.
RES_COMMENT | SRestriction structure describes a comment restriction, which associates a comment with a restriction.
RES_COMPAREPROPS | SRestriction structure describes a compare properties restriction, which compares two property values.
RES_CONTENT | SRestriction structure describes a content restriction, which searches a property value for specific content.
RES_EXIST | SRestriction structure describes an exist restriction, which determines if a property is supported.
RES_NOT | SRestriction structure describes a NOT restriction, which applies a logical NOT operation to a restriction.
RES_OR | SRestriction structure describes an OR restriction, which applies a logical OR operation to a restriction.
RES_PROPERTY | SRestriction structure describes a property restriction, which determines if a property value matches a particular value.
RES_SIZE | SRestriction structure describes a size restriction, which determines if a property value is a particular size.
RES_SUBRESTRICTION | SRestriction structure describes a subobject restriction, which applies a restriction to a message's attachments or recipients.
res
Union of restriction structures describing the filter to be applied. The specific structure included in the res member depends on the value of the rt member. The mapping between restriction type and structure is listed in the following table.
Restriction type | Structure
RES_AND | SAndRestriction
RES_BITMASK | SBitMaskRestriction
RES_COMMENT | SCommentRestriction
RES_COMPAREPROPS | SComparePropsRestriction
RES_CONTENT | SContentRestriction
RES_EXIST | SExistRestriction
RES_NOT | SNotRestriction
RES_OR | SOrRestriction
RES_PROPERTY | SPropertyRestriction
RES_SIZE | SSizeRestriction
RES_SUBRESTRICTION | SSubRestriction

Back to top


SRow

typedef struct _SRow {
    ULONG         ulAdrEntryPad;
    ULONG         cValues;
    LPSPropValue  lpProps;
    } SRow, FAR *LPSRow;

Describes a row from a table containing selected properties for a specific object.

ulAdrEntryPad
Padding bytes to properly align the property values pointed to by the lpProps member.
cValues
Count of property values pointed to by lpProps.
lpProps
Address of an array of SPropValue structures that describe the property values for the columns in the row.

Back to top


SRowSet

typedef struct _SRowSet {
    ULONG   cRows;
    SRow    aRow[MAPI_DIM];
    } SRowSet;

Contains an array of SRow structures, each SRow structure describing a row from a table.

cRows
Count of SRow structures in the aRow member
aRow[MAPI_DIM]
Array of SRow structures, one for each row in the table.

Back to top


SSortOrder

typedef struct _SSortOrder {
    ULONG ulPropTag;
    ULONG ulOrder;
    } SSortOrder, FAR *LPSSortOrder;

Defines how to sort rows of a table, describing the column to use as the sort key and the direction of the sort.

ulPropTag
Property tag identifying the sort key or, for a categorized sort, the category column.
ulOrder
Order in which the data is to be sorted. Possible values are:
TABLE_SORT_ASCEND | The table should be sorted in ascending order.
TABLE_SORT_COMBINE | The sort operation should create a category that combines the property identified as the sort key column in the ulPropTag member with the sort key column specified in the previous SSortOrder structure.
TABLE_SORT_COMBINE can only be used when the SSortOrder structure is being used as an entry in an SSortOrderSet structure to specify multiple sort orders for a categorized sort. TABLE_SORT_COMBINE cannot be used in the first SSortOrder structure in an SSortOrderSet structure.
TABLE_SORT_DESCEND | The table should be sorted in descending order.

Back to top


SSortOrderSet

typedef struct _SSortOrderSet {
    ULONG      cSorts;
    ULONG      cCategories;
    ULONG      cExpanded;
    SSortOrder aSort[MAPI_DIM];
    } SSortOrderSet, FAR *LPSSortOrderSet;

Defines a collection of sort keys for a table to be used for standard or categorized sorting.

cSorts
Count of SSortOrder structures that are included in the aSort member.
cCategories
Count of columns that are designated as category columns. Possible values range from zero, which indicates a non-categorized or standard sort, to the number indicated by the cSorts member.
cExpanded
Count of categories that start in an expanded state, where all the rows that apply to the category are visible in the table view. Possible values range from zero to the number indicated by cCategories.
aSort[MAPI_DIM]
Array of SSortOrder structures, each defining a sort order.

Back to top


WAB_PARAM

typedef struct _tagWAB_PARAM
{
    ULONG   cbSize;
    HWND    hwnd;
    LPTSTR  szFileName;
    ULONG   ulFlags;
    } WAB_PARAM ;

Contains the input information to pass to WABOpen.

cbSize
Size, in bytes, of the WAB_PARAM structure.
hwnd
hWnd parameter of the calling client application. Can be NULL.
szFileName
Internet Explorer Address Book file name to open. If this parameter is NULL, the default Address Book file is opened.
ulFlags
Currently not implemented in Internet Explorer Address Book.


Internet Mail and News Registry Layout

This topic describes how to make your e-mail reader or newsreader available in the list of mail/news programs for Microsoft® Internet Explorer, and how to integrate tightly with Internet Explorer.

Client Registry Settings Overview

Mail Keys

News Keys

Client Registry Settings Overview

Internet Explorer 3.0 supports an open architecture for non-HTTP clients, such as mail and news. This section outlines the registry settings used by Internet Explorer to determine which clients to use and how to use them. The section also outlines the registry settings that third-party clients must provide in order to be recognized and used by the system as the default client.

A new "Clients" key has been defined under HKEY_LOCAL_MACHINE\SOFTWARE. Right now, there are two defined clients: mail and news, which are subkeys of this key.

Key Value Meaning
HKLM\SOFTWARE\Clients\Mail (default) Subkey name where information about the default mail client can be found.

The root key of the information for this client can be found by appending this string to HKLM\Software\Clients\Mail.

HKLM\SOFTWARE\Clients\News (default) Subkey name where information about the default news client can be found.

The root key of the information for this client can be found by appending this string to HKLM\Software\Clients\News

So, for example, if this value is "Internet Mail and News", information about this client can be found at HKLM\SOFTWARE\Clients\Mail\Internet Mail and News.

Mail Keys

Key | Value | Meaning
HKLM\SOFTWARE\Clients\Mail\clientname (default) Friendly name for this client.

The list of clients in the Internet Control Panel is generated by enumerating all the client subkeys and appending the friendly name for each to the list.

HKLM\SOFTWARE\Clients\Mail\clientname\Protocols\mailto (various) Contains a mirror of the registry settings that the application needs to have written under HKEY_CLASSES_ROOT\mailto in order to service mailto URLs.

This entire registry hierarchy will replace the existing mailto: registry hierarchy.

HKLM\SOFTWARE\Clients\Mail\clientname\shell\open\command | (default) | Contains the command line that will launch the mail client into its default view (typically the Inbox).

News Keys

Key | Value | Meaning
HKLM\SOFTWARE\Clients\News\clientname (default) Friendly name for this client.

The list of clients in the Internet Control Panel is generated by enumerating all the client subkeys and appending the friendly name for each to the list.

HKLM\SOFTWARE\Clients\News\clientname\Protocols\news (various) Contains a mirror of the registry settings that the application needs to have written under HKEY_CLASSES_ROOT\news in order to service news URLs.

This entire registry hierarchy will replace the existing news: registry hierarchy.

HKLM\SOFTWARE\Clients\News\clientname\Protocols\nntp (various) Contains a mirror of the registry settings that the application needs to have written under HKEY_CLASSES_ROOT\nntp in order to service nntp URLs.

This entire registry hierarchy will replace the existing nntp: registry hierarchy.

HKLM\SOFTWARE\Clients\News\clientname\Protocols\snews (various) Contains a mirror of the registry settings that the application needs to have written under HKEY_CLASSES_ROOT\snews in order to service snews URLs.

This entire registry hierarchy will replace the existing snews: registry hierarchy.

HKLM\SOFTWARE\Clients\News\clientname\shell\open\command | (default) | Contains the command line that will launch the news client into its default view.


Internet Ratings

The Platform for Internet Content Selection (PICS) is a W3C group chartered to define a standard for the creation of rating systems and rating information. PICS is the open W3C standard for solving the problems with minors accessing adult content on the Internet; Microsoft views PICS as the best direction for solving these problems. This document describes how to support ratings on the Microsoft® Internet Explorer platform. It is intended for HTML authors who wish to support PICS ratings on their site, and also for programmers who are developing Web authoring or viewing tools and applications.

The PICS Standard

Internet Ratings API

Internet Ratings API Reference

The PICS Standard

This section describes how the PICS system works, shows an example of rating information within an HTML page, and briefly describes the PICS specification.

How the PICS system works

The PICS system has two types of components: rating systems and rating labels. A rating system defines the criteria for how content is rated. PICS has created a meta-language for defining the different categories and the different values for rating content. For example, the Motion Picture Association of America (MPAA) rating system has one category with five values: G, PG, PG-13, R, and NC-17. Using the PICS specification, rating systems with multiple categories can be defined.

The rating label is the actual rating information. The label can appear on a Web page as part of the HTML content, on a third-party Web site, or anywhere else that a particular client application "knows" to look for them. Each item of content that is rated would have its own label. PICS has defined the syntax for these rating labels, as well as extensions to many Internet protocols to support labels.

The PICS system works by matching labels to their associated systems. The client software, either part of the Web browser or a separate application, allows parents to decide what levels of content they want to allow their children to see for each rating system. Then, as the child uses the PICS-aware Web browser or application, the Web browser finds the rating labels for the content and checks against the values the parent has set by calling a function in the Internet Ratings API. If the content is rated higher than the child is allowed, the content is not displayed.

Example of HTML tagged ratings

Ratings are specified by using an additional tag within the HTML header (<HEAD> rating information </HEAD>). The rating is in English text, as defined by the PICS specification. More details are provided in the full PICS documentation found on the PICS Web site: http://www.w3.org/PICS/ External Link.

The following example shows the general format of rating information within an HTML page.

<HTML>
<HEAD>
<META http-equiv="PICS-Label" content='(PICS-1.0 "http://www.rsac.org"
labels on "1996.11.05T08:15-0500"
until "1996.12.31T23:59-0000"
for "http://www.rsac.org/index.html"
by "RSAC "
rating (language 2 nudity 0 violence 1))'>
</HEAD>

The core of the rating label is the rating string, which provides a list of category/value pairs. For each category, the name and the associated value are listed.

What PICS has defined

PICS has defined two specifications—one for creating rating systems and one for creating rating labels. A rating system defines the criteria for how content is rated. Based on the PICS specification for rating systems, any group or individual could define a system for rating content. Using the PICS specification, you could take the MPAA rating system and define it as a PICS-compliant rating system.

The PICS specification is quite extensive, and it allows for a system to contain multiple categories. The MPAA system has only one category with five values: G, PG, PG-13, R, and NC-17. It has been criticized for being too simplistic and not offering granularity on multiple dimensions. PICS solves this problem by allowing the creator of the rating system to have great flexibility in how the system is defined.

PICS has not defined an actual rating system or an actual scheme for rating Internet content. PICS is a framework and a language that allows any group or organization to rate content on their own criteria. PICS has not created a replacement for the movie rating system, nor does it intend to.

For more information about rating systems, see the PICS specification on their Web site: http://www.w3.org External Link.

Amendments to the PICS specification

The PICS specification makes no provisions for storing information on rating systems locally. On the Microsoft Windows® platform, the text description for PICS rating systems is contained in a text file with an .rat extension. This file would contain all the category and value information that PICS has defined as necessary. Microsoft may define fields for information about a given rating system, including its PICS rating server URL if it has one.

What Internet content providers should know about PICS

Internet Content Providers (ICPs) need to be aware that they must take the initiative in getting their content rated by a PICS-compliant rating system. For a rating system to be useful, the browser application must deny access to sites that are unrated. ICPs should contact the PICS committee for a listing of rating groups that are based on PICS.

Microsoft is committed to supporting the PICS standard and providing API and reference information for other products that want to support PICS. In addition, Microsoft is assisting several third-party groups to create PICS-based rating systems. In particular, the Recreation Software Advisory Council (RSAC) has created a rating system called RSACi. Their Web site, http://www.rsac.org External Link, provides a simple online mechanism for getting content rated through their system.

What developers of Web authoring tools should know about PICS

Developers of Web authoring tools need to be PICS-aware so that their tools support the ability to easily enter META tags into Web pages. Web authoring tools can help promote the PICS technology by providing templates or wizards for adding PICS ratings to documents.

Of significant importance is the ability to maintain ratings for groups or "virtual trees" of pages. Some PICS-compliant rating systems might offer ratings for groups of content. This will allow larger sites to section adult content from general audience content. Web authoring and management tools need to provide the ability to propagate rating information across user-defined groups of pages.

Microsoft intends to provide support for the easy addition of PICS-compliant rating information into appropriate Internet content tools.

Internet Ratings API

The Microsoft Internet Ratings API provides Win32®-based applications with easy access to PICS-based Internet ratings support and related services. These functions provide any application with access to a PICS rating parsing engine, as well as a mechanism for comparing ratings against the user information settings in Internet Explorer 4.0. This API will be available as part of Internet Explorer 4.0.

The functions in the Internet Ratings API set facilitate access to the ratings support in the following ways:

  • Provide a common interface for parsing and obtaining PICS-compliant rating information. A browser or other application can support ratings with the addition of only a few function calls. By providing task-oriented functions, applications need only make a few function calls to support ratings.
  • Eliminate the need for individual applications to define their own control systems. With this API, applications need only find the rating information for a given piece of content. Additional APIs for retrieving some types of Internet ratings are provided.

Overview of Internet ratings functions

The PICS specification allows for rating information to appear in HTML tags, in HTTP headers, and on a third-party URL. For performance reasons, each individual browser is responsible for obtaining HTML- and HTTP-based rating information (for details on obtaining these mechanisms, consult the PICS specification).

The following table summarizes the PICS-support API functions. This table lists all the functions for finding, pairing, and comparing rating information.
Function | Description
RatingAccessDeniedDialog,RatingAccessDeniedDialog2 | Displays a system dialog box informing the user that access has been denied.
RatingCheckUserAccess | Takes in a PICS rating, parses it, and compares it against what a specified user can see.
RatingEnable | Enables and disables ratings.
RatingEnabledQuery | Specifies whether ratings are on or off.
RatingFreeDetails | Frees a pointer to denial information.
RatingObtainCancel | Cancels a call to RatingObtainQuery.
RatingObtainQuery | Obtains ratings from certain locations and compares them.
RatingSetupUI | Displays a modal dialog box that allows a supervising parent to set levels of restrictions.

Using the Internet ratings functions

A browser or other application would typically use the rating functions in the following fashion:

  1. The browser starts, and the user connects to the Internet.
  2. The user enters a URL.
  3. The browser calls the RatingEnabledQuery function. If the function returns S_FALSE, the browser allows access to the content.
  4. The browser calls the RatingObtainQuery function and passes the URL. The function checks the local list, and then the third-party list or any third-party add-on is activated. If the function finds a rating for the URL, it calls RatingCheckUserAccess with the rating. If RatingObtainQuery does not return an error immediately, eventually the browser's callback function will be called.
  5. Meanwhile, the browser searches for a rating label within the content being downloaded from the site. If it finds an HTML/HTTP rating, it calls the RatingCheckUserAccess function.
  6. If no rating label is found within the document, the browser calls RatingCheckUserAccess with a NULL rating label, to determine whether the user can access unrated content.
  7. When both RatingCheckUserAccess and RatingObtainQuery have been called, the browser has received at least one explicit access-allowed or access-denied report. If RatingObtainQuery explicitly allowed or denied access, that result should override any rating found in the document and the user's ability to see unrated content.
  8. If access is denied, the browser calls the RatingAccessDeniedDialog function. Depending on the supervisor's response to the dialog box, this function can indicate that access should be allowed after all.
  9. If access is allowed, the browser displays the content.

Finding HTML/HTTP rating labels

The PICS specification defines the Backus-Naur Form (BNF) syntax for rating information, or rating nuggets. PICS specifies that rating nuggets can appear as part of HTML documents, within the header tags. The PICS specification also allows for rating information to appear as part of the HTTP headers.

For performance and logistic reasons, it is the responsibility of the browser to obtain HTML- and HTTP-level ratings. Details on how to find HTML-based ratings are part of the PICS specification. Details on HTTP ratings and the associated HTTP header are specified by PICS.

The PICS committee might eventually provide reference code for applications that want to find HTML/HTTP-based ratings.


Internet Ratings API Reference

This section contains detailed reference information about the functions in the Microsoft Internet Ratings API.

  • RatingAccessDeniedDialog
  • RatingAccessDeniedDialog2
  • RatingCheckUserAccess
  • RatingEnable
  • RatingEnabledQuery
  • RatingFreeDetails
  • RatingObtainCancel
  • RatingObtainQuery
  • RatingSetupUI


RatingAccessDeniedDialog

HRESULT RatingAccessDeniedDialog(
    HWND hwndParent,
    LPCTSTR pszUsername,
    LPCTSTR pszContentDescription,
    LPVOID pRatingDetails
);

Displays a modal dialog box telling the user that access to the requested content is denied. The supervisor can set an option that adds controls to the dialog box; these controls would allow a supervisor to enter a user name and password to override the rating and allow access.

  • Returns one of the following values:
    S_OK | The supervisor entered the password. Access should be allowed.
    S_FALSE | The user is still denied access to the content.
    Error values | An error occurred.
hwndParent
Handle to the parent window for the modal dialog box.
pszUsername
Address of a string that contains the name of the user who was denied access. If this parameter is NULL, the user name is extracted from the structure specified by pRatingDetails, or the current user name is used.
pszContentDescription
Address of a string that describes the content to which access was denied.
pRatingDetails
Opaque pointer returned by the RatingCheckUserAccess function. This parameter can provide the dialog box with additional information about why access was denied, such as whether the site is considered rated, which ratings exceeded limits, and where the rating was obtained.

See also RatingCheckUserAccess


RatingAccessDeniedDialog2

HRESULT RatingAccessDeniedDialog2(
     HWND hwndParent,
     LPCSTR pszUsername,
     LPVOID pRatingDetails);

This function is identical in functionality to RatingAccessDeniedDialog except that if a ratings dialog box is already being displayed modal to the specified parent window, the details from the second call are inserted into the existing dialog box.

  • Returns one of the following values:
    S_OK | The supervisor entered the password. Access should be allowed.
    S_FALSE | The user is still denied access to the content.
    Error values | An error occurred.
hwndParent
Handle to the parent window for the modal dialog box.
pszUsername
Address of a string that contains the name of the user who was denied access. If this parameter is NULL, the user name is extracted from the structure specified by pRatingDetails, or the current user name is used.
pRatingDetails
Opaque pointer returned by the RatingCheckUserAccess function. This parameter can provide the dialog box with additional information about why access was denied, such as whether the site is considered rated, which ratings exceeded limits, and where the rating was obtained.

See also RatingCheckUserAccess


RatingCheckUserAccess

HRESULT RatingCheckUserAccess(
    LPCTSTR pszUsername,
    LPCTSTR pszURL,
    LPCTSTR pszRatingInfo,
    LPBYTE pData,
    DWORD cbData,
    LPVOID *ppRatingDetails
);

Determines whether the user is allowed to view the given content based on the associated rating label. An application calls this function when it finds a rating label.

  • Returns one of the following values:
    S_OK | Access is allowed.
    S_FALSE | Access is denied.
    Error values | Content should be considered unrated.
pszUsername
Address of a string that contains the name of the user whose access to the content should be validated. A NULL value indicates the currently logged on user. For Internet Explorer version 3.0, NULL is the only valid value for this parameter.
pszURL
Address of the URL to which the rating label is to apply. The function uses this parameter to validate the corresponding field in the rating label, to verify that the rating label actually belongs to the URL for which the label was obtained. This parameter can be NULL if a URL is not applicable.
pszRatingInfo
Address of the PICS label to parse and verify (for example, the text between the "content" single quotation marks in the example in Example of HTML Tagged Ratings). This parameter can be NULL if the application cannot find a rating in the content itself; in this case, the function returns a value that indicates whether the user is allowed to see unrated content.
pData and cbData
Address of the content being rated and the length, in bytes, of the content data stream. These parameters may be necessary if the rating itself contains a hash of the data for security reasons. If pData is NULL, the cbData parameter is ignored, and the hash cannot be validated.
ppRatingDetails
Address of a variable that contains a pointer to an opaque data structure that describes in more detail why access to the content is denied. This parameter has meaning only to the RatingAccessDeniedDialog function. This parameter can be NULL, in which case the dialog box created by RatingAccessDeniedDialog cannot report detailed information to the user. If this parameter is not NULL, the application must call the RatingFreeDetails function to free the data, no matter what value the RatingCheckUserAccess function returns or what value is stored in ppRatingDetails.

This function allows ratings of any content type, including CD-ROMs, news groups, Web sites, and so on, provided the client application can find the rating information. The RatingObtainQuery function makes an internal call to the RatingCheckUserAccess function before calling the application's callback function.

See also RatingAccessDeniedDialog, RatingFreeDetails, RatingObtainQuery


RatingEnable

HRESULT RatingEnable(
     HWND hwndParent,
     LPCSTR pszUsername,
     BOOL fEnable);

Enables or disables ratings.

  • Returns one of the following values:
    S_OK | If fEnable was TRUE, ratings have been enabled. Otherwise, ratings were disabled.
    S_FALSE | Ratings were not successfully enabled or disabled.
    E_ACCESSDENIED | Ratings were enabled, and the user specified a bad password.
    HRESULT_FROM_WIN32(ERROR_BAD_USERNAME) | The specified username was invalid.
hwndParent
Handle of a parent window used for any dialog boxes that might be presented.
pszUsername
Address of a string that contains the name of the user requesting that ratings should be enabled or disabled.
fEnable
Boolean value indicating whether ratings should be enabled or disabled. TRUE indicates that ratings should be enabled. FALSE indicates the contrary.


RatingEnabledQuery

HRESULT RatingEnabledQuery(void)

Reports whether ratings should be enforced or not. If the supervisor has not configured any restrictions or has temporarily disabled them, the application may allow access to all content and need not call any other rating functions.

  • Returns one of the following values:
    S_OK | Ratings are enabled and should be enforced.
    S_FALSE | Ratings are disabled and should be ignored.


RatingFreeDetails

HRESULT RatingFreeDetails(
    LPVOID pRatingDetails
);

Frees the detail information returned by the RatingCheckUserAccess function.

pRatingDetails
Opaque pointer returned by RatingCheckUserAccess.

See also RatingCheckUserAccess


RatingObtainCancel

HRESULT RatingObtainCancel(
    HANDLE hRatingObtainQuery
);

Allows a browser to cancel its request to obtain the rating for a URL.

hRatingObtainQuery
Handle obtained by a previous call to the RatingObtainQuery function.

See also RatingObtainQuery


RatingObtainQuery

HRESULT RatingObtainQuery(
    LPCTSTR pszTargetUrl,
    DWORD dwUserData,
    void (*fCallback)(
        DWORD dwUserData,
        HRESULT hres,
        LPCTSTR pszRating,
        LPVOID lpvRatingDetails
    ),
    HANDLE *phRatingObtainQuery
);

Encapsulates the process of checking ratings that appear on a local list, third-party PICS server, or future third-party add-on rating services.

pszTargetUrl
URL whose ratings are to be queried.
dwUserData
Data to be passed to the callback function specified by fCallback.
fCallback
Application-defined function that is called upon completion. This function is called in the context of a different thread than the one that called RatingObtainQuery.

The callback function has the following parameters:
dwUserData | Data supplied in the initial call to RatingObtainQuery.
hres Result of the query. Can be one of the following values:
S_OK | Rating found and access allowed.
S_FALSE | Rating found and access denied.
Any error values | Rating or service unavailable; look for ratings from other sources if possible.
pszRating | Rating information for the document if it is available. (Note that the application can choose to ignore this parameter because RatingCheckUserAccess has already been called to generate the hres parameter).
lpvRatingDetails | Token that can be used in the RatingAccessDeniedDialog dialog box. This must be freed with a call to RatingFreeDetails.

phRatingObtainQuery
Address of a handle that can be used to cancel this operation. This parameter can be NULL if the handle is not needed.

A browser obtains the URL from the user and calls this function. Asynchronously, this function searches for a rating for the specified document. When the search ends, the function calls the application's callback function, on a different thread than the one that called RatingObtainQuery. While waiting for the callback to be called, browsers may choose to download the content but prevent the user from accessing it until the query is resolved.

If RatingObtainQuery returns an error, the application should assume the site is unrated by local and third-party ratings, and look for the HTML/HTTP-level ratings itself.


RatingSetupUI

HRESULT RatingSetupUI(
    HWND hwndParent,
    LPCSTR pszUsername
);

Displays a modal dialog box that allows a supervising parent to set levels of restrictions. The RatingCheckUserAccess function uses these settings to compare against rating labels.

hwndParent
Handle to the parent window for the modal dialog box.
pszUsername
Address of a string that contains the name of the user whose settings should be configured. If this parameter is NULL, settings for all users are set. This parameter must be NULL in Internet Explorer version 3.0.

This function ensures that the current user is a supervisor before allowing access to the configuration user interface.


Internet Shortcuts API Reference

This topic explains the Internet Shortcuts API for managing "shortcuts" to URL locations.

IUniformResourceLocator Interface

Internet Shortcut Global Functions

Internet Shortcut Enumerated Types

Internet Shortcut Structures


IUniformResourceLocator Interface

This section provides information about the following IUniformResourceLocator interface methods:

  • IUniformResourceLocator::GetURL
  • IUniformResourceLocator::InvokeCommand
  • IUniformResourceLocator::SetURL


IUniformResourceLocator::GetURL

HRESULT GetURL(
    LPSTR *ppszURL
);

Retrieves an object's uniform resource locator (URL).

  • Returns S_OK if the object's URL was retrieved successfully. If the object does not have a URL associated with it, the function returns S_FALSE and sets ppszURL to NULL. Otherwise, the return value is an error code that can be one of the following:
    E_OUTOFMEMORY | There is not enough memory to complete the operation.
    IS_E_EXEC_FAILED | The URL's protocol handler failed to run.
    URL_E_INVALID_SYNTAX | The URL's syntax is invalid.
    URL_E_UNREGISTERED_PROTOCOL | The URL's protocol does not have a registered protocol handler.
ppszURL
Address of an LPSTR that will be filled in with a pointer to the object's URL. Because this method allocates memory for the string, you must instantiate an IMalloc interface and free the memory using IMalloc::Free when it is no longer needed. The following code fragment provides an example of how this can be done.
//  START CODE FRAGMENT
{
    // In this example, pURL is a global IUniformResourceLocator pointer.
    LPSTR lpTemp;

    hres = pURL->GetURL(&lpTemp);
    if (SUCCEEDED(hres)){
        IMalloc* pMalloc;
        hres = SHGetMalloc(&pMalloc);
        if (SUCCEEDED(hres)){
            pMalloc->Free(lpTemp);
            pMalloc->Release();
        }
    }
}
//  END CODE FRAGMENT


IUniformResourceLocator::InvokeCommand

HRESULT InvokeCommand(
    PURLINVOKECOMMANDINFO pURLCommandInfo;
);

Runs a command on an object's URL.

  • Returns S_OK if the object's URL was opened successfully. If the object does not have a URL associated with it, the function returns S_FALSE. Otherwise, the return value is an error code that can be one of the following:
    E_OUTOFMEMORY | There is not enough memory to complete the operation.
    IS_E_EXEC_FAILED | The URL's protocol handler failed to run.
    URL_E_INVALID_SYNTAX | The URL's syntax is invalid.
    URL_E_UNREGISTERED_PROTOCOL | The URL's protocol does not have a registered protocol handler.
pURLCommandInfo
Address of a URLINVOKECOMMANDINFO structure that contains command information for the function.


IUniformResourceLocator::SetURL

HRESULT SetURL(
    LPCSTR pcszURL,
    DWORD dwInFlags
);

Sets an object's URL.

  • Returns S_OK if the object's URL was set successfully. Otherwise, the return value is an error code that can be one of the following:
    E_OUTOFMEMORY | There is not enough memory to complete the operation.
    IS_E_EXEC_FAILED | The URL's protocol handler failed to run.
    URL_E_INVALID_SYNTAX | The URL's syntax is invalid.
    URL_E_UNREGISTERED_PROTOCOL | The URL's protocol does not have a registered protocol handler.
pcszURL
Address of a zero-terminated string that contains the URL to set. The protocol scheme may be included as part of the URL.
dwInFlags
Flag value that specifies the behavior for setting the protocol scheme. This field can contain one of the following values:
IURL_SETURL_FL_GUESS_PROTOCOL | If the protocol scheme is not specified in pcszURL, the system automatically chooses a scheme and adds it to the URL.
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL | If the protocol scheme is not specified in pcszURL, the system adds the default protocol scheme to the URL.


Internet Shortcut Global Functions

This section contains information about the following Internet Shortcut global functions:

  • InetIsOffline
  • MIMEAssociationDialog
  • TranslateURL
  • URLAssociationDialog


InetIsOffline

BOOL InetIsOffline (
    DWORD dwFlags
);

Determines whether the system is connected to the Internet.

  • Returns TRUE if the local system in not currently connected to the Internet. Returns FALSE if the local system is connected to the Internet or if no attempt has yet been made to connect to the Internet.
dwFlags
Input flags for the function. This must be set to zero.


MIMEAssociationDialog

HRESULT WINAPI MIMEAssociationDialog (
    HWND    hwndParent,
    DWORD   dwInFlags,
    LPCSTR  pcszFile,
    LPCSTR  pcszMIMEContentType,
    LPSTR   pszAppBuf,
    UINT    ucAppBufLen
);

Runs the unregistered MIME content type dialog box.

  • Returns S_OK if the content type was successfully associated with the extension. In this case, the extension is associated as the default for the content type, and pszAppBuf points to the string that contains the path of the specified application. The function returns S_FALSE if nothing was registered. Otherwise, the return value will be one of the following:
    E_ABORT | The user canceled the operation.
    E_FLAGS | The flag combination passed in dwInFlags is invalid.
    E_OUTOFMEMORY | There was insufficient memory available to complete the operation.
    E_POINTER | One of the input pointers is invalid.
hwndParent
Handle to the parent window of any posted child windows.
dwInFlags
Bit flag value that specifies if an association is to be registered. The bit flag is the value MIMEASSOCDLG_FL_REGISTER_ASSOC (0x0001). If this bit is set, the selected application is registered as the handler for the given MIME type. If this bit is clear, no association is registered.

An application is registered only if this flag is set and the user indicates that a persistent association is to be made.

Registration is impossible if the string at pcszFile does not contain an extension.

pcszFile
Address of a null-terminated string that contains the name of the target file. This file must conform to the content type described by the pcszMIMEContentType parameter.
pcszMIMEContentType
Address of a null-terminated string that contains the unregistered content type.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
Size of pszAppBuf, in characters.

Note This function does not validate the syntax of the input content type string at pcszMIMEContentType. A successful return value does not indicate that the specified MIME content type is valid.


TranslateURL

HRESULT WINAPI TranslateURL(
    LPCSTR pcszURL,
    DWORD dwInFlags,
    LPSTR *ppszTranslatedURL
);

Applies common translations to a given URL string, creating a new URL string.

  • Returns S_OK upon success, or S_FALSE if the URL did not require translation. If an error occurs, the function returns one of the following values:
    E_FLAGS | The flag combination passed in dwInFlags is invalid.
    E_OUTOFMEMORY | There was insufficient memory to complete the operation.
    E_POINTER | One of the input pointers is invalid.
pcszURL
Address of the URL string to be translated.
dwInFlags
Bit flags that specify how the URL string is to be translated. This value can be a combination of the following:
TRANSLATEURL_FL_GUESS_PROTOCOL | If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL | If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.
ppszTranslatedURL
Pointer variable that receives the pointer to the newly created, translated URL string, if any. The *ppszTranslatedURL parameter is valid only if the function returns S_OK.

This function does not validate the input URL string. A successful return value does not indicate that the URL strings are valid URLs.


URLAssociationDialog

HRESULT WINAPI URLAssociationDialog(
    HWND hwndParent,
    DWORD dwInFlags,
    LPCSTR pcszFile,
    LPCSTR pcszURL,
    LPSTR pszAppBuf,
    UINT ucAppBufLen
);

Invokes the unregistered URL protocol dialog box. This dialog box allows the user to select an application to associate with a previously unknown protocol.

  • Returns S_OK if the application is registered with the URL protocol, or S_FALSE if nothing is registered. For example, the function returns S_FALSE when the user elects to perform a one-time execution via the selected application.
hwndParent
Handle to the parent window.
dwInFlags
Bit flags that specify the behavior of the function. This value can be a combination of the following:
URLASSOCDLG_FL_USE_DEFAULT_NAME | Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC | Register the selected application as the handler for the protocol specified in pcszURL. The application is registered only if this flag is set and the user indicates that a persistent association is desired.
pcszFile
Address of a constant zero-terminated string that contains the file name to associate with the URL's protocol.
pcszURL
Address of a constant zero-terminated string that contains the URL with an unknown protocol.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
The size of pszAppBuf, in characters.


Internet Shortcut Enumerated Types

This section contains information on the following Internet Shortcut enumerated types:

  • IURL_SETURL_FLAGS
  • IURL_SETURL_INVOKECOMMAND_FLAGS
  • MIMEASSOCIATIONDIALOG_IN_FLAGS
  • TRANSLATEURL_IN_FLAGS
  • URLASSOCIATIONDIALOG_IN_FLAGS


IURL_SETURL_FLAGS

typedef enum iurl_seturl_flags{
    IURL_SETURL_FL_GUESS_PROTOCOL         = 0x0001,
    IURL_SETURL_FL_USE_DEFAULT_PROTOCOL   = 0x0002
}  IURL_SETURL_FLAGS;

The following enumerated values are used with the IUniformResourceLocator::SetURL method. They are passed in as the dwInFlags parameter.

IURL_SETURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system automatically chooses a scheme and adds it to the URL.
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system adds the default protocol to the URL.


IURL_SETURL_INVOKECOMMAND_FLAGS

typedef enum iurl_invokecommand_flags{
    IURL_INVOKECOMMAND_FL_ALLOW_UI           = 0x0001,
    IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB   = 0x0002,
}  IURL_INVOKECOMMAND_FLAGS;

The following enumerated values are used in the dwFlags member of the URLINVOKECOMMANDINFO structure.

IURL_INVOKECOMMAND_FL_ALLOW_UI
If this bit is set, interaction with the user is allowed and the hwndParent member of the URLINVOKECOMMANDINFO structure is valid. If this bit is clear, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
If this bit is set, the default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member of the URLINVOKECOMMANDINFO structure is ignored. If this bit is clear, the verb is specified by pcszVerb.


MIMEASSOCIATIONDIALOG_IN_FLAGS

typedef enum mimeassociationdialog_in_flags{
    MIMEASSOCDLG_FL_REGISTER_ASSOC     = 0x0001
} MIMEASSOCIATIONDIALOG_IN_FLAGS;

The following enumerated value is used with the MIMEAssociationDialog function to determine how it executes.

MIMEASSOCDLG_FL_REGISTER_ASSOC
If this bit is set, the selected application is registered as the handler for the given MIME type. If this bit is clear, no association is registered.

An application is registered only if this flag is set and the user indicates that a persistent association is to be made.


TRANSLATEURL_IN_FLAGS

typedef enum translateurl_in_flags {
    TRANSLATEURL_FL_GUESS_PROTOCOL         = 0x0001,
    TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL   = 0x0002,
} TRANSLATEURL_IN_FLAGS;

The following enumerated values are used with the TranslateURL function to determine how it will execute.

TRANSLATEURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.


URLASSOCIATIONDIALOG_IN_FLAGS

typedef enum urlassociationdialog_in_flags {
    URLASSOCDLG_FL_USE_DEFAULT_NAME  = 0x0001,
    URLASSOCDLG_FL_REGISTER_ASSOC    = 0x0002
} URLASSOCIATIONDIALOG_IN_FLAGS;

The following enumerated values are used with the URLAssociationDialog function to determine how it executes.

URLASSOCDLG_FL_USE_DEFAULT_NAME
Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC
Register the selected application as the handler for the protocol specified in the pcszURL parameter of URLAssociationDialog. The application is registered only if this flag is set and the user indicates that a persistent association is desired.


Internet Shortcut Structures Internet Shortcut Structures *
  * Previous Topic: URLASSOCIATIONDIALOG_IN_FLAGS
  * Next Topic: URLINVOKECOMMANDINFO

Internet Shortcut Structures

This section provides information about the following Internet Shortcut structure:

  • URLINVOKECOMMANDINFO


URLINVOKECOMMANDINFO

typedef struct  {
    DWORD    dwcbSize;
    DWORD    dwFlags;
    HWND     hwndParent;
    LPCSTR  pcszVerb;
} URLINVOKECOMMANDINFO, *PURLINVOKECOMMANDINFO;

Contains information for use with the IUniformResourceLocator::InvokeCommand method.

dwcbSize
Size of this structure, in bytes.
dwFlags
Flag value that specifies how the IUniformResourceLocator::InvokeCommand method will execute. This value can be a combination of the following:
IURL_INVOKECOMMAND_FL_ALLOW_UI
Interaction with the user is allowed and the hwndParent member of this structure is valid. If this is not set, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
Default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member is ignored. If this bit is not set, the verb is specified by pcszVerb.
hwndParent
Handle to the parent window. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.
pcszVerb
Address of a zero-terminated string that contains the verb to be invoked by IUniformResourceLocator::InvokeCommand. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.


Offline Browsing

Supporting Offline Browsing in Applications and Components

To further provide users with the best browsing experience, Internet Explorer 4.0 introduces offline browsing to the Win32 platform. Offline browsing allows users to view Web pages from the cache, a local repository of files gathered from the Web through normal browsing and the delivery of content subscriptions.

Understanding the Global Offline State

Application Development Considerations for Offline Browsing

Offline Considerations for Component Developers

Considering Backward Compatibility

Conclusion

Understanding the Global Offline State

In conjunction with this feature, users can choose to work offline by selecting the corresponding menu item from the File menu in Internet Explorer 4.0.

Once this item is selected, the system enters a global offline state independent of any current network connection, and content is read exclusively from the cache. If the content is not available locally, Internet Explorer 4.0 prompts the user to go online or to continue working offline.

The following document describes the API elements that enable third-party developers to hook into the offline browsing architecture. It also provides some recommendations to developers to help them provide a seamless experience to users.

Application Development Considerations for Offline Browsing

At the core of Internet Explorer 4.0 is URLMON.DLL and WININET.DLL. These DLLs handle all low-level requests made by the browser for Internet resources. Using the WININET and URLMON APIs, developers targeting Internet, Intranet, and Extranet environments can easily contribute to a positive offline browsing experience.

Determining the Global Offline State

Internet Explorer 4.0 uses URL Monikers which in turn uses the WININET API to perform all network requests including URL navigation and caching. WININET automatically checks the global offline state before making a resource request. If the system is globally offline, WININET attempts to retrieve the resource exclusively from the cache. If the resource is present, the request succeeds. Otherwise, the request fails. If the request fails, Internet Explorer 4.0 checks if the user is in the global offline state. An application can use the WININET InternetQueryOption function to check the global offline state.

   // Returns true if the global state is offline. Otherwise, false.
   BOOL IsGlobalOffline(void)
   {
      DWORD dwState = 0, dwSize = sizeof(DWORD);
      BOOL fRet = FALSE;

      if(InternetQueryOption(NULL,
         INTERNET_OPTION_CONNECTED_STATE, &dwState,
         &dwSize))
      {
         if(dwState & INTERNET_STATE_DISCONNECTED_BY_USER)
            fRet = TRUE;
      }
      return fRet;
   }

If the user explicitly chooses to navigate to unavailable content, Internet Explorer uses the WININET InternetGoOnline function to present the user with a dialog box that allows the user to "Connect" or "Stay Offline." If "Connect" is chosen, the function invokes InternetAutoDial. This function attempts to establish a network connection and, upon success, takes the system out of global offline mode. If InternetGoOnline succeeds, the system is connected and globally online. An application can then make the request for the resource again.

Here's some code that demonstrates the overall logic:

   // Cache the Internet handle if not already available.
   DWORD dwAccessType = INTERNET_OPEN_TYPE_PRECONFIG;
   DWORD dwInetOpenFlags = 0;

   hInternet = InternetOpen(
         "007",
         dwAccessType,
         NULL,
         NULL,
         dwInetOpenFlags);

   hFile = InternetOpenUrl(
         hInternet,
         szURL,
         NULL, 0, 0, 0);

   if (!hFile)
   {
      if (IsGlobalOffline())
      {
         // If globally offline, ask the user for permission to go online.
         if (InternetGoOnline(szURL, g_hwnd, INTERENT_GOONLINE_REFRESH))
         {
            // try again now that we're online
            hFile = InternetOpenUrl(
               hInternet,
               szURL,
               NULL, 0, 0, 0);
            if (!hFile)
            {
               InternetCloseHandle(hInternet);
               return;
            }
      }
   }

If the user chooses to go online and the second request fails, the resource simply may not exist as is the case when a user specifies a bad URL in the address bar or clicks on a stale hyperlink.

Detecting if Content is Locally Available

While it is essential that the user be presented with a dialog box before they are taken out of global offline mode, applications should make every effort to avoid bothering the user unnecessarily. When the user is viewing hyperlinks on a page, Internet Explorer 4.0 provides the user with a visual indicator, a small crossed-out circle attached to the cursor known as the offline hand, to indicate that the content is not available in the cache.

Not in Cache

By recognizing this cursor, the user is given the chance to preempt the "go online" dialog box. The following code can be used to determine if the content at a specified address is available locally.

   BOOL IsAvailableOffline(LPCWSTR wszUrl)
   {
      HRESULT hr;
      DWORD   dwUsesNet, dwCached;
      DWORD   dwSize;

      if (!wszUrl)
        return E_INVALIDARG;

      // First, let URLMON check the protocol scheme.
      hr = CoInternetQueryInfo(wszUrl,
            QUERY_USES_NETWORK,
            0,
            &dwUsesNet,
            sizeof(dwUsesNet),
            &dwSize,
            0);

      if (FAILED(hr) || !dwUsesNet)
         return true;

      // Then let URLMON peek in the cache.
      hr = CoInternetQueryInfo(wszUrl,
            QUERY_IS_CACHED_OR_MAPPED,
            0,
            &dwCached,
            sizeof(dwCached),
            &dwSize,
            0);

      if (FAILED(hr))
        return false;

      return dwCached;
   }

The offline hand is a cursor resource in SHDOCVW.DLL. The following code demonstrates how to load and display the cursor:

   HINSTANCE hInst = LoadLibrary("shdocvw.dll");
   hCursor = (HCURSOR)LoadCursor(hInst,
      MAKEINTRESOURCE(IDC_OFFLINE_HAND));
   if (hCursor)
      SetCursor(hCursor);

Setting the Global Offline Mode

A third-party can use the API elements presented above or implement their own. Given the user's explicit permission, here is how an application or component can change the offline mode of the system:

   void SetGlobalOffline(BOOL fGoOffline)
   {
      INTERNET_CONNECTED_INFO ci;

      memset(&ci, 0, sizeof(ci));
      if(fGoOffline)
      {
         ci.dwConnectedState = INTERNET_STATE_DISCONNECTED_BY_USER;
         ci.dwFlags = ISO_FORCE_DISCONNECTED;
      }
      else
     {
        ci.dwConnectedState = INTERNET_STATE_CONNECTED;
     }

     InternetSetOption(NULL,
         INTERNET_OPTION_CONNECTED_STATE, &ci, sizeof(ci));
   }

Typically, only application developers should attempt to manipulate the global offline state. Just as applications should minimize the interruption of the user's experience, component developers should focus upon seamless integration into their container's UI. The following section discusses how a specialized container, the Active Desktop, enables components to provide consistent behavior with minimal additional implementation requirements.

Offline Considerations for Component Developers

Internet Explorer 4.0 turns the user's desktop into a Web page by introducing the Active Desktop. Users can can add any content viewable in the browser as an item to the Active Desktop using the Web tab of the system's Display property sheet. Programmatically, Active Desktop items can be added using the IActiveDesktop interface. Custom components such as ActiveX controls and Java applets can be integrated into the Active Desktop by embedding them in content inserted into the Active Desktop.

Since the majority of users does not have a persistent connection to a network, components used as Active Desktop items should not make network requests when the user first logs in. A system configured for dialup use that is not in global offline mode will automatically present dialer UI or incur unexpected dial-up charges each time the user logs in. A control that ignores this recommendation will quickly lose popularity with users.

Understanding the Offline Ambient

The discussion regarding the global offline state makes it clear that applications and components that make calls through URLMON and WININET need not add any special flags to their requests to achieve offline behavior. Since the global offline state is an integral part of these low-level components, no attempt will be made to access the net when the system is globally offline. When the system is not globally offline, however, a network-aware component must consider the case where the system is disconnected from the Internet.

To help components that access network resources exhibit desirable behavior when embedded in the Active Desktop, Internet Explorer 4.0 introduces a new ambient property with a dispatch ID of DISPID_AMBIENT_OFFLINEIFNOTCONNECTED. Before attempting any network requests, an ActiveX control should retrieve the value of this ambient. If the ambient property is true, a component should check the connection state of the system using the WININET InternetGetConnectedState function. If the function indicates that the computer is disconnected, the control should add the appropriate offline flag in its requests to URLMON and WININET. This will prevent these APIs from displaying dialer UI. Note that a component is free to check the connected state and act appropriately regardless of the container in which they are embedded.

Detecting the Offline Ambient

A control need only retrieve the property once at initialization time through the IDispatch interface exposed by the container's client site. A control detects additional changes to all ambients via its implementation of IOleControl::OnAmbientPropertyChange. The following code shows how a control built using the Active Template Library (ATL) might implement this:

   #include <idispids.h>

   // Cache the container's OFFLINEIFNOTCONNECTED ambient.
   HRESULT GetAmbientOffline(LPUNKNOWN pUnkContainer,
              BOOL* pfAmbientOffline)
   {
      HRESULT hr;

      if (!pfAmbientOffline || !pUnkContainer)
         return E_INVALIDARG;

      *pfAmbientOffline = false;

      // Obtain container OA interface through its client site.
      CComQIPtr<IDispatch, &IID_IDispatch> spDisp(pUnkContainer);

    DISPPARAMS dispParams = {NULL, NULL, 0, 0};
    VARIANT vResult = {0};
    hr = spDisp->Invoke(
        DISPID_AMBIENT_OFFLINEIFNOTCONNECTED,
        IID_NULL,
        0,
        DISPATCH_PROPERTYGET,
        &dispParams,
        &vResult,
        NULL,
        NULL);

    if (SUCCEEDED(hr))
    {
         // Cache the value in a member variable.
         *pfAmbientOffline =
            (VARIANT_TRUE == V_BOOL(&vResult) ? true : false);

       VariantClear(&vResult);
       }
    return hr;
   }

   // Implementation of IObjectWithSite::SetSite:
   // Mostly delegates to ATL's default implementation
   // but additionally retrieves the ambient.
   STDMETHODIMP CAxOffl::SetSite(LPUNKNOWN pUnkSite)
   {
      HRESULT hr;
      if (SUCCEEDED(hr =
            IObjectWithSiteImpl<CAxOffl>::SetSite(pUnkSite))
        && pUnkSite)
      {
         hr = GetAmbientOffline(&m_AmbientOffline, m_spUnkSite);
      }

      return hr;
   }

   // Listen for notifications regarding changes to this ambient.
   STDMETHODIMP CAxOffl::OnAmbientPropertyChange(DISPID dispid)
   {
      HRESULT hr;

      if (dispid == DISPID_AMBIENT_OFFLINEIFNOTCONNECTED)
      {
       hr = GetOfflineIfNotConnected();
      }
      return S_OK;
   }

An ActiveX control that uses URL Monikers to make network resource requests should add BINDF_OFFLINE to the bind flags it returns via IBindStatusCallback::GetBindInfo as follows:

   void SetBindfFlags(BOOL fAmbientOffline, LPDWORD  grfBINDF)
   {
      if(fAmbientOffline)
      {
         DWORD dwConnectedStateFlags;
         if((!(InternetGetConnectedState(&dwConnectedStateFlags, 0)))
            &&
              (0 == (dwConnectedStateFlags &
                             INTERNET_CONNECTION_MODEM_BUSY)))
         {   // use the cache
            *grfBINDF |= BINDF_OFFLINEOPERATION;
            *grfBINDF &= ~BINDF_GETFROMCACHE_IF_NET_FAIL;
         }
         else // Use the net; cache if net request fails.
         {
            *grfBINDF |= BINDF_GETFROMCACHE_IF_NET_FAIL;
            *grfBINDF &= ~BINDF_OFFLINEOPERATION;
         }
      }
   }

Similarly, an ActiveX control that uses WININET should add INTERNET_FLAG_OFFLINE to the flags it passes to InternetOpen.

   void SetInetOpenFlags(BOOL fAmbientOffline, LPDWORD pdwOpenFlags)
   {
      // A component should first and foremost pay attention to
      // the offline ambient provided by its container.
      if  (fAmbientOffline)
      {
         DWORD dwConnectedStateFlags;
         BOOL fIsConnected =
            InternetGetConnectedState(&dwConnectedStateFlags, 0);

         // If not connected and not because the line is busy.
         if ( (!fIsConnected) && (0 ==
           (dwConnectedStateFlags & INTERNET_CONNECTION_MODEM_BUSY)))
         {
            // use the cache exclusively
            *pdwOpenFlags |= INTERNET_FLAG_OFFLINE;
        *pdwOpenFlags &= ~INTERNET_FLAG_CACHE_IF_NET_FAIL;
         }
         else
         {
            // Do not treat this as an offline operation
            // but use the cache if the net request fails.
        *pdwOpenFlags |= INTERNET_FLAG_CACHE_IF_NET_FAIL;
            *pdwOpenFlags &= ~INTERNET_FLAG_OFFLINE;
         }
      }
   }

While an application developer can use discretion in setting the bind flags by independently displaying a UI if a site is inaccessible, a control should always make an offline request to the URLMON or WININET APIs when it determines the system is disconnected from the network and the OFFLINEIFNOTCONNECTED ambient is set to TRUE. Contrary behavior will result in a repeated, unsolicited online request UI to be presented to the user.

Considering Backward Compatibility

Component authors who wish to maintain compatibility with previous versions of Internet Explorer should use dynamic rather than static linking when calling functions such as InternetGetConnectedState. This call was not available in Internet Explorer 3.0x. The following code demonstrates how to load and call InternetGetConnectedState without statically linking to WININET.LIB.

   typedef  BOOL (WINAPI* PFNINTERNETGETCONNECTEDSTATE)(LPDWORD, DWORD);

   HRESULT DynInternetGetConnectedState(LPDWORD pdwFlags)
   {
      PFNINTERNETGETCONNECTEDSTATE pfnInternetGetConnectedState;
      BOOL fConnected;

      if (!pdwFlags) return E_INVALIDARG;

      HMODULE hModule = LoadLibrary("wininet.dll");
      if (!hModule)
         return E_FAIL;

      pfnInternetGetConnectedState =
         (PFNINTERNETGETCONNECTEDSTATE)GetProcAddress(hModule,
            "InternetGetConnectedState");

      if (!pfnInternetGetConnectedState)
         return E_FAIL;

      fConnected = (*pfnInternetGetConnectedState)(pdwFlags, 0);

      FreeLibrary(hModule);
      return (fConnected ? S_OK : S_FALSE);
   }

If the component implementing this function is hosted in Internet Explorer 3.0x, the call to GetProcAddress will return NULL, and DynInternetGetConnectedState will return E_FAIL. The component can then either make the network request regardless of the connected state or execute its own code to determine the state using sockets.

Conclusion

Internet Explorer 4.0 extends the browsing experience by providing offline services to application and component developers authoring for the Win32 platform. Through the use of this infrastructure, users can look forward to consistent behavior online and offline among all network-savvy applications and components.


Open Software Description (OSD)

The Open Software Description (OSD) is a format based on the Extensible Markup Language (XML). OSD uses unique XML tags to describe software components, including their versions, underlying structure, relationships to other components, and dependencies.

Open Software Description Overview

Open Software Description Reference


Open Software Description Overview

Open Software Description (OSD) provides the vocabulary to do software updates through the Internet. Microsoft® Internet Explorer 4.01 provides some enhancements to this support (for more information on these changes, see Changes in Microsoft Internet Explorer 4.01). When new versions of your software become available, OSD provides a mechanism, known as publishing, to notify the user. In addition, OSD provides the functionality to describe in great detail how to install ActiveX™ Controls, and Java packages and class files.

The OSD vocabulary is used in these ways:

Automatically Notifying Users of New Versions
Updating ActiveX Controls Whenever New Versions Are Available
Extending Internet Component Download
Extending the Channel Definition Format (CDF)

Changes in Microsoft Internet Explorer 4.01

The following table briefly summarizes the changes between Microsoft Internet Explorer 4.0 and Microsoft Internet Explorer 4.01.
Feature | 4.0 | 4.01
Advertise new application version | yes | yes
Precache new application version | yes | yes
OSD-aware shortcuts | no | yes
ActiveX control precache | yes | yes
ActiveX channel upgrade | no | yes
OSD-based Java install | yes | yes

Note Internet Explorer 4.0 is able to precache an ActiveX control only if an OBJECT tag uses the same code base as the software update channel.

Automatically Notifying Users of New Versions

OSD can be used to automatically notify the user when a new version is available, if the user is subscribed to the appropriate software distribution channel. This notification occurs when the user launches the application from the shortcut (.lnk). The new version can be precached in the Internet Explorer cache, waiting to be installed offline or online when the user chooses to upgrade.

This feature is available to applications that:

  • Meet Designed for Microsoft Windows Logo Program (version 3) requirements.
  • Include the MajorVersion and MinorVersion registry keys.
  • Can be uninstalled.

For an example of how to use OSD to automatically notify users of new versions, see Publishing Applications to the Internet Using OSD.

Updating ActiveX Controls Whenever New Versions Are Available

If an ActiveX control is available on the user's computer and the user is subscribed to that control's software update channel, OSD allows the system to automatically update the control with a newer version as soon as the user browses to any Web site that uses that control.

For an example of how to use OSD to automatically update an ActiveX control, see Automatically Updating ActiveX Controls Using Software Update Channels

Extending Internet Component Download

In Microsoft Internet Explorer 3.0, the installation and dependency information for software (usually used for ActiveX Controls) was contained in an INF file. For Microsoft Internet Explorer 4.0, using OSD provides three main advantages:

  • Ability to describe Java packages. Internet Explorer 4.0 can distribute and install Java packages and applications using OSD to describe the distribution unit.
  • Handle complex dependencies. INFs are limited in that they can express only one level of dependency. Using OSD, Internet Explorer 4.0 can process software dependencies of any depth or recursion.
  • Filter criteria for a heterogeneous network. In addition to describing software, OSD can describe the operating requirements of the software. These requirements include:
    • Processor type
    • Operating system
    • Language

For more information on adding language dependencies using OSD, see Setting Language Dependency Using OSD. For more information on extending Internet Component Download, see Extending Internet Component Download Using OSD in the Internet Component Download documentation.

Extending the Channel Definition Format (CDF)

CDF provides the vocabulary for describing a channel, or an automatic distribution of Web content. OSD adds the vocabulary necessary for describing software packages. In Microsoft Internet Explorer, recognizing OSD tags in a CDF file allows automatic software updates. An application of this concept is the Microsoft Internet Explorer 4.0 Software Updates channel itself. This channel is a CDF that contains additional OSD tags.


Publishing Applications to the Internet Using OSD

This article describes how to use Microsoft® Internet Explorer 4.01 support for the Channel Definition Format (CDF) and Open Software Description (OSD) to publish applications to the Internet.

This article describes how to:

  • Prepare the application so it can utilize this functionally.
  • Create a software update channel (described by a CDF file), which your users will subscribe to in order to receive updates.
  • Utilize the OSD vocabulary inside the CDF file to describe new versions of your software.

Notes and Requirements

  • This document applies to applications, not ActiveX™ Controls or Java applets. For more information about updating an ActiveX control, see the Automatically Updating ActiveX Controls Using Software Update Channels article. For more information about Java applets, see the Extending Internet Component Download Using OSD article.
  • Users must have the Enable Scheduled Subscription Updates option set, or they must manually update their subscriptions to allow Internet Explorer 4.01 to check for updates. This option is enabled by default.

Preparing the Application

Before creating a software update channel, the application should be prepared to handle two tasks:

  • Modifying the registry during setup to allow Internet Explorer to maintain the users' security settings and update their subscription to your channel.
  • Modifying the shortcut to enable update notifications to be displayed to users when they use that shortcut to access your application. This step is necessary only if you want the software update dialog box to appear when using the shortcut to the application when an update is available.

Modifying the Registry to Maintain the User's Security Settings

Because your users are receiving updates through the Internet, Internet Explorer respects the URL Security Zone setting you are in when making the software update. The behavior is as follows.
Security Zone level for your site | Software update channel behavior
High | No software update functions available
Medium | Requires the AuthorizedCDFPrefix (see below)
Low | All software update functions available

For the medium setting, you must (during your installation routine) set the AuthorizedCDFPrefix key in the registry for your particular AppName (the Microsoft Application Logo 5 name). This authorizes particular URLs to notify the user of updates. The reason for this is security. By entering the URLs that are authorized to update your software, you prevent rogue sites from publishing false updates.

AuthorizedCDFPrefix is a new key you must create under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<Your App Name> branch of the registry. Any number of new string values is added to this key, each of which represents a location where Internet Explorer can get software updates. For example, if one of the strings is "http://testserver", any URL beginning with these letters is authorized to publish software updates. If you want to allow any site to publish updates, you can simply use "http:" as the string.

Modifying the shortcut

In either the installation process for the software or the initial launch of the application, the shortcut to the application must be modified so that the system will be able to notify the user of any updates. This also requires Internet Explorer 4.01 to work.

Note Microsoft Installer (MSI) technology, which will be released in the near future, automatically generates modified shortcuts.

To modify the shortcut, you must do one of following:

  • Call the following Windows® function inside your installation code (or on the very first execution of your program) to create the shortcut:
    IShellLink::SetPath(::{9db1186f-40df-11d1-aa8c-00c04fb67863}: AppName :: Path);

    In this function, ::{9db1186f-40df-11d1-aa8c-00c04fb67863}: is a special identifier that should be used as listed; AppName is the name of your application in the registry's uninstall branch under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<Your App Name>, and Path is the path to the program (the normal target of the shortcut).

  • "Bless" your shortcut after it is created using the Blesslnk tool provided by Microsoft in the \bin directory of the Internet Client SDK 4.01 refresh package. After placing your shortcut on the user's computer, you must run the following command:
    Blesslnk -l AppName FullPath

    where AppName is the name of your application in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<Your App Name> branch of the registry, and FullPath is the full directory path to the shortcut.

Creating the Software Update Channel

Creating your own software update channel for Internet Explorer 4.01 is extremely easy. Simply use the following example, replacing the information with your own by following the simple steps below.

<?XML version="1.0"?>

<CHANNEL HREF="http://testserver/logo5/logo5.htm">
    <TITLE>Green (MSAppLogo5) Test Channel</TITLE>
    <LOGO HREF="http://testserver/logo5/green.ico" STYLE="icon"/>
    <USAGE VALUE="SoftwareUpdate"/>
    <SOFTPKG HREF="http://testserver/logo5/logo5.htm"
        NAME="{55272F7E-1B37-11D1-8933-00805F8A4D63}"
        VERSION="1,1,0,1"
        STYLE="MSAppLogo5"
        PRECACHE="yes">
        <TITLE>Green</TITLE>
        <ABSTRACT>Abstract: Green v1.1 application installed via channel</ABSTRACT>
        <IMPLEMENTATION>
            <CODEBASE HREF="http://testserver/logo5/green-x.exe" />
        </IMPLEMENTATION>
    </SOFTPKG>
</CHANNEL>

Make these changes to customize this example for your own software update channel:

  1. Replace CHANNEL HREF to point to a URL that you want users to be sent to when they first subscribe to the channel and when they click the channel in the future.
  2. Change the TITLE to your own. This will show up in the Internet Explorer Favorites/Software Updates folder. This is usually your software's title plus the words "Update Channel".
  3. The LOGO is shown next to the TITLE in the Internet Explorer Software Updates folder. Choose your own custom icon or delete this tag (from <LOGO to />) to use the default satellite dish logo from Internet Explorer.
  4. Replace SOFTPKG HREF to point to a URL that you want users to be sent to when an update is available. Initially (before there's a new version), if you don't know where the new information will be posted, you can point this to the same location as used for the CHANNEL HREF.
  5. Change the NAME to either a GUID (as shown) representing your software or to the application's name in the Uninstall branch of the registry (not the friendly name). If you don't know the name, run Regedit and look at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall to find the name. It will be listed under the Uninstall branch on the left.
  6. Change the VERSION number to your own. The version "a,b,c,d" is a.b.d.
  7. Change the PRECACHE to "no" if you do not want Internet Explorer to automatically receive the update at the subscription update time (either way, Internet Explorer will not install the update; it will simply make it available offline on the user's computer if you leave PRECACHE on).
  8. Change the TITLE to reflect your software's name. This will be shown in the update dialog box when the user is notified of an update.
  9. Change the ABSTRACT to give the user a description of the software. This will also be shown in the update dialog box.
  10. Change the CODEBASE to point to the URL of your software. This can point to a CAB or an EXE file. This does not point to an HTML page.

When you are done with these easy steps, put the CDF file on your Web server and request your users to subscribe to this channel when they come to your page. Your text can say, "Click here to subscribe to a channel to receive notifications of future updates of this software. You will remain anonymous, and we will not give out your name and address."

Handling Updates

In the future, when the new version is available, you will need to change the CDF file on your Web server. On the next subscription update on your users' computers, they will get the new CDF. Make the following modifications:

  1. Change the VERSION number to a larger number.
  2. Either overwrite the old CAB, EXE, or other file pointed to by the CODEBASE element with the new file, or change the CODEBASE to point to the new file.
  3. Replace the SOFTPKG HREF to point to the URL that you want the user to be sent to in order to read about the features and installation instructions of the new software.

After the next subscription update, the users can be notified of the new software in two ways:

  • If the shortcut to the application was modified, an update box (like the one below) will appear when they execute the shortcut to the application.

    Software Update Dialog Box

    Note that this requires the user to be running Internet Explorer 4.01 with the Windows Desktop Update. In addition, it requires a modification to the shortcut to your program.

  • In Internet Explorer, under Software Updates, there will be a gleam on your channel like the one shown here on the Circle Control channel.

    Sample Software Update Menu

    When the user clicks the gleaming channel, he or she will be taken to the page described by the <SOFTPKG HREF=http://testserver/your_update_page.htm> tag to read about the update. This page is also the page used to set up the program.

You can use this example with your own software update channel to get up and running very quickly.

For additional information about the OSD vocabulary, see the specification at http://www.microsoft.com/standards/osd. For additional information on CDF, see the specification at http://www.microsoft.com/standards/cdf-f.htm.


Automatically Updating ActiveX Controls

Situation: Your company develops CoolControl, an ActiveX™ control, and user Joe has version 1.0 of CoolControl installed on his system. Joe originally downloaded this control when he visited Site Y, where he also subscribed to a software update channel to automatically receive new versions of this control. Now you have developed version 2.0 of CoolControl and you want all users of CoolControl 1.0 to upgrade. The next time Joe visits any site that uses the CoolControl (including Site Y), he will automatically have CoolControl 2.0 installed from the site of your choice (or even precached so he can install the control offline).

How to Automatically Update an ActiveX Control Using a Software Update Channel


How to Automatically Update an ActiveX Control

  1. Create an \osd\GenericSample share off the root directory of your Web server. If you are using the Personal Web Server on your local computer, create a directory (\osd) under the \Webshare\Wwwroot directory and then create a subdirectory (\GenericSample) under the \osd directory.
  2. Copy the contents of the \samples\osd\GenericSample directory of the Internet Client SDK refresh package into the share.
  3. Update the HREF attribute of the CHANNEL element in circ3_orig.cdf, circ3_adv.cdf, and circ3_pc.cdf by replacing <your server> with the name of your actual server.
  4. Copy the updated version of circ3_orig.cdf as circ3.cdf in the same share.
  5. Open Microsoft® Internet Explorer 4.01 or later and browse to circ3.htm (which will install the Circle ActiveX™ Control version 1).
  6. Subscribe to circ3.cdf by clicking the addchannel.gif (1685 bytes) link.
    • If you are subscribing a user to an automatic subscription, it is important to obtain the user's consent first.
    • Click Customize to configure Internet Explorer to either send an e-mail notification upon new software availability, or choose a custom schedule to tell Internet Explorer when to check for new software. You can set schedules in the CDF file with the SCHEDULE tag under CHANNEL.
    • The circ3.cdf file has a tag that specifies it should be displayed in Internet Explorer under the Favorites/Software Updates folder.

Now assume you have a new build, build 2, of Circle ready to roll out. You want to automatically upgrade all build 1 users as soon as they hit any page that uses the Circle control.

Note This can also be used for a new version, but the control used in this example had only two builds of the same version available.

  1. Copy circ3_pc.cdf on top of circ3.cdf. (Alternatively, use circ3_adv.cdf instead of circ3_pc.cdf if you don't want to automatically preload the user's cache with the bits. Preload does not mean autoinstall; Microsoft Internet Explorer just caches the new bits so the user can later install the control faster and even while offline). The new CDF advertises version 2 of the Circle control.

    Note To run this demonstration again, you must copy circ3_orig.cdf back on top of circ3.cdf. You will also have to copy circ3_v1.cab on top of circ3.cab.

  2. Copy circ3_v2.cab on top of circ3.cab. This is exactly the same as the real-life situation where the external world sees only circ3.cab but you have circ3_v1.cab (version 1) and circ3_v2.cab (version 2). When you update to version 2, you don't want version 1 available anymore, so you copy circ3_v2.cab over circ3.cab, the external distribution cabinet file.
  3. On the client computer, first make sure that the zone you are in is set for Custom. Under ActiveX Controls And Plugins/Download Unsigned ActiveX Controls, select Enable. Note that this is needed only for the demonstration file because the CABs are not signed; if they were signed, this would not be needed. Then select Favorites/Update All Subscriptions, or right-click the Circle channel (under Favorites/Software Updates) and select Update Now. Note that if the CDF had set an automatic schedule, this update would have happened automatically like any other subscription in Internet Explorer.
  4. The Circle channel icon will gleam (red gleam on upper-left corner of the icon). If you set up the e-mail notification during subscription, you will receive an e-mail notifying you of the updated software. When the user clicks the Circle channel, Internet Explorer will navigate to the home page of the channel. This page has instructions on how to download/install the new version of Circle (in this case just a link to an HTML page with the OBJECT element for the new version of Circle).
  5. Alternately, if you return to view circ3.htm (or any page that uses the Circle ActiveX Control version 1), the client will be automatically upgraded to version 2 because Internet Explorer knows that version 2 is available. In this simple example, note that the only way to see the version difference between the two Circle controls is to view the properties on the Circle control in the Downloaded Program Files directory.


Setting Language Dependency Using OSD

  • Deliver localized language versions of applications/controls to the appropriate language systems automatically through code download.
  • Allow users to download and preview English versions of applications/controls, and provide an automatic notification/download of users' language version when it becomes available (replacing their English version should they choose to do so).
  • Make it easy for developers to author and for PMs to manage.
  • Ensure that the mechanism does not break download on Microsoft® Internet Explorer 3.0.

The model is based on a data file (an OSD file) housed in a signed cabinet (CAB) file (for security) that specifies which languages and platforms the application supports and at which location.

This OSD is alone in a main CAB placed in the GUID directory for the control/application on the object store or at some code base URL location. The OSD tells Internet Component Download which languages are available under the DEPENDENCY element by specifying sections for those languages.

If the specific language CAB is empty or not found and English is supported, code download proceeds to download the English version of the control/application. The next time this object is referenced, Internet Component Download checks the LanguageCheckPeriod default value (expressed in days and implemented by the control/application itself in the OSD). Internet Component Download compares the downloaded date plus elapsed days with the current date to decide whether to download the main CAB again to check for language updates. If the language has become available, Internet Component Download shows a certificate to the user and downloads the localized control (not really informing the user what it's up to).

Applications should make sure they place all the language values they intend to support in the DllRegisterServer routine or in an INF file in the main CAB's OSD from the very beginning. This ensures an appropriate placeholder is put in the registry for future upgrading when the language version matching the browser becomes available. Internet Component Download (code download) looks up the language of the browser by checking the version information of Shdocvw32.dll and compares it to the semicolon-delimited IS01739 name language section. If a match is found, CDL downloads the CAB.

If the specific language CAB is empty or not found and English is not supported (only German, for example), the download will proceed by following the same path as an unmet dependency would in Internet Component Download (an empty box is displayed in the HTML).

Notes:

  • Avoiding repeated certificates.

    A variance between languages is allowed in the amount of time until the version becomes available through the LanguageCheckPeriod key with DWORD values.

    [LanguageCheckPeriod]
                EN   	1
                FR 	5
                ES	30
                JA	60
                DE	30
                KO	90
                ZH-CN	120
                ZH-TW	120

    The number inside the language would specify how much time to allow before checking again for that particular language. This is easy to implement, provides flexibility, and minimizes the certificate downloads for the user.

  • Default language.

    The language version is housed in an object referenced by the default IMPLEMENTATION element.

  • Applications/controls must implement the check period values in the OSD file.

    It's up to the application to implement the LanguageCheckPeriod key under its CLSID. This should be done in the DllRegisterServer routine or in an INF placed in the main data CAB. In the absence of this, given a mismatch, Internet Component Download defaults to 30 days.

Wins:

  • No confusing user interface for the user to have to respond to.
  • The appropriate language version of the control/application is delivered automatically, based on the user's browser language.
  • Easy to administer for the PM through a single OSD in a single CAB.
  • Download hits on the server and time on the net for users is minimized, while letting them preview the application/control in English until their language version becomes available.
  • Method falls within the OSD model using XML, which is maintainable over time.
  • Application/control developers do not have to use satellite localization with complicated dependencies. They have separate CABs for each language.

Constructing CABs for Multiple Languages

To support multiple languages, two types of CAB files need to be present:

  • Main data CAB
  • Individual language CABs

Main data CAB

The main data CAB consists of three text files:

  • INF file to allow installation on Internet Explorer 30
  • INF file to set a language check period
  • Main OSD file

The main OSD file contains the different language implementation information, as well as the locations of the individual language CABs.

You will need to edit these files as languages become available by adding IMPLEMENTATION sections.

The following is an example of the main OSD file.

<?XML version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd">
<?XML::namespace href="http://www.microsoft.com/standards/osd/msicd.dtd" as="msicd"?>

<SOFTPKG NAME="{039397C0-46DF-11D0-99CB-00C04FD64497}" VERSION="4,3,0,2077" >
    <Title>MS Chat</Title>
    <MSICD::NativeCode>
        <Code NAME="MsChatPr.ocx" CLASSID="clsid:039397C0-46DF-11D0-99CB-00C04FD64497"
            VERSION="4,3,0,2077">
    <IMPLEMENTATION>
        <LANGUAGE VALUE="ja" />
        <Processor VALUE="x86" />
        <Codebase HREF="JaChatPr.cab" />
    </IMPLEMENTATION>
    <IMPLEMENTATION>
        <LANGUAGE VALUE="de" />
        <Processor VALUE="x86" />
        <Codebase HREF="DeChatPr.cab" />
    </IMPLEMENTATION>
    <IMPLEMENTATION>
        <Processor VALUE="x86" />
        <Codebase HREF="EnChatPr.cab" />
    </IMPLEMENTATION>
        </Code>
    <Code NAME="RegEntry">
        <IMPLEMENTATION>
           <Codebase FILENAME="langchk.inf" />
        </IMPLEMENTATION>
    </Code>

    </MSICD::NativeCode>
</SOFTPKG>

The following is a sample INF file to set the language check period.

; Copyright (c) 1996 Microsoft Corporation

[Version]
Signature="$Chicago$"
AdvancedINF=2.5

[DefaultInstall]
AddReg=IEIntl.Add.Reg

[DefaultInstall.NT]
AddReg=IEIntl.Add.Reg

[IEIntl.Add.Reg]
HKCR,%MSCHATCHECK%,"DE",3,"5"
HKCR,%MSCHATCHECK%,"JA",3,"5"
HKCR,%MSCHATCHECK%,"FR",3,"15"
HKCR,%MSCHATCHECK%,"KO",3,"15"
HKCR,%MSCHATCHECK%,"TW",3,"15"
HKCR,%MSCHATCHECK%,"",,"Enabled"

[Strings]
MSCHATCHECK = "CLSID\{039397C0-46DF-11D0-99CB-00C04FD64497}\LanguageCheckPeriod"

Individual language CABs

The individual language CABs contain the following files:

  • Specific language version of object
  • Object OSD file

The object OSD file would contain the information on how to install this language version, including any code dependencies and so on.


Open Software Description Reference

This Open Software Description (OSD) reference contains all the elements that are defined by the Osd.dtd file. These elements can be used in OSD and Channel Definition Format (CDF) files to describe software. There are additional elements described in Microsoft Internet Component Download Reference that can be used to describe software in more detail and enhance information provided by the OSD elements.
ABSTRACT CODEBASE DEPENDENCY
DISKSIZE IMPLEMENTATION IMPLTYPE
LANGUAGE LICENSE MEMSIZE
OS OSVERSION PROCESSOR
SOFTPKG TITLE VM

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


ABSTRACT

<ABSTRACT>

Specifies a short summary, or headline, describing the software contained in the distribution unit.

Number of allowed occurrences: None or one
Parent elements | Child elements
IMPLEMENTATION | None
SOFTPKG

The end tag </ABSTRACT> is required.

Example
<ABSTRACT>Enter the short summary or headline here.</ABSTRACT>
Applies To

OSD


CODEBASE

<CODEBASE
FILENAME="file"
HREF="url"
SIZE="n"
STYLE="ActiveSetup" | "MSICD"
/>

Specifies the location of the file or distribution unit to be installed.

FILENAME="file"
Name of the codebase. When this attribute is used, the file is expected to exist in the same archive (CAB file) as the OSD file.
HREF="url"
URL of the codebase. When this attribute is used, the file is expected to exist on the network. Note that either fully qualified or relative URLs are allowed.
SIZE="n"
Maximum allowable size for the distribution unit. The number is given in kilobytes (K). If SIZE is exceeded, the distribution unit will not be downloaded. If SIZE is not specified, no kilobyte limit is enforced. This attribute is valid only within CDF files.
STYLE="ActiveSetup" | "MSICD"
Mechanism the computer uses to download and install files from the Internet. This attribute is valid only within CDF files.
"ActiveSetup" | Uses the ActiveX™ "Active Setup" engine.
"MSICD" | Uses the Microsoft® Internet Component Download (MSICD) to download distribution units and look at the Open Software Description (OSD) file for processing instructions. To use Internet Explorer 3.0 processing procedures, the distribution unit can contain a *.inf file.

Number of allowed occurrences: None or one
Parent elements | Child elements
IMPLEMENTATION | None

When contained within a DEPENDENCY block, only the HREF attribute is used. If no CODEBASE is specified, Internet Explorer checks the object store for the distribution unit. When used as a child element of a NATIVECODE or JAVA block and no CODEBASE is specified, Internet Explorer checks the current distribution unit for the files to be installed.

Applies To

CDF, OSD


DEPENDENCY

<DEPENDENCY
 ACTION="Assert" | "Install"
>

Specifies an additional distribution unit that needs to be present for the software distribution (SOFTPKG) to function correctly.

ACTION="Assert" | "Install"
Action to take if the required distribution unit is not present on the user's computer. When set to "Install", the required files should be downloaded and installed so the software distribution can be processed without errors. When set to "Assert", the SOFTPKG is ignored if the distribution unit is not already on the computer. This is the default. This attribute is valid only in the context of an OSD file. For a CDF file, the value "Assert" is automatically assumed.

Number of allowed occurrences: Any number
Parent elements Child elements
SOFTPKG SOFTPKG

The end tag </DEPENDENCY> is required.

Applies To

CDF, OSD


DISKSIZE DISKSIZE *
  * Previous Topic: DEPENDENCY
  * Next Topic: IMPLEMENTATION

DISKSIZE

Not currently implemented.


IMPLEMENTATION

<IMPLEMENTATION>

Specifies the configuration required by the current software distribution. If the configuration parameters are not met, the SOFTPKG element is not processed.

Number of allowed occurrences: Any number
Parent elements Child elements
CODE CODEBASE
PACKAGE LANGUAGE
SOFTPKG OS
PROCESSOR

The end tag </IMPLEMENTATION> is required.

Example

<SOFTPKG
    HREF="http://www.bar.edu/launch-page.htm"
    NAME="The Second Sample"
    AUTOINSTALL="Yes"
    VERSION="2,1,0,0"
    STYLE="MSICD">

    <TITLE>A second sample software distribution</TITLE>
    <ABSTRACT>This software distribution will be auto-installed on your computer by default.
        The user can override the default settings in the subscription wizard. Needs
        "The First Sample" already installed to work.
    </ABSTRACT>
    <LOGO HREF="ielogo.gif" STYLE="image" / >
    <LANGUAGE VALUE = "en;de" / >
    <USAGE VALUE="email"></USAGE>

    <IMPLEMENTATION>
        <OS VALUE="winnt" />
        <CODEBASE VALUE="http://www.bar.edu/bar/bar-nt.cab" / >
    </IMPLEMENTATION>

    <IMPLEMENTATION>
        <OS VALUE="win95" />
        <CODEBASE VALUE="http://www.bar.edu/bar/bar-95.cab" / >
    </IMPLEMENTATION>

    <DEPENDENCY>
        <SOFTPKG NAME="The First Sample" VERSION="2,1,0,0" / >
    </DEPENDENCY>

</SOFTPKG>

Applies To

CDF, OSD


IMPLTYPE IMPLTYPE *
  * Previous Topic: IMPLEMENTATION
  * Next Topic: LANGUAGE

IMPLTYPE

Not currently implemented.


LANGUAGE

<LANGUAGE
VALUE="language"
/>

Specifies a semicolon-delimited list of RFC 1766 language codes used for international distribution.

VALUE="language"
Required. One or more codes that indicate which languages the software's user interface supports. For example, the code "en" indicates English.

Number of allowed occurrences: Any number
Parent elements | Child elements
IMPLEMENTATION | None
DEPENDENCY
SOFTPKG

Example

<LANGUAGE VALUE="en"/>

Applies To

CDF, OSD


LICENSE LICENSE *
  * Previous Topic: LANGUAGE
  * Next Topic: MEMSIZE

LICENSE

Not currently implemented.


MEMSIZE MEMSIZE *
  * Previous Topic: LICENSE
  * Next Topic: OS

MEMSIZE

Not currently implemented.


OS

<OS
 VALUE="Mac" | "Win95" | "Winnt" />

Specifies the operating system the software supports.

VALUE="Mac" | "Win95" | "Winnt"
Required. Supported operating system.
"Mac" | Macintosh® (MacOS)
"Win95" | Microsoft® Windows® 95
"Winnt" | Microsoft® Windows NT®

Number of allowed occurrences: Any number (per parent element)
Parent elements Child elements
IMPLEMENTATION OSVERSION

Example

<OS VALUE="Win95"/>

Applies To

CDF, OSD


OSVERSION

<OSVERSION
 VALUE="a,b,c,d"
/>

Specifies the version of the operating system the software supports. This element assumes that the software can run on all versions of the operating system greater than or equal to the one specified.

VALUE="a,b,c,d"
Required. Major, minor, custom, and build version numbers.

Number of allowed occurrences: Any number (per parent element)
Parent elements | Child elements
OS | None

Applies To

CDF, OSD


PROCESSOR

<PROCESSOR
 VALUE="Alpha" | "MIPS" | "PPC" | "x86" />

Specifies the type of processor the software will run on.

VALUE="Alpha" | "MIPS" | "PPC" | "x86"
Required. Supported processor is Alpha, MIPS, PowerPC, or x86, respectively.

Number of allowed occurrences: Any number (per parent element)
Parent elements | Child elements
IMPLEMENTATION | None

Example

<PROCESSOR VALUE="x86"/>

Applies To

CDF, OSD


SOFTPKG

<SOFTPKG
AUTOINSTALL="No" | "Yes"
HREF="url"
NAME="string"
PRECACHE="No" | "Yes"
STYLE="ActiveSetup" | "MSICD"
VERSION="a,b,c,d"
>

Defines a software distribution.

AUTOINSTALL="No" | "Yes"
Browser should download the distribution unit and automatically install it when set to "Yes". The default value is "No". This attribute is valid only within CDF files.
HREF="url"
Required. "Launch URL" for this SOFTPKG element. This attribute is valid only within CDF files.
NAME="string"
Required. Name of this distribution.
PRECACHE="No" | "Yes"
Browser should download the distribution unit and leave it in the cache without attempting to autoinstall when set to "Yes". The AUTOINSTALL attribute takes precedence over PRECACHE when they are used together. The default value is "No". This attribute is valid only within CDF files.
STYLE="ActiveSetup" | "MSICD"
Mechanism the computer uses to download and install files from the Internet. This attribute is valid only within CDF files.
"ActiveSetup" | Use the ActiveX™ "Active Setup" engine.
"MSICD" | Use the Microsoft® Internet Component Download (MSICD) to download distribution units and look at the Open Software Description (OSD) file for processing instructions.
VERSION="a,b,c,d"
Major, minor, custom, and build version numbers.

Number of allowed occurrences: Any number (One or none per CDF or OSD file recommended)
Parent elements Child elements
CHANNEL ABSTRACT
IMPLEMENTATION
LANGUAGE
LOGO
TITLE
USAGE

The end tag </SOFTPKG> is required.

Example

<SOFTPKG
    HREF="http://www.foo.edu/launch-page.htm"
    NAME="The First Sample"
    PRECACHE="Yes"
    VERSION="2,1,0,0"
    STYLE="MSICD">
        <TITLE>This is a sample software distribution</TITLE>
        <ABSTRACT>Put a useful description here. The user will benefit from it.</ABSTRACT>
        <LOGO HREF="ielogo.ico" STYLE="icon" / >
        <LANGUAGE VALUE="en;de"/ >
        <USAGE VALUE="email"></USAGE>
        <IMPLEMENTATION>
            <CODEBASE VALUE="http://www.microsoft.com/foo/foo.cab" / >
</IMPLEMENTATION>
</SOFTPKG>

Note For more information about software distribution and the Open Software Description format, see Creating Software Channels for Internet Explorer 4.0.

Applies To

CDF, OSD


TITLE

<TITLE>

Specifies the string that will appear in the title bar.

Number of allowed occurrences: None or one
Parent Elements | Child Elements
IMPLEMENTATION | None
SOFTPKG

The end tag </TITLE> is required.

Example
<TITLE>Title of the package</TITLE>
Applies To

OSD


VM VM *
  * Previous Topic: TITLE
  * Next Topic: Pluggable Protocols

VM

Not currently implemented.


Pluggable Protocols

Pluggable protocols provide capability create custom URL protocols. This section covers the pluggable protocol functionality exported by the Urlmon.dll dynamic-link library (DLL).

Pluggable Protocols Overview

Pluggable Protocols Reference


Pluggable Protocols Overview

Pluggable protocols provide capability create custom URL protocols. This section covers the pluggable protocol functionality exported by the Urlmon.dll dynamic-link library (DLL).

Introduction

About URLs and Name Spaces

About Pluggable Protocols

Creating an Asynchronous Pluggable Protocol Handler

Appendix A: Registering an Application to a URL Protocol

Appendix B: Debugging Tips

Introduction

If you want to compile programs that use the functionality provided in Urlmon.dll, you must make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory, of the C/C++ compiler you use.

This documentation assumes that you have an understanding of Microsoft® Win32® programming. Also, for asynchronous monikers, asynchronous pluggable protocols, and URL monikers you should have an understanding of OLE and COM programming. For the Internet-related interfaces, methods, and functions, an understanding of the format and syntax of URLs is also required. For more information, see RFC 1738, Uniform Resource Locators (URL). You can find this document at http://ds.internic.net/rfc/rfc1738.txt. External Link

About URLs and Name Spaces

A Uniform Resource Locator (URL) follows the syntax described in RFC 1738, which specifies a protocol scheme followed by a scheme-specific portion (<scheme>:<scheme-specific portion>). For example, in the URL http://www.microsoft.com/, "http" is the scheme and "//www.microsoft.com/" is the scheme-specific portion.

The beginning portion of the scheme-specific portion of the URL contains the server name. This portion of the URL is often referred to as the URL name space.

About Pluggable Protocols

Microsoft Internet Explorer uses two mechanisms for registering new URL protocol handlers. The first method is to register a URL protocol and its associated application so that all attempts to navigate to a URL using that protocol launch the application (for example, registering applications to handle mailto: or news: URLs). The second method uses the Asynchronous Pluggable Protocols API, which allows you to define new protocols by mapping the protocol scheme to a class.

For information on how to register an application for a particular URL protocol, see Appendix B: Registering an Application to a URL Protocol.

Asynchronous pluggable protocols offer three ways to map a protocol scheme to a class:

  • Permanently registering an asynchronous pluggable protocol handler in the registry. The handler is used for any URLs with the specified scheme (such as http, ftp, and so on).
  • Permanently or temporarily registering a pluggable name space handler. The handler is used for any URLs with the specified pattern in the scheme-specific portion of the URL for a particular protocol scheme.
  • Permanently or temporarily registering a MIME filter. The handler manipulates the data stream it receives and returns a data stream for any resources of the specified MIME type.

Note All asynchronous pluggable protocols must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Interfaces related to asynchronous pluggable protocols

  • IBindProtocol
  • IInternet
  • IInternetBindInfo
  • IInternetProtocol
  • IInternetProtocolInfo
  • IInternetProtocolRoot
  • IInternetProtocolSink
  • IInternetSession

Functions related to asynchronous pluggable protocols

  • CoInternetGetSession

About Asynchronous Pluggable Protocols

An asynchronous pluggable protocol handler is an apartment-threaded Component Object Model (COM) object that handles any calls made to the protocol scheme that it is registered for. When a client application makes a request, Urlmon looks up the protocol scheme in the registry and creates an instance of the protocol handler registered for that protocol scheme. If the protocol scheme was successfully mapped to the class identifier (CLSID) of a protocol handler, CoCreateInstance is called with that class asking for an IClassFactory interface. An instance of the protocol handler is obtained with IClassFactory::CreateInstance.

To register a custom URL protocol, add a key for the protocol scheme of the custom URL protocol to the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler\protocol_scheme. Under that key, the string value, CLSID, must be set to the CLSID of the protocol handler.

To register the custom protocol scheme example, you would have to add a key named example to the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler. Under the new key, HKEY_CLASSES_ROOT\PROTOCOLS\Handler\example, the string value, CLSID, must be assigned the CLSID of the protocol handler. Any URLs with the protocol scheme example: would be handled by the protocol handler associated with the CLSID value.

The protocol handler cannot use any Windows® messaging to switch back to the thread it was instantiated on, since the protocol handler must work on non-GUI threads.

Note All asynchronous pluggable protocols must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

About Pluggable Name Space Handlers

A pluggable name space handler is an asynchronous pluggable protocol handler that you can set up to handle various protocol schemes and patterns. If a pluggable name space handler understands a particular URL, the handler will start successfully. Otherwise, the pluggable name space handler indicates that the default protocol handler for that protocol scheme should be used. A pluggable name space handler can be installed permanently or temporarily and can include specific patterns to indicate when it should be used.

Multiple pluggable name space handlers can be registered either temporarily or permanently. Temporarily registered pluggable name space handlers are called first and in the reverse order in which they were registered. This means the temporary pluggable name space handler that was registered last will be called first. Permanent name space handlers are not called in a specific order, so there is no way to ensure which handler will be called first.

Note All asynchronous pluggable name space handlers must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Permanent pluggable name space handlers

To set up a permanent pluggable name space handler, you must register it in the registry with the key HKEY_CLASSES_ROOT\PROTOCOLS\Name-Space Handler\protocol_scheme\handler_name. Under this key, you must set the values for a CLSID and any pattern string that you include. If no pattern strings are set, the handler is called for all requests for the specified protocol scheme.

If there are multiple permanent pluggable name space handlers registered, the order in which they are called is random, so handlers should specify only name spaces that they have control over to avoid handling name spaces specified by another handler.

In the following example, the pluggable name space handler Ohserv-Handler is to be called for all HTTP requests with the URL http://ohserv/.

HKEY_CLASSES_ROOT\PROTOCOLS\Name-Space Handler\http\Ohserv-Handler
    CLSID = {..}
    Pattern1 = "ohserv"

Pattern1 is a pattern string that is used to determine if this handler should be used on a particular URL. If a handler has multiple pattern strings (Pattern1, Pattern2, Pattern3, and so on), the browser checks the pattern strings listed to see if any of them match the URL the browser is trying to access. If there is a match, the handler is used; if there isn't, the handler is not used.

Note Valid pattern strings cannot have a leading wildcard character, such as *.com, and should handle only a specific group of known name spaces (for example, URLs for your company's Web sites). Pattern strings that could include numerous Web sites might conflict with other name space handlers that are provided for that specific site.

Temporary pluggable name space handlers

You can register and unregister a temporary pluggable name space handler by using the IInternetSession interface.

About Pluggable MIME Filters

A pluggable MIME filter is an asynchronous pluggable protocol that receives data through a stream, does some operation on the data, and returns a data stream. The output data might be in a different format from the original stream.

Multiple pluggable MIME filters can be registered either temporarily or permanently. Temporarily registered pluggable MIME filters are called first and in the reverse order in which they were registered. That means the pluggable MIME filters registered last will be called first.

For information on how Internet Explorer 4.0 determines MIME types, see Appendix A: MIME Type Detection in Internet Explorer 4.0.

Note All asynchronous pluggable MIME filters must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Permanent pluggable MIME filters

You must register a permanent pluggable MIME filter in the registry with the key HKEY_CLASSES_ROOT\PROTOCOLS\Filter\\<mime_filter> and with a value for a MIME filter. This value must be a CLSID.

Temporary pluggable MIME filters

You can register and unregister a temporary pluggable MIME filter by using the IInternetSession interface.

Creating an Asynchronous Pluggable Protocol Handler

Use the following steps to create an asynchronous pluggable protocol handler:

  1. Implement the IInternetProtocol interface.
  2. Implement the IInternetProtocolRoot interface.
  3. Implement the IClassFactory interface.
  4. Optional. Implement IInternetProtocolInfo. Support for the HTTP protocol is provided by the transaction handler.
  5. If IInternetProtocolInfo is implemented, provide support for PARSE_SECURITY_URL and PARSE_SECURITY_DOMAIN, so the URL security zone manager can handle the security properly.
  6. Write the code for your protocol handler.
  7. Provide support for BINDF_NO_UI and BINDF_SILENTOPERATION.
  8. Add a subkey for your protocol handler in the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler.
  9. Create a string value, CLSID, under the subkey and set the string to the CLSID of your protocol handler.

After the protocol handler is created and added to the registry, it can be used by any application using the functionality provided by Urlmon.dll. The following list contains the general order of the calls made between Urlmon.dll and your protocol handler when a URL with the protocol scheme you registered your handler for is called:

  1. Urlmon.dll calls IUnknown::QueryInterface on your protocol handler for the IInternetProtocolInfo interface.

    Calling the asynchronous pluggable protocol

  2. If IInternetProtocolInfo is implemented, Urlmon.dll calls your pluggable protocol handler's IInternetProtocolInfo::ParseUrl interface.

    Calling the asynchronous pluggable protocol

    If the protocol handler is being called for an update of a subscription by Microsoft Internet Explorer 4.0, the pluggable protocol handler's IInternetProtocolInfo::QueryInfo method will also be called with the QUERYOPTION value set to QUERY_USES_CACHE. Only pluggable protocol handlers that use the Internet cache and return TRUE for the QUERY_USES_CACHE flag will be supported by the Internet Explorer subscription mechanism.

  3. Urlmon.dll calls IUnknown::QueryInterface on your pluggable protocol handler for its IInternetProtocol interface.

    Calling the asynchronous pluggable protocol

  4. Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Start method with the URL and passes the address of the Urlmon.dll's IInternetProtocolSink and IInternetBindInfo interfaces.

    Calling the asynchronous pluggable protocol

  5. Your pluggable protocol handler should access the requested data. First it will request the data from the Internet.

    Requesting the data from the Internet

  6. After your pluggable protocol handler begins downloading data, your pluggable protocol handler should call the Urlmon.dll's IInternetProtocolSink::ReportData method.

    Notifying the transaction handler that data is available

  7. Urlmon.dll calls your protocol handler's IInternetProtocol::Read method.

    Reading the data

  8. Your pluggable protocol handler might call Urlmon.dll's IInternetProtocolSink::ReportProgress method. The pluggable protocol handler must report the MIME type, using the BINDSTATUS_MIMETYPEAVAILABLE status code, to allow a pluggable MIME filter to be called (if there is a MIME filter registered for the MIME type reported).

  9. Steps 6 through 8 are repeated until your protocol handler is finished downloading the requested data.
  10. Your pluggable protocol handler must call the Urlmon.dll's IInternetProtocolSink::ReportResult method.

  11. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::LockRequest method.

  12. Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Terminate method.

    Terminating the pluggable protocol

  13. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::Read method until all the data is retrieved.

    Reading the remaining data

  14. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::UnlockRequest method.

    Unlocking the request

Note Your pluggable protocol handler's IInternetProtocol::Read method might continue to get called even after your IInternetProtocol::Read method has indicated that all the data has been read. All asynchronous pluggable protocol handlers must be prepared for this possibility.

Creating a Pluggable MIME Filter

A pluggable MIME filter is essentially an asynchronous pluggable protocol handler that implements an IInternetProtocolSink interface. Urlmon.dll will use the MIME filter's implementation of IInternetProtocolSink to notify the pluggable MIME filter that it has data ready to be filtered.

Also, filters that handle multiple MIME types must register a separate CLSID for each MIME type they handle:

  1. The transaction handler calls the pluggable MIME filter's IInternetProtocolRoot::Start method.

    Reading the data

  2. The transaction handler calls the pluggable MIME filter's IInternetProtocolSink::ReportProgress and IInternetProtocolSink::ReportData methods.

    Reading the data

  3. The pluggable MIME filter calls the transaction handler's IInternetProtocol::Read method.

    Reading the data

  4. The pluggable MIME filter calls the transaction handler's IInternetProtocolSink::ReportData method.

    Reading the data

  5. The transaction handler calls the pluggable MIME filter's IInternetProtocol::Read method.

    Reading the data

More details will be provided in future versions of this documentation.


Appendix A: Registering an Application to a URL Protocol

To enable an application to handle a particular URL protocol you must add a new key, with the appropriate keys and values, to the registry in HKEY_CLASSES_ROOT.

The new registry key must match the protocol scheme that is being added. For instance, to add the protocol note:, the key added to HKEY_CLASSES_ROOT should be note. Under this new key, the Default string value should be the name of the new protocol, and the URLProtocol string value should contain either protocol-specific information or an empty string. Also under the new key, a DefaultIcon key and a shell key should be added. The Default string value under the DefaultIcon key must be the file name to use as an icon for this new URL protocol. Under the shell key, a key using a verb (such as open) should be added. A command key and a DDEEXEC key can be added under the key using a verb. The values under the command and DDEEXEC keys are used to call the application.

The following example shows which registry values must be added to register a new application (notepad.exe in this example) to handle a new URL protocol (note:).

[HKEY_CLASSES_ROOT]
    [note]
        (Default) = "URL:Note Protocol"
        URL Protocol = ""
        [DefaultIcon]
            (Default) = "notepad.exe"
        [shell]
            [open]
                [command]
                    (Default) = "c:\windows\notepad.exe %1"

By adding these settings to the registry, attempts to navigate to URLs such as note:c:\myfile.txt would launch Notepad to edit the file c:\myfile.txt. Of course, all the commands supported under Shell\Open are supported, including DDEEXEC (in other words, "command" is not the only key you can put under the verb).


Appendix B: Debugging Tips

Currently, the retail version of Urlmon.dll handles exceptions caused by all pluggable protocols. Developers trying to debug a custom pluggable protocol handler can do one of the following:

  • Trap the exceptions in your custom pluggable protocol handler before they get passed to Urlmon.dll.
  • Use a debugging tool that has the ability to trap the exceptions before they are passed to Urlmon.dll.

Also, some functions and methods return an HRESULT that is undefined, such as IInternetSecurityManager::SetZoneMapping. Many of these HRESULTs are generated by a macro that sets the low word to a valid Win32® error code and the high word to 8007.


Pluggable Protocols Reference

This reference covers the APIs that are exported from the Urlmon.dll dynamic-link library. These APIs allow a developer to:

  • Create monikers that can instantiate a named object and return a pointer to one of the object's interfaces asynchronously.
  • Create an asynchronous moniker whose data is referenced by a URL (Uniform Resource Locator).
  • Implement customized URL protocols, name space handlers, and MIME filters.
  • Use functions that combine the functionality of asynchronous monikers and URL monikers.
  • Manage URL security zones.

The reference contains the interfaces, methods, functions, structures, enumerated types, security zone flags, and error codes used by these APIs.

Interfaces

Methods

Functions

Structures

Enumerated Types


Interfaces

This section contains the interfaces exposed by monikers, URLs, security zones, and pluggable protocols.
IDataFilter
IEncodingFilterFactory
IInternet
IInternetBindInfo
IInternetProtocol
IInternetProtocolInfo
IInternetProtocolRoot
IInternetProtocolSink
IInternetSession


IDataFilter IDataFilter *
  * Previous Topic: Interfaces
  * Next Topic: IEncodingFilterFactory

IDataFilter

No currently implemented.


IEncodingFilterFactory IEncodingFilterFactory *
  * Previous Topic: IDataFilter
  * Next Topic: IInternet

IEncodingFilterFactory

Not currently implemented.


IInternet

IInternet provides an implementation of the IUnknown interface, which allows client programs to determine if asynchronous pluggable protocols are supported. No additional methods are supported by this interface.


IInternetBindInfo

This interface is implemented by the system and provides data that the protocol might need to bind successfully.
IInternetBindInfo methods | Description
GetBindInfo | Gets the BINDINFO structure associated with the binding operation.
GetBindString | Gets the strings needed by the protocol for its operation.


IInternetProtocol

IInternetProtocol is the main interface that is exposed by an asynchronous pluggable protocol. This interface and IInternetProtocolSink communicate with each other very closely during download operations.
IInternetProtocol methods | Description
LockRequest | Locks the request so that IInternetProtocolRoot::Terminate can be called and the remaining data can be read.
Read | Reads data retrieved by the pluggable protocol handler.
Seek | Moves the current seek offset.
UnlockRequest | Frees any resources associated with a lock. Called only if IInternetProtocol::LockRequest was called.


IInternetProtocolInfo

This interface provides information about the URL being handled by the protocol handler.
IInternetProtocolInfo methods | Description
CombineUrl | Combines a base and relative URL into a full URL.
CompareUrl | Compares two URLs.
ParseUrl | Parses a URL.
QueryInfo | Retrieves information associated with a URL.


IInternetProtocolRoot

This interface is used to control the operation of an asynchronous pluggable protocol handler.
IInternetProtocolRoot methods | Description
Abort | Aborts an operation in progress.
Continue | Allows the pluggable protocol handler to continue processing data on the apartment (or user interface) thread. This method is called in response to a call to IInternetProtocolSink::Switch.
Resume | Not currently implemented.
Start | Starts the class associated with the asynchronous pluggable protocol.
Suspend | Not currently implemented.
Terminate | Releases the resources used by the pluggable protocol handler.


IInternetProtocolSink

This interface receives the reports and binding data from the asynchronous pluggable protocol. It is a free-threaded interface and can be called from any thread.
IInternetProtocolSink methods | Description
ReportData | Reports the amount of data that is available on the thread.
ReportProgress | Reports progress made in a state operation.
ReportResult | Reports the result of an operation on the thread.
Switch | Passes data from an asynchronous pluggable protocol's worker thread intended for the same asynchronous pluggable protocol's apartment thread. IInternetProtocolSink should pass this data, without modification, back to the asynchronous pluggable protocol by calling its IInternetProtocolRoot::Continue method.

This interface is implemented by client applications interacting directly with an asynchronous pluggable protocol and pluggable MIME filters.


IInternetSession

This interface is implemented by the client application to create temporary pluggable protocol handlers.
IInternetSession methods | Description
CreateBinding | Not currently implemented.
GetCache | Not currently implemented.
GetSessionOption | Not currently implemented.
RegisterMimeFilter | Temporarily registers a MIME filter.
RegisterNameSpace | Temporarily registers a name space handler.
SetCache | Not currently implemented.
SetSessionOption | Not currently implemented.
UnregisterMimeFilter | Unregisters a pluggable MIME filter.
UnregisterNameSpace | Unregisters a temporary pluggable name space handler.


Methods

This section contains the methods exposed by monikers, URLs, security zones, and pluggable protocols.
IInternetBindInfo::GetBindInfo
IInternetBindInfo::GetBindString
IInternetProtocol::LockRequest
IInternetProtocol::Read
IInternetProtocol::Seek
IInternetProtocol::UnlockRequest
IInternetProtocolInfo::CombineUrl
IInternetProtocolInfo::CompareUrl
IInternetProtocolInfo::ParseUrl
IInternetProtocolInfo::QueryInfo
IInternetProtocolRoot::Abort
IInternetProtocolRoot::Continue
IInternetProtocolRoot::Resume
IInternetProtocolRoot::Start
IInternetProtocolRoot::Suspend
IInternetProtocolRoot::Terminate
IInternetProtocolSink::ReportData
IInternetProtocolSink::ReportProgress
IInternetProtocolSink::ReportResult
IInternetProtocolSink::Switch
IInternetSession::CreateBinding
IInternetSession::GetCache
IInternetSession::GetSessionOption
IInternetSession::RegisterMimeFilter
IInternetSession::RegisterNameSpace
IInternetSession::SetCache
IInternetSession::SetSessionOption
IInternetSession::UnregisterMimeFilter
IInternetSession::UnregisterNameSpace


IInternetBindInfo::GetBindInfo

HRESULT GetBindInfo(
    [out] DWORD *grfBINDF,
    [in, out, unique] BINDINFO * pbindinfo
);

Gets the BINDINFO structure associated with the binding operation.

grfBINDF
Address of a value taken from the BINDF enumeration indicating whether the bind should proceed synchronously or asynchronously.
pbindinfo
Address of the BINDINFO structure, which describes how the client wants the binding to occur.

The size of the BINDINFO structure has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of this method before writing to members of the structure. See Handling BINDINFO Structures in Asynchronous and URL Monikers Overview for more information.


IInternetBindInfo::GetBindString

HRESULT GetBindString(
    [in] ULONG ulStringType,
    [in, out] LPOLESTR *ppwzStr,
    [in] ULONG cEl,
    [in, out] ULONG *pcElFetched
);

Gets the strings needed by the protocol for its operation.

ulStringType
Unsigned long integer value that indicates the type of string or strings that should be returned. Can be one of the BINDSTRING values.
ppwzStr
Address of an array of strings.
cEl
Unsigned long integer value that indicates the number of elements in the array provided.
pcElFetched
Address of an unsigned long integer that indicates the number of elements filled in the array.

This method is used if the protocol requires any additional information, such as a username or password, needed to access a URL.


IInternetProtocol::LockRequest

HRESULT LockRequest(
    [in] DWORD dwOptions
);

Locks the requested resource so that IInternetProtocolRoot::Terminate can be called and the remaining data can be read.

  • Returns S_OK if successful. If the requested resource cannot be locked, the method returns INET_E_CANNOT_LOCK_REQUEST.
dwOptions

For asynchronous pluggable protocols that do not need to lock a request, the method should just return S_OK.


IInternetProtocol::Read

HRESULT Read(
    [out] LPVOID pv,
    [in] ULONG cb,
    [out] ULONG *pcbRead
);

Reads data retrieved by the pluggable protocol handler.

  • Returns one of the following values:
    INET_E_DATA_NOT_AVAILABLE | There is no more data available from the server, but more data was expected.
    INET_E_DOWNLOAD_FAILURE | The read failed.
    E_PENDING | The read operation is pending.
    S_OK | The read was successful, but there is still additional data available.
    S_FALSE | All of the data has been completely downloaded.
pv
Address of the buffer where the information will be stored.
cb
ULONG value that indicates the size of the buffer.
pcbRead
Address of a ULONG value that indicates the amount of data stored in the buffer.

Developers who are implementing an asynchronous pluggable protocol must be prepared to have their implementation of IInternetProtocol::Read continue to be called a few extra times after it has returned S_FALSE.


IInternetProtocol::Seek

HRESULT Seek(
    [in] LARGE_INTEGER dlibMove,
    [in] DWORD dwOrigin,
    [out] ULARGE_INTEGER *plibNewPosition
);

Moves the current seek offset.

  • Returns S_OK if successful, or E_FAIL if the protocol does not support seekable data retrieval.
dlibMove
Large integer value that indicates how far to move the offset.
dwOrigin
DWORD value that indicates where the move should begin.
plibNewPosition
Address of an unsigned long integer value that indicates the new offset.


IInternetProtocol::UnlockRequest

HRESULT UnlockRequest();

Frees any resources associated with a lock.

This method is called only if IInternetProtocol::LockRequest was called.


IInternetProtocolInfo::CombineUrl

HRESULT CombineUrl(
    [in] LPCWSTR pwzBaseUrl,
    [in] LPCWSTR pwzRelativeUrl,
    [in] DWORD dwCombineFlags,
    [out] LPWSTR pwzResult,
    [in] DWORD cchResult,
    [out] DWORD *pcchResult,
    [in] DWORD dwReserved
);

Combines a base and relative URL into a full URL.

  • Returns one of the following values:
    S_OK | Success.
    S_FALSE | The buffer was too small to contain the resulting URL.
    INET_E_DEFAULT_ACTION
pwzBaseUrl
String value containing the base URL.
pwzRelativeUrl
String value containing the relative URL.
dwCombineFlags
Double-word value that controls the combining process. Can be one of the following values:
ICU_BROWSER_MODE
ICU_ENCODE_SPACES_ONLY
ICU_DECODE
ICU_NO_ENCODE
ICU_NO_META
pwzResult
String variable where the full URL will be stored.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value to store the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.

For more information on the dwCombineFlags values, see the InternetCombineUrl function in the Win32 Internet Functions Reference.


IInternetProtocolInfo::CompareUrl

HRESULT CompareUrl(
    [in] LPCWSTR pwzUrl1,
    [in] LPCWSTR pwzUrl2,
    [in] DWORD dwCompareFlags
);

Compares two URLs and determines if they are equal.

  • Returns S_OK if equal, or S_FALSE otherwise.
pwzUrl1
String value that contains the first URL.
pwzUrl2
String value that contains the second URL.
dwCompareFlags
Double-word value that controls the comparison. Set to TRUE to ignore slashes, FALSE otherwise.


IInternetProtocolInfo::ParseUrl

HRESULT ParseUrl(
    [in] LPCWSTR pwzUrl,
    [in] PARSEACTION ParseAction,
    [in] DWORD dwParseFlags,
    [out] LPWSTR pwzResult,
    [in] DWORD cchResult,
    [out] DWORD *pcchResult,
    [in] DWORD dwReserved
);

Parses a URL.

  • Returns one of the following values:
    S_OK | Success.
    S_FALSE | The buffer was too small to contain the resulting URL.
    INET_E_DEFAULT_ACTION
pwzUrl
String value containing the URL to parse.
ParseAction
PARSEACTION value that determines the information to be parsed from the URL.
dwParseFlags
Reserved. Must be set to zero.
pwzResult
String value that contains the information parsed from the URL.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value that contains the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.


IInternetProtocolInfo::QueryInfo

HRESULT QueryInfo(
    [in] LPCWSTR pwzUrl,
    [in] QUERYOPTION QueryOption,
    [in] DWORD dwQueryFlags,
    [in, out] LPVOID pBuffer,
    [in] DWORD cbBuffer,
    [in, out] DWORD *pcbBuf,
    [in] DWORD dwReserved
);

Retrieves information related to the specified URL.

  • Returns one of the following values:
    S_OK | The information requested was retrieved successfully.
    S_FALSE | The buffer was too small to store the information.
    INET_E_QUERYOPTION_UNKNOWN | The option requested is unknown.
pwzUrl
String value containing the URL.
QueryOption
QUERYOPTION value that indicates what option to query.
dwQueryFlags
Reserved. Must be set to zero.
pBuffer
Address of the buffer where the information will be stored.
cbBuffer
Double-word value containing the size of the buffer.
pcbBuf
Address of a double-word variable where the size of the requested information will be stored.
dwReserved
Reserved. Must be set to zero.


IInternetProtocolRoot::Abort

HRESULT Abort(
    [in] HRESULT hrReason,
    [in] DWORD dwOptions
);

Aborts an operation that is in progress.

  • Returns one of the following values:
    S_OK | Success.
    E_PENDING | The operation started and will complete asynchronously.
    INET_E_xxx | Internet-specific errors.
hrReason
HRESULT value that contains the reason for the abort.
dwOptions
DWORD value that determines if the abort happens synchronously or asynchronously. The default is asynchronously.


IInternetProtocolRoot::Continue

HRESULT Continue(
    [in] PROTOCOLDATA *pPROTOCOLDATA
);

Allows the pluggable protocol handler to continue processing data on the apartment thread. This method is called in response to a call to IInternetProtocolSink::Switch.

  • Returns one of the following values:
    S_OK | Success.
    E_PENDING | The next state will complete asynchronously.
    INET_E_xxx | Internet-specific errors.
pPROTOCOLDATA
Holder for the PROTOCOLDATA structure data passed to IInternetProtocolSink::Switch.


IInternetProtocolRoot::Resume IInternetProtocolRoot::Resume *
  * Previous Topic: IInternetProtocolRoot::Continue
  * Next Topic: IInternetProtocolRoot::Start

IInternetProtocolRoot::Resume

Not currently implemented.


IInternetProtocolRoot::Start

HRESULT Start(
    [in] LPCWSTR szUrl,
    [in] IInternetProtocolSink *pOIProtSink,
    [in] IInternetBindInfo *pOIBindInfo,
    [in] DWORD grfPI,
    [in] DWORD dwReserved
);

Starts the operation.

  • Returns one of the following values:
    S_OK | Success.
    E_PENDING | The operation started and will complete asynchronously.
    INET_E_USE_DEFAULT_PROTOCOLHANDLER | The handler cannot handle this URL, so the default handler should be used.
    INET_E_xxx | Internet-specific errors.
szUrl
String value containing the URL. For a pluggable MIME filter, this parameter contains the MIME type.
pOIProtSink
Address of the protocol sink provided by the client.
pOIBindInfo
Address of the IInternetBindInfo interface from which the protocol gets download-specific information.
grfPI
DWORD value containing the flags that determine if the method only parses or if it parses and downloads the URL. Can be one of the PI_FLAGS values.
dwReserved
For pluggable MIME filters, contains the address of a PROTOCOLFILTERDATA structure. Otherwise, it is reserved and must be set to zero.

INET_E_USE_DEFAULT_PROTOCOLHANDLER can be returned only by a pluggable name-space handler or MIME filter. Only a single permanently registered asynchronous pluggable protocol handler can be assigned to a particular scheme (such as FTP), so there are no other handlers to default to.


IInternetProtocolRoot::Suspend IInternetProtocolRoot::Suspend *
  * Previous Topic: IInternetProtocolRoot::Start
  * Next Topic: IInternetProtocolRoot::Terminate

IInternetProtocolRoot::Suspend

Not currently implemented.


IInternetProtocolRoot::Terminate

HRESULT Terminate(
    [in] DWORD dwOptions
);

Releases the resources used by the pluggable protocol handler.

dwOptions
Reserved. Must be set to zero.

Notes to implementers

Urlmon.dll will not call this method until your asynchronous pluggable protocol handler calls Urlmon.dll's IInternetProtocolSink::ReportResult method. When your IInternetProtocolRoot::Terminate method is called, your asynchronous pluggable protocol handler should free all resources it has allocated.

Notes to callers

This method should be called after receiving a call to your IInternetProtocolSink::ReportResult method and after the protocol handler's IInternetProtocol::LockRequest method has been called.


IInternetProtocolSink::ReportData

HRESULT ReportData(
    [in] DWORD grfBSCF,
    [in] ULONG ulProgress,
    [in] ULONG ulProgressMax
);

Reports the amount of data that is available on the thread.

  • Returns S_OK if successful, or E_FAIL if called after an IInternetProtocolRoot::Abort call.
grfBSCF
DWORD value that evaluates to a BSCF value that indicates the type of data available. BSCF_LASTDATANOTIFICATION indicates that all available data has been reported.
ulProgress
Unsigned long integer value that indicates the progress made so far.
ulProgressMax
Unsigned long integer value that indicates the total amount of work to be done.


IInternetProtocolSink::ReportProgress

HRESULT ReportProgress(
    [in] ULONG ulStatusCode,
    [in] LPCWSTR szStatusText
);

Reports progress made during a state operation.

  • Returns S_OK if successful, or E_FAIL if called after an Abort operation.
ulStatusCode
BINDSTATUS value that indicates the status of the state operation.
szStatusText
String value that describes the status of the state operation.

Asynchronous pluggable protocol handlers should not generate the BINDSTATUS_BEGINDOWNLOADDATA, BINDSTATUS_ENDDOWNLOADDATA, and BINDSTATUS_DOWNLOADINGDATA reports, since they are generated internally when the data arrives.


IInternetProtocolSink::ReportResult

HRESULT ReportResult(
    [in] HRESULT hrResult,
    [in] DWORD dwError,
    [in] LPCWSTR szResult
);

Reports the result of the operation when called on any thread.

  • Returns S_OK if successful, or E_FAIL if called in the wrong sequence.
hrResult
HRESULT value that indicates the result returned by the operation.
dwError
Unsigned long integer value that is a protocol-specific code.
szResult
Protocol-specific result string that should be NULL if the operation succeeded.

Notes to implementers

After your IInternetProtocolSink::ReportResult method is called, your application should call the protocol handler's IInternetProtocol::LockRequest method to lock the resource you are reading from the protocol handler. Then your application should call the protocol handler's IInternetProtocolRoot::Terminate method.

Notes to callers

The call to IInternetProtocolSink::ReportResult is the last call that your pluggable protocol handler must make to the client application's IInternetProtocolSink interface.


IInternetProtocolSink::Switch

HRESULT Switch(
    [in] PROTOCOLDATA *pPROTOCOLDATA
);

Passes data from an asynchronous pluggable protocol's worker thread intended for the same asynchronous pluggable protocol's apartment thread. The IInternetProtocolSink interface should pass this data, without modification, back to the asynchronous pluggable protocol by calling its IInternetProtocolRoot::Continue method.

  • Returns S_OK if successful, or E_FAIL if called when an asynchronous operation is pending.
pPROTOCOLDATA
Address of a PROTOCOLDATA structure containing the data to be passed back to the apartment thread.

Asynchronous pluggable protocol handlers may operate asynchronously in a separate worker thread. This method allows the protocol handler to pass data back to the apartment (or user interface) thread it was created on.


IInternetSession::CreateBinding

HRESULT CreateBinding(
    [in] LPBC pBC,
    [in] LPCWSTR szUrl,
    [in] IUnknown *pUnkOuter,
    [out, unique] IUnknown **ppUnk,
    [out, unique] IInternetProtocol **ppOInetProt,
    [in] DWORD dwOption
);

Not currently implemented.


IInternetSession::GetCache

HRESULT GetCache(
    [out, unique] IInternetCache **ppOInetCache,
    [in] DWORD dwOption
);

Not currently implemented. Must return E_NOTIMPL.


IInternetSession::GetSessionOption

HRESULT GetSessionOption(
    [in] DWORD dwOption,
    [in, out] LPVOID pBuffer,
    [in, out] DWORD *pdwBufferLength,
    [in] DWORD dwReserved
);

Not currently implemented. Must return E_NOTIMPL..


IInternetSession::RegisterMimeFilter

HRESULT RegisterMimeFilter(
    [in] IClassFactory *pCF,
    [in] REFCLSID rclsid,
    [in] LPCWSTR pwzType
);

Temporarily registers a pluggable MIME filter.

  • Returns one of the following values:
    S_OK | Success.
    E_FAIL | The operation failed.
    E_NOINTERFACE | The class factory could not be obtained.
pCF
Address of an IClassFactory interface where an IInternetProtocol object can be created.
rclsid
Reference to the pluggable MIME handler.
pwzType
String value that contains the MIME to register.

An application can register a pluggable MIME handler for a particular period when it wants to handle requests for some MIMEs by calling IInternetSession::RegisterMimeFilter. This method can be called multiple times using the same interface to register the different MIME types it wants to handle.


IInternetSession::RegisterNameSpace

HRESULT RegisterNameSpace(
    [in] IClassFactory *pCF,
    [in] REFCLSID rclsid,
    [in] LPCWSTR pwzProtocol,
    [in] ULONG cPatterns,
    [in] const LPCWSTR *ppwzPatterns,
    [in] DWORD dwReserved
);

Temporarily registers a pluggable name space handler.

  • Returns one of the following values:
    S_OK | Success.
    E_FAIL | The operation failed.
    E_NOINTERFACE | The class factory could not be obtained.
pCF
Address of an IClassFactory interface where an IInternetProtocol object can be created.
rclsid
Reference to the pluggable name space handler.
pwzProtocol
String value that contains the protocol to be handled.
cPatterns
Unsigned long integer that indicates the number of elements in the ppwzPatterns parameter.
ppwzPatterns
Array of strings containing the patterns the handler will be used for.
dwReserved
Reserved. Must be set to zero.

An application can register a pluggable name space handler for a particular period when it wants to handle requests for some protocols by calling IInternetSession::RegisterNameSpace. If ppwzPatterns and cPatterns are NULL, the registered pluggable name space handler will be called for all protocol requests. This method can be called multiple times using the same interface to register the different name spaces it wants to handle.


IInternetSession::SetCache IInternetSession::SetCache *
  * Previous Topic: IInternetSession::RegisterNameSpace
  * Next Topic: IInternetSession::SetSessionOption

IInternetSession::SetCache

HRESULT SetCache(
    [in] IInternetCache *pOInetCache,
    [in] DWORD dwOption
);

Not currently implemented. Must return E_NOTIMPL.


IInternetSession::SetSessionOption

HRESULT SetSessionOption(
    [in] DWORD dwOption,
    [in] LPVOID pBuffer,
    [in] DWORD dwBufferLength,
    [in] DWORD dwReserved
);

Not currently implemented. Must return E_NOTIMPL.

Sets the options for an Internet session.


IInternetSession::UnregisterMimeFilter

HRESULT UnregisterMimeFilter(
    [in] IClassFactory *pCF,
    [in] LPCWSTR pwzType
);

Unregisters a temporary pluggable MIME filter.

  • Returns S_OK if successful (pluggable name space handler was removed), or E_FAIL if the pluggable name space handler was not registered.
pCF
Address of the IClassFactory interface that created the filter.
pwzType
String value that indicates the MIME that the filter was handling.


IInternetSession::UnregisterNameSpace

HRESULT UnregisterNameSpace(
    [in] IClassFactory *pCF,
    [in] LPCWSTR pszProtocol
);

Unregisters a temporary pluggable name space handler.

  • Returns S_OK if successful, or E_FAIL if the pluggable name space handler was not registered.
pCF
Address of the IClassFactory interface that created the handler.
pszProtocol
String value that contains the protocol that was handled.


Functions

This section describes the functions included in monikers, URLs, security zones, and pluggable protocols.
CoInternetGetProtocolFlags
CoInternetGetSession
CoInternetParseUrl


CoInternetGetProtocolFlags

STDAPI CoInternetGetProtocolFlags(
    LPCWSTR pwzUrl,
    DWORD *pdwFlags,
    DWORD dwReserved
);

Retrieves the protocol flags for a specified URL.

pwzUrl
String value containing the URL.
pdwFlags
Address of a double-word value that contains the protocol flags.
dwReserved
Reserved. Must be set to zero.


CoInternetGetSession

STDAPI CoInternetGetSession(
    DWORD dwSessionMode,
    IInternetSession **ppIInternetSession,
    DWORD dwReserved
);

Creates a session that allows temporary asynchronous pluggable protocols to be implemented and returns the IInternetSession interface of the session.

  • Returns one of the following values:
    S_OK | Successful.
    E_OUTOFMEMORY | Not enough memory to create a session.
    E_INVALIDARG | One of the arguments is invalid.
dwSessionMode
Reserved. Must be set to zero.
ppIInternetSession
Address of the pointer to the IInternetSession interface.
dwReserved
Reserved. Must be set to zero.


CoInternetParseUrl

STDAPI CoInternetParseUrl(
    LPCWSTR pwzUrl,
    PARSEACTION ParseAction,
    DWORD dwFlags,
    LPWSTR pszResult,
    DWORD cchResult,
    DWORD *pcchResult,
    DWORD dwReserved
);

Parses URLs. (This is a helper API.)

  • Returns one of the following values:
    S_OK | Success.
    S_FALSE | The buffer was too small to contain the resulting URL.
    INET_E_DEFAULT_ACTION
pwzUrl
String value containing the URL to parse.
ParseAction
PARSEACTION value that determines the information to be parsed from the URL.
dwFlags
Double-word value that controls the parsing operation.
pwzResult
String value that contains the information parsed from the URL.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value that contains the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.


Structures

This section contains the structures that are exposed by Urlmon.dll.
PROTOCOLDATA
PROTOCOLFILTERDATA


PROTOCOLDATA

typedef struct _tagPROTOCOLDATA{
    DWORD grfFlags;
    DWORD dwState;
    LPVOID pData;
    ULONG cbData;
}  PROTOCOLDATA;

Contains state information about the protocol that is transparent to the transaction handler.

grfFlags
Double-word value that contains the flags.
dwState
Double-word value that contains the state of the protocol handler.
pData
Address of the data buffer.
cbData
Double-word value containing the size of the data buffer.


PROTOCOLFILTERDATA

typedef struct _tagPROTOCOLFILTERDATA {
    DWORD cbSize;
    IInternetProtocolSink *pProtocolSink;
    IInternetProtocol *pProtocol;
    IUnknown *pUnk;
    DWORD dwFilterFlags;
} PROTOCOLFILTERDATA;

Contains the IInternetProtocolSink and IInternetProtocol interfaces of the application calling a pluggable MIME filter.

cbSize
Unsigned long integer value containing the size of the structure.
pProtocolSink
Address of the application's implementation of IInternetProtocolSink.
pProtocol
Address of the application's implementation of IInternetProtocol.
pUnk
Address of the IUnknown interface.
dwFilterFlags
Reserved. Must be set to zero.


Enumerated Types

This section contains the enumerated types that are exposed by Urlmon.dll.
OIBDG_FLAGS
PARSEACTION
PI_FLAGS

OIBDG_FLAGS

Obsolete. Do not use.

PARSEACTION

typedef enum _tagPARSEACTION {
    PARSE_CANONICALIZE = 1,
    PARSE_FRIENDLY,
    PARSE_SECURITY_URL,
    PARSE_ROOTDOCUMENT,
    PARSE_DOCUMENT,
    PARSE_ANCHOR,
    PARSE_ENCODE,
    PARSE_DECODE,
    PARSE_PATH_FROM_URL,
    PARSE_URL_FROM_PATH,
    PARSE_MIME,
    PARSE_SERVER,
    PARSE_SCHEMA,
    PARSE_SITE,
    PARSE_DOMAIN,
    PARSE_LOCATION,
    PARSE_SECURITY_DOMAIN
} PARSEACTION;

An enumerated type that contains the different options for URL parsing operations.

PARSE_CANONICALIZE
Canonicalize the URL.
PARSE_FRIENDLY
Retrieve the user-friendly name for the URL.
PARSE_SECURITY_URL
Retrieve the URL that should be used by the security manager to make security decisions. The returned URL should either return just the name space of the protocol or map the protocol to a known protocol (such as HTTP).
PARSE_ROOTDOCUMENT
Return the URL of the root document for this site.
PARSE_DOCUMENT
Remove the anchor part of the URL.
PARSE_ANCHOR
Remove everything from the URL before the anchor(#).
PARSE_ENCODE
Encode the URL.
PARSE_DECODE
Decode the URL.
PARSE_PATH_FROM_URL
Get the path from the URL, if available.
PARSE_URL_FROM_PATH
Create a URL from the given path.
PARSE_MIME
Return the MIME type of this URL.
PARSE_SERVER
Return the server name.
PARSE_SCHEMA
Retrieve the schema for this URL.
PARSE_SITE
Retrieve the site associated with this URL.
PARSE_DOMAIN
Retrieve the domain associated with this URL.
PARSE_LOCATION
Retrieve the location associated with this URL.
PARSE_SECURITY_DOMAIN
Retrieve the security form of the URL. The returned URL should return a base URL that contains no username, password, directory path, resource, or any other extra information.


PI_FLAGS

typedef enum _tagPI_FLAGS{
    PI_PARSE_URL = 0x00000001,
    PI_FILTER_MODE = 0x00000002,
    PI_FORCE_ASYNC = 0x00000004,
    PI_USE_WORKERTHREAD = 0x00000008,
    PI_MIMEVERIFICATION = 0x00000010,
    PI_CLSIDLOOKUP = 0x00000020,
    PI_DATAPROGRESS = 0x00000040,
    PI_SYNCHRONOUS = 0x00000080,
    PI_APARTMENTTHREADED = 0x00000100,
    PI_CLASSINSTALL = 0x00000200,
    PD_FORCE_SWITCH = 0x00010000
} PI_FLAGS;

This enumerated type contains the flags that control the asynchronous pluggable protocol handler.

PI_PARSE_URL
Asynchronous pluggable protocol should parse the URL and return S_OK if the URL is syntactically correct; otherwise S_FALSE.
PI_FILTER_MODE
Asynchronous pluggable protocol handler that it is running in filter mode and data will come in through the IInternetProtocolSink interface it exposes. The QueryInterface method will be called on the protocol handler for its IInternetProtocolSink interface.
PI_FORCE_ASYNC
Asynchronous pluggable protocol handler should do as little work as possible on the apartment (or user interface) thread and continue on a worker thread as soon as possible.
PI_USE_WORKERTHREAD
Asynchronous pluggable protocol handler should use worker threads and not use the apartment thread.
PI_MIMEVERIFICATION
Asynchronous pluggable protocol handler should verify and report the MIME type.
PI_CLSIDLOOKUP
Asynchronous pluggable protocol handler should find the CLSID associated with the MIME type.
PI_DATAPROGRESS
Asynchronous pluggable protocol handler should report its progress.
PI_SYNCHRONOUS
Asynchronous pluggable protocol handler should work synchronously.
PI_APARTMENTTHREADED
Asynchronous pluggable protocol handler should use the apartment (or user interface) thread only.
PI_CLASSINSTALL
PD_FORCE_SWITCH


Predefined Protocols

Microsoft® Internet Explorer 4.0 implements various protocols that can be used to identify certain information. This document describes the protocols that Internet Explorer 4.0 implements or supports.

res:

The res: protocol specifies a resource that will be obtained from a module. This protocol takes the following format:

"res://resource file[/resource type]/resource id"

The following list describes each element:
resource file | Required. Specifies the path and file name of the module that contains the resource.
resource type | Optional. Specifies the string or numerical resource type. This can be either a custom resource type or one of the RT_ pre-defined resource types described in FindResource and defined in WINUSER.H. If a numerical resource type is being specified, the actual number of the identifier, not the identifier itself, must follow a '#' character. See the example below for more information. If this parameter is not specified, the default resource type is RT_HTML.
resource id | Required. Specifies the string or numerical identifier of the resource. If a numerical identifier is being specified, the actual number of the identifier, not the identifier itself, must follow a '#' character. See the example below for more information.

The following example shows the correct and incorrect way to format the numerical identifier for the resource type:

//winuser.h defines RT_BITMAP
#include <winuser.h>

//this is correct
"res://mydll.dll/#2/MYBITMAP"

//this is not correct
"res://mydll.dll/RT_BITMAP/MYBITMAP"

The following example shows the correct and incorrect way to format the numerical identifier for the resource identifier:

#define MYBITMAP 234

//this is correct
"res://mydll.dll/#2/#234"

//this is not correct
"res://mydll.dll/#2/MYBITMAP"


Programming the Document Object Model from C/C++

This document describes the interfaces used to access the Dynamic HTML Object Model of Internet Explorer 4.0 as implemented by MSHTML.DLL (IE4/MSHTML). These interfaces may be used by applications hosting IE4/MSHTML directly, indirectly through the WebBrowser control or by controls and COM objects hosted by IE4/MSHTML.

The Dynamic HTML Object Model interfaces give C and C++ programmers access to the HTML object model of Internet Explorer 4.0. Used in ActiveX controls and applications hosting IE4/MSHTML, these interfaces give direct access to the objects, properties, methods, collections, and events described in the object model. This gives C and C++ programmers the same level of control over Dynamic HTML as script programmers.

The following sections describe the interfaces and their member functions. For a listing of the interfaces, see Interfaces and Scripting Objects.


Overview

All interfaces for accessing the dynamic HTML object model are based on IDispatch and are the basis of access to the object model that is also used by scripts. It is therefore important that anyone using the interfaces to manipulate the object model also be familiar with the structure and functionality as defined in the Dynamic HTML overviews and Object Model references.

The Interfaces and Scripting Objects section shows how objects within the Dynamic HTML object model map to the interfaces. For example, using this map, you can see that the IHTMLDocument2 interface maps to the document object. Further examination of the interface shows how the properties of the document object are available through get_ and put_ methods. The object's methods map to methods available in the interface, and events can be hooked up using standard OLE Automation connection points.

Examples of how to use the object model interfaces can be seen in the following samples in the Internet Client SDK:

  • Driller
  • colbtn
  • WalkAll

Recommendations for Using the Interfaces

Usually, anything that can be done using script within the document can also be performed using the interfaces to manipulate the object model. It is therefore recommended that before writing code to use the object model interfaces, developers should prototype the functionality using script within an HTML document.

The following HTML example shows how to navigate the all collection of the document and obtain the tag name of each element in the document using script. The equivalent C++ code is demonstrated in the Driller and WalkAll samples of the Internet Client SDK using the object model interfaces.

<HTML>
<HEAD>
    <TITLE>Page Title</TITLE>
</HEAD>

<SCRIPT LANGUAGE="JavaScript">
    function Loaded()
        {
        var c = document.all.length;
        var i;
        for(i=0; i < c; i++)
            {
            spanTAGS.innerHTML = spanTAGS.innerHTML + document.all.item(i).tagName + "<BR>";
            }
        }
</SCRIPT>

<BODY onload="Loaded()">

    <SPAN id="spanTAGS"></SPAN>

</BODY>
</HTML>

Obtaining the Document Interface

To start using the object model interfaces, you need to obtain the IHTMLDocument2 interface for the document. Once you have this interface, you can access all the elements within the document. How the document interface is obtained depends upon how your application is being implemented. Each scenario listed below requires that the document interface be obtained in a different manner.

  • When hosting an MSHTML object.
  • When hosting an instance of the WebBrowser control.
  • From an ActiveX™ control contained in a page.

Obtaining the document interface when hosting MSHTML

When hosting an MSHTML object, you create the object using CoCreateInstance. Once the object is created, you can call its QueryInterface method, requesting IID_IHTMLDocument2. The WalkAll sample in the Internet Client SDK demonstrates how to do this.

Obtaining the document interface when hosting the WebBrowser control

When hosting the WebBrowser control, you perform the following steps to obtain the document pointer:

  1. Call IWebBrowser2::get_Document to obtain the document's IDispatch pointer.
  2. Call QueryInterface on the IDispatch pointer obtained in the previous step, requesting IID_IHTMLDocument2.

Obtaining the document interface from an ActiveX control

The Accessing Dynamic HTML section of the ActiveX Controls documentation details how to obtain the document interface from an ActiveX control.

Using the Document Interface

Once you have obtained the document interface, you can use any of the IHTMLDocument2 interfaces to obtain or modify the document's properties. This will most commonly involve getting some of the IHTMLElementCollection interfaces for the different element collections contained in the document.

A very common collection is the all collection. The all collection is obtained using the IHTMLDocument2::get_all method. This method returns an IHTMLElementCollection interface that contains all the elements in the document. You can then enumerate the elements using the IHTMLElementCollection::item method. The IHTMLElementCollection::item method supplies you with an IDispatch pointer that you can call QueryInterface on, requesting IID_IHTMLElement. This will give you an IHTMLElement interface pointer that you can use to obtain or set information for the individual element.

Most elements provide an interface for working with that specific element. These element-specific interface names take the format of IHTMLXXXXElement, where XXXX is the name of the element. To obtain the element-specific interface, you simply call QueryInterface on the IHTMLElement interface, requesting the element-specific interface that is desired. For example, the IMG element provides an IHTMLImgElement interface that can be used to work with the image element specifically. For a list of the element-specific interfaces that are available, see the interface listing in Programming the Document Object Model from C/C++.


ICSSFilter ICSSFilter *
  * Previous Topic: Overview
  * Next Topic: ICSSFilter::OnAmbientPropertyChange

ICSSFilter

This interface is implemented by a control that is being used as a filter.

ICSSFilter Methods


ICSSFilter::OnAmbientPropertyChange

HRESULT OnAmbientPropertyChange(
    LONG dispid
);

Notifies the filter of an ambient property change in the element.

  • Returns S_OK if successful, or an error value otherwise.
dispid
Long integer value that contains the DISPID of the property.


ICSSFilter::SetSite

HRESULT SetSite(
    ICSSFilterSite *pSink
);

Initializes the site being filtered.

  • Returns S_OK if successful, or an error value otherwise.
pSink
Address of an ICSSFilterSite interface of the site that will be filtered.


ICSSFilterSite ICSSFilterSite *
  * Previous Topic: ICSSFilter::SetSite
  * Next Topic: ICSSFilterSite::FireOnFilterChangeEvent

ICSSFilterSite

This interface provides a filter control with access to elements.

ICSSFilterSite Methods


ICSSFilterSite::FireOnFilterChangeEvent

HRESULT FireOnFilterChangeEvent(void);

Fires the onfilterchange method for the specified object.

  • Returns S_OK if successful, or an error value otherwise.


ICSSFilterSite::GetElement

HRESULT GetElement(
    IHTMLElement **ppElem
);

Retrieves the interface to the element the filter is influencing.

  • Returns S_OK if successful, or an error value otherwise.
ppElem
Address of a pointer to the IHTMLElement interface of the element.


IHTMLAnchorElement

Anchor elements designate the start or destination of a hypertext link. The Anchor element requires the href or the name property to be specified.

Text and/or images can be within an anchor. To represent images that are anchors, a border in the visited or not visited color is displayed.

IHTMLAnchorElement Methods
blur focus get_accessKey
get_hash get_host get_hostname
get_href get_Methods get_mimeType
get_name get_nameProp get_onblur
get_onfocus get_pathname get_port
get_protocol get_protocolLong get_rel
get_rev get_search get_tabIndex
get_target get_urn put_accessKey
put_hash put_host put_hostname
put_href put_Methods put_name
put_onblur put_onfocus put_pathname
put_port put_protocol put_rel
put_rev put_search put_tabIndex
put_target put_urn

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLAnchorElement::blur

HRESULT blur(void);

Causes a control to lose the focus and executes the code specified for the onblur event.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLAnchorElement::focus

HRESULT focus(void);

Causes the anchor element to receive the focus and executes the code specified for the onfocus event.

  • Returns S_OK if successful, or an error value otherwise.


AccessKey Property

*
  * Previous Topic: IHTMLAnchorElement::focus
  * Next Topic: IHTMLAnchorElement::get_hash

IHTMLAnchorElement::get_accessKey

HRESULT get_accessKey(
    BSTR *p
);

Retrieves the accelerator key for the A object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that contains the accelerator key for the element.

Up Top of Page

IHTMLAnchorElement::put_accessKey

HRESULT put_accessKey(
    BSTR v
);

Sets an accelerator key for the element. Pressing CTRL+key selects this anchor element in the user's browser.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the key.


Hash Property

*
  * Previous Topic: IHTMLAnchorElement::get_accessKey
  * Next Topic: IHTMLAnchorElement::get_host

IHTMLAnchorElement::get_hash

HRESULT get_hash(
    BSTR *p
);

Retrieves the string associated with the hash property of the A object.

p
Address of a string variable that receives the value.

Up Top of Page

IHTMLAnchorElement::put_hash

HRESULT put_hash(
    BSTR v
);

Sets the string following the # symbol in the HREF attribute of the anchor element.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the hash portion of the URL.

This property is useful for moving to a bookmark within a document. Assigning an invalid value does not cause an error.


Host Property

*
  * Previous Topic: IHTMLAnchorElement::get_hash
  * Next Topic: IHTMLAnchorElement::get_hostname

IHTMLAnchorElement::get_host

HRESULT get_host(
    BSTR *p
);

Retrieves the host name and the optional port information of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the host name. If no host name is available, this parameter receives an empty string.

Up Top of Page

IHTMLAnchorElement::put_host

HRESULT put_host(
    BSTR v
);

Sets the host name and the optional port information of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the host name and the optional port information.


Hostname Property

*
  * Previous Topic: IHTMLAnchorElement::get_host
  * Next Topic: IHTMLAnchorElement::get_href

IHTMLAnchorElement::get_hostname

HRESULT get_hostname(
    BSTR *p
);

Retrieves the host-name portion of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the host name. If no host name is available, this parameter receives an empty string.

Up Top of Page

IHTMLAnchorElement::put_hostname

HRESULT put_hostname(
    BSTR v
);

Sets the host-name portion of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the host name.


Href Property

*
  * Previous Topic: IHTMLAnchorElement::get_hostname
  * Next Topic: IHTMLAnchorElement::get_Methods

IHTMLAnchorElement::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the destination URL or anchor point.

This method retrieves the href property of the A object.

Up Top of Page

IHTMLAnchorElement::put_href

HRESULT put_href(
    BSTR v
);

Sets the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the destination URL or anchor point.

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's id attribute.


Methods Property

*
  * Previous Topic: IHTMLAnchorElement::get_href
  * Next Topic: IHTMLAnchorElement::get_mimeType

IHTMLAnchorElement::get_Methods

HRESULT get_Methods(
    BSTR *p
);

Retrieves a list of methods that the user can perform on an object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives a comma-separated list of HTTP methods supported by the object for public use.

The functions that the user can perform on an object are more accurately given by the HTTP protocol when it is used, but it might, for reasons similar to the title property, be useful to include the information in advance in the link. For example, the HTML user agent might choose a different rendering as a function of the methods allowed, and thus something that is searchable might get a different icon.

Up Top of Page

IHTMLAnchorElement::put_Methods

HRESULT put_Methods(
    BSTR v
);

Sets information about the functions that the user can perform on an object.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying a comma-separated list of HTTP methods supported by the object for public use.

The functions that the user can perform on an object are more accurately given by the HTTP protocol when it is used, but it might, for reasons similar to the title property, be useful to include the information in advance in the link. For example, the HTML user agent might choose a different rendering as a function of the methods allowed, and thus something that is searchable might get a different icon.


IHTMLAnchorElement::get_mimeType

HRESULT get_mimeType(
    BSTR *p
);

Retrieves the MIME type for the file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the MIME type.


Name Property

*
  * Previous Topic: IHTMLAnchorElement::get_mimeType
  * Next Topic: IHTMLAnchorElement::get_nameProp

IHTMLAnchorElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name.

This method is related to the name property of the A object.

Up Top of Page

IHTMLAnchorElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the anchor.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the name.

This method is related to the name property of the A object.


IHTMLAnchorElement::get_nameProp

HRESULT get_nameProp(
    BSTR *p
);

Retrieves the file name from the URL that the browser uses to locate the anchor.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the file name.


Onblur Property

*
  * Previous Topic: IHTMLAnchorElement::get_nameProp
  * Next Topic: IHTMLAnchorElement::get_onfocus

IHTMLAnchorElement::get_onblur

HRESULT get_onblur(
    VARIANT *p
);

Retrieves the inline script associated with the onblur event on the A object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

Up Top of Page

IHTMLAnchorElement::put_onblur

HRESULT put_onblur(
    VARIANT v
);

Sets the inline script associated with the onblur event on the A element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.


Onfocus Property

*
  * Previous Topic: IHTMLAnchorElement::get_onblur
  * Next Topic: IHTMLAnchorElement::get_pathname

IHTMLAnchorElement::get_onfocus

HRESULT get_onfocus(
    VARIANT *p
);

Retrieves the inline script associated with the onfocus event on the A object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

Up Top of Page

IHTMLAnchorElement::put_onfocus

HRESULT put_onfocus(
    VARIANT v
);

Sets the inline script associated with the onfocus event on the A element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.


Pathname Property

*
  * Previous Topic: IHTMLAnchorElement::get_onfocus
  * Next Topic: IHTMLAnchorElement::get_port

IHTMLAnchorElement::get_pathname

HRESULT get_pathname(
    BSTR *p
);

Retrieves the file or object path from the URL for the current browser location.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the path.

Up Top of Page

IHTMLAnchorElement::put_pathname

HRESULT put_pathname(
    BSTR v
);

Sets the file or object path of the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the path.


Port Property

*
  * Previous Topic: IHTMLAnchorElement::get_pathname
  * Next Topic: IHTMLAnchorElement::get_protocol

IHTMLAnchorElement::get_port

HRESULT get_port(
    BSTR *p
);

Retrieves the port number from the URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the port number. If no port is specified, this parameter receives an empty string.

Up Top of Page

IHTMLAnchorElement::put_port

HRESULT put_port(
    BSTR v
);

Sets the port number in a URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the port number.


Protocol Property

*
  * Previous Topic: IHTMLAnchorElement::get_port
  * Next Topic: IHTMLAnchorElement::get_protocolLong

IHTMLAnchorElement::get_protocol

HRESULT get_protocol(
    BSTR *p
);

Retrieves the protocol portion of the URL that the browser uses to locate the item associated with the anchor. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the protocol.

Up Top of Page

IHTMLAnchorElement::put_protocol

HRESULT put_protocol(
    BSTR v
);

Sets the protocol portion of the URL; that is, the initial substring up to and including the first colon. The protocol indicates the URL's access method.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the protocol.


IHTMLAnchorElement::get_protocolLong

HRESULT get_protocolLong(
    BSTR *p
);

Retrieves the long name of the protocol that the browser uses to locate the item associated with the anchor (for example, "Hypertext Transfer Protocol").

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the protocol name.


Rel Property

*
  * Previous Topic: IHTMLAnchorElement::get_protocolLong
  * Next Topic: IHTMLAnchorElement::get_rev

IHTMLAnchorElement::get_rel

HRESULT get_rel(
    BSTR *p
);

Retrieves the relationship(s) described by the hypertext link from the anchor to the target.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the relationship(s). This parameter receives a comma-separated list of relationship values.

Values and their semantics will be registered by the HTML registration authority. The default relationship, if no other is given, is void. The rel property is used only when the href property is present.

Up Top of Page

IHTMLAnchorElement::put_rel

HRESULT put_rel(
    BSTR v
);

Specifies the relationship(s) described by the hypertext link from the anchor to the target.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the relationship(s). This parameter is a comma-separated list of relationship values.

Values and their semantics will be registered by the HTML registration authority. The default relationship, if no other is given, is void. The rel property is used only when the href property is present.


Rev Property

*
  * Previous Topic: IHTMLAnchorElement::get_rel
  * Next Topic: IHTMLAnchorElement::get_search

IHTMLAnchorElement::get_rev

HRESULT get_rev(
    BSTR *p
);

Same as the rel property, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor can have both rel and rev properties.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the relationship(s). This parameter receives a comma-separated list of relationship values.

Up Top of Page

IHTMLAnchorElement::put_rev

HRESULT put_rev(
    BSTR v
);

Same as the rel property, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor can have both rel and rev properties.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the relationship(s). This parameter is a comma-separated list of relationship values.


Search Property

*
  * Previous Topic: IHTMLAnchorElement::get_rev
  * Next Topic: IHTMLAnchorElement::get_tabIndex

IHTMLAnchorElement::get_search

HRESULT get_search(
    BSTR *p
);

Retrieves the substring that follows the ? symbol in the HREF attribute of the anchor element. This is the query string or form data.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the query string or form data.

Up Top of Page

IHTMLAnchorElement::put_search

HRESULT put_search(
    BSTR v
);

Sets the substring that follows the ? symbol in the HREF attribute of the anchor element. This is the query string or form data.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the query string or form data.


TabIndex Property

*
  * Previous Topic: IHTMLAnchorElement::get_search
  * Next Topic: IHTMLAnchorElement::get_target

IHTMLAnchorElement::get_tabIndex

HRESULT get_tabIndex(
    short *p
);

Retrieves the tab index of the Anchor element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a short integer variable that receives the tab index of the element.

Up Top of Page

IHTMLAnchorElement::put_tabIndex

HRESULT put_tabIndex(
    short v
);

Sets the tab index of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Short integer value that specifies the tab index to set.


Target Property

*
  * Previous Topic: IHTMLAnchorElement::get_tabIndex
  * Next Topic: IHTMLAnchorElement::get_urn

IHTMLAnchorElement::get_target

HRESULT get_target(
    BSTR *p
);

Retrieves the target window or frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that contains the target window or frame. Can be one of the following values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

Up Top of Page

IHTMLAnchorElement::put_target

HRESULT put_target(
    BSTR v
);

Sets the window or frame to target.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the target window or frame. Can be one of the following values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.


Urn Property

*
  * Previous Topic: IHTMLAnchorElement::get_target
  * Next Topic: IHTMLAnchorElement::put_accessKey

IHTMLAnchorElement::get_urn

HRESULT get_urn(
    BSTR *p
);

Retrieves a uniform resource name (URN) for a target document. The format of URNs is under discussion (1994) by various working groups of the Internet Engineering Task Force.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the uniform resource name.

Up Top of Page

IHTMLAnchorElement::put_urn

HRESULT put_urn(
    BSTR v
);

Sets a uniform resource name (URN) for a target document. The format of URNs is under discussion (1994) by various working groups of the Internet Engineering Task Force.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the uniform resource name.


IHTMLAreaElement

This interface specifies the shape of a "hot spot" in a client-side image MAP.

IHTMLAreaElement Methods
blur focus get_alt
get_coords get_hash get_host
get_hostname get_href get_noHref
get_onblur get_onfocus get_pathname
get_port get_protocol get_search
get_shape get_tabIndex get_target
put_alt put_coords put_hash
put_host put_hostname put_href
put_noHref put_onblur put_onfocus
put_pathname put_port put_protocol
put_search put_shape put_tabIndex
put_target


IHTMLAreaElement::blur

HRESULT blur(void);

Causes the element to lose the focus and executes the code specified by get_onblur.

  • Returns S_OK if successful, or an error value otherwise.

See also put_onblur


IHTMLAreaElement::focus

HRESULT focus(void);

Causes the element to receive the focus and executes the onfocus event.

  • Returns S_OK if successful, or an error value otherwise.

See also get_onfocus, put_onfocus


Alt Property

*
  * Previous Topic: IHTMLAreaElement::focus
  * Next Topic: IHTMLAreaElement::get_coords

IHTMLAreaElement::get_alt

HRESULT get_alt(
    BSTR *p
);

Retrieves the optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the optional text.

See also put_alt

Up Top of Page

IHTMLAreaElement::put_alt

HRESULT put_alt(
    BSTR v
);

Sets the optional text, which is used as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the optional text.

See also get_alt


Coords Property

*
  * Previous Topic: IHTMLAreaElement::get_alt
  * Next Topic: IHTMLAreaElement::get_hash

IHTMLAreaElement::get_coords

HRESULT get_coords(
    BSTR *p
);

Retrieves the coordinates that define the hot spot's shape.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the coordinates.

See also put_coords

Up Top of Page

IHTMLAreaElement::put_coords

HRESULT put_coords(
    BSTR v
);

Sets the coordinates that define the hot spot's shape.

  • Returns S_OK if successful, or an error value otherwise.
v
String value containing the coordinates.

See also get_shape


Hash Property

*
  * Previous Topic: IHTMLAreaElement::get_coords
  * Next Topic: IHTMLAreaElement::get_host

IHTMLAreaElement::get_hash

HRESULT get_hash(
    BSTR *p
);

Retrieves the string stored in the hash property of the AREA object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the hash portion of the URL. If the URL has no hash string, this parameter receives an empty string.

See also put_hash

Up Top of Page

IHTMLAreaElement::put_hash

HRESULT put_hash(
    BSTR v
);

Sets the string associated with the hash property of the AREA object.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the hash portion of the URL.

This property is useful for moving to a bookmark within a document. Assigning an invalid value does not cause an error.

See also get_hash


Host Property

*
  * Previous Topic: IHTMLAreaElement::get_hash
  * Next Topic: IHTMLAreaElement::get_hostname

IHTMLAreaElement::get_host

HRESULT get_host(
    BSTR *p
);

Retrieves the host name and the optional port information of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of the string variable where the host name and optional port information will be stored.

See also put_host

Up Top of Page

IHTMLAreaElement::put_host

HRESULT put_host(
    BSTR v
);

Sets the host name and the optional port information of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the host name and port information.

See also get_host


Hostname Property

*
  * Previous Topic: IHTMLAreaElement::get_host
  * Next Topic: IHTMLAreaElement::get_href

IHTMLAreaElement::get_hostname

HRESULT get_hostname(
    BSTR *p
);

Retrieves the host-name part of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the host name. If no host name is available, this parameter receives an empty string.

See also put_hostname

Up Top of Page

IHTMLAreaElement::put_hostname

HRESULT put_hostname(
    BSTR v
);

Sets the host-name portion of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the host name.

See also get_hostname


Href Property

*
  * Previous Topic: IHTMLAreaElement::get_hostname
  * Next Topic: IHTMLAreaElement::get_noHref

IHTMLAreaElement::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL.

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's id attribute.

See also put_href

Up Top of Page

IHTMLAreaElement::put_href

HRESULT put_href(
    BSTR v
);

Sets the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the URL.

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's id attribute.

See also get_href


NoHref Property

*
  * Previous Topic: IHTMLAreaElement::get_href
  * Next Topic: IHTMLAreaElement::get_onblur

IHTMLAreaElement::get_noHref

HRESULT get_noHref(
    VARIANT_BOOL *p
);

Determines whether clicks in this region should cause no action.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that is set to TRUE if clicks cause no action, or FALSE otherwise. The default value for this property is FALSE.

See also put_noHref

Up Top of Page

IHTMLAreaElement::put_noHref

HRESULT put_noHref(
    VARIANT_BOOL v
);

Sets whether clicks in this region should cause no action.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that determines if an action should occur. TRUE causes no action when clicked; FALSE does. The default value for this property is FALSE.

See also get_noHref


Onblur Property

*
  * Previous Topic: IHTMLAreaElement::get_noHref
  * Next Topic: IHTMLAreaElement::get_onfocus

IHTMLAreaElement::get_onblur

HRESULT get_onblur(
    VARIANT *p
);

Retrieves the inline script associated with the onblur event on the AREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of VARIANT structure that contains the script.

Up Top of Page

IHTMLAreaElement::put_onblur

HRESULT put_onblur(
    VARIANT v
);

Sets the inline script associated with the onblur event for the AREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onblur


Onfocus Property

*
  * Previous Topic: IHTMLAreaElement::get_onblur
  * Next Topic: IHTMLAreaElement::get_pathname

IHTMLAreaElement::get_onfocus

HRESULT get_onfocus(
    VARIANT *p
);

Retrieves the inline script associated with the onfocus event on the AREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

Up Top of Page

IHTMLAreaElement::put_onfocus

HRESULT put_onfocus(
    VARIANT v
);

Sets the inline script associated with the onfocus event for the AREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onfocus


Pathname Property

*
  * Previous Topic: IHTMLAreaElement::get_onfocus
  * Next Topic: IHTMLAreaElement::get_port

IHTMLAreaElement::get_pathname

HRESULT get_pathname(
    BSTR *p
);

Retrieves the file or object path from the URL for the current browser location.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the path.

See also put_pathname

Up Top of Page

IHTMLAreaElement::put_pathname

HRESULT put_pathname(
    BSTR v
);

Sets the file or object path of the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the path.

See also get_pathname


Port Property

*
  * Previous Topic: IHTMLAreaElement::get_pathname
  * Next Topic: IHTMLAreaElement::get_protocol

IHTMLAreaElement::get_port

HRESULT get_port(
    BSTR *p
);

Retrieves the port number from the URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the port number. If no port is specified, this parameter receives an empty string.

See also put_port

Up Top of Page

IHTMLAreaElement::put_port

HRESULT put_port(
    BSTR v
);

Sets the port number in a URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the port number.

See also get_port


Protocol Property

*
  * Previous Topic: IHTMLAreaElement::get_port
  * Next Topic: IHTMLAreaElement::get_search

IHTMLAreaElement::get_protocol

HRESULT get_protocol(
    BSTR *p
);

Retrieves the protocol portion of the URL. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the protocol.

See also put_protocol

Up Top of Page

IHTMLAreaElement::put_protocol

HRESULT put_protocol(
    BSTR v
);

Sets the initial substring up to and including the first colon, which indicates the URL's access method.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the protocol substring.

See also get_protocol


Search Property

*
  * Previous Topic: IHTMLAreaElement::get_protocol
  * Next Topic: IHTMLAreaElement::get_shape

IHTMLAreaElement::get_search

HRESULT get_search(
    BSTR *p
);

Retrieves the substring that follows the ? symbol in the href property of the AREA object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the query string or form data.

See also put_search

Up Top of Page

IHTMLAreaElement::put_search

HRESULT put_search(
    BSTR v
);

Sets the substring that follows the ? symbol in the href property of the AREA object. This is the query string or form data.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the query string or form data.

See also get_search


Shape Property

*
  * Previous Topic: IHTMLAreaElement::get_search
  * Next Topic: IHTMLAreaElement::get_tabIndex

IHTMLAreaElement::get_shape

HRESULT get_shape(
    BSTR *p
);

Retrieves the type of shape used in the image map.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of the following strings:
"circ"
"circle"
"poly"
"polygon"
"rect"
"rectangle"

Each shape causes the coords property of the AREA object to take a different set of values. The relationships are as follows:
RECT | Rectangle. Takes four coordinates: x1, y1, x2, and y2.
RECTANGLE | Rectangle. Takes four coordinates: x1, y1, x2, and y2.
CIRC | Circle. Takes three coordinates: centerx, centery, and radius.
CIRCLE | Circle. Takes three coordinates: centerx, centery, and radius.
POLY | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.
POLYGON | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.

See also put_shape

Up Top of Page

IHTMLAreaElement::put_shape

HRESULT put_shape(
    BSTR v
);

Sets the type of shape used in the image map.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the shape. Can be one of these values:
"circ"
"circle"
"poly"
"polygon"
"rect"
"rectangle"

Each shape causes the coords property to take a different set of values. The relationships are described as follows:
RECT | Rectangle. Takes four coordinates: x1, y1, x2, and y2.
RECTANGLE | Rectangle. Takes four coordinates: x1, y1, x2, and y2.
CIRC | Circle. Takes three coordinates: centerx, centery, and radius.
CIRCLE | Circle. Takes three coordinates: centerx, centery, and radius.
POLY | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.
POLYGON | Polygon. Takes three or more pairs of coordinates denoting a polygonal region.

See also get_shape


TabIndex Property

*
  * Previous Topic: IHTMLAreaElement::get_shape
  * Next Topic: IHTMLAreaElement::get_target

IHTMLAreaElement::get_tabIndex

HRESULT get_tabIndex(
    short *p
);

Retrieves the tab index for the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a short integer variable that receives the tab index.

Tab selection order is determined by the value of the tabIndex property as follows:

  • All elements with tabIndex > 0 are selected in increasing tabIndex order, or in source order for duplicate tabIndex values.
  • All elements with tabIndex = 0, or without tabIndex set, are selected next, in source order if more than one.
  • Elements with tabIndex = -1 are omitted from tab selection.

See also put_tabIndex

Up Top of Page

IHTMLAreaElement::put_tabIndex

HRESULT put_tabIndex(
    short v
);

Sets the tab index for the object.

  • Returns S_OK if successful, or an error value otherwise.
v
Short integer value specifying the tab index.

Tab selection order is determined by the value of the tabIndex property as follows:

  • All elements with tabIndex > 0 are selected in increasing tabIndex order, or in source order for duplicate tabIndex values.
  • All elements with tabIndex = 0, or without tabIndex set, are selected next, in source order if more than one.
  • Elements with tabIndex = -1 are omitted from tab selection.

See also get_tabIndex


Target Property

*
  * Previous Topic: IHTMLAreaElement::get_tabIndex
  * Next Topic: IHTMLAreaElement::put_alt

IHTMLAreaElement::get_target

HRESULT get_target(
    BSTR *p
);

Retrieves the target window or frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the target window or frame. Can be one of the following values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

Up Top of Page

IHTMLAreaElement::put_target

HRESULT put_target(
    BSTR v
);

Sets the target window or frame.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the target window or frame. Can be one of the following special values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

See also get_target


IHTMLAreasCollection

This interface is a collection of areas that make up the image map.

Areas can be added or removed from the collection. This collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.

This is a collection of AREA tags.

IHTMLAreasCollection Methods
add get_length get_newEnum
item put_length remove
tags


IHTMLAreasCollection::add

HRESULT add(
    IHTMLElement *element,
    VARIANT before
);

Adds an element to the collection.

  • Returns S_OK if successful, or an error value otherwise.
element
Address of the IHTMLElement interface of the element to add.
before
VARIANT structure containing the number specifying the position within the collection to place the element. If no value is given, the method places the element at the end of the collection.

See also IHTMLElement, remove


Length Property

*
  * Previous Topic: IHTMLAreasCollection::add
  * Next Topic: IHTMLAreasCollection::get__newEnum

IHTMLAreasCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the number of elements.

See also put_length

Up Top of Page

IHTMLAreasCollection::put_length

HRESULT put_length(
    long v
);

Sets the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value that specifies the number of elements.

See also get_length


IHTMLAreasCollection::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Retrieves an enumerator interface which can be used to iterate through the areas collection of the AREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to a variable of IUnknown type.


IHTMLAreasCollection::item

HRESULT item(
    VARIANT name,
    VARIANT index,
    Rob

);

Retrieves an element or a collection from the given collection. The index parameter determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
name
VARIANT structure that contains the number or string specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter contains a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
index
VARIANT structure that contains the number specifying the position of an element to retrieve. This parameter is used when name is a string. The method uses the string to construct a collection of all elements that have a name or id equal to the string, then retrieves from this collection the element at the position specified by index.
pdisp
Address of a pointer to an IDispatch interface.


IHTMLAreasCollection::remove

HRESULT remove(
    long index
);

Removes an element from the collection.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value that specifies the element to remove. The method removes the element at the given position in the collection, where 0 is the first position, 1 the second, and so on.

See also add


IHTMLAreasCollection::tags

HRESULT tags(
    VARIANT tagName,
    IDispatch **pdisp
);

Retrieves a collection of all elements in the given collection that have the given HTML tag name.

  • Returns S_OK if successful, or an error value otherwise.
tagName
VARIANT structure containing the name of elements to retrieve.
pdisp
Address of a pointer to an IDispatch interface.

This method returns an empty collection if no elements having the given name are found. Use the length property on the collection to determine the number of elements it contains.


IHTMLBaseElement

This interface specifies the document's base URL. The base URL is used to ensure that your document is not reviewed out of context.

This element can be used only within the HEAD tag.

IHTMLBaseElement Methods


Href Property

*
  * Previous Topic: IHTMLBaseElement
  * Next Topic: IHTMLBaseElement::get_target

IHTMLBaseElement::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the document's full URL in case the document gets read out of context and the reader wants to refer to the original.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the base URL.

See also put_href

Up Top of Page

IHTMLBaseElement::put_href

HRESULT put_href(
    BSTR v
);

Sets the document's full URL in case the document gets read out of context and the reader wants to refer to the original.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the base URL.

See also get_href


Target Property

*
  * Previous Topic: IHTMLBaseElement::get_href
  * Next Topic: IHTMLBaseElement::put_href

IHTMLBaseElement::get_target

HRESULT get_target(
    BSTR *p
);

Retrieves the window or frame at which to target the contents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the target, or one of these values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

See also put_target

Up Top of Page

IHTMLBaseElement::put_target

HRESULT put_target(
    BSTR v
);

Sets the window or frame at which to target the contents.

  • Returns S_OK if successful, or an error value otherwise.
v
String value that specifies the target. Can be one of these values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

See also get_target


IHTMLBaseFontElement

This interface sets a base font value to be used as the default font when rendering text.

This element can be used only within the HEAD tag.

IHTMLBaseFontElement Methods


Color Property

*
  * Previous Topic: IHTMLBaseFontElement
  * Next Topic: IHTMLBaseFontElement::get_face

IHTMLBaseFontElement::get_color

HRESULT get_color(
    VARIANT *p
);

Retrieves the color used by the font.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. It can be one of the color names or values given in the Color Table reference documentation.

See also put_color

Up Top of Page

IHTMLBaseFontElement::put_color

HRESULT put_color(
    VARIANT v
);

Sets the color to be used by the font.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or numeric value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also get_color


Face Property

*
  * Previous Topic: IHTMLBaseFontElement::get_color
  * Next Topic: IHTMLBaseFontElement::get_size

IHTMLBaseFontElement::get_face

HRESULT get_face(
    BSTR *p
);

Retrieves the name of the typeface for the base font.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name of the typeface.

See also put_face

Up Top of Page

IHTMLBaseFontElement::put_face

HRESULT put_face(
    BSTR v
);

Sets the typeface to use for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String value that specifies the font.

See also get_face


Size Property

*
  * Previous Topic: IHTMLBaseFontElement::get_face
  * Next Topic: IHTMLBaseFontElement::put_color

IHTMLBaseFontElement::get_size

HRESULT get_size(
    long *p
);

Retrieves the font size used for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the size. It can be an integer value in the range 1 through 7, with 7 representing the largest font.

See also put_size

Up Top of Page

IHTMLBaseFontElement::put_size

HRESULT put_size(
    long v
);

Sets the font size for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the font size. This property takes an integer value in the range 1 through 7, with 7 representing the largest font.

See also get_size


IHTMLBGsound

This interface provides the methods for controlling background sound elements. These methods include the src, volume, balance, and loop properties for the sound element.

The BGSOUND tag enables you to create pages with background sounds or "sound tracks".

This element can be used only within the HEAD tag.

IHTMLBGsound Methods
get_balance get_loop get_src
get_volume put_balance put_loop
put_src put_volume

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Balance Property

*
  * Previous Topic: IHTMLBGsound
  * Next Topic: IHTMLBGsound::get_loop

IHTMLBGsound::get_balance

HRESULT get_balance(
    VARIANT *p
);

Retrieves the balance value of the background sound. The value specifies how the sound is divided between left and right speakers.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the balance.

See also put_balance

Up Top of Page

IHTMLBGsound::put_balance

HRESULT put_balance(
    VARIANT v
);

Sets the balance value of the background sound. The value specifies how the sound is divided between left and right speakers.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the balance value to set.

See also get_balance


Loop Property

*
  * Previous Topic: IHTMLBGsound::get_balance
  * Next Topic: IHTMLBGsound::get_src

IHTMLBGsound::get_loop

HRESULT get_loop(
    VARIANT *p
);

Retrieves the number of times the sound will loop when activated.

  • Returns S_OK if successful, or an error value otherwise.
p
VARIANT structure containing a numeric value that specifies the number of times to loop. If this parameter receives -1 (infinite), the video will loop continuously.

Following are descriptions on how the loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also put_loop

Up Top of Page

IHTMLBGsound::put_loop

HRESULT put_loop(
    VARIANT v
);

Sets the number of times the sound will loop when activated.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the value that specifies the number of times to loop. If this parameter is -1 (infinite), the sound will loop continuously.

Following are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also get_loop


Src Property

*
  * Previous Topic: IHTMLBGsound::get_loop
  * Next Topic: IHTMLBGsound::get_volume

IHTMLBGsound::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves the URL of the sound to be played.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL.

See also put_src

Up Top of Page

IHTMLBGsound::put_src

HRESULT put_src(
    BSTR v
);

Sets the URL of a sound to be played.

  • Returns S_OK if successful, or an error value otherwise.
v
String value that specifies the URL.

See also get_src


Volume Property

*
  * Previous Topic: IHTMLBGsound::get_src
  * Next Topic: IHTMLBGsound::put_balance

IHTMLBGsound::get_volume

HRESULT get_volume(
    VARIANT *p
);

Retrieves the volume setting for the sound. The higher the setting, the louder the sound.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the volume setting.

See also put_volume

Up Top of Page

IHTMLBGsound::put_volume

HRESULT put_volume(
    VARIANT v
);

Sets the volume setting for the sound. The higher the setting, the louder the sound.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or numeric value specifying the volume setting.

See also get_volume


IHTMLBlockElement

This interface provides access to properties and methods available to most block elements.

IHTMLBlockElement Methods


Clear Property

*
  * Previous Topic: IHTMLBlockElement
  * Next Topic: IHTMLBlockElement::put_clear

IHTMLBlockElement::get_clear

HRESULT get_clear(
    BSTR *p
);

Retrieves the clear value, specifying whether the element allows floating elements on its left and/or right sides.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
none | No floating elements allowed.
left | Floating elements allowed on the left side.
right | Floating elements allowed on the right side.
both | Floating elements allowed on both sides.

See also put_clear

Up Top of Page

IHTMLBlockElement::put_clear

HRESULT put_clear(
    BSTR v
);

Sets the clear value, specifying whether the element allows floating elements on its left and/or right sides.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the clear value. Can be one of these values:
none | No floating elements allowed.
left | Floating elements allowed on the left side.
right | Floating elements allowed on the right side.
both | Floating elements allowed on both sides.

See also get_clear


IHTMLBodyElement

This interface provides access to the BODY object. The methods that act on the IHTMLBodyElement allow you to control the behavior and characteristics of the BODY element.

This interface specifies the beginning and end of the document body.

Use the IHTMLDocument2::get_body method to retrieve a pointer to the IHTMLBodyElement interface for a document's BODY object.

The BODY element is a block element.

IHTMLBodyElement Methods
put_background get_background put_bgProperties
get_bgProperties put_leftMargin get_leftMargin
put_topMargin get_topMargin put_rightMargin
get_rightMargin put_bottomMargin get_bottomMargin
put_noWrap get_noWrap put_bgColor
get_bgColor put_text get_text
put_link get_link put_vLink
get_vLink put_aLink get_aLink
put_onload get_onload put_onunload
get_onunload put_scroll get_scroll
put_onselect get_onselect put_onbeforeunload
get_onbeforeunload createTextRange

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Background Property

*
  * Previous Topic: IHTMLBodyElement::put_background
  * Next Topic: IHTMLBodyElement::put_bgProperties

IHTMLBodyElement::get_background

HRESULT get_background(
    BSTR *p
);

Retrieves the URL of the background picture, if any. The picture is tiled behind the text and graphics on the page.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL of the background picture.

See also put_background

Up Top of Page

IHTMLBodyElement::put_background

HRESULT put_background(
    BSTR v
);

Sets a background picture. The picture is tiled behind the text and graphics on the page.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the URL of the background picture.

See also get_background


BgProperties Property

*
  * Previous Topic: IHTMLBodyElement::put_bgProperties
  * Next Topic: IHTMLBodyElement::put_leftMargin

IHTMLBodyElement::get_bgProperties

HRESULT get_bgProperties(
    BSTR *p
);

Retrieves the properties for the background picture; for example, whether the picture is a fixed watermark or scrolls with the page

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a string variable that receives the background properties. This parameter receives "fixed" if the background picture is fixed and does not scroll with the page, or an empty string ("") if the background picture scrolls.

See also put_bgProperties

Up Top of Page

IHTMLBodyElement::put_bgProperties

HRESULT put_bgProperties(
    BSTR v
);

Sets the properties for the background picture. For example, specifies whether the picture is a fixed watermark or scrolls with the page

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the background properties. If this parameter is "fixed", the background picture is fixed and does not scroll with the page. If set to an empty string (""), the background picture scrolls.

See also get_bgProperties


LeftMargin Property

*
  * Previous Topic: IHTMLBodyElement::put_leftMargin
  * Next Topic: IHTMLBodyElement::put_topMargin

IHTMLBodyElement::get_leftMargin

HRESULT get_leftMargin(
    VARIANT *p
);

Retrieves the left margin for the entire body of the page. This property overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the left margin. This property receives "" if the margin is exactly on the left edge.

See also put_leftMargin

Up Top of Page

IHTMLBodyElement::put_leftMargin

HRESULT put_leftMargin(
    VARIANT v
);

Sets the left margin for the entire body of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the left margin. If set to "", the margin will be exactly on the left edge.

See also get_leftMargin


TopMargin Property

*
  * Previous Topic: IHTMLBodyElement::put_topMargin
  * Next Topic: IHTMLBodyElement::put_rightMargin

IHTMLBodyElement::get_topMargin

HRESULT get_topMargin(
    VARIANT *p
);

Retrieves the margin for the top of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the top margin. This property receives "" if the margin is exactly on the top edge.

See also put_topMargin

Up Top of Page

IHTMLBodyElement::put_topMargin

HRESULT put_topMargin(
    VARIANT v
);

Sets the margin for the top of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or numeric value specifying the top margin. If set to "", the margin will be exactly on the top edge.

See also get_topMargin


RightMargin Property

*
  * Previous Topic: IHTMLBodyElement::put_rightMargin
  * Next Topic: IHTMLBodyElement::put_bottomMargin

IHTMLBodyElement::get_rightMargin

HRESULT get_rightMargin(
    VARIANT *p
);

Retrieves the right margin for the entire body of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the right margin. This property receives "" if the margin is exactly on the right edge.

See also put_rightMargin

Up Top of Page

IHTMLBodyElement::put_rightMargin

HRESULT put_rightMargin(
    VARIANT v
);

Sets the right margin for the entire body of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the right margin. If set to "", the margin will be exactly on the right edge.

See also get_rightMargin


BottomMargin Property

*
  * Previous Topic: IHTMLBodyElement::put_bottomMargin
  * Next Topic: IHTMLBodyElement::put_noWrap

IHTMLBodyElement::get_bottomMargin

HRESULT get_bottomMargin(
    VARIANT *p
);

Retrieves the margin for the bottom of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the bottom margin. This property receives "" if the margin is exactly on the bottom edge.

See also put_bottomMargin

Up Top of Page

IHTMLBodyElement::put_bottomMargin

HRESULT put_bottomMargin(
    VARIANT v
);

Sets the margin for the bottom of the page and overrides the default margin.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing either a string or value specifying the bottom margin. If set to "", the margin will be exactly on the bottom edge.

See also get_bottomMargin


NoWrap Property

*
  * Previous Topic: IHTMLBodyElement::put_noWrap
  * Next Topic: IHTMLBodyElement::put_bgColor

IHTMLBodyElement::get_noWrap

HRESULT get_noWrap(
    VARIANT_BOOL *p
);

Determines whether automatic word wrapping is enabled or disabled for the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if automatic word-wrapping is enabled for the document, or FALSE otherwise. The default value for this property is FALSE.

See also put_noWrap

Up Top of Page

IHTMLBodyElement::put_noWrap

HRESULT put_noWrap(
    VARIANT_BOOL v
);

Enables or disables automatic word wrapping for the document.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that contains the word-wrap flag. If TRUE, the browser performs automatic word wrapping for the document. If FALSE, it doesn't. The default value for this property is FALSE.

See also get_noWrap


BgColor Property

*
  * Previous Topic: IHTMLBodyElement::put_bgColor
  * Next Topic: IHTMLBodyElement::put_text

IHTMLBodyElement::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color of the page.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

JScript supports the entire set of valid property colors both as strings and their numerical equivalents as a string. JScript always returns the property as the numeric equivalent as a string regardless of the format to which the value was set.

See also put_bgColor

Up Top of Page

IHTMLBodyElement::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color of the page.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

JScript supports the entire set of valid property colors both as strings and their numerical equivalents as a string. JScript always returns the property as the numeric equivalent as a string regardless of the format to which the value was set.

See also get_bgColor


Text Property

*
  * Previous Topic: IHTMLBodyElement::put_text
  * Next Topic: IHTMLBodyElement::put_link

IHTMLBodyElement::get_text

HRESULT get_text(
    VARIANT *p
);

Retrieves the current text (foreground) color of the document body.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

The text is formatted within the current context of the document.

See also put_text

Up Top of Page

IHTMLBodyElement::put_text

HRESULT put_text(
    VARIANT v
);

Sets the text (foreground) color for the document body.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

The text is formatted within the current context of the document.

See also get_text


Link Property

*
  * Previous Topic: IHTMLBodyElement::put_link
  * Next Topic: IHTMLBodyElement::put_vLink

IHTMLBodyElement::get_link

HRESULT get_link(
    VARIANT *p
);

Retrieves the color used for links that have not yet been visited.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. Can be one of the color names or values given in the Color Table reference documentation.

See also put_link

Up Top of Page

IHTMLBodyElement::put_link

HRESULT put_link(
    VARIANT v
);

Sets the color of links that have not yet been visited.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing either a string or value specifying the color. Can be one of the color names or values given in the Color Table reference documentation.

See also get_link


VLink Property

*
  * Previous Topic: IHTMLBodyElement::put_vLink
  * Next Topic: IHTMLBodyElement::put_aLink

IHTMLBodyElement::get_vLink

HRESULT get_vLink(
    VARIANT *p
);

Retrieves the color used for links that have been visited.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. Can be one of the color names or values given in the Color Table reference documentation.

See also put_vLink

Up Top of Page

IHTMLBodyElement::put_vLink

HRESULT put_vLink(
    VARIANT v
);

Sets the color of links that have been visited.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or value specifying the color. Can be one of the color names or values given in the Color Table reference documentation.

See also get_vLink


ALink Property

*
  * Previous Topic: IHTMLBodyElement::put_aLink
  * Next Topic: IHTMLBodyElement::put_onload

IHTMLBodyElement::get_aLink

HRESULT get_aLink(
    VARIANT *p
);

Retrieves the color used for the active link.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. Can be one of the color names or values given in the Color Table reference documentation.

See also put_aLink

Up Top of Page

IHTMLBodyElement::put_aLink

HRESULT put_aLink(
    VARIANT v
);

Sets the color for the active link.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing either a string or value specifying the color. Can be one of the color names or values given in the Color Table reference documentation.

See also get_aLink


Onload Property

*
  * Previous Topic: IHTMLBodyElement::put_onload
  * Next Topic: IHTMLBodyElement::put_onunload

IHTMLBodyElement::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script associated with the onload event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that will hold the script.

See also put_onload

Up Top of Page

IHTMLBodyElement::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event on the BODY element. Occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script.

See also get_onload


Onunload Property

*
  * Previous Topic: IHTMLBodyElement::put_onunload
  * Next Topic: IHTMLBodyElement::put_scroll

IHTMLBodyElement::get_onunload

HRESULT get_onunload(
    VARIANT *p
);

Retrieves the inline script associated with the onunload event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onunload

Up Top of Page

IHTMLBodyElement::put_onunload

HRESULT put_onunload(
    VARIANT v
);

Sets the inline script associated with the onunload event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script.

See also get_onunload


Scroll Property

*
  * Previous Topic: IHTMLBodyElement::put_scroll
  * Next Topic: IHTMLBodyElement::put_onselect

IHTMLBodyElement::get_scroll

HRESULT get_scroll(
    BSTR *p
);

Determines whether the scroll bars are on or off.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives "yes" if the scroll bars are on, or "no" if they are off.

See also put_scroll

Up Top of Page

IHTMLBodyElement::put_scroll

HRESULT put_scroll(
    BSTR v
);

Turns the scroll bars on or off.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying whether to turn the scroll bars on or off. Specify "yes" to turn on the scroll bars, or "no" to turn them off.

See also get_scroll


Onselect Property

*
  * Previous Topic: IHTMLBodyElement::put_onselect
  * Next Topic: IHTMLBodyElement::put_onbeforeunload

IHTMLBodyElement::get_onselect

HRESULT get_onselect(
    VARIANT *p
);

Retrieves the inline script associated with the onselect event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onselect

Up Top of Page

IHTMLBodyElement::put_onselect

HRESULT put_onselect(
    VARIANT v
);

Sets the inline script associated with the onselect event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script.

See also get_onselect


Onbeforeunload Property

*
  * Previous Topic: IHTMLBodyElement::put_onbeforeunload
  * Next Topic: IHTMLBodyElement::createTextRange

IHTMLBodyElement::get_onbeforeunload

HRESULT get_onbeforeunload(
    VARIANT *p
);

Retrieves the inline script associated with the onbeforeunload event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

The handler for this event should return NULL if doing the unload is safe, or a text string to prompt the user to decide to cancel or continue with the unload operation. Only the user's response to the warning can stop the new navigation causing the unload; the event handler itself cannot unilaterally block the operation. If the handler returns a non-NULL string, a modal dialog box appears that displays the explanatory string. The dialog box shows three buttons with the message for user action:

  • Continue—the unload operation proceeds.
  • Cancel—the navigation causing the unload is immediately canceled.
  • Help—(strongly recommended)—displays additional explanatory text, such as "This operation may cause existing content information to be lost. Choose Continue if this is OK, or Cancel to retain the information."

In the case of frames, the full sequence of onbeforeunload events is fired on each frame in the same order, depth-first, that onunload events are about to be fired. A dialog box is presented for each event handler that returns a non-NULL string. The first Cancel response stops the potential navigation, in which case no unload occurs. If there is no Cancel response, the unload proceeds and onunload events fire.

See also put_onbeforeunload

Up Top of Page

IHTMLBodyElement::put_onbeforeunload

HRESULT put_onbeforeunload(
    VARIANT v
);

Sets the inline script associated with the onbeforeunload event on the BODY element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script.

The handler for this event should return NULL if doing the unload is safe, or a text string to prompt the user to decide to cancel or continue with the unload operation. Only the user's response to the warning can stop the new navigation causing the unload; the event handler itself cannot unilaterally block the operation. If the handler returns a non-NULL string, a modal dialog box appears that displays the explanatory string. The dialog box shows three buttons with the message for user action:

  • Continue—the unload operation proceeds.
  • Cancel—the navigation causing the unload is immediately canceled.
  • Help—(strongly recommended)—displays additional explanatory text, such as "This operation may cause existing content information to be lost. Choose Continue if this is OK, or Cancel to retain the information."

In the case of frames, the full sequence of onbeforeunload events is fired on each frame in the same order, depth-first, that onunload events are about to be fired. A dialog box is presented for each event handler that returns a non-NULL string. The first Cancel response stops the potential navigation, in which case no unload occurs. If there is no Cancel response, the unload proceeds and onunload events fire.

See also get_onbeforeunload


IHTMLBodyElement::createTextRange

HRESULT createTextRange(
    IHTMLTxtRange **range
);

Creates a text range object for the BODY object. You use a text range to examine and modify the text within the element.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a pointer to the IHTMLTxtRange interface that is created.


IHTMLBRElement IHTMLBRElement *
  * Previous Topic: IHTMLBodyElement::createTextRange
  * Next Topic: IHTMLBRElement::get_clear

IHTMLBRElement

This interface inserts a line break.

IHTMLBRElement Methods


Clear Property

*
  * Previous Topic: IHTMLBRElement
  * Next Topic: IHTMLBRElement::put_clear

IHTMLBRElement::get_clear

HRESULT get_clear(
    BSTR *p
);

Determines whether vertical space is inserted so that the next text displayed is past left- or right-aligned floating images.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of the following values:
all | Place text after all images.
left | Place text past left-aligned images.
right | Place text past right-aligned images.

See also put_clear

Up Top of Page

IHTMLBRElement::put_clear

HRESULT put_clear(
    BSTR v
);

Inserts vertical space so that the next text displayed will be past left- and/or right-aligned floating images.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying one of the following values:
all | Place text after all images.
left | Place text past left-aligned images.
right | Place text past right-aligned images.

See also get_clear


IHTMLButtonElement

This interface renders content as an HTML button.

This element is a block element.

IHTMLButtonElement Methods
get_type put_value get_value
put_name get_name put_status
get_status put_disabled get_disabled
get_form createTextRange

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLButtonElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the visual appearance and default behavior of the button.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
button | Creates a command button. This is the default value for this property.
reset | Creates a reset button. If in a form, this button resets the fields in the form to their initial values.
submit | Creates a submit button. If in a form, this button submits the form.


Value Property

*
  * Previous Topic: IHTMLButtonElement::put_value
  * Next Topic: IHTMLButtonElement::put_name

IHTMLButtonElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the value of the button control. The value is submitted to the server as a name/value pair.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the value.

See also put_value

Up Top of Page

IHTMLButtonElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the value of the button control. The value is submitted to the server as a name/value pair.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the value.

See also get_value


Name Property

*
  * Previous Topic: IHTMLButtonElement::put_name
  * Next Topic: IHTMLButtonElement::put_status

IHTMLButtonElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the button control.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a string variable that receives the name.

This method is related to the name property of the BUTTON object.

See also put_name

Up Top of Page

IHTMLButtonElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the button control.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the name.

This method is related to the name property of the BUTTON object.

See also get_name


Status Property

*
  * Previous Topic: IHTMLButtonElement::put_status
  * Next Topic: IHTMLButtonElement::put_disabled

IHTMLButtonElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the status of the button control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the status. Can be TRUE, FALSE, or NULL.

See also put_status

Up Top of Page

IHTMLButtonElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the status of the button control.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure specifying the status. Can be TRUE, FALSE, or NULL.

See also get_status


Disabled Property

*
  * Previous Topic: IHTMLButtonElement::put_disabled
  * Next Topic: IHTMLButtonElement::get_form

IHTMLButtonElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLButtonElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears greyed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLButtonElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLFormElement interface of the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLButtonElement::createTextRange

HRESULT createTextRange(
    IHTMLTxtRange **range
);

Creates a text range object for the BUTTON object. You use a text range to examine and modify the text within the element.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a pointer to the IHTMLTxtRange interface of the text range created.


IHTMLCommentElement IHTMLCommentElement *
  * Previous Topic: IHTMLButtonElement::createTextRange
  * Next Topic: IHTMLCommentElement::put_text

IHTMLCommentElement

This interface indicates a comment that will not be displayed.

IHTMLCommentElement Methods


Text Property

*
  * Previous Topic: IHTMLCommentElement::put_text
  * Next Topic: IHTMLControlElement

IHTMLCommentElement::get_text

HRESULT get_text(
    BSTR *p
);

Retrieves the text contained within the COMMENT object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the text.

The text is formatted within the current context of the document.

See also put_text

Up Top of Page

IHTMLCommentElement::put_text

HRESULT put_text(
    BSTR v
);

Sets the text contained within the COMMENT object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text.

See also get_text


IHTMLControlElement

This interface is a base interface for control type elements such as IHTMLImgElement.

IHTMLControlElement Methods
put_tabIndex get_tabIndex focus
put_accessKey get_accessKey put_onblur
get_onblur put_onfocus get_onfocus
put_onresize get_onresize blur
addFilter removeFilter get_clientWidth
get_clientHeight get_clientTop get_clientLeft

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


TabIndex Property

*
  * Previous Topic: IHTMLControlElement::put_tabIndex
  * Next Topic: IHTMLControlElement::focus

IHTMLControlElement::get_tabIndex

HRESULT get_tabIndex(
    short *p
);

Retrieves the tab index for the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a short integer variable that receives the tab index.

Tab selection order is determined by the value of the tabIndex property as follows:

  • All elements with tabIndex > 0 are selected in increasing tabIndex order, or in source order for duplicate tabIndex values.
  • All elements with tabIndex = 0, or without tabIndex set, are selected next, in source order if more than one.
  • Elements with tabIndex = -1 are omitted from tab selection.

See also put_tabIndex

Up Top of Page

IHTMLControlElement::put_tabIndex

HRESULT put_tabIndex(
    short v
);

Sets the tab index for the object. The tab index determines the tab selection order.

  • Returns S_OK if successful, or an error value otherwise.
v
Short integer value specifying the tab index.

Tab selection order is determined by the value of the tabIndex property as follows:

  • All elements with tabIndex > 0 are selected in increasing tabIndex order, or in source order for duplicate tabIndex values.
  • All elements with tabIndex = 0, or without tabIndex set, are selected next, in source order if more than one.
  • Elements with tabIndex = -1 are omitted from tab selection.

See also get_tabIndex


IHTMLControlElement::focus

HRESULT focus(void);

Causes a control to receive the focus and executes the code specified by onfocus.

  • Returns S_OK if successful, or an error value otherwise.

See also blur


AccessKey Property

*
  * Previous Topic: IHTMLControlElement::put_accessKey
  * Next Topic: IHTMLControlElement::put_onblur

IHTMLControlElement::get_accessKey

HRESULT get_accessKey(
    BSTR *p
);

Retrieves an accelerator for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the accelerator key.

See also put_accessKey

Up Top of Page

IHTMLControlElement::put_accessKey

HRESULT put_accessKey(
    BSTR v
);

Sets an accelerator for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the accelerator.

See also get_accessKey


Onblur Property

*
  * Previous Topic: IHTMLControlElement::put_onblur
  * Next Topic: IHTMLControlElement::put_onfocus

IHTMLControlElement::get_onblur

HRESULT get_onblur(
    VARIANT *p
);

Retrieves the inline script associated with the onblur event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onblur

Up Top of Page

IHTMLControlElement::put_onblur

HRESULT put_onblur(
    VARIANT v
);

Sets the inline script associated with the onblur event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onblur


Onfocus Property

*
  * Previous Topic: IHTMLControlElement::put_onfocus
  * Next Topic: IHTMLControlElement::put_onresize

IHTMLControlElement::get_onfocus

HRESULT get_onfocus(
    VARIANT *p
);

Retrieves the inline script associated with the onfocus event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onfocus

Up Top of Page

IHTMLControlElement::put_onfocus

HRESULT put_onfocus(
    VARIANT v
);

Sets the inline script associated with the onfocus event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
v
Variable of VARIANT type.

See also get_onfocus


Onresize Property

*
  * Previous Topic: IHTMLControlElement::put_onresize
  * Next Topic: IHTMLControlElement::blur

IHTMLControlElement::get_onresize

HRESULT get_onresize(
    VARIANT *p
);

Retrieves the inline script associated with the onresize event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onresize

Up Top of Page

IHTMLControlElement::put_onresize

HRESULT put_onresize(
    VARIANT v
);

Sets the inline script associated with the onresize event on the control element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script.

See also get_onresize


IHTMLControlElement::blur

HRESULT blur(void);

Causes a control to lose focus and fires the onblur event.

  • Returns S_OK if successful, or an error value otherwise.

See also focus


IHTMLControlElement::addFilter

HRESULT addFilter(
    IUnknown *pUnk
);

Adds the specified filter to the list of filters influencing this element.

  • Returns S_OK if successful, or an error value otherwise.
pUnk
Address of the IUnknown interface of the filter to be added.

See also removeFilter


IHTMLControlElement::removeFilter

HRESULT removeFilter(
    IUnknown *pUnk
);

Removes the specified filter from the list of filters influencing this element.

  • Returns S_OK if successful, or an error value otherwise.
pUnk
Address of a variable of IUnknown type.

See also addFilter


IHTMLControlElement::get_clientHeight

HRESULT get_clientHeight(
    long *p
);

Retrieves the height of the element, in pixels. This height does not take into account any margin, border, scroll bar, or padding that might have been applied to the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height of the element.


IHTMLControlElement::get_clientWidth

HRESULT get_clientWidth(
    long *p
);

Retrieves the width of the element, in pixels. This width does not take into account any margin, border, scroll bar, or padding that might have been applied to the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width of the element.

Up Top of Page


IHTMLControlElement::get_clientTop

HRESULT get_clientTop(
    long *p
);

Retrieves the top coordinates of the client area inside this element's borders.

p
Long integer value containing the coordinates for the top corner of the client area inside this element's borders.

Up Top of Page


IHTMLControlElement::get_clientLeft

HRESULT get_clientLeft(
    long *p
);

Retrieves the left coordinates of the client area inside this element's borders.

p
Long integer value containing the coordinates for the left corner of the client area inside this element's borders.

Up Top of Page


IHTMLControlRange

The IHTMLControlRange interface contains a range of control type elements. This interface is used for control selection and represents an array of controls that can be operated on as a group.

IHTMLControlRange Methods
select add remove
item scrollIntoView queryCommandSupported
queryCommandEnabled queryCommandState queryCommandIndeterm
queryCommandText queryCommandValue execCommand
execCommandShowHelp commonParentElement get_length

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLControlRange::select

HRESULT select(void);

Highlights the input area of a form element.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLControlRange::add

HRESULT add(
    IHTMLControlElement *item
);

Adds an element to the collection.

  • Returns S_OK if successful, or an error value otherwise.
item
Address of the IHTMLControlElement interface to add.


IHTMLControlRange::remove

HRESULT remove(
    long index
);

Removes an element from the collection.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value containing the index of the element to remove.

See also add


IHTMLControlRange::item

HRESULT item(
    long index,
    IHTMLElement **pdisp
);

Retrieves an element or a collection from the given collection. The index parameter determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value containing the zero-based index of the item to retrieve.
pdisp
Address of a pointer to the IHTMLElement interface for the element or collection.

Up Top of Page


IHTMLControlRange::scrollIntoView

HRESULT scrollIntoView(
    VARIANT varargStart
);

Scrolls the object into view, aligning it at either the top or bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
varargStart
Boolean value specifying whether to place the object at the top of the window or at the bottom. If TRUE, the method scrolls the object so that its top is visible at the top of the window. If FALSE, the bottom of the object is visible at the bottom of the window. If no value is given, the object scrolls to the top by default.

Depending on the size of the given object and the current window, this method may not be able to put the item at the very top or very bottom, but will position the object as close to the requested position as possible.


IHTMLControlRange::queryCommandSupported

HRESULT queryCommandSupported(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is supported.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the command is supported, or FALSE otherwise.


IHTMLControlRange::queryCommandEnabled

HRESULT queryCommandEnabled(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is currently available.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String containing an identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the command is available, or FALSE otherwise.


IHTMLControlRange::queryCommandState

HRESULT queryCommandState(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Retrieves the current status of the given command. The status indicates whether the command has been carried out on the object.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing an identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the given command has been carried out, FALSE if it has not, or NULL if the function cannot determine the status of the command.


IHTMLControlRange::queryCommandIndeterm

HRESULT queryCommandIndeterm(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is in the indeterminate state.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing an identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the given command is in the indeterminate state, or FALSE otherwise.


IHTMLControlRange::queryCommandText

HRESULT queryCommandText(
    BSTR cmdID,
    BSTR *pcmdText
);

Retrieves the string associated with the given command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing an identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdText
Address of a Boolean variable that receives the command string.


IHTMLControlRange::queryCommandValue

HRESULT queryCommandValue(
    BSTR cmdID,
    VARIANT *pcmdValue
);

Retrieves the current value of the given command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdValue
Address of a Boolean variable that receives a string representing the command value. If the command is not supported, this variable receives NULL.


IHTMLControlRange::execCommand

HRESULT execCommand(
    BSTR cmdID,
    VARIANT_BOOL showUI,
    VARIANT value,
    VARIANT_BOOL *pfRet
);

Executes the given command over the current selection or text range.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String identifier of a command. Can be any command identifier given in the list of Command Identifiers.
showUI
Boolean value specifying whether to display a user interface if the command supports one. If TRUE, the command displays a user interface, if applicable; otherwise, it doesn't.
value
VARIANT structure containing a value to pass to the command. Possible values depend on the value of cmdID.
pfRet
Address of a Boolean variable that receives TRUE if the function is successful, or FALSE otherwise.


IHTMLControlRange::execCommandShowHelp

HRESULT execCommandShowHelp(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Displays help information for the given command identifier.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if successful, or FALSE otherwise.


IHTMLControlRange::commonParentElement

HRESULT commonParentElement(
    IHTMLElement **Parent
);

Retrieves the interface to the first parent element that contains all the controls that are currently stored in this range and within its scope.

  • Returns S_OK if successful, or an error value otherwise.
Parent
Address of a pointer to the IHTMLElement interface of the element.


IHTMLControlRange::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in the collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the number of elements.


IHTMLDatabinding

This interface encapsulates the databinding methods that an IHTMLElement interface can support. To access these methods, a control should query IHTMLElement for this interface.

IHTMLDatabinding Methods


DataFld Property

*
  * Previous Topic: IHTMLDatabinding::put_dataFld
  * Next Topic: IHTMLDatabinding::put_dataSrc

IHTMLDatabinding::get_dataFld

HRESULT get_dataFld(
    BSTR *p
);

Retrieves the field of a given data source (as specified by the dataFld property) to bind to the given element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the field.

See also put_dataFld

Up Top of Page

IHTMLDatabinding::put_dataFld

HRESULT put_dataFld(
    BSTR v
);

Sets the field of a given data source (as specified by the dataFld property) to bind to the given element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the field.

See also get_dataFld


DataSrc Property

*
  * Previous Topic: IHTMLDatabinding::put_dataSrc
  * Next Topic: IHTMLDatabinding::put_dataFormatAs

IHTMLDatabinding::get_dataSrc

HRESULT get_dataSrc(
    BSTR *p
);

Retrieves the identifier of the data source object that supplies the data that is bound to this element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the identifier of the data source object.

See also put_dataSrc

Up Top of Page

IHTMLDatabinding::put_dataSrc

HRESULT put_dataSrc(
    BSTR v
);

Sets the identifier of the data source object that supplies the data that is bound to this element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the identifier of the data source object.

See also get_dataSrc


DataFormatAs Property

*
  * Previous Topic: IHTMLDatabinding::put_dataFormatAs
  * Next Topic: IHTMLDDElement

IHTMLDatabinding::get_dataFormatAs

HRESULT get_dataFormatAs(
    BSTR *p
);

Retrieves the type of the data to bind to the given element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the type of data.

See also put_dataFormatAs

Up Top of Page

IHTMLDatabinding::put_dataFormatAs

HRESULT put_dataFormatAs(
    BSTR v
);

Sets the type of the data to bind to the given element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the type of data.

See also get_dataFormatAs


IHTMLDDElement IHTMLDDElement *
  * Previous Topic: IHTMLDatabinding::get_dataFormatAs
  * Next Topic: IHTMLDDElement::put_noWrap

IHTMLDDElement

This interface provides access to the DD object.

IHTMLDDElement Methods


NoWrap Property

*
  * Previous Topic: IHTMLDDElement::put_noWrap
  * Next Topic: IHTMLDialog

IHTMLDDElement::get_noWrap

HRESULT get_noWrap(
    VARIANT_BOOL *p
);

Determines whether automatic word wrapping is enabled or disabled for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if automatic word-wrapping is enabled for the element, or FALSE otherwise. The default value for this property is FALSE.

See also put_noWrap

Up Top of Page

IHTMLDDElement::put_noWrap

HRESULT put_noWrap(
    VARIANT_BOOL v
);

Enables or disables automatic word wrapping for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value containing the word-wrap flag. If TRUE, the browser performs automatic word wrapping on the element text. If FALSE, it doesn't. The default value for this property is FALSE.

See also get_noWrap


IHTMLDialog

This interface provides access to information about an HTML dialog box.

The dialog object is the special window object created by the IHTMLWindow2::showModalDialog method. From within the dialog window, scripts reference the dialog object as the top-level window property. There is no such dialog property in the dialog.

IHTMLDialog Methods
put_dialogTop get_dialogTop put_dialogLeft
get_dialogLeft put_dialogWidth get_dialogWidth
put_dialogHeight get_dialogHeight get_dialogArguments
put_returnValue get_returnValue close
toString


DialogTop Property

*
  * Previous Topic: IHTMLDialog::put_dialogTop
  * Next Topic: IHTMLDialog::put_dialogLeft

IHTMLDialog::get_dialogTop

HRESULT get_dialogTop(
    VARIANT *p
);

Retrieves the top coordinate of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the top coordinate.

This property applies only to windows created using the showModalDialog method.

See also put_dialogTop

Up Top of Page

IHTMLDialog::put_dialogTop

HRESULT put_dialogTop(
    VARIANT v
);

Sets the top coordinate of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing either a string or value specifying the top coordinate.

This property applies only to windows created using the showModalDialog method.

See also get_dialogTop


DialogLeft Property

*
  * Previous Topic: IHTMLDialog::put_dialogLeft
  * Next Topic: IHTMLDialog::put_dialogWidth

IHTMLDialog::get_dialogLeft

HRESULT get_dialogLeft(
    VARIANT *p
);

Retrieves the left coordinate of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the left coordinate.

This property applies only to windows created using the showModalDialog method.

See also put_dialogLeft

Up Top of Page

IHTMLDialog::put_dialogLeft

HRESULT put_dialogLeft(
    VARIANT v
);

Sets the left coordinate of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the left coordinate.

This property applies only to windows created using the showModalDialog method.

See also get_dialogLeft


DialogWidth Property

*
  * Previous Topic: IHTMLDialog::put_dialogWidth
  * Next Topic: IHTMLDialog::put_dialogHeight

IHTMLDialog::get_dialogWidth

HRESULT get_dialogWidth(
    VARIANT *p
);

Retrieves the width of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the width.

This property applies only to windows created using the showModalDialog method.

See also put_dialogWidth

Up Top of Page

IHTMLDialog::put_dialogWidth

HRESULT put_dialogWidth(
    VARIANT v
);

Sets the width of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or value specifying the width.

This property applies only to windows created using the showModalDialog method.

See also get_dialogWidth


DialogHeight Property

*
  * Previous Topic: IHTMLDialog::put_dialogHeight
  * Next Topic: IHTMLDialog::get_dialogArguments

IHTMLDialog::get_dialogHeight

HRESULT get_dialogHeight(
    VARIANT *p
);

Retrieves the height of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the height.

This property applies only to windows created using the showModalDialog method.

See also put_dialogHeight

Up Top of Page

IHTMLDialog::put_dialogHeight

HRESULT put_dialogHeight(
    VARIANT v
);

Sets the height of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or value specifying the height.

This property applies only to windows created using the showModalDialog method.

See also get_dialogHeight


IHTMLDialog::get_dialogArguments

HRESULT get_dialogArguments(
    VARIANT *p
);

Retrieves the variable or array of variables passed into the modal dialog window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the variables.

This property applies only to windows created using the showModalDialog method.


ReturnValue Property

*
  * Previous Topic: IHTMLDialog::put_returnValue
  * Next Topic: IHTMLDialog::close

IHTMLDialog::get_returnValue

HRESULT get_returnValue(
    VARIANT *p
);

Retrieves the return value of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the return value, which can be either TRUE or FALSE.

For event handler functions, the value of this property takes precedence over values returned by the function, such as through a return statement.

See also put_returnValue

Up Top of Page

IHTMLDialog::put_returnValue

HRESULT put_returnValue(
    VARIANT v
);

Sets the return value of the dialog box.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or value specifying the return value, which can be either TRUE or FALSE.

For event handler functions, the value of this property takes precedence over values returned by the function, such as through a return statement.

See also get_returnValue


IHTMLDialog::close IHTMLDialog::close *
  * Previous Topic: IHTMLDialog::get_returnValue
  * Next Topic: IHTMLDialog::toString

IHTMLDialog::close

HRESULT close(void);

Closes the dialog box.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLDialog::toString

HRESULT toString(
    BSTR *String
);

Retrieves a string representation of the dialog object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a string variable that receives the string representation.


IHTMLDivElement

The DIV element is used with the className property to represent different kinds of containers.

This element is a block element.

IHTMLDivElement Methods


Align Property

*
  * Previous Topic: IHTMLDivElement::put_align
  * Next Topic: IHTMLDivElement::put_noWrap

IHTMLDivElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves the alignment of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also put_align

Up Top of Page

IHTMLDivElement::put_align

HRESULT put_align(
    BSTR v
);

Sets the alignment of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also get_align


NoWrap Property

*
  * Previous Topic: IHTMLDivElement::put_noWrap
  * Next Topic: IHTMLDivPosition

IHTMLDivElement::get_noWrap

HRESULT get_noWrap(
    VARIANT_BOOL *p
);

Determines whether automatic word wrapping is enabled or disabled for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if automatic word wrapping is enabled for the element, or FALSE otherwise. The default value for this property is FALSE.

See also put_noWrap

Up Top of Page

IHTMLDivElement::put_noWrap

HRESULT put_noWrap(
    VARIANT_BOOL v
);

Enables or disables automatic word wrapping for the text in the division.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that contains the word-wrap flag. If TRUE, the browser performs automatic word wrapping on the division contents. If FALSE, it doesn't. The default value for this property is FALSE.

See also get_noWrap


IHTMLDivPosition

This interface enables you to specify how adjacent text is aligned with respect to a DIV object.

IHTMLDivPosition Methods


Align Property

*
  * Previous Topic: IHTMLDivPosition::put_align
  * Next Topic: IHTMLDListElement

IHTMLDivPosition::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image input type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLDivPosition::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image input type. It is undefined for all other types.

See also get_align


IHTMLDListElement IHTMLDListElement *
  * Previous Topic: IHTMLDivPosition::get_align
  * Next Topic: IHTMLDListElement::put_compact

IHTMLDListElement

This interface denotes a definition list.

This element is a block element.

IHTMLDListElement Methods


Compact Property

*
  * Previous Topic: IHTMLDListElement::put_compact
  * Next Topic: IHTMLDocument

IHTMLDListElement::get_compact

HRESULT get_compact(
    VARIANT_BOOL *p
);

Determines whether the list is being compacted to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if the list is being compacted, or FALSE otherwise.

The default value for this property is FALSE.

See also put_compact

Up Top of Page

IHTMLDListElement::put_compact

HRESULT put_compact(
    VARIANT_BOOL v
);

Specifies that the list should be compacted to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that contains the compact flag. If TRUE, the list is compacted; if FALSE, it is not.

The default value for this property is FALSE.

See also get_compact


IHTMLDocument

A document object represents the HTML document in a given browser window. You use the document object to retrieve information about the document, to examine and modify the HTML elements and text within the document, and to process events.

Typically, every window object has a corresponding document object that you can retrieve by calling the QueryInterface function with the IID_IHTMLDocument or IID_IHTMLDocument2 interface identifier. Windows that contain HTML documents always have valid document objects, but windows that contain documents in other formats may not. In general, before attempting to retrieve the document object for a window that is not the current window, make sure that the source file associated with that window is an HTML document file or a file that can be represented as an HTML document (for example, a text file).

IHTMLDocument Methods
get_Script


IHTMLDocument::get_Script

HRESULT get_Script(
    IDispatch **p
);

Retrieves an interface pointer that provides access to the scripting object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to an IDispatch interface to the scripting object.


IHTMLDocument2

A document object represents the HTML document in a given browser window. You use the document object to retrieve information about the document, to examine and modify the HTML elements and text within the document, and to process events.

Typically, every window object has a corresponding document object that you can retrieve by calling the IUnknown::QueryInterface method with the IID_IHTMLDocument or IID_IHTMLDocument2 interface identifier. Windows that contain HTML documents always have valid document objects, but windows that contain documents in other formats might not. In general, before attempting to retrieve the document object for a window that is not the current window, make sure that the source file associated with that window is an HTML document file or a file that can be represented as an HTML document (for example, a text file).

IHTMLDocument2 Methods
get_all get_body get_activeElement
get_images get_applets get_links
get_forms get_anchors put_title
get_title get_scripts get_selection
get_readyState get_frames get_embeds
get_plugins put_alinkColor get_alinkColor
put_bgColor get_bgColor put_fgColor
get_fgColor put_linkColor get_linkColor
put_vlinkColor get_vlinkColor get_referrer
get_location get_lastModified put_URL
get_URL put_domain get_domain
put_cookie get_cookie put_expando
get_expando put_charset get_charset
put_defaultCharset get_defaultCharset get_mimeType
get_fileSize get_fileCreatedDate get_fileModifiedDate
get_fileUpdatedDate get_security get_protocol
get_nameProp write writeln
open close clear
queryCommandSupported queryCommandEnabled queryCommandState
queryCommandIndeterm queryCommandText queryCommandValue
execCommand execCommandShowHelp createElement
put_onhelp get_onhelp put_onclick
get_onclick put_ondblclick get_ondblclick
put_onkeyup get_onkeyup put_onkeydown
get_onkeydown put_onkeypress get_onkeypress
put_onmouseup get_onmouseup put_onmousedown
get_onmousedown put_onmousemove get_onmousemove
put_onmouseout get_onmouseout put_onmouseover
get_onmouseover put_onreadystatechange get_onreadystatechange
put_onafterupdate get_onafterupdate put_onrowexit
get_onrowexit put_onrowenter get_onrowenter
put_ondragstart get_ondragstart put_onselectstart
get_onselectstart elementFromPoint get_parentWindow
get_styleSheets put_onbeforeupdate get_onbeforeupdate
put_onerrorupdate get_onerrorupdate toString

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLDocument2::get_all

HRESULT get_all(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the elements in an HTML document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection of elements.

The collection includes one element object for each valid HTML tag. If a valid tag has a matching end tag, both tags are represented by the same element object. The collection always includes one element object for each of the HTML, HEAD, and BODY tags regardless of whether the tags are present in the document. If the document contains invalid or unknown tags, the collection includes one element object for each. Unlike valid end tags, unknown end tags are represented by their own element objects. The order of the element objects in the collection is the same as the order of corresponding tags in the document. Although the collection indicates the order of tags, it does not indicate which tags contain others.

You can use the length property to determine the number of element objects in the collection, and the item or tags function to retrieve individual objects or collections of objects from the collection. You can retrieve individual objects by specifying the object's index or by using its name property. Index values can be either numbers or names. Number values are zero-based, that is, 0 for the first element object, 1 for the next, and so on. A name is valid only if it is defined by a name or ID property for at least one of the elements in the collection. If the name is defined by more than one element, you can use it to retrieve a collection of all element objects that define that name.

See also get_body


IHTMLDocument2::get_body

HRESULT get_body(
    IHTMLElement **p
);

Retrieves an interface pointer to the document's BODY object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the BODY object.

See also get_all


IHTMLDocument2::get_activeElement

HRESULT get_activeElement(
    IHTMLElement **p
);

Retrieves a pointer to the interface of the element that has the focus, which is determined by the activeElement property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the element that currently has the focus.


IHTMLDocument2::get_images

HRESULT get_images(
    IHTMLElementCollection **p
);

Retrieves a pointer to the IHTMLElementCollection interface of the zero-based collection of all the images in an HTML document. The images are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the images collection.


IHTMLDocument2::get_applets

HRESULT get_applets(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the APPLET objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the applet collection.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be referenced only by ordinal position.


IHTMLDocument2::get_links

HRESULT get_links(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the LINK and AREA objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection containing all the LINK and AREA elements.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be only referenced by ordinal position.


IHTMLDocument2::get_forms

HRESULT get_forms(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the FORM objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection of the collection containing all the FORM objects in an HTML document.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be only referenced by ordinal position.


IHTMLDocument2::get_anchors

HRESULT get_anchors(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the A objects in an HTML document. The elements are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection containing all the A objects in the HTML document.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be only referenced by ordinal position.


Title Property

*
  * Previous Topic: IHTMLDocument2::put_title
  * Next Topic: IHTMLDocument2::get_scripts

IHTMLDocument2::get_title

HRESULT get_title(
    BSTR *p
);

Retrieves the title of the document. The title identifies the contents of the document and is displayed in the header bar of the document window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the title.

This function retrieves the TITLE object in the document header (defined by the HEAD object).

See also put_title

Up Top of Page

IHTMLDocument2::put_title

HRESULT put_title(
    BSTR v
);

Sets the title of the document. The title identifies the contents of the document and is displayed in the header bar of the document window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the document title.

This function sets the TITLE object in the document header (defined by the HEAD object).

See also get_title


IHTMLDocument2::get_scripts

HRESULT get_scripts(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the SCRIPT objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection that contains all the SCRIPT objects.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.


IHTMLDocument2::get_selection

HRESULT get_selection(
    IHTMLSelectionObject **p
);

Retrieves an interface pointer to an object representing the active selection. The active selection can be an insertion point, or a highlighted block of text or other elements in the document upon which the user or a script can carry out an action.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to an IHTMLSelectionObject interface of the object representing the active selection.

You typically use the selection object as input from the user identifying the portion of the document to act on, or as output to the user showing the results of an action.

The user, a script, or an object can create a selection. The user creates a selection by dragging the mouse over a portion of the document. A script or object creates a selection by calling the select method on a text range or similar object.

To carry out work on a selection, you can create a text range object from the selection by using the createRange method.

A document can have only one selection at a time. The selection has a type that determines whether it is empty or contains a contiguous block of consecutive text and/or elements. Although an empty selection contains nothing, it is useful for marking a position in the document.


IHTMLDocument2::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current status of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the download status of the object. Can be one of these strings:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the three states they expose.


IHTMLDocument2::get_frames

HRESULT get_frames(
    IHTMLFramesCollection2 **p
);

Retrieves an interface pointer to a zero-based collection of all the FRAME objects in an HTML document, if the document contains the FRAMESET object. If the document contains the BODY object, this is a collection of all IFRAME objects in the document. In either case, the objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLFramesCollection2 interface of the collection.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.


IHTMLDocument2::get_embeds

HRESULT get_embeds(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the EMBED objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.


IHTMLDocument2::get_plugins

HRESULT get_plugins(
    IHTMLElementCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the EMBED objects in an HTML document. The objects are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the collection.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.


AlinkColor Property

*
  * Previous Topic: IHTMLDocument2::put_alinkColor
  * Next Topic: IHTMLDocument2::put_bgColor

IHTMLDocument2::get_alinkColor

HRESULT get_alinkColor(
    VARIANT *p
);

Retrieves the color that the browser uses to indicate the active link.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. It can be one of the color names or values given in the Color Table reference documentation.

See also put_alinkColor

Up Top of Page

IHTMLDocument2::put_alinkColor

HRESULT put_alinkColor(
    VARIANT v
);

Sets the color that the browser uses to indicate the active link.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also get_alinkColor


BgColor Property

*
  * Previous Topic: IHTMLDocument2::put_bgColor
  * Next Topic: IHTMLDocument2::put_fgColor

IHTMLDocument2::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color of the page.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLDocument2::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color of the page.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


FgColor Property

*
  * Previous Topic: IHTMLDocument2::put_fgColor
  * Next Topic: IHTMLDocument2::put_linkColor

IHTMLDocument2::get_fgColor

HRESULT get_fgColor(
    VARIANT *p
);

Retrieves the color of the document foreground text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

Changing this property after the document is rendered does not change the displayed color.

JScript supports the entire set of valid property colors both as strings and their numerical equivalents as a string. JScript always returns the property as the numeric equivalent as a string regardless of the format to which the value was set.

The default foreground color is UA-specific.

See also put_fgColor

Up Top of Page

IHTMLDocument2::put_fgColor

HRESULT put_fgColor(
    VARIANT v
);

Sets the color of the document foreground text.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

Changing this property after the document is rendered does not change the displayed color.

The default foreground color is browser specific.

See also get_fgColor


LinkColor Property

*
  * Previous Topic: IHTMLDocument2::put_linkColor
  * Next Topic: IHTMLDocument2::put_vlinkColor

IHTMLDocument2::get_linkColor

HRESULT get_linkColor(
    VARIANT *p
);

Retrieves the color of the document links.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_linkColor

Up Top of Page

IHTMLDocument2::put_linkColor

HRESULT put_linkColor(
    VARIANT v
);

Sets the color of the document links.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_linkColor


VlinkColor Property

*
  * Previous Topic: IHTMLDocument2::put_vlinkColor
  * Next Topic: IHTMLDocument2::get_referrer

IHTMLDocument2::get_vlinkColor

HRESULT get_vlinkColor(
    VARIANT *p
);

Retrieves the color of links that have already been visited.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_vlinkColor

Up Top of Page

IHTMLDocument2::put_vlinkColor

HRESULT put_vlinkColor(
    VARIANT v
);

Sets the color of links that have already been visited.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_vlinkColor


IHTMLDocument2::get_referrer

HRESULT get_referrer(
    BSTR *p
);

Retrieves the URL of the previous location.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL.


IHTMLDocument2::get_location

HRESULT get_location(
    IHTMLLocation **p
);

Retrieves an interface pointer to a location object. The object contains information about the current location (full URL) of the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLLocation interface of the location object.


IHTMLDocument2::get_lastModified

HRESULT get_lastModified(
    BSTR *p
);

Retrieves a string containing the last-modified date of the page (if the page provides one).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the last-modified date.


URL Property

*
  * Previous Topic: IHTMLDocument2::put_URL
  * Next Topic: IHTMLDocument2::put_domain

IHTMLDocument2::get_URL

HRESULT get_URL(
    BSTR *p
);

Retrieves the URL for the current document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL.

This function performs the same action as the IHTMLLocation::get_href function.

See also put_URL

Up Top of Page

IHTMLDocument2::put_URL

HRESULT put_URL(
    BSTR v
);

Sets the URL for the current document. This function causes the browser to browse to the location specified by the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

This function performs the same action as the IHTMLLocation::put_href function.

See also get_URL


Domain Property

*
  * Previous Topic: IHTMLDocument2::put_domain
  * Next Topic: IHTMLDocument2::put_cookie

IHTMLDocument2::get_domain

HRESULT get_domain(
    BSTR *p
);

Retrieves or the security domain of the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the security domain.

The domain property initially returns the hostname of the server that the page is from. This property can be assigned the domain suffix to allow sharing of pages across frames. For example, a page in one frame from home.microsoft.com and a page from www.microsoft.com would initially not be able to communicate with each other. However, by setting the domain property of both pages to the suffix, microsoft.com, both pages would be considered secure and now code can access between the pages.

See also put_domain

Up Top of Page

IHTMLDocument2::put_domain

HRESULT put_domain(
    BSTR v
);

Sets or returns the security domain of the document.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the security domain.

The domain property initially returns the host name of the server the page is from. This property can be assigned the domain suffix to allow sharing of pages across frames. For example, a page in one frame from home.microsoft.com and a page from www.microsoft.com would initially not be able to communicate with each other. However, by setting the domain property of both pages to the suffix, microsoft.com, both pages would be considered secure and now code can be shared between the pages.

See also get_domain


Cookie Property

*
  * Previous Topic: IHTMLDocument2::put_cookie
  * Next Topic: IHTMLDocument2::put_expando

IHTMLDocument2::get_cookie

HRESULT get_cookie(
    BSTR *p
);

Retrieves the string value of a cookie, which is a small piece of information stored by the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the cookie.

See also put_cookie

Up Top of Page

IHTMLDocument2::put_cookie

HRESULT put_cookie(
    BSTR v
);

Sets the string value of a cookie, which is a small piece of information stored by the browser.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the cookie.

See also get_cookie


Expando Property

*
  * Previous Topic: IHTMLDocument2::put_expando
  * Next Topic: IHTMLDocument2::put_charset

IHTMLDocument2::get_expando

HRESULT get_expando(
    VARIANT_BOOL *p
);

Determines whether the document supports the use of expando properties.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if the document supports expando properties, or FALSE otherwise.

See also put_expando

Up Top of Page

IHTMLDocument2::put_expando

HRESULT put_expando(
    VARIANT_BOOL v
);

Specifies whether the document supports the use of expando properties.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. If TRUE, the document supports expando properties; if FALSE, it does not.

See also get_expando


Charset Property

*
  * Previous Topic: IHTMLDocument2::put_charset
  * Next Topic: IHTMLDocument2::put_defaultCharset

IHTMLDocument2::get_charset

HRESULT get_charset(
    BSTR *p
);

Retrieves the character set used to encode the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the current character set.

See also put_charset

Up Top of Page

IHTMLDocument2::put_charset

HRESULT put_charset(
    BSTR v
);

Specifies the character set used to encode the document.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the character set.

See also get_charset


DefaultCharset Property

*
  * Previous Topic: IHTMLDocument2::put_defaultCharset
  * Next Topic: IHTMLDocument2::get_mimeType

IHTMLDocument2::get_defaultCharset

HRESULT get_defaultCharset(
    BSTR *p
);

Retrieves the default character set of the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name of the default character set.

See also put_defaultCharset

Up Top of Page

IHTMLDocument2::put_defaultCharset

HRESULT put_defaultCharset(
    BSTR v
);

Specifies the default character set of the document.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the default character set.

See also get_defaultCharset


IHTMLDocument2::get_mimeType

HRESULT get_mimeType(
    BSTR *p
);

Retrieves the MIME type for the document file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the MIME type.


IHTMLDocument2::get_fileSize

HRESULT get_fileSize(
    BSTR *p
);

Retrieves the size, in bytes, of the document file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the size of the document file.


IHTMLDocument2::get_fileCreatedDate

HRESULT get_fileCreatedDate(
    BSTR *p
);

Retrieves the date when the document file was created.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the creation date. The date consists of the weekday, month, date, and year.


IHTMLDocument2::get_fileModifiedDate

HRESULT get_fileModifiedDate(
    BSTR *p
);

Retrieves the date when the document file was most recently modified.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the modification date. The date consists of the weekday, month, date, and year.

See also get_fileUpdatedDate


IHTMLDocument2::get_fileUpdatedDate

HRESULT get_fileUpdatedDate(
    BSTR *p
);

Retrieves the date when the document file was last updated.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the date. The date consists of the weekday, month, date, and year.

See also get_fileModifiedDate


IHTMLDocument2::get_security

HRESULT get_security(
    BSTR *p
);

Retrieves security information for the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the security information.


IHTMLDocument2::get_protocol

HRESULT get_protocol(
    BSTR *p
);

Retrieves the protocol portion of the URL that the browser uses to locate the document file. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the protocol.


IHTMLDocument2::get_nameProp

HRESULT get_nameProp(
    BSTR *p
);

Retrieves the file name from the URL that the browser uses to locate the document file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the file name.


IHTMLDocument2::write

HRESULT write(
    SAFEARRAY *psarray
);

Writes one or more HTML expressions to a document in the specified window.

  • Returns S_OK if successful, or an error value otherwise.
psarray
Address of a safe array containing the text and HTML tags to write.

See also writeln


IHTMLDocument2::writeln

HRESULT writeln(
    SAFEARRAY *psarray
);

Writes one or more HTML expressions to a document in the specified window, followed by a carriage return.

  • Returns S_OK if successful, or an error value otherwise.
psarray
Address of a safe array containing the text and HTML tags to write.

In HTML, the carriage return is ignored unless within preformatted text.

See also write


IHTMLDocument2::open

HRESULT open(
    BSTR url,
    VARIANT name,
    VARIANT features,
    VARIANT replace ,
    IDispatch **pomWindowResult
);

Opens a stream to collect the output of the write or writeln method.

  • Returns S_OK if successful, or an error value otherwise.
url
String value containing the URL of the resource.
name
VARIANT structure that contains the name.
features
VARIANT structure that contains the features.
replace
VARIANT structure.
pomWindowResult
Address of a pointer to the IDispatch interface.

See also close


IHTMLDocument2::close

HRESULT close(void);

Closes an output stream and forces data sent to layout to display.

  • Returns S_OK if successful, or an error value otherwise.

See also open


IHTMLDocument2::clear IHTMLDocument2::clear *
  * Previous Topic: IHTMLDocument2::close
  * Next Topic: IHTMLDocument2::queryCommandSupported

IHTMLDocument2::clear

HRESULT clear(void);

This is a no-op.

  • Returns S_OK.


IHTMLDocument2::queryCommandSupported

HRESULT queryCommandSupported(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is supported.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing the identifier of a command.
pfRet
Address of a Boolean variable that receives TRUE if the command is supported, or FALSE otherwise.


IHTMLDocument2::queryCommandEnabled

HRESULT queryCommandEnabled(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is currently available.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the command is available, or FALSE otherwise.


IHTMLDocument2::queryCommandState

HRESULT queryCommandState(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Retrieves the current status of the given command. The status indicates whether the command has been carried out on the object.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value that contains the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the given command has been carried out, FALSE if it has not, or NULL if the function cannot determine the status of the command.


IHTMLDocument2::queryCommandIndeterm

HRESULT queryCommandIndeterm(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is in the indeterminate state.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value that contains the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if the given command is in the indeterminate state, or FALSE otherwise.


IHTMLDocument2::queryCommandText

HRESULT queryCommandText(
    BSTR cmdID,
    BSTR *pcmdText
);

Returns the string associated with a command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value that contains the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdText
Address of a string variable where the text associated with the command will be stored.


IHTMLDocument2::queryCommandValue

HRESULT queryCommandValue(
    BSTR cmdID,
    VARIANT *pcmdValue
);

Retrieves the current value of the given command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value that contains the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdValue
Address of a VARIANT structure that receives a string representing the command value. If the command is not supported, this variable receives NULL.


IHTMLDocument2::execCommand

HRESULT execCommand(
    BSTR cmdID,
    VARIANT_BOOL showUI,
    VARIANT value,
    VARIANT_BOOL *pfRet
);

Executes the given command over the current selection or text range.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value containing the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
showUI
Boolean value specifying whether to display a user interface if the command supports one. If TRUE, the command displays a user interface, if applicable; otherwise, it doesn't.
value
VARIANT structure to pass to the command. Possible values depend on the value of cmdID.
pfRet
Address of a Boolean variable that receives TRUE if the function is successful, or FALSE otherwise.


IHTMLDocument2::execCommandShowHelp

HRESULT execCommandShowHelp(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Displays help information for the given command identifier.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
String value that contains the identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a Boolean variable that receives TRUE if successful, or FALSE otherwise.


IHTMLDocument2::createElement

HRESULT createElement(
    BSTR eTag,
    IHTMLElement **newElem
);

Creates an instance of the element object for the specified tag. Only new IMG and OPTION objects can be created. Before they can be used, new objects must be explicitly added to their respective collections.

  • Returns S_OK if successful, or an error value otherwise.
eTag
String value specifiying the type of element to create.
newElem
Address of a pointer to the IHTMLElement interface of the new element.


Onhelp Property

*
  * Previous Topic: IHTMLDocument2::put_onhelp
  * Next Topic: IHTMLDocument2::put_onclick

IHTMLDocument2::get_onhelp

HRESULT get_onhelp(
    VARIANT *p
);

Retrieves the inline script associated with the onhelp event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onhelp

Up Top of Page

IHTMLDocument2::put_onhelp

HRESULT put_onhelp(
    VARIANT v
);

Sets the inline script associated with the onhelp event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the inline script.

See also get_onhelp


Onclick Property

*
  * Previous Topic: IHTMLDocument2::put_onclick
  * Next Topic: IHTMLDocument2::put_ondblclick

IHTMLDocument2::get_onclick

HRESULT get_onclick(
    VARIANT *p
);

Retrieves the inline script associated with the onclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onclick

Up Top of Page

IHTMLDocument2::put_onclick

HRESULT put_onclick(
    VARIANT v
);

Sets the inline script associated with the onclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the inline script.

See also get_onclick


Ondblclick Property

*
  * Previous Topic: IHTMLDocument2::put_ondblclick
  * Next Topic: IHTMLDocument2::put_onkeyup

IHTMLDocument2::get_ondblclick

HRESULT get_ondblclick(
    VARIANT *p
);

Retrieves the inline script associated with the ondblclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondblclick

Up Top of Page

IHTMLDocument2::put_ondblclick

HRESULT put_ondblclick(
    VARIANT v
);

Sets the inline script associated with the ondblclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script.

See also get_ondblclick


Onkeyup Property

*
  * Previous Topic: IHTMLDocument2::put_onkeyup
  * Next Topic: IHTMLDocument2::put_onkeydown

IHTMLDocument2::get_onkeyup

HRESULT get_onkeyup(
    VARIANT *p
);

Retrieves the inline script associated with the onkeyup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeyup

Up Top of Page

IHTMLDocument2::put_onkeyup

HRESULT put_onkeyup(
    VARIANT v
);

Sets the inline script associated with the onkeyup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onkeyup


Onkeydown Property

*
  * Previous Topic: IHTMLDocument2::put_onkeydown
  * Next Topic: IHTMLDocument2::put_onkeypress

IHTMLDocument2::get_onkeydown

HRESULT get_onkeydown(
    VARIANT *p
);

Retrieves the inline script associated with the onkeydown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeydown

Up Top of Page

IHTMLDocument2::put_onkeydown

HRESULT put_onkeydown(
    VARIANT v
);

Sets the inline script associated with the onkeydown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onkeydown


Onkeypress Property

*
  * Previous Topic: IHTMLDocument2::put_onkeypress
  * Next Topic: IHTMLDocument2::put_onmouseup

IHTMLDocument2::get_onkeypress

HRESULT get_onkeypress(
    VARIANT *p
);

Retrieves the inline script associated with the onkeypress event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeypress

Up Top of Page

IHTMLDocument2::put_onkeypress

HRESULT put_onkeypress(
    VARIANT v
);

Sets the inline script associated with the onkeypress event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onkeypress


Onmouseup Property

*
  * Previous Topic: IHTMLDocument2::put_onmouseup
  * Next Topic: IHTMLDocument2::put_onmousedown

IHTMLDocument2::get_onmouseup

HRESULT get_onmouseup(
    VARIANT *p
);

Retrieves the inline script associated with the onmouseup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmouseup

Up Top of Page

IHTMLDocument2::put_onmouseup

HRESULT put_onmouseup(
    VARIANT v
);

Sets the inline script associated with the onmouseup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onmouseup


Onmousedown Property

*
  * Previous Topic: IHTMLDocument2::put_onmousedown
  * Next Topic: IHTMLDocument2::put_onmousemove

IHTMLDocument2::get_onmousedown

HRESULT get_onmousedown(
    VARIANT *p
);

Retrieves the inline script associated with the onmousedown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmousedown

Up Top of Page

IHTMLDocument2::put_onmousedown

HRESULT put_onmousedown(
    VARIANT v
);

Sets the inline script associated with the onmousedown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onmousedown


Onmousemove Property

*
  * Previous Topic: IHTMLDocument2::put_onmousemove
  * Next Topic: IHTMLDocument2::put_onmouseout

IHTMLDocument2::get_onmousemove

HRESULT get_onmousemove(
    VARIANT *p
);

Retrieves the inline script associated with the onmousemove event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmousemove

Up Top of Page

IHTMLDocument2::put_onmousemove

HRESULT put_onmousemove(
    VARIANT v
);

Sets the inline script associated with the onmousemove event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onmousemove


Onmouseout Property

*
  * Previous Topic: IHTMLDocument2::put_onmouseout
  * Next Topic: IHTMLDocument2::put_onmouseover

IHTMLDocument2::get_onmouseout

HRESULT get_onmouseout(
    VARIANT *p
);

Retrieves the inline script associated with the onmouseout event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmouseout

Up Top of Page

IHTMLDocument2::put_onmouseout

HRESULT put_onmouseout(
    VARIANT v
);

Sets the inline script associated with the onmouseout event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmouseout


Onmouseover Property

*
  * Previous Topic: IHTMLDocument2::put_onmouseover
  * Next Topic: IHTMLDocument2::put_onreadystatechange

IHTMLDocument2::get_onmouseover

HRESULT get_onmouseover(
    VARIANT *p
);

Retrieves the inline script associated with the onmouseover event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the data.

See also put_onmouseover

Up Top of Page

IHTMLDocument2::put_onmouseover

HRESULT put_onmouseover(
    VARIANT v
);

Sets the inline script associated with the onmouseover event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onmouseover


Onreadystatechange Property

*
  * Previous Topic: IHTMLDocument2::put_onreadystatechange
  * Next Topic: IHTMLDocument2::put_onafterupdate

IHTMLDocument2::get_onreadystatechange

HRESULT get_onreadystatechange(
    VARIANT *p
);

Retrieves the inline script associated with the onreadystatechange event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onreadystatechange

Up Top of Page

IHTMLDocument2::put_onreadystatechange

HRESULT put_onreadystatechange(
    VARIANT v
);

Sets the inline script associated with the onreadystatechange event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onreadystatechange


Onafterupdate Property

*
  * Previous Topic: IHTMLDocument2::put_onafterupdate
  * Next Topic: IHTMLDocument2::put_onrowexit

IHTMLDocument2::get_onafterupdate

HRESULT get_onafterupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onafterupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onafterupdate

Up Top of Page

IHTMLDocument2::put_onafterupdate

HRESULT put_onafterupdate(
    VARIANT v
);

Sets the inline script associated with the onafterupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onafterupdate


Onrowexit Property

*
  * Previous Topic: IHTMLDocument2::put_onrowexit
  * Next Topic: IHTMLDocument2::put_onrowenter

IHTMLDocument2::get_onrowexit

HRESULT get_onrowexit(
    VARIANT *p
);

Retrieves the inline script associated with the onrowexit event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onrowexit

Up Top of Page

IHTMLDocument2::put_onrowexit

HRESULT put_onrowexit(
    VARIANT v
);

Sets the inline script associated with the onrowexit event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onrowexit


Onrowenter Property

*
  * Previous Topic: IHTMLDocument2::put_onrowenter
  * Next Topic: IHTMLDocument2::put_ondragstart

IHTMLDocument2::get_onrowenter

HRESULT get_onrowenter(
    VARIANT *p
);

Retrieves the inline script associated with the onrowenter event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onrowenter

Up Top of Page

IHTMLDocument2::put_onrowenter

HRESULT put_onrowenter(
    VARIANT v
);

Sets the inline script associated with the onrowenter event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onrowenter


Ondragstart Property

*
  * Previous Topic: IHTMLDocument2::put_ondragstart
  * Next Topic: IHTMLDocument2::put_onselectstart

IHTMLDocument2::get_ondragstart

HRESULT get_ondragstart(
    VARIANT *p
);

Retrieves the inline script associated with the ondragstart event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondragstart

Up Top of Page

IHTMLDocument2::put_ondragstart

HRESULT put_ondragstart(
    VARIANT v
);

Sets the inline script associated with the ondragstart event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_ondragstart


Onselectstart Property

*
  * Previous Topic: IHTMLDocument2::put_onselectstart
  * Next Topic: IHTMLDocument2::elementFromPoint

IHTMLDocument2::get_onselectstart

HRESULT get_onselectstart(
    VARIANT *p
);

Retrieves the inline script associated with the onselect event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onselectstart

Up Top of Page

IHTMLDocument2::put_onselectstart

HRESULT put_onselectstart(
    VARIANT v
);

Sets the inline script associated with the onselect event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onselectstart


IHTMLDocument2::elementFromPoint

HRESULT elementFromPoint(
    long x,
    long y,
    IHTMLElement **elementHit
);

Retrieves the element at the specified x and y coordinates.

  • Returns S_OK if successful, or an error value otherwise.
x
Long integer value specifying the horizontal coordinate, in window coordinates.
y
Long integer value specifying the vertical coordinate, in window coordinates.
elementHit
Address of a pointer to the IHTMLElement interface for the element at the given coordinates.

Window coordinates are relative to the top-left corner of the window, which is at coordinates 0,0.


IHTMLDocument2::get_parentWindow

HRESULT get_parentWindow(
    IHTMLWindow2 **p
);

Retrieves an interface pointer to the window object for the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLWindow2 interface associated with the parent window.


IHTMLDocument2::get_styleSheets

HRESULT get_styleSheets(
    IHTMLStyleSheetsCollection **p
);

Retrieves an interface pointer to a zero-based collection of the style sheet objects exposed from the document object. Each style sheet object represents an individual style sheet that is defined for the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLStyleSheetsCollection interface of the collection.


Onbeforeupdate Property

*
  * Previous Topic: IHTMLDocument2::put_onbeforeupdate
  * Next Topic: IHTMLDocument2::put_onerrorupdate

IHTMLDocument2::get_onbeforeupdate

HRESULT get_onbeforeupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onbeforeupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onbeforeupdate

Up Top of Page

IHTMLDocument2::put_onbeforeupdate

HRESULT put_onbeforeupdate(
    VARIANT v
);

Sets the inline script associated with the onbeforeupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onbeforeupdate


Onerrorupdate Property

*
  * Previous Topic: IHTMLDocument2::put_onerrorupdate
  * Next Topic: IHTMLDocument2::toString

IHTMLDocument2::get_onerrorupdate

HRESULT get_onerrorupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onerrorupdate event on the object.

p
Address of a VARIANT structure to store the script.

See also put_onerrorupdate

Up Top of Page

IHTMLDocument2::put_onerrorupdate

HRESULT put_onerrorupdate(
    VARIANT v
);

Sets the inline script associated with the onerrorupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the script to set.

See also get_onerrorupdate


IHTMLDocument2::toString

HRESULT toString(
    BSTR *String
);

Retrieves a string representation of the document object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a string variable that receives the string representation.


IHTMLDTElement

This interface provides access for controlling the text wrapping characteristics for the IHTMLDTElement object.

IHTMLDTElement Methods


NoWrap Property

*
  * Previous Topic: IHTMLDTElement::put_noWrap
  * Next Topic: IHTMLElement

IHTMLDTElement::get_noWrap

HRESULT get_noWrap(
    VARIANT_BOOL *p
);

Determines whether automatic word wrapping is enabled or disabled for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if automatic word-wrapping is enabled for the element, or FALSE otherwise. The default value is FALSE.

See also put_noWrap

Up Top of Page

IHTMLDTElement::put_noWrap

HRESULT put_noWrap(
    VARIANT_BOOL v
);

Enables or disables automatic word wrapping for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that contains the word-wrap setting. If TRUE, the browser performs automatic word wrapping on the element. If FALSE, it doesn't. The default value is FALSE.

See also get_noWrap


IHTMLElement

The element object interface provides the ability to programmatically access the properties and methods that are common to all element objects.

IHTMLElement Methods
setAttribute getAttribute removeAttribute
put_className get_className put_id
get_id get_tagName get_parentElement
get_style put_onhelp get_onhelp
put_onclick get_onclick put_ondblclick
get_ondblclick put_onkeydown get_onkeydown
put_onkeyup get_onkeyup put_onkeypress
get_onkeypress put_onmouseout get_onmouseout
put_onmouseover get_onmouseover put_onmousemove
get_onmousemove put_onmousedown get_onmousedown
put_onmouseup get_onmouseup get_document
put_title get_title put_language
get_language put_onselectstart get_onselectstart
scrollIntoView contains get_sourceIndex
get_recordNumber put_lang get_lang
get_offsetLeft get_offsetTop get_offsetWidth
get_offsetHeight get_offsetParent put_innerHTML
get_innerHTML put_innerText get_innerText
put_outerHTML get_outerHTML put_outerText
get_outerText insertAdjacentHTML insertAdjacentText
get_parentTextEdit get_isTextEdit click
get_filters put_ondragstart get_ondragstart
toString put_onbeforeupdate get_onbeforeupdate
put_onafterupdate get_onafterupdate put_onerrorupdate
get_onerrorupdate put_onrowexit get_onrowexit
put_onrowenter get_onrowenter put_ondatasetchanged
get_ondatasetchanged put_ondataavailable get_ondataavailable
put_ondatasetcomplete get_ondatasetcomplete put_onfilterchange
get_onfilterchange get_children get_all

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLElement::setAttribute

HRESULT setAttribute(
    BSTR strAttributeName,
    VARIANT AttributeValue,
    VARIANT_BOOL fCaseSensitive
);

Sets the value of the given attribute. If the attribute is not already present, the method adds the attribute to the element and sets the value.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to set.
AttributeValue
VARIANT structure containing a string, number, or Boolean value to assign to the attribute.
fCaseSensitive
Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in strAttributeName must match exactly those in the attribute name.

Be careful when spelling attribute names. If fCaseSensitive is TRUE and strAttributeName does not have the same uppercase and lowercase letters as the attribute, this method creates a new attribute.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fCaseSensitive is FALSE, this method assigns values only to the first attribute (the first to be created with this name). All other attributes of the same name are ignored.

See also getAttribute


IHTMLElement::getAttribute

HRESULT getAttribute(
    BSTR strAttributeName,
    LONG fFlags,
    VARIANT *AttributeValue
);

Retrieves the value of the given attribute.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to retrieve.
fFlags
Long integer value that contains the flags for this method.
AttributeValue
Address of a VARIANT structure that receives a string, number, or Boolean value as defined by the attribute. If the attribute is not present, this method returns NULL.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fFlags is FALSE, this method retrieves values only for the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

See also setAttribute


IHTMLElement::removeAttribute

HRESULT removeAttribute(
    BSTR strAttributeName,
    VARIANT_BOOL fCaseSensitive,
    VARIANT_BOOL *pfSuccess
);

Removes the given attribute from the element.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to remove.
fCaseSensitive
Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in strAttributeName must match exactly those in the attribute name.
pfSuccess
Address of a variable that receives TRUE if the function succeeds, or FALSE otherwise.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fCaseSensitive is FALSE, this method removes only the last attribute (the last to be created with this name). All other attributes of the same name are ignored.


ClassName Property

*
  * Previous Topic: IHTMLElement::put_className
  * Next Topic: IHTMLElement::put_id

IHTMLElement::get_className

HRESULT get_className(
    BSTR *p
);

Retrieves the value of the className property of the given object. The property is typically used to associate a particular style rule in a style sheet with the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the value of the property, which can be any valid string.

By default, the value is equal to the string assigned to the className property of the given object, or is an empty string if the property is not explicitly assigned.

See also put_className

Up Top of Page

IHTMLElement::put_className

HRESULT put_className(
    BSTR v
);

Sets the value of the className property of the object. The property is typically used to associate a particular style rule in a style sheet with the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be any valid string.

By default, the property is equal to the string assigned to the className property of the given object, or is an empty string if the attribute is not explicitly assigned.

See also get_className


Id Property

*
  * Previous Topic: IHTMLElement::put_id
  * Next Topic: IHTMLElement::get_tagName

IHTMLElement::get_id

HRESULT get_id(
    BSTR *p
);

Retrieves the value of the id property for the object. The property is an SGML identifier used as the target for hypertext links or for naming particular objects in associated style sheets.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the value of the id property. For scripting, this can be any alphanumeric string that begins with a letter, and can include the underbar (_) character.

The value of the id property should be unique throughout the scope of the current document. If there is more than one object with the same identifier, a collection of those named items is created that can only be referenced by ordinal position.

See also put_id

Up Top of Page

IHTMLElement::put_id

HRESULT put_id(
    BSTR v
);

Sets the value of the id property for the object. The property is an SGML identifier used as the target for hypertext links or for naming particular objects in associated style sheets.

  • Returns S_OK if successful, or an error value otherwise.
v
String containing the ID. For scripting, this can be any alphanumeric string that begins with a letter, and can include the underbar (_) character.

The value of the id property should be unique throughout the scope of the current document. If there is more than one object with the same identifier, a collection of those named items is created that can only be referenced by ordinal position.

See also get_id


IHTMLElement::get_tagName

HRESULT get_tagName(
    BSTR *p
);

Retrieves the name of the current object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name.


IHTMLElement::get_parentElement

HRESULT get_parentElement(
    IHTMLElement **p
);

Retrieves an interface pointer that provides access to the parent object's properties and methods.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the parent object. The variable receives NULL if the current object is the top-most object.

Up Top of Page


IHTMLElement::get_style

HRESULT get_style(
    IHTMLStyle **p
);

Retrieves an inline style sheet for the tag.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLStyle interface for the style sheet.

Up Top of Page


Onhelp Property

*
  * Previous Topic: IHTMLElement::put_onhelp
  * Next Topic: IHTMLElement::put_onclick

IHTMLElement::get_onhelp

HRESULT get_onhelp(
    VARIANT *p);

Retrieves the inline script associated with the onhelp event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onhelp

Up Top of Page

IHTMLElement::put_onhelp

HRESULT put_onhelp(
    VARIANT v
);

Sets the inline script associated with the onhelp event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the inline script.

See also get_onhelp


Onclick Property

*
  * Previous Topic: IHTMLElement::put_onclick
  * Next Topic: IHTMLElement::put_ondblclick

IHTMLElement::get_onclick

HRESULT get_onclick(
    VARIANT *p
);

Retrieves the inline script associated with the onclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onclick

Up Top of Page

IHTMLElement::put_onclick

HRESULT put_onclick(
    VARIANT v
);

Sets the inline script associated with the onclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the inline script.

See also get_onclick


Ondblclick Property

*
  * Previous Topic: IHTMLElement::put_ondblclick
  * Next Topic: IHTMLElement::put_onkeydown

IHTMLElement::get_ondblclick

HRESULT get_ondblclick(
    VARIANT *p
);

Retrieves the inline script associated with the ondblclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondblclick

Up Top of Page

IHTMLElement::put_ondblclick

HRESULT put_ondblclick(
    VARIANT v
);

Sets the inline script associated with the ondblclick event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script.

See also get_ondblclick


Onkeydown Property

*
  * Previous Topic: IHTMLElement::put_onkeydown
  * Next Topic: IHTMLElement::put_onkeyup

IHTMLElement::get_onkeydown

HRESULT get_onkeydown(
    VARIANT *p
);

Retrieves the inline script associated with the onkeydown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeydown

Up Top of Page

IHTMLElement::put_onkeydown

HRESULT put_onkeydown(
    VARIANT v
);

Sets the inline script associated with the onkeydown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onkeydown


Onkeyup Property

*
  * Previous Topic: IHTMLElement::put_onkeyup
  * Next Topic: IHTMLElement::put_onkeypress

IHTMLElement::get_onkeyup

HRESULT get_onkeyup(
    VARIANT *p
);

Retrieves the inline script associated with the onkeyup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeyup

Up Top of Page

IHTMLElement::put_onkeyup

HRESULT put_onkeyup(
    VARIANT v
);

Sets the inline script associated with the onkeyup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onkeyup


Onkeypress Property

*
  * Previous Topic: IHTMLElement::put_onkeypress
  * Next Topic: IHTMLElement::put_onmouseout

IHTMLElement::get_onkeypress

HRESULT get_onkeypress(
    VARIANT *p
);

Retrieves the inline script associated with the onkeypress event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onkeypress

Up Top of Page

IHTMLElement::put_onkeypress

HRESULT put_onkeypress(
    VARIANT v
);

Sets the inline script associated with the onkeypress event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onkeypress


Onmouseout Property

*
  * Previous Topic: IHTMLElement::put_onmouseout
  * Next Topic: IHTMLElement::put_onmouseover

IHTMLElement::get_onmouseout

HRESULT get_onmouseout(
    VARIANT *p
);

Retrieves the inline script associated with the onmouseout event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script in.

See also put_onmouseout

Up Top of Page

IHTMLElement::put_onmouseout

HRESULT put_onmouseout(
    VARIANT v
);

Sets the inline script associated with the onmouseout event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmouseout


Onmouseover Property

*
  * Previous Topic: IHTMLElement::put_onmouseover
  * Next Topic: IHTMLElement::put_onmousemove

IHTMLElement::get_onmouseover

HRESULT get_onmouseover(
    VARIANT *p
);

Retrieves the inline script associated with the onkeyup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmouseover

Up Top of Page

IHTMLElement::put_onmouseover

HRESULT put_onmouseover(
    VARIANT v
);

Sets the inline script associated with the onmouseover event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmouseover


Onmousemove Property

*
  * Previous Topic: IHTMLElement::put_onmousemove
  * Next Topic: IHTMLElement::put_onmousedown

IHTMLElement::get_onmousemove

HRESULT get_onmousemove(
    VARIANT *p
);

Retrieves the inline script associated with the onmousemove event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmousemove

Up Top of Page

IHTMLElement::put_onmousemove

HRESULT put_onmousemove(
    VARIANT v
);

Sets the inline script associated with the onmousemove event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmousemove


Onmousedown Property

*
  * Previous Topic: IHTMLElement::put_onmousedown
  * Next Topic: IHTMLElement::put_onmouseup

IHTMLElement::get_onmousedown

HRESULT get_onmousedown(
    VARIANT *p
);

Retrieves the inline script associated with the onmousedown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmousedown

Up Top of Page

IHTMLElement::put_onmousedown

HRESULT put_onmousedown(
    VARIANT v
);

Sets the inline script associated with the onmousedown event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmousedown


Onmouseup Property

*
  * Previous Topic: IHTMLElement::put_onmouseup
  * Next Topic: IHTMLElement::get_document

IHTMLElement::get_onmouseup

HRESULT get_onmouseup(
    VARIANT *p
);

Retrieves the inline script associated with the onmouseup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onmouseup

Up Top of Page

IHTMLElement::put_onmouseup

HRESULT put_onmouseup(
    VARIANT v
);

Sets the inline script associated with the onmouseup event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onmouseup


IHTMLElement::get_document

HRESULT get_document(
    IDispatch **p
);

Retrieves an interface pointer that provides access to the document object's properties and methods.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IDispatch interface for the document object. The variable receives NULL if the current object is the top-most object.

See also IHTMLDocument2


Title Property

*
  * Previous Topic: IHTMLElement::put_title
  * Next Topic: IHTMLElement::put_language

IHTMLElement::get_title

HRESULT get_title(
    BSTR *p
);

Retrieves the title of the style sheet.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the title. It is FALSE for style sheets that do not specify a title, and that title is not currently selected.

The application of individual style sheets can be turned on and off dynamically. Note that the value of this property is also controlled by whether titled style sheets are applied.

See also put_title

Up Top of Page

IHTMLElement::put_title

HRESULT put_title(
    BSTR v
);

Sets the title of the style sheet.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the title. It is FALSE for style sheets that do not specify a title, and that title is not currently selected.

The application of individual style sheets can be turned on and off dynamically. Note that the value of this property is also controlled by whether titled style sheets are applied.

See also get_title


Language Property

*
  * Previous Topic: IHTMLElement::put_language
  * Next Topic: IHTMLElement::put_onselectstart

IHTMLElement::get_language

HRESULT get_language(
    BSTR *p
);

Retrieves the language that the current script is written in.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the language. Can be one of these values:
JScript | Specifies that the script is written in JScript.
Jscript | Specifies the language as JScript.
vbs | Specifies the language is VBScript.
vbscript | Specifies that the script is written in VBScript.

See also put_language

Up Top of Page

IHTMLElement::put_language

HRESULT put_language(
    BSTR v
);

Sets the language that the current script is written in.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the language. Can be one of the following values;
JScript | Specifies that the script is written in JScript.
Jscript | Specifies the language as JScript.
vbs | Specifies the language is VBScript.
vbscript | Specifies that the script is written in VBScript.

See also get_language


Onselectstart Property

*
  * Previous Topic: IHTMLElement::put_onselectstart
  * Next Topic: IHTMLElement::scrollIntoView

IHTMLElement::get_onselectstart

HRESULT get_onselectstart(
    VARIANT *p
);

Retrieves the inline script associated with the onselect event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onselectstart

Up Top of Page

IHTMLElement::put_onselectstart

HRESULT put_onselectstart(
    VARIANT v
);

Sets the inline script associated with the onselect event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onselectstart


IHTMLElement::scrollIntoView

HRESULT scrollIntoView(
    VARIANT varargStart
);

Scrolls the object into view, aligning it at either the top or bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
varargStart
VARIANT structure containing a Boolean value specifying whether to place the object at the top of the window or at the bottom. If TRUE, the method scrolls the object so that its top is visible at the top of the window. If FALSE, the bottom of the object is visible at the bottom of the window. If no value is given, the object scrolls to the top by default.

Depending on the size of the given object and the current window, this method might not be able to put the item at the very top or very bottom, but will always position the object as close to the requested position as possible.


IHTMLElement::contains

HRESULT contains(
    IHTMLElement *pChild,
    VARIANT_BOOL *pfResult
);

Determines whether the given object is contained within the current object.

  • Returns S_OK if successful, or an error value otherwise.
pChild
Address of the IHTMLElement interface of the element object to check.
pfResult
Address of a Boolean variable that receives TRUE if the pChild element is contained, or FALSE otherwise.


IHTMLElement::get_sourceIndex

HRESULT get_sourceIndex(
    long *p
);

Retrieves the ordinal position of the element in the source order.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the element's ordinal position.


IHTMLElement::get_recordNumber

HRESULT get_recordNumber(
    VARIANT *p
);

Retrieves the ordinal record from the data set that generated the element. Applies to a bound, repeated table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the ordinal record.

This property can be used in conjunction with the ADO recordset available from every data source object through the object's recordset property.


Lang Property

*
  * Previous Topic: IHTMLElement::put_lang
  * Next Topic: IHTMLElement::get_offsetLeft

IHTMLElement::get_lang

HRESULT get_lang(
    BSTR *p
);

Retrieves the current language.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the an ISO standard language abbreviation of the current language.

The parser can use this property to determine how to display language-specific choices for quotations, numbers, and so on.

See also put_lang

Up Top of Page

IHTMLElement::put_lang

HRESULT put_lang(
    BSTR v
);

Sets the language to use.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying an ISO standard language abbreviation.

The parser can use this property to determine how to display language-specific choices for quotations, numbers, and so on.

See also get_lang


IHTMLElement::get_offsetLeft

HRESULT get_offsetLeft(
    long *p
);

Retrieves the calculated left position of the element, relative to the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the left position, in pixels.


IHTMLElement::get_offsetTop

HRESULT get_offsetTop(
    long *p
);

Retrieves the calculated top position of the element, relative to the element's parent.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the top position, in pixels.


IHTMLElement::get_offsetWidth

HRESULT get_offsetWidth(
    long *p
);

Retrieves the width of the element relative to the document's top-left corner.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the width, in pixels.


IHTMLElement::get_offsetHeight

HRESULT get_offsetHeight(
    long *p
);

Retrieves the height of the element, relative to the parent coordinate system.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the height, in pixels.


IHTMLElement::get_offsetParent

HRESULT get_offsetParent(
    IHTMLElement **p
);

Retrieves the container element object that defines the top and left offsets.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface for the container element object.

Up Top of Page


InnerHTML Property

*
  * Previous Topic: IHTMLElement::put_innerHTML
  * Next Topic: IHTMLElement::put_innerText

IHTMLElement::get_innerHTML

HRESULT get_innerHTML(
    BSTR *p
);

Retrieves the HTML between the start and end tags of the current element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the HTML. This can be any valid string containing any combination of text and HTML tags.

When setting this property, the given string completely replaces the existing content of the element. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also put_innerHTML

Up Top of Page

IHTMLElement::put_innerHTML

HRESULT put_innerHTML(
    BSTR v
);

Sets the HTML between the start and end tags of the current element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying any combination of text and HTML tags.

When setting this property, the given string completely replaces the existing content of the element. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also get_innerHTML


InnerText Property

*
  * Previous Topic: IHTMLElement::put_innerText
  * Next Topic: IHTMLElement::put_outerHTML

IHTMLElement::get_innerText

HRESULT get_innerText(
    BSTR *p
);

Retrieves the text between the start and end tags of the current element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the text. It can be any valid string.

When setting this property, the given string completely replaces the existing content of the element.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also put_innerText

Up Top of Page

IHTMLElement::put_innerText

HRESULT put_innerText(
    BSTR v
);

Sets the text between the start and end tags of the current element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text. It can be any valid string.

When setting this property, the given string completely replaces the existing content of the element.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also get_innerText


OuterHTML Property

*
  * Previous Topic: IHTMLElement::put_outerHTML
  * Next Topic: IHTMLElement::put_outerText

IHTMLElement::get_outerHTML

HRESULT get_outerHTML(
    BSTR *p
);

Retrieves the current element object and its content in HTML.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the current element object, including its start and end tags, and the element's content in HTML. It can be any valid string containing any combination of text and HTML tags.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also put_outerHTML

Up Top of Page

IHTMLElement::put_outerHTML

HRESULT put_outerHTML(
    BSTR v
);

Replaces the current element object and its content with the given HTML.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the replacement HTML. It can be any valid string containing any combination of text and HTML tags.

When setting this property, the given string completely replaces the current element, including its start and end tags. If the string contains HTML tags, the string is parsed and formatted as it is placed into the document.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also get_outerHTML


OuterText Property

*
  * Previous Topic: IHTMLElement::put_outerText
  * Next Topic: IHTMLElement::insertAdjacentHTML

IHTMLElement::get_outerText

HRESULT get_outerText(
    BSTR *p
);

Retrieves the outerText property of the current element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the text of the current element object. It can be any valid string.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also put_outerText

Up Top of Page

IHTMLElement::put_outerText

HRESULT put_outerText(
    BSTR v
);

Sets the outerText property of the current element object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the new text for the current element object. It can be any valid string.

You cannot set this property while the document is loading. Wait for the onload event before attempting to set it.

See also get_outerText


IHTMLElement::insertAdjacentHTML

HRESULT insertAdjacentHTML(
    BSTR where,
    BSTR html
);

Inserts the given HTML text into the element object at the given location. If the text contains HTML tags, the method parses and formats the text as it inserts.

  • Returns S_OK if successful, or an error value otherwise.
where
String specifying where to insert the HTML text. Can be one of these strings:
BeforeBegin | Inserts the text immediately before the element.
AfterBegin | Inserts the text after the start of the element but before all other content in the element.
BeforeEnd | Inserts the text immediately before the end of the element but after all other content in the element.
AfterEnd | Inserts the text immediately after the end of the element.
html
String specifying the HTML text to insert.

You cannot insert text while the document is loading. Wait for the onload event before attempting to call this method.


IHTMLElement::insertAdjacentText

HRESULT insertAdjacentText(
    BSTR where,
    BSTR text
);

Inserts the given text into the element object at the given place. The method inserts the text as plain text.

  • Returns S_OK if successful, or an error value otherwise.
where
String specifying where to insert the text. Can be one of these strings:
BeforeBegin | Inserts the text immediately before the element.
AfterBegin | Inserts the text after the start of the element but before all other content in the element.
BeforeEnd | Inserts the text immediately before the end of the element but after all other content in the element.
AfterEnd | Inserts the text immediately after the end of the element.
text
String specifying the text to insert.

You cannot insert text while the document is loading. Wait for the onload event before attempting to call this method.


IHTMLElement::get_parentTextEdit

HRESULT get_parentTextEdit(
    IHTMLElement **p
);

Retrieves an object that can be used to create a text range that contains the original object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface for the new parent object. This parameter receives NULL if no suitable parent object exists.

Up Top of Page


IHTMLElement::get_isTextEdit

HRESULT get_isTextEdit(
    VARIANT_BOOL *p
);

Retrieves whether a text range object can be created using the given object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if a text range can be created, and FALSE otherwise.

Only the BODY, BUTTON, and TEXTAREA objects and an INPUT object having text input type can be used to create a text range object.


IHTMLElement::click

HRESULT click(void);

Simulates a click by causing the onclick event to fire.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLElement::get_filters

HRESULT get_filters(
    IHTMLFiltersCollection **p
);

Retrieves a collection of filter objects for an element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLFiltersCollection interface of the collection.

Up Top of Page


Ondragstart Property

*
  * Previous Topic: IHTMLElement::put_ondragstart
  * Next Topic: IHTMLElement::toString

IHTMLElement::get_ondragstart

HRESULT get_ondragstart(
    VARIANT *p
);

Retrieves the inline script associated with the ondragstart event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondragstart

Up Top of Page

IHTMLElement::put_ondragstart

HRESULT put_ondragstart(
    VARIANT v
);

Sets the inline script associated with the ondragstart event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_ondragstart


IHTMLElement::toString

HRESULT toString(
    BSTR *String
);

Retrieves a string representation of the element object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a string variable that receives the string representation.


Onbeforeupdate Property

*
  * Previous Topic: IHTMLElement::put_onbeforeupdate
  * Next Topic: IHTMLElement::put_onafterupdate

IHTMLElement::get_onbeforeupdate

HRESULT get_onbeforeupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onbeforeupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onbeforeupdate

Up Top of Page

IHTMLElement::put_onbeforeupdate

HRESULT put_onbeforeupdate(
    VARIANT v
);

Sets the inline script associated with the onbeforeupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onbeforeupdate


Onafterupdate Property

*
  * Previous Topic: IHTMLElement::put_onafterupdate
  * Next Topic: IHTMLElement::put_onerrorupdate

IHTMLElement::get_onafterupdate

HRESULT get_onafterupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onafterupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onafterupdate

Up Top of Page

IHTMLElement::put_onafterupdate

HRESULT put_onafterupdate(
    VARIANT v
);

Sets the inline script associated with the onafterupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onafterupdate


Onerrorupdate Property

*
  * Previous Topic: IHTMLElement::put_onerrorupdate
  * Next Topic: IHTMLElement::put_onrowexit

IHTMLElement::get_onerrorupdate

HRESULT get_onerrorupdate(
    VARIANT *p
);

Retrieves the inline script associated with the onerrorupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onerrorupdate

Up Top of Page

IHTMLElement::put_onerrorupdate

HRESULT put_onerrorupdate(
    VARIANT v
);

Sets the inline script associated with the onerrorupdate event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onerrorupdate


Onrowexit Property

*
  * Previous Topic: IHTMLElement::put_onrowexit
  * Next Topic: IHTMLElement::put_onrowenter

IHTMLElement::get_onrowexit

HRESULT get_onrowexit(
    VARIANT *p
);

Retrieves the inline script associated with the onrowexit event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onrowexit

Up Top of Page

IHTMLElement::put_onrowexit

HRESULT put_onrowexit(
    VARIANT v
);

Sets the inline script associated with the onrowexit event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onrowexit


Onrowenter Property

*
  * Previous Topic: IHTMLElement::put_onrowenter
  * Next Topic: IHTMLElement::put_ondatasetchanged

IHTMLElement::get_onrowenter

HRESULT get_onrowenter(
    VARIANT *p
);

Retrieves the inline script associated with the onrowenter event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onrowenter

Up Top of Page

IHTMLElement::put_onrowenter

HRESULT put_onrowenter(
    VARIANT v
);

Sets the inline script associated with the onrowenter event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onrowenter


Ondatasetchanged Property

*
  * Previous Topic: IHTMLElement::put_ondatasetchanged
  * Next Topic: IHTMLElement::put_ondataavailable

IHTMLElement::get_ondatasetchanged

HRESULT get_ondatasetchanged(
    VARIANT *p
);

Retrieves the inline script associated with the ondatasetchanged event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondatasetchanged

Up Top of Page

IHTMLElement::put_ondatasetchanged

HRESULT put_ondatasetchanged(
    VARIANT v
);

Sets the inline script associated with the ondatasetchanged event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_ondatasetchanged


Ondataavailable Property

*
  * Previous Topic: IHTMLElement::put_ondataavailable
  * Next Topic: IHTMLElement::put_ondatasetcomplete

IHTMLElement::get_ondataavailable

HRESULT get_ondataavailable(
    VARIANT *p
);

Retrieves the inline script associated with the ondataavailable event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondataavailable

Up Top of Page

IHTMLElement::put_ondataavailable

HRESULT put_ondataavailable(
    VARIANT v
);

Sets the inline script associated with the ondataavailable event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_ondataavailable


Ondatasetcomplete Property

*
  * Previous Topic: IHTMLElement::put_ondatasetcomplete
  * Next Topic: IHTMLElement::put_onfilterchange

IHTMLElement::get_ondatasetcomplete

HRESULT get_ondatasetcomplete(
    VARIANT *p
);

Retrieves the inline script associated with the ondatasetcomplete event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_ondatasetcomplete

Up Top of Page

IHTMLElement::put_ondatasetcomplete

HRESULT put_ondatasetcomplete(
    VARIANT v
);

Sets the inline script associated with the ondatasetcomplete event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_ondatasetcomplete


Onfilterchange Property

*
  * Previous Topic: IHTMLElement::put_onfilterchange
  * Next Topic: IHTMLElement::get_children

IHTMLElement::get_onfilterchange

HRESULT get_onfilterchange(
    VARIANT *p
);

Retrieves the inline script associated with the onfilterchange event on the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure to store the script.

See also put_onfilterchange

Up Top of Page

IHTMLElement::put_onfilterchange

HRESULT put_onfilterchange(
    VARIANT v
);

Sets the inline script associated with the onfilterchange event on the object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to set.

See also get_onfilterchange


IHTMLElement::get_children

HRESULT get_children(
    IDispatch **p
);

Retrieves the collection that contains all the immediate children of this object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IDispatch interface of the collection.


IHTMLElement::get_all

HRESULT get_all(
    IDispatch **p
);

Retrieves the collection of all the objects in the HTML that are within the scope of this object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IDispatch interface of the collection.


IHTMLElementCollection

This interface provides access to a collection of element objects.

This collection is indexed first by name, then by id. If duplicate names are found, a collection of those named items is returned. Collections of duplicate names must subsequently be referenced by ordinal position.

A zero-based collection, in source order, of all elements in a given form. This collection can contain any combination of INPUT, SELECT, and TEXTAREA elements.

IHTMLElementCollection Methods


IHTMLElementCollection::toString

HRESULT toString(
    BSTR *String
);

Retrieves a string representation of the element collection object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a string variable that receives the string representation.


Length Property

*
  * Previous Topic: IHTMLElementCollection::put_length
  * Next Topic: IHTMLElementCollection::get__newEnum

IHTMLElementCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of objects in the collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the number of elements.

See also put_length

Up Top of Page

IHTMLElementCollection::put_length

HRESULT put_length(
    long v
);

Sets the size, in objects, of the collection.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the number of elements.

See also get_length


IHTMLElementCollection::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Retrieves an enumerator for the collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IUnknown interface of the enumerator.


IHTMLElementCollection::item

HRESULT item(
    VARIANT name,
    VARIANT index,
    IDispatch **pdisp
);

Retrieves an object or a collection from the given collection. The name determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
name
VARIANT structure containing a string or value specifying the object or collection to retrieve. If this parameter is a number, the method returns the object in the collection at the given position, where the first object has value 0, the second has 1, and so on. If this parameter contains a string, the method returns a collection of objects, where the value of the name or id property for each object is equal to the string.
index
VARIANT structure containing a value specifying the position of an object to retrieve. This parameter is used when name is a string. The method uses the string to construct a collection of all objects that have a name or id equal to the string, then retrieves from this collection the element at the position specified by index.
pdisp
Address of the IDispatch interface of the collection or object.


IHTMLElementCollection::tags

HRESULT tags(
    VARIANT tagName,
    IDispatch **pdisp
);

Retrieves a collection of all objects in the given collection that have the given HTML tag name.

  • Returns S_OK if successful, or an error value otherwise.
tagName
VARIANT structure containing a string specifying the HTML tag name of the objects to retrieve.
pdisp
Address of the IDispatch interface of the collection.

This method returns an empty collection if no objects having the given name are found. Use the length property on the collection to determine the number of objects it contains.


IHTMLEmbedElement

This interface provides access to the EMBED object.

IHTMLEmbedElement Methods
put_hidden get_hidden get_palette
get_pluginspage put_src get_src
put_units get_units put_name
get_name put_width get_width
put_height get_height

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Hidden Property

*
  * Previous Topic: IHTMLEmbedElement::put_hidden
  * Next Topic: IHTMLEmbedElement::get_palette

IHTMLEmbedElement::get_hidden

HRESULT get_hidden(
    BSTR *p
);

Determines whether the embedded element is currently hidden or shown.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the status.

See also put_hidden

Up Top of Page

IHTMLEmbedElement::put_hidden

HRESULT put_hidden(
    BSTR v
);

Hides or shows the embedded element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying if the embedded element is hidden. TRUE hides the embedded element, and FALSE shows it.

See also get_hidden


IHTMLEmbedElement::get_palette

HRESULT get_palette(
    BSTR *p
);

Retrieves the palette used for the embedded document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the palette.


IHTMLEmbedElement::get_pluginspage

HRESULT get_pluginspage(
    BSTR *p
);

Retrieves the plug-ins supporting this embedded document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the plug-ins.


Src Property

*
  * Previous Topic: IHTMLEmbedElement::put_src
  * Next Topic: IHTMLEmbedElement::put_units

IHTMLEmbedElement::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves the URL of the embedded document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL.

See also put_src

Up Top of Page

IHTMLEmbedElement::put_src

HRESULT put_src(
    BSTR v
);

Sets the URL of the embedded document.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_src


Units Property

*
  * Previous Topic: IHTMLEmbedElement::put_units
  * Next Topic: IHTMLEmbedElement::put_name

IHTMLEmbedElement::get_units

HRESULT get_units(
    BSTR *p
);

Retrieves the current units used to caculate the height and width.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that contains the unit type. Can be either "pixels" or "ems".

See also put_units

Up Top of Page

IHTMLEmbedElement::put_units

HRESULT put_units(
    BSTR v
);

Sets the units that the height and width are calculated in.

  • Returns S_OK if successful, or an error value otherwise.
v
String value that contains the units. Can be either "pixels" or "ems".

See also get_units


Name Property

*
  * Previous Topic: IHTMLEmbedElement::put_name
  * Next Topic: IHTMLEmbedElement::put_width

IHTMLEmbedElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the window or frame name, or one of these values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the top-most level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also put_name

Up Top of Page

IHTMLEmbedElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name. It can be the name of a window or frame, or one of the following values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the top-most level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also get_name


Width Property

*
  * Previous Topic: IHTMLEmbedElement::put_width
  * Next Topic: IHTMLEmbedElement::put_height

IHTMLEmbedElement::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLEmbedElement::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains a value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Height Property

*
  * Previous Topic: IHTMLEmbedElement::put_height
  * Next Topic: IHTMLEventObj

IHTMLEmbedElement::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLEmbedElement::put_height

HRESULT put_height(
    VARIANT v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


IHTMLEventObj

This interface provides access to the event processes, such as the element in which the event occurred, the state of the keyboard keys, the location of the mouse, and the state of the mouse buttons.

The event object is only available during an event, that is, you can use it in event handlers but not in other code. You retrieve the event object by calling the IHTMLWindow2::get_event method.

Although all event properties are available to all event objects, some properties might not have meaningful values during some events. For example, the values retrieved by the get_fromElement and the get_toElement methods are meaningful only when processing the onmouseover and onmouseout events.

IHTMLEventObj Methods
get_srcElement get_altKey get_ctrlKey
get_shiftKey put_returnValue get_returnValue
put_cancelBubble get_cancelBubble get_fromElement
get_toElement put_keyCode get_keyCode
get_button get_type get_qualifier
get_reason get_x get_y
get_clientX get_clientY get_offsetX
get_offsetY get_screenX get_screenY
get_srcFilter


IHTMLEventObj::get_srcElement

HRESULT get_srcElement(
    IHTMLElement **p
);

Retrieves an interface pointer for the object in which the event occurred.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the object.

Up Top of Page


IHTMLEventObj::get_altKey

HRESULT get_altKey(
    VARIANT_BOOL *p
);

Retrieves the state of the ALT key.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolen variable that receives TRUE if the key is down, or FALSE otherwise.


IHTMLEventObj::get_ctrlKey

HRESULT get_ctrlKey(
    VARIANT_BOOL *p
);

Retrieves the state of the CTRL key.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolen variable that receives TRUE if the key is down, or FALSE otherwise.


IHTMLEventObj::get_shiftKey

HRESULT get_shiftKey(
    VARIANT_BOOL *p
);

Retrieves the state of the SHIFT key.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if the key is down, or FALSE otherwise.


ReturnValue Property

*
  * Previous Topic: IHTMLEventObj::put_returnValue
  * Next Topic: IHTMLEventObj::put_cancelBubble

IHTMLEventObj::get_returnValue

HRESULT get_returnValue(
    VARIANT *p
);

Retrieves the return value of the event or dialog.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the return value. It can be either TRUE or FALSE.

For event handler functions, the value of this property takes precedence over values returned by the function, such as through a return statement.

See also put_returnValue

Up Top of Page

IHTMLEventObj::put_returnValue

HRESULT put_returnValue(
    VARIANT v
);

Sets the return value of the event.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the return value. It can be either TRUE of FALSE.

For event handler functions, the value of this property takes precedence over values returned by the function, such as through a return statement.

See also get_returnValue


CancelBubble Property

*
  * Previous Topic: IHTMLEventObj::put_cancelBubble
  * Next Topic: IHTMLEventObj::get_fromElement

IHTMLEventObj::get_cancelBubble

HRESULT get_cancelBubble(
    VARIANT_BOOL *p
);

Retrieves whether the current event should bubble up the hierarchy of event handlers.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean variable that receives TRUE if bubbling has been canceled, or FALSE otherwise.

Using this property to cancel bubbling for an event does not affect subsequent events.

See also put_cancelBubble

Up Top of Page

IHTMLEventObj::put_cancelBubble

HRESULT put_cancelBubble(
    VARIANT_BOOL v
);

Sets whether the current event should bubble up the hierarchy of event handlers.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that contains the cancel-bubble flag. TRUE cancels bubbling for this event, preventing the next event handler in the hierarchy from receiving the event. FALSE enables bubbling; this is the default value.

Using this property to cancel bubbling for an event does not affect subsequent events.

See also get_cancelBubble


IHTMLEventObj::get_fromElement

HRESULT get_fromElement(
    IHTMLElement **p
);

Retrieves the object being moved from for the onmouseover and onmouseout events.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the object.

Up Top of Page


IHTMLEventObj::get_toElement

HRESULT get_toElement(
    IHTMLElement **p
);

Retrieves the object being moved to for the onmouseover and onmouseout events.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElement interface of the object.

Up Top of Page


KeyCode Property

*
  * Previous Topic: IHTMLEventObj::put_keyCode
  * Next Topic: IHTMLEventObj::get_button

IHTMLEventObj::get_keyCode

HRESULT get_keyCode(
    long *p
);

Retrieves the Unicode key code associated with the key that caused the event.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the Unicode key code. It can be any key code in the range 1 to 255. It is zero if no key caused the event.

If you set this property, the given key code replaces the existing value. Subsequent event handlers receive the new value rather than the original.

This property is intended to be used with the onkeydown, onkeyup, and onkeypress events.

See also put_keyCode

Up Top of Page

IHTMLEventObj::put_keyCode

HRESULT put_keyCode(
    long v
);

Sets the Unicode key code associated with the key that caused the event.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying any Unicode key code in the range 1 to 255. It is zero if no key caused the event.

If you set this property, the given key code replaces the existing value. Subsequent event handlers receive the new value rather than the original.

This property is intended to be used with the onkeydown, onkeyup, and onkeypress events.

See also get_keyCode


IHTMLEventObj::get_button

HRESULT get_button(
    long *p
);

Retrieves which mouse button, if any, is pressed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives one of these values:
0 | No button.
1 | Left button is pressed.
2 | Right button is pressed.
4 | Middle button is pressed.

This property is intended to be used with the onmousedown, onmouseup, and onmousemove events. For other events, it typically is 0 regardless of the state of the mouse buttons.


IHTMLEventObj::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the event name as a string.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the event name.

Events are returned without the "on" prefix. For example, the "onclick" event is returned as "click".


IHTMLEventObj::get_qualifier

HRESULT get_qualifier(
    BSTR *p
);

Specifies the event qualifier.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the event qualifier. In Internet Explorer 4.0, it is always set to "".


IHTMLEventObj::get_reason

HRESULT get_reason(
    long *p
);

Retrieves the disposition of data transfer for a data source object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives an integer value specifying the reason for completion. Can be one of these values:
0 | Data transmitted successfully.
1 | Data transfer aborted.
2 | Data transfer in error.


IHTMLEventObj::get_x

HRESULT get_x(
    long *p
);

Retrieves the position of the mouse hit relative to the object in the parent heirarchy that is positioned using the CSS positioning attribute. If no object in the heirarchy has been positioned, the BODY is the default.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the position of the mouse hit.

If the mouse is outside the window when the event is called, this property returns -1.

See also get_y


IHTMLEventObj::get_y

HRESULT get_y(
    long *p
);

Retrieves the position of the mouse hit relative to the object in the parent heirarchy that is positioned using the CSS positioning attribute. If no object in the heirarchy has been positioned, the BODY is the default.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the position of the mouse hit.

If the mouse is outside the window at the time the event fires, this property returns -1.

See also get_x


IHTMLEventObj::get_clientX

HRESULT get_clientX(
    long *p
);

Retrieves the horizontal position of the mouse hit relative to the top of the client area of the window. This does not include window decorations or scroll bars.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the position.

See also get_clientY


IHTMLEventObj::get_clientY

HRESULT get_clientY(
    long *p
);

Retrieves the vertical position of the mouse hit relative to side of the client area of the window. This does not include window decorations or scroll bars.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the position.

See also get_clientX


IHTMLEventObj::get_offsetX

HRESULT get_offsetX(
    long *p
);

Returns container-relative positions. These match the offsetLeft and offsetTop properties of the object. Use offsetParent to find the container object that defines this coordinate system.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the positions.

See also get_offsetY


IHTMLEventObj::get_offsetY

HRESULT get_offsetY(
    long *p
);

Returns container-relative positions. These match the offsetLeft and offsetTop properties of the object. Use offsetParent to find the container object that defines this coordinate system.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the positions.

See also get_offsetX


IHTMLEventObj::get_screenX

HRESULT get_screenX(
    long *p
);

Returns coordinates relative to the physical screen size.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the screen coordinates.

See also get_screenY


IHTMLEventObj::get_screenY

HRESULT get_screenY(
    long *p
);

Returns coordinates relative to the physical screen size.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the screen coordinates.

See also get_screenX


IHTMLEventObj::get_srcFilter

HRESULT get_srcFilter(
    BSTR *p
);

Specifies the filter object that caused the onfilterchange event.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the filter object.


IHTMLFieldSetElement

This interface draws a box around the text and other elements it contains. This element is useful for grouping elements in a form and for distinctively marking text in a document.

IHTMLFieldSetElement Methods


Align Property

*
  * Previous Topic: IHTMLFieldSetElement::put_align
  * Next Topic: IHTMLFiltersCollection

IHTMLFieldSetElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLFieldSetElement::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. This can be one of the following values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text, minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


IHTMLFiltersCollection

This interface provides the ability to access the collection of filters for the object. This is a zero-based collection of filters that is exposed from the document object. The methods for this interface allow for obtaining the number of filters in the collection, enumerating over the collection, or requesting a single filter from the collection.

IHTMLFiltersCollection Methods


IHTMLFiltersCollection::get_length

HRESULT get_length (
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the length.


IHTMLFiltersCollection::get__newEnum

HRESULT get__newEnum (
    IUnknown **p
);

Retrieves an OLE enumeration interface. This will enumerate over the filters in this collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to an IUnknown interface.


IHTMLFiltersCollection::item

HRESULT item (
    VARIANT *pvarIndex,
    VARIANT *pvarResult
);

Retrieves a collection of filters, or a single item from the collection. The pvarIndex parameter determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
pvarIndex
Address of a VARIANT structure specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or ID property for each element is equal to the string.
pvarResult
Address of a VARIANT structure that receives an element object or a collection of element objects if successful, or NULL otherwise.


IHTMLFontElement

This interface specifies a new font face, size, and color to be used for rendering the enclosed text.

IHTMLFontElement Methods


Color Property

*
  * Previous Topic: IHTMLFontElement::put_color
  * Next Topic: IHTMLFontElement::put_face

IHTMLFontElement::get_color

HRESULT get_color(
    VARIANT *p
);

Retrieves the color used by the font.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. It can be one of the color names or values given in the Color Table reference documentation.

See also put_color

Up Top of Page

IHTMLFontElement::put_color

HRESULT put_color(
    VARIANT v
);

Sets the color to be used by the font.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also get_color


Face Property

*
  * Previous Topic: IHTMLFontElement::put_face
  * Next Topic: IHTMLFontElement::put_size

IHTMLFontElement::get_face

HRESULT get_face(
    BSTR *p
);

Retrieves the current font's typeface.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the font's typeface.

See also put_face

Up Top of Page

IHTMLFontElement::put_face

HRESULT put_face(
    BSTR v
);

Sets the typeface to use for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font.

See also get_face


Size Property

*
  * Previous Topic: IHTMLFontElement::put_size
  * Next Topic: IHTMLFontNamesCollection

IHTMLFontElement::get_size

HRESULT get_size(
    VARIANT *p
);

Retrieves the current font size for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the font size. This property is an integer value in the range 1 through 7, with 7 representing the largest font.

See also put_size

Up Top of Page

IHTMLFontElement::put_size

HRESULT put_size(
    VARIANT v
);

Sets the font size for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Integer value specifying the font size. This property takes an integer value in the range 1 through 7, with 7 representing the largest font.

See also get_size


IHTMLFontNamesCollection

This interface is for the collection of all the font names supported by the system, created by using the system font enumeration calls. The collection is maintained by the IHTMLOptionsHolder object, which returns this interface for collection access.

IHTMLFontNamesCollection Methods


IHTMLFontNamesCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of elements.


IHTMLFontNamesCollection::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Returns an OLE enumeration interface. This will enumerate over the names in this collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the IUnknown interface pointer.


IHTMLFontNamesCollection::item

HRESULT item(
    long index,
    BSTR *pBstr
);

Retrieves an element or a collection from the collection. The index determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
index
Address of a variable specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
pBstr
Address of a variable that receives an element object or a collection of element objects if successful, or null otherwise.


IHTMLFontSizesCollection

This interface is for the collection of all the font sizes available for a font on the system. The collection of fonts and sizes that this is built from is maintained in the IHTMLOptionsHolder object. This interface is returned when that collection is accessed.

IHTMLFontSizesCollection Methods


IHTMLFontSizesCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the number of font sizes in the collection.

This property is read-write on the areas and the options collection for image maps and select boxes, respectively. This allows a developer to shrink the collection.


IHTMLFontSizesCollection::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Returns an OLE enumeration interface. This will enumerate over the sizes in this collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the IUnknown interface pointer.


IHTMLFontSizesCollection::get_forFont

HRESULT get_forFont(
    BSTR *p
);

Returns a string of the font name that this collection of font sizes applies to.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the font name.


IHTMLFontSizesCollection::item

HRESULT item(
    long index,
    long *plSize
);

Retrieves a single element or a collection from the collection. The index parameter determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
index
Address of a variable specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
plSize
Address of a variable that receives an element object or a collection of element objects if successful, or null otherwise.


IHTMLFormElement

This interface specifies that the contained controls take part in a form.

When programming the form, all control-like elements are added to the form as named items. In addition, these items are exposed through the IHTMLFormElement::item method.

When the focus is on a control in a form, pressing the ESC key once causes the value of the control to revert back to the last value, and pressing the ESC key again resets the form.

If one and only one text box is on a form, pressing ENTER fires the onsubmit event. If the form has a submit button, the button appears with a dark border, indicating that pressing ENTER submits the form.

This element is a block element.

IHTMLFormElement Methods
put_action get_action put_dir
get_dir put_encoding get_encoding
put_method get_method get_elements
put_target get_target put_name
get_name put_onsubmit get_onsubmit
put_onreset get_onreset submit
reset put_length get_length
get__newEnum item tags

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Action Property

*
  * Previous Topic: IHTMLFormElement::put_action
  * Next Topic: IHTMLFormElement::put_dir

IHTMLFormElement::get_action

HRESULT get_action(
    BSTR *p
);

Retrieves the address to be used to carry out the action of the form. If none is specified, the base URL of the document is used.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the address.

The way the data is submitted depends upon the value of the method and encoding properties.

See also put_action

Up Top of Page

IHTMLFormElement::put_action

HRESULT put_action(
    BSTR v
);

Sets the address to be used to carry out the action of the form. If none is specified, the base URL of the document is used.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the address.

The way the data is submitted depends upon the value of the method and encoding properties.

See also get_action


Dir Property

*
  * Previous Topic: IHTMLFormElement::put_dir
  * Next Topic: IHTMLFormElement::put_encoding

IHTMLFormElement::get_dir

HRESULT get_dir(
    BSTR *p
);

Retrieves the direction value for the form. The direction represents the direction of the text on the form.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of the following strings:
"leftToRight" | The direction is from left to right.
"rightToLeft" | The direction is from right to left.

See also put_dir

Up Top of Page

IHTMLFormElement::put_dir

HRESULT put_dir(
    BSTR v
);

Sets the form's direction property. The direction represents the direction of the text on the form.

  • Returns S_OK if successful, or an error value otherwise.
v
String variable that contains one of the following strings:
"leftToRight" | The direction is from left to right.
"rightToLeft" | The direction is from right to left.

See also get_dir


Encoding Property

*
  * Previous Topic: IHTMLFormElement::put_encoding
  * Next Topic: IHTMLFormElement::put_method

IHTMLFormElement::get_encoding

HRESULT get_encoding(
    BSTR *p
);

Retrieves the mime-encoding for the form. This property corresponds to the HTML ENCTYPE= attribute.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the mime-encoding. The default is "application/x-www-form-urlencoded". Internet Explorer 4.0 also recognizes "multipart/form-data", which with a POST method is required to submit a file upload to the server

See also put_encoding

Up Top of Page

IHTMLFormElement::put_encoding

HRESULT put_encoding(
    BSTR v
);

Sets the mime encoding for the form. This property corresponds to the HTML ENCTYPE= attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the mime encoding. The default is "application/x-www-form-urlencoded". Internet Explorer 4.0 also recognizes "multipart/form-data", which with a POST method is required to submit a file upload to the server

See also get_encoding


Method Property

*
  * Previous Topic: IHTMLFormElement::put_method
  * Next Topic: IHTMLFormElement::get_elements

IHTMLFormElement::get_method

HRESULT get_method(
    BSTR *p
);

Retrieves how the form data should be sent to the server, either as GET or POST.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that reeives the send method. Can be one of these values:
get | Append the arguments to the action URL and open it as if it were an anchor.
post | Send the data through an HTTP POST transaction.

See also put_method

Up Top of Page

IHTMLFormElement::put_method

HRESULT put_method(
    BSTR v
);

Specifies how the form data should be sent to the server, either as GET or POST.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying how to send the data. Can be one of these values:
get | Append the arguments to the action URL and open it as if it were an anchor.
post | Send the data through an HTTP POST transaction.

See also get_method


IHTMLFormElement::get_elements

HRESULT get_elements(
    IDispatch **p
);

Retrieves an interface pointer to a zero-based collection of the elements in the form. The pointer provides access to the properties and methods of the elements. The order of the elements in the collection is determined by the HTML source.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.


Target Property

*
  * Previous Topic: IHTMLFormElement::put_target
  * Next Topic: IHTMLFormElement::put_name

IHTMLFormElement::get_target

HRESULT get_target(
    BSTR *p
);

Retrieves the window or frame to target the contents at.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name of the target window or frame, or one of the following special values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

See also put_target

Up Top of Page

IHTMLFormElement::put_target

HRESULT put_target(
    BSTR v
);

Sets the window or frame to target the contents at.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name of the target window or frame. Can also be one of the following special values:
_blank | Specifies to load the link into a new blank window. This window is not named.
_parent | Specifies to load the link into the immediate parent of the document the link is in.
_self | Specifies to load the link into the same window the link was clicked in.
_top | Specifies to load the link into the full body of the window.

If there is no frame or window that matches the specified target, a new window is opened for the link.

The default value for the target depends upon the URL and site. If the user does not leave the site, the default is _self, but if the user exits to a new site, the default is _top.

See also get_target


Name Property

*
  * Previous Topic: IHTMLFormElement::put_name
  * Next Topic: IHTMLFormElement::put_onsubmit

IHTMLFormElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLFormElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Onsubmit Property

*
  * Previous Topic: IHTMLFormElement::put_onsubmit
  * Next Topic: IHTMLFormElement::put_onreset

IHTMLFormElement::get_onsubmit

HRESULT get_onsubmit(
    VARIANT *p
);

Retrieves the inline script associated with the onsubmit event for a FORM element. A submit event occurs when a user submits a form (clicks a Submit button).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onsubmit

Up Top of Page

IHTMLFormElement::put_onsubmit

HRESULT put_onsubmit(
    VARIANT v
);

Sets the inline script associated with the onsubmit event for a FORM element. A submit event occurs when a user submits a form (clicks a Submit button).

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onsubmit


Onreset Property

*
  * Previous Topic: IHTMLFormElement::put_onreset
  * Next Topic: IHTMLFormElement::submit

IHTMLFormElement::get_onreset

HRESULT get_onreset(
    VARIANT *p
);

Retrieves the inline script associated with the onreset event for a FORM element. A reset event occurs when a user resets a form (clicks a Reset button).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onreset

Up Top of Page

IHTMLFormElement::put_onreset

HRESULT put_onreset(
    VARIANT v
);

Sets the inline script associated with the onreset event for a FORM element. A reset event occurs when a user resets a form (clicks a Reset button).

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onreset


IHTMLFormElement::submit

HRESULT submit(
    void
);

Submits the form and fires the onsubmit event.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLFormElement::reset

HRESULT reset(
    void
);

Simulates a mouse click on a reset button for the calling form.

  • Returns S_OK if successful, or an error value otherwise.


Length Property

*
  * Previous Topic: IHTMLFormElement::put_length
  * Next Topic: IHTMLFormElement::get__newEnum

IHTMLFormElement::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the length.

This property is read-write on the areas and the options collection for image maps and select boxes, respectively. This allows a developer to shrink the collection.

See also put_length

Up Top of Page

IHTMLFormElement::put_length

HRESULT put_length(
    long v
);

Sets the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the length.

This property is read-write on the areas and the options collection for image maps and select boxes, respectively. This allows a developer to shrink the collection.

See also get_length


IHTMLFormElement::get__newEnum

HRESULT get__newEnum(
     IUnknown **p
);

Retrieves an enumerator interface which can be used to iterate through the form element collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the IUnknown interface pointer.


IHTMLFormElement::item

HRESULT item(
    VARIANT name,
    VARIANT index,
    IDispatch **pdisp
);

Retrieves an element or a collection from the given collection. The index determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
name
Number or string specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter contains a string, the method returns a collection of elements, where the value of the NAME or ID= property for each element is equal to the string.
index
Number specifying the position of an element to retrieve. This parameter is used when name is a string. The method uses the string to construct a collection of all elements that have a NAME or ID= equal to the string, then retrieves from this collection the element at the position specified by index.
pdisp
Address of a variable that receives an interface pointer to the element object.


IHTMLFormElement::tags

HRESULT tags(
    VARIANT tagName,
    IDispatch **pdisp
);

Retrieves a collection of all elements in the given collection that have the given HTML tag name.

  • Returns S_OK if successful, or an error value otherwise.
tagName
String specifying the name of a tag.
pdisp
Address of a variable that receives an interface pointer to the element collection.

This method returns an empty collection if no elements having the given name are found. Use the length property on the collection to determine the number of elements it contains.


IHTMLFrameBase

This interface provides access to properties and methods that are common to FRAME and IFRAME elements.

IHTMLFrameBase Methods
put_src get_src put_name
get_name put_border get_border
put_frameBorder get_frameBorder put_frameSpacing
get_frameSpacing put_marginWidth get_marginWidth
put_marginHeight get_marginHeight put_noResize
get_noResize put_scrolling get_scrolling

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Src Property

*
  * Previous Topic: IHTMLFrameBase::put_src
  * Next Topic: IHTMLFrameBase::put_name

IHTMLFrameBase::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves the URL of the associated file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_src

Up Top of Page

IHTMLFrameBase::put_src

HRESULT put_src(
    BSTR v
);

Sets the URL of the associated file.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_src


Name Property

*
  * Previous Topic: IHTMLFrameBase::put_name
  * Next Topic: IHTMLFrameBase::put_border

IHTMLFrameBase::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the window or frame name, or one of these values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also put_name

Up Top of Page

IHTMLFrameBase::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name. It can be the name of a window or frame, or one of the following values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also get_name


Border Property

*
  * Previous Topic: IHTMLFrameBase::put_border
  * Next Topic: IHTMLFrameBase::put_frameBorder

IHTMLFrameBase::get_border

HRESULT get_border(
    VARIANT *p
);

Retrieves the thickness of the border.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the thickness.

Setting a border to zero or omitting the attribute causes no border to be displayed. Supplying the border attribute without a value defaults to a single border.

See also put_border

Up Top of Page

IHTMLFrameBase::put_border

HRESULT put_border(
    VARIANT v
);

Specifies the thickness of the border.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the thickness.

Setting a border to zero or omitting the attribute causes no border to be displayed. Supplying the border attribute without a value defaults to a single border.

See also get_border


FrameBorder Property

*
  * Previous Topic: IHTMLFrameBase::put_frameBorder
  * Next Topic: IHTMLFrameBase::put_frameSpacing

IHTMLFrameBase::get_frameBorder

HRESULT get_frameBorder(
    BSTR *p
);

Determines whether a border is currently being displayed for the frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives "Yes" if the frame has an inset border, or "No" if it has no border.

See also put_frameBorder

Up Top of Page

IHTMLFrameBase::put_frameBorder

HRESULT put_frameBorder(
    BSTR v
);

Specifies whether to display a border for the frame.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether to display a border. If this parameter is "Yes", the frame will have an inset border. If it is "No", the frame will have no border. Any other value turns on the borders.

See also get_frameBorder


FrameSpacing Property

*
  * Previous Topic: IHTMLFrameBase::put_frameSpacing
  * Next Topic: IHTMLFrameBase::put_marginWidth

IHTMLFrameBase::get_frameSpacing

HRESULT get_frameSpacing(
    VARIANT *p
);

Retrieves the amount of additional space between the frames, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the amount of additional space. The default spacing is 2 pixels.

The amount defined for frameSpacing does not include the width of the frameBorder. frameSpacing can be set on one or more FRAMESETs, and applies to the contained FRAMESET unless the contained FRAMESET defines a different frameSpacing.

See also put_frameSpacing

Up Top of Page

IHTMLFrameBase::put_frameSpacing

HRESULT put_frameSpacing(
    VARIANT v
);

Creates additional space between the frames, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of additional space. The default spacing is 2 pixels.

The amount defined for frameSpacing does not include the width of the frameBorder. frameSpacing can be set on one or more FRAMESETs, and applies to the contained FRAMESET unless the contained FRAMESET defines a different frameSpacing.

See also get_frameSpacing


MarginWidth Property

*
  * Previous Topic: IHTMLFrameBase::put_marginWidth
  * Next Topic: IHTMLFrameBase::put_marginHeight

IHTMLFrameBase::get_marginWidth

HRESULT get_marginWidth(
    VARIANT *p
);

Retrieves the width, in pixels, of the left and right margins for the text in a frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

Margins cannot be less than 1 nor so large that the text cannot be displayed.

See also put_marginWidth

Up Top of Page

IHTMLFrameBase::put_marginWidth

HRESULT put_marginWidth(
    VARIANT v
);

Sets the width, in pixels, of the left and right margins for the text in a frame.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying margin widths.

Margins cannot be less than 1 nor too large that the text cannot be displayed.

See also get_marginWidth


MarginHeight Property

*
  * Previous Topic: IHTMLFrameBase::put_marginHeight
  * Next Topic: IHTMLFrameBase::put_noResize

IHTMLFrameBase::get_marginHeight

HRESULT get_marginHeight(
    VARIANT *p
);

Retrieves the width, in pixels, of the top and bottom margins for the text in a frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

Margins cannot be less than 1 nor so large that the text cannot be displayed.

See also put_marginHeight

Up Top of Page

IHTMLFrameBase::put_marginHeight

HRESULT put_marginHeight(
    VARIANT v
);

Sets the width, in pixels, of the top and bottom margins for the text in a frame.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying margin widths.

Margins cannot be less than 1 nor so large that the text cannot be displayed.

See also get_marginHeight


NoResize Property

*
  * Previous Topic: IHTMLFrameBase::put_noResize
  * Next Topic: IHTMLFrameBase::put_scrolling

IHTMLFrameBase::get_noResize

HRESULT get_noResize(
    VARIANT_BOOL *p
);

Retrieves whether the user can resize the frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the frame is not resizeable, or FALSE if it is.

See also put_noResize

Up Top of Page

IHTMLFrameBase::put_noResize

HRESULT put_noResize(
    VARIANT_BOOL v
);

Specifies whether the user can resize the frame.

  • Returns S_OK if successful, or an error value otherwise.
v
Resize flag. TRUE means the size is fixed; the user cannot resize the frame. FALSE means the user can resize the frame. This is the default value for the property.

See also get_noResize


Scrolling Property

*
  * Previous Topic: IHTMLFrameBase::put_scrolling
  * Next Topic: IHTMLFrameElement

IHTMLFrameBase::get_scrolling

HRESULT get_scrolling(
    BSTR *p
);

Retrieves a value indicating whether the frame can be scrolled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
auto | The browser determines if the scroll bars are necessary. This is the default value.
no | The frame cannot be scrolled.
yes | The frame can be scrolled.

See also put_scrolling

Up Top of Page

IHTMLFrameBase::put_scrolling

HRESULT put_scrolling(
    BSTR v
);

Specifies whether the frame can be scrolled.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying one of these values:
auto | The browser determines if the scroll bars are necessary. This is the default value.
no | The frame cannot be scrolled.
yes | The frame can be scrolled.

See also get_scrolling


IHTMLFrameElement

This interface specifies an individual frame within a FRAMESET.

This element is a block element.

IHTMLFrameElement Methods


BorderColor Property

*
  * Previous Topic: IHTMLFrameElement::put_borderColor
  * Next Topic: IHTMLFramesCollection2

IHTMLFrameElement::get_borderColor

HRESULT get_borderColor(
    VARIANT *p
);

Retrieves the border color.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColor

Up Top of Page

IHTMLFrameElement::put_borderColor

HRESULT put_borderColor(
    VARIANT v
);

Sets the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColor


IHTMLFramesCollection2

This is a zero-based collection of all FRAME elements if the document contains the FRAMESET element. If the document contains the BODY element, this is a collection of all IFRAME elements in the document. In either case, the order of frames is determined by the HTML source.

This collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can only be referenced by ordinal position.

This is a collection of FRAME tags.

IHTMLFramesCollection2 Methods


IHTMLFramesCollection2::item

HRESULT item(
    VARIANT *pvarIndex,
    VARIANT *pvarResult
);

Retrieves an element or a collection from the frames collection. The index determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
pvarIndex
Address of a variable specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
pvarResult
Address of a variable that receives an element object or a collection of element objects if successful, or null otherwise.


IHTMLFramesCollection2::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in the frames collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of elements.


IHTMLFrameSetElement

This interface specifies a frameset. Framesets are used to organize multiple frames and nested framesets. A frameset organizes multiple frames on the screen. Only FRAME, nested FRAMESET, and the NOFRAMES tags are valid within a frameset.

This element is a block element.

IHTMLFrameSetElement Methods
put_rows get_rows put_cols
get_cols put_border get_border
put_borderColor get_borderColor put_frameBorder
get_frameBorder put_frameSpacing get_frameSpacing
put_name get_name put_onload
get_onload put_onunload get_onunload
put_onbeforeunload get_onbeforeunload

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Rows Property

*
  * Previous Topic: IHTMLFrameSetElement::put_rows
  * Next Topic: IHTMLFrameSetElement::put_cols

IHTMLFrameSetElement::get_rows

HRESULT get_rows(
    BSTR *p
);

Retrieves a comma-delimited list of frames to create. Each item in the list contains the initial size of the row.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the comma-delimited list.

See also put_rows

Up Top of Page

IHTMLFrameSetElement::put_rows

HRESULT put_rows(
    BSTR v
);

Specifies a comma-delimited list of frames to create. Each item in the list contains the initial size of the row.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying a comma-delimited list of frames.

See also get_rows


Cols Property

*
  * Previous Topic: IHTMLFrameSetElement::put_cols
  * Next Topic: IHTMLFrameSetElement::put_border

IHTMLFrameSetElement::get_cols

HRESULT get_cols(
    BSTR *p
);

Retrieves a comma-delimited list of frames to create. Each item in the list contains the initial size of the column.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the comma-delimited list.

See also put_cols

Up Top of Page

IHTMLFrameSetElement::put_cols

HRESULT put_cols(
    BSTR v
);

Specifies a comma-delimited list of frames to create. Each item in the list contains the initial size of the column.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying a comma-delimited list of frames.

See also get_cols


Border Property

*
  * Previous Topic: IHTMLFrameSetElement::put_border
  * Next Topic: IHTMLFrameSetElement::put_borderColor

IHTMLFrameSetElement::get_border

HRESULT get_border(
    VARIANT *p
);

Retrieves the border color and must be used with the border property, except for frames.

  • Returns S_OK if successful, or an error value otherwise.
v
Addres of a variable that receives a string or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also put_border

Up Top of Page

IHTMLFrameSetElement::put_border

HRESULT put_border(
    VARIANT v
);

Sets the border color and must be used with the border property, except for frames.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also get_border


BorderColor Property

*
  * Previous Topic: IHTMLFrameSetElement::put_borderColor
  * Next Topic: IHTMLFrameSetElement::put_frameBorder

IHTMLFrameSetElement::get_borderColor

HRESULT get_borderColor(
    VARIANT *p
);

Retrieves the border color.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColor

Up Top of Page

IHTMLFrameSetElement::put_borderColor

HRESULT put_borderColor(
    VARIANT v
);

Sets the border color.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColor


FrameBorder Property

*
  * Previous Topic: IHTMLFrameSetElement::put_frameBorder
  * Next Topic: IHTMLFrameSetElement::put_frameSpacing

IHTMLFrameSetElement::get_frameBorder

HRESULT get_frameBorder(
    BSTR *p
);

Determines whether a border is currently being displayed for the frame.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives "Yes" if the frame has an inset border, or "No" if it has no border.

See also put_frameBorder

Up Top of Page

IHTMLFrameSetElement::put_frameBorder

HRESULT put_frameBorder(
    BSTR v
);

Specifies whether to display a border for the frame.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether to display a border. If this parameter is "Yes", the frame will have an inset border. If it is "No", the frame will have no border. Any other value turns on the borders.

See also get_frameBorder


FrameSpacing Property

*
  * Previous Topic: IHTMLFrameSetElement::put_frameSpacing
  * Next Topic: IHTMLFrameSetElement::put_name

IHTMLFrameSetElement::get_frameSpacing

HRESULT get_frameSpacing(
    VARIANT *p
);

Retrieves the amount of additional space between the frames, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the amount of additional space. The default spacing is 2 pixels.

The amount defined for frameSpacing does not include the width of the frameBorder. frameSpacing can be set on one or more FRAMESETs, and applies to the contained FRAMESET unless the contained FRAMESET defines a different frameSpacing.

See also put_frameSpacing

Up Top of Page

IHTMLFrameSetElement::put_frameSpacing

HRESULT put_frameSpacing(
    VARIANT v
);

Creates additional space between the frames, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of additional space. The default spacing is 2 pixels.

The amount defined for frameSpacing does not include the width of the frameBorder. frameSpacing can be set on one or more FRAMESETs, and applies to the contained FRAMESET unless the contained FRAMESET defines a different frameSpacing.

See also get_frameSpacing


Name Property

*
  * Previous Topic: IHTMLFrameSetElement::put_name
  * Next Topic: IHTMLFrameSetElement::put_onload

IHTMLFrameSetElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the window or frame name, or one of these values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also put_name

Up Top of Page

IHTMLFrameSetElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name. It can be the name of a window or frame, or one of the following values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also get_name


Onload Property

*
  * Previous Topic: IHTMLFrameSetElement::put_onload
  * Next Topic: IHTMLFrameSetElement::put_onunload

ITMLFrameSetElement::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script associated with the onload event before a FRAME element is loaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onload

Up Top of Page

IHTMLFrameSetElement::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event before a FRAME element is loaded.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onload


Onunload Property

*
  * Previous Topic: IHTMLFrameSetElement::put_onunload
  * Next Topic: IHTMLFrameSetElement::put_onbeforeunload

IHTMLFrameSetElement::get_onunload

HRESULT get_onunload(
    VARIANT *p
);

Retrieves the inline script associated with the onunload event before a FRAME element is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onunload

Up Top of Page

IHTMLFrameSetElement::put_onunload

HRESULT put_onunload(
    VARIANT v
);

Sets the inline script associated with the onunload event before a FRAME element is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onunload


Onbeforeunload Property

*
  * Previous Topic: IHTMLFrameSetElement::put_onbeforeunload
  * Next Topic: IHTMLHeaderElement

IHTMLFrameSetElement::get_onbeforeunload

HRESULT get_onbeforeunload(
    VARIANT *p
);

Retrieves the inline script associated with the onbeforeunload event before a FRAME element is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

This event is fired before the onunload event. It provides an opportunity to warn the user if the window is currently in an unsaved state and the information will be lost.

See also put_onbeforeunload

Up Top of Page

IHTMLFrameSetElement::put_onbeforeunload

HRESULT put_onbeforeunload(
    VARIANT v
);

Sets the inline script associated with the onbeforeunload event before a FRAME element is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

This event is fired before the onunload event. It provides an opportunity to warn the user if the window is currently in an unsaved state and the information will be lost.

See also get_onbeforeunload


IHTMLHeaderElement IHTMLHeaderElement *
  * Previous Topic: IHTMLFrameSetElement::get_onbeforeunload
  * Next Topic: IHTMLHeaderElement::put_align

IHTMLHeaderElement

This interface renders text as a heading style.

This element is a block element.

IHTMLHeaderElement Methods


Align Property

*
  * Previous Topic: IHTMLHeaderElement::put_align
  * Next Topic: IHTMLHRElement

IHTMLHeaderElement::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also put_align

Up Top of Page

IHTMLHeaderElement::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also get_align


IHTMLHRElement

This interface draws a horizontal rule.

This element is a block element.

IHTMLHRElement Methods
put_align get_align put_color
get_color put_noShade get_noShade
put_width get_width put_size
get_size


Align Property

*
  * Previous Topic: IHTMLHRElement::put_align
  * Next Topic: IHTMLHRElement::put_color

IHTMLHRElement::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also put_align

Up Top of Page

IHTMLHRElement::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also get_align


Color Property

*
  * Previous Topic: IHTMLHRElement::put_color
  * Next Topic: IHTMLHRElement::put_noShade

IHTMLHRElement::get_color

HRESULT get_color(
    VARIANT *p
);

Retrieves the color to be used by the horizontal rule.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also put_color

Up Top of Page

IHTMLHRElement::put_color

HRESULT put_color(
    VARIANT v
);

Sets the color to be used by the horizontal rule.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. It can be one of the color names or values given in the Color Table reference documentation.

See also get_color


NoShade Property

*
  * Previous Topic: IHTMLHRElement::put_noShade
  * Next Topic: IHTMLHRElement::put_width

IHTMLHRElement::get_noShade

HRESULT get_noShade(
    VARIANT_BOOL *p
);

Determines whether the horizontal rule is drawn with 3-D shading.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if 3-D shading is used, or FALSE if not.

The default value for this property is FALSE.

See also put_noShade

Up Top of Page

IHTMLHRElement::put_noShade

HRESULT put_noShade(
    VARIANT_BOOL v
);

Specifies whether to draw the horizontal rule with 3-D shading.

  • Returns S_OK if successful, or an error value otherwise.
v
Shading flag. If TRUE, the rule is 3-D shaded; if FALSE, it is not.

The default value for this property is FALSE.

See also get_noShade


Width Property

*
  * Previous Topic: IHTMLHRElement::put_width
  * Next Topic: IHTMLHRElement::put_size

IHTMLHRElement::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the horizontal rule, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLHRElement::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the horizontal rule, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Size Property

*
  * Previous Topic: IHTMLHRElement::put_size
  * Next Topic: IHTMLIFrameElement

IHTMLHRElement::get_size

HRESULT get_size(
    VARIANT *p
);

Retrieves the height of the horizontal rule, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

See also put_size

Up Top of Page

IHTMLHRElement::put_size

HRESULT put_size(
    VARIANT v
);

Sets the height of the horizontal rule, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the height.

See also get_size


IHTMLIFrameElement IHTMLIFrameElement *
  * Previous Topic: IHTMLHRElement::get_size
  * Next Topic: IHTMLIFrameElement::put_vspace

IHTMLIFrameElement

This interface creates inline floating frames.

This element is a block element.

IHTMLIFrameElement Methods


Vspace Property

*
  * Previous Topic: IHTMLIFrameElement::put_vspace
  * Next Topic: IHTMLIFrameElement::put_hspace

IHTMLIFrameElement::get_vspace

HRESULT get_vspace(
    long *p
);

Retrieves the width of the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width of the vertical margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_vspace

Up Top of Page

IHTMLIFrameElement::put_vspace

HRESULT put_vspace(
    long v
);

Sets the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width of the vertical margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_vspace


Hspace Property

*
  * Previous Topic: IHTMLIFrameElement::put_hspace
  * Next Topic: IHTMLIFrameElement::put_align

IHTMLIFrameElement::get_hspace

HRESULT get_hspace(
    long *p
);

Retrieves the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_hspace

Up Top of Page

IHTMLIFrameElement::put_hspace

HRESULT put_hspace(
    long v
);

Sets the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_hspace


Align Property

*
  * Previous Topic: IHTMLIFrameElement::put_align
  * Next Topic: IHTMLImageElementFactory

IHTMLIFrameElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLIFrameElement::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


IHTMLImageElementFactory IHTMLImageElementFactory *
  * Previous Topic: IHTMLIFrameElement::get_align
  * Next Topic: IHTMLImageElementFactory::create

IHTMLImageElementFactory

This interface is used to create new instances of the OPTION element.

IHTMLImageElementFactory Methods
create


IHTMLImageElementFactory::create

HRESULT create(
    VARIANT width,
    VARIANT height,
    IHTMLImgElement **ppImgElement
);

Creates a new IMG element of the specified width and height.

  • Returns S_OK if successful, or an error value otherwise.
width
Width, in pixels, of the new IMG element.
height
Height, in pixels, of the new IMG element.
ppImgElement
Address of a variable that receives an interface pointer to the new IMG element.

See also IHTMLImgElement


IHTMLImgElement

This interface provides access to some of the properties and methods supported by the IMG element and the INPUT element of the image type. The other properties and methods are accessible through the IHTMLImgElement interface.

The IMG element embeds an image or a video clip in a document. It supports the onfocus event and can receive the input focus only if it has been associated with a MAP element.

IHTMLImgElement Methods
put_isMap get_isMap put_useMap
get_useMap get_mimeType get_fileSize
get_fileCreatedDate get_fileModifiedDate get_fileUpdatedDate
get_protocol get_href get_nameProp
put_border get_border put_vspace
get_vspace put_hspace get_hspace
put_alt get_alt put_src
get_src put_lowsrc get_lowsrc
put_vrml get_vrml get_dynsrc
get_readyState get_complete put_loop
get_loop put_align get_align
put_onload get_onload put_onerror
get_onerror put_onabort get_onabort
put_name get_name put_width
get_width put_height get_height
put_start get_start

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IsMap Property

*
  * Previous Topic: IHTMLImgElement::put_isMap
  * Next Topic: IHTMLImgElement::put_useMap

IHTMLImgElement::get_isMap

HRESULT get_isMap(
    VARIANT_BOOL *p
);

Determines whether the picture is a server-side image map.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the picture is a server-side image map, or FALSE if not.

See also put_isMap

Up Top of Page

IHTMLImgElement::put_isMap

HRESULT put_isMap(
    VARIANT_BOOL v
);

Specifies whether the picture is a server-side image map.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that, if TRUE, specifies that the picture is a server-side image map.

See also get_isMap


UseMap Property

*
  * Previous Topic: IHTMLImgElement::put_useMap
  * Next Topic: IHTMLImgElement::get_mimeType

IHTMLImgElement::get_useMap

HRESULT get_useMap(
    BSTR *p
);

Retrieves the URL used as a client-side image map. The URL includes the bookmark extension (#name), if any.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_useMap

Up Top of Page

IHTMLImgElement::put_useMap

HRESULT put_useMap(
    BSTR v
);

Identifies a URL, often with a bookmark extension (#name), to use as a client-side image map.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_useMap


IHTMLImgElement::get_mimeType

HRESULT get_mimeType(
    BSTR *p
);

Retrieves the MIME type for the file.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the MIME type. This parameter receives "text/html" for HTML files.


IHTMLImgElement::get_fileSize

HRESULT get_fileSize(
    BSTR *p
);

Retrieves the size, in bytes, of the image file associated with the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the file size.


IHTMLImgElement::get_fileCreatedDate

HRESULT get_fileCreatedDate(
    BSTR *p
);

Retrieves the creation date of the image file associated with the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the creation date. The date consists of the weekday, month, date, and year.


IHTMLImgElement::get_fileModifiedDate

HRESULT get_fileModifiedDate(
    BSTR *p
);

Retrieves the date when the image file associated with the element was most recently modified.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the modification date. The date consists of the weekday, month, date, and year.


IHTMLImgElement::get_fileUpdatedDate

HRESULT get_fileUpdatedDate(
    BSTR *p
);

Retrieves the date when the image file associated with the element was last updated.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the date. The date consists of the weekday, month, date, and year.


IHTMLImgElement::get_protocol

HRESULT get_protocol(
    BSTR *p
);

Retrieves the protocol portion of the URL that the browser uses to locate the image or video clip associated with the element. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the protocol.


IHTMLImgElement::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the entire URL that the browser uses to locate the image or video clip associated with the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.


IHTMLImgElement::get_nameProp

HRESULT get_nameProp(
    BSTR *p
);

Retrieves the file name from the URL that the browser uses to locate the image or video clip associated with the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the file name.


Border Property

*
  * Previous Topic: IHTMLImgElement::put_border
  * Next Topic: IHTMLImgElement::put_vspace

IHTMLImgElement::get_border

HRESULT get_border(
    VARIANT *p
);

Retrieves the current thickness of the border around the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border thickness.

See also put_border

Up Top of Page

IHTMLImgElement::put_border

HRESULT put_border(
    VARIANT v
);

Sets the thickness of the border around the element.

  • Returns S_OK if successful, or an error value otherwise.
v
A string or value specifying the border thickness.

See also get_border


Vspace Property

*
  * Previous Topic: IHTMLImgElement::put_vspace
  * Next Topic: IHTMLImgElement::put_hspace

IHTMLImgElement::get_vspace

HRESULT get_vspace(
    long *p
);

Retrieves the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the vertical margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_vspace

Up Top of Page

IHTMLImgElement::put_vspace

HRESULT put_vspace(
    long v
);

Sets the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_vspace


Hspace Property

*
  * Previous Topic: IHTMLImgElement::put_hspace
  * Next Topic: IHTMLImgElement::put_alt

IHTMLImgElement::get_hspace

HRESULT get_hspace(
    long *p
);

Retrieves the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_hspace

Up Top of Page

IHTMLImgElement::put_hspace

HRESULT put_hspace(
    long v
);

Sets the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_hspace


Alt Property

*
  * Previous Topic: IHTMLImgElement::put_alt
  * Next Topic: IHTMLImgElement::put_src

IHTMLImgElement::get_alt

HRESULT get_alt(
    BSTR *p
);

Retrieves the optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the optional text.

See also put_alt

Up Top of Page

IHTMLImgElement::put_alt

HRESULT put_alt(
    BSTR v
);

Indicates optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the optional text.

See also get_alt


Src Property

*
  * Previous Topic: IHTMLImgElement::put_src
  * Next Topic: IHTMLImgElement::put_lowsrc

IHTMLImgElement::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves the URL of a sound to be played.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_src

Up Top of Page

IHTMLImgElement::put_src

HRESULT put_src(
    BSTR v
);

Sets the URL of an image to be shown.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_src


Lowsrc Property

*
  * Previous Topic: IHTMLImgElement::put_lowsrc
  * Next Topic: IHTMLImgElement::put_vrml

IHTMLImgElement::get_lowsrc

HRESULT get_lowsrc(
    BSTR *p
);

Retrieves the URL of a lower-resolution image to display.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

Setting the SRC= attribute in code has the side-effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, you should alter the lowsrc property before setting the src property. If the URL in the src property refers to an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

See also put_lowsrc

Up Top of Page

IHTMLImgElement::put_lowsrc

HRESULT put_lowsrc(
    BSTR v
);

Specifies the URL of a lower-resolution image to display.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

Setting the SRC= attribute in code has the side-effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, you should alter the lowsrc property before setting the src property. If the URL in the src property refers to an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

See also get_lowsrc


Vrml Property

*
  * Previous Topic: IHTMLImgElement::put_vrml
  * Next Topic: IHTMLImgElement::put_dynsrc

IHTMLImgElement::get_vrml

HRESULT get_vrml(
    BSTR *p
);

Retrieves the URL of the VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_vrml

Up Top of Page

IHTMLImgElement::put_vrml

HRESULT put_vrml(
    BSTR v
);

Specifies the URL of a VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_vrml


Dynsrc Property

*
  * Previous Topic: IHTMLImgElement::put_dynsrc
  * Next Topic: IHTMLImgElement::get_readyState

IHTMLImgElement::get_dynsrc

HRESULT get_dynsrc(
    BSTR *p
);

Retrieves the address of a video clip or VRML world to be displayed in the window. Stands for Dynamic Source.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the address.

See also put_dynsrc

Up Top of Page

IHTMLImgElement::put_dynsrc

HRESULT put_dynsrc(
    BSTR v
);

Sets the address of a video clip or VRML world to be displayed in the window. Stands for Dynamic Source.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the address.

See also get_dynsrc


IHTMLImgElement::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states they expose.


IHTMLImgElement::get_complete

HRESULT get_complete(
    VARIANT_BOOL *p
);

Retrieves whether the specified element is fully loaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the element is fully loaded, or FALSE otherwise.


Loop Property

*
  * Previous Topic: IHTMLImgElement::put_loop
  * Next Topic: IHTMLImgElement::put_align

IHTMLImgElement::get_loop

HRESULT get_loop(
    VARIANT *p
);

Retrieves the number of times a video loops when activated.

  • Returns S_OK if successful, or an error value otherwise.
p
Value specifying the number of times to loop. If this parameter receives -1 (infinite), the video will loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also put_loop

Up Top of Page

IHTMLImgElement::put_loop

HRESULT put_loop(
    VARIANT v
);

Sets the number of times a video will loop when activated.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of times to loop. If this parameter is -1 (infinite), the video will loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also get_loop


Align Property

*
  * Previous Topic: IHTMLImgElement::put_align
  * Next Topic: IHTMLImgElement::put_onload

IHTMLImgElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLImgElement::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


Onload Property

*
  * Previous Topic: IHTMLImgElement::put_onload
  * Next Topic: IHTMLImgElement::put_onerror

IHTMLImgElement::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script associated with the onload event for an IMG element. The onload event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onload

Up Top of Page

IHTMLImgElement::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event for an IMG element. The onload event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onload


Onerror Property

*
  * Previous Topic: IHTMLImgElement::put_onerror
  * Next Topic: IHTMLImgElement::put_onabort

IHTMLImgElement::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event for an IMG element. The onerror event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onerror

Up Top of Page

IHTMLImgElement::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event for an IMG element. The onerror event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onerror


Onabort Property

*
  * Previous Topic: IHTMLImgElement::put_onabort
  * Next Topic: IHTMLImgElement::put_name

IHTMLImgElement::get_onabort

HRESULT get_onabort(
    VARIANT *p
);

Retrieves the inline script associated with the onabort event for an IMG element. The onabort event occurs when the user aborts the download of the image.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onabort

Up Top of Page

IHTMLImgElement::put_onabort

HRESULT put_onabort(
    VARIANT v
);

Sets the inline script associated with the onabort event for an IMG element. The onabort event occurs when the user aborts the download of the image.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onabort


Name Property

*
  * Previous Topic: IHTMLImgElement::put_name
  * Next Topic: IHTMLImgElement::put_width

IHTMLImgElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLImgElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Width Property

*
  * Previous Topic: IHTMLImgElement::put_width
  * Next Topic: IHTMLImgElement::put_height

IHTMLImgElement::get_width

HRESULT get_width(
    long *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLImgElement::put_width

HRESULT put_width(
    long v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Height Property

*
  * Previous Topic: IHTMLImgElement::put_height
  * Next Topic: IHTMLImgElement::put_start

IHTMLImgElement::get_height

HRESULT get_height(
    long *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLImgElement::put_height

HRESULT put_height(
    long v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


Start Property

*
  * Previous Topic: IHTMLImgElement::put_start
  * Next Topic: IHTMLInputButtonElement

IHTMLImgElement::get_start

HRESULT get_start(
    BSTR *p
);

Retrieves when a video clip should start playing.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
fileopen | The video starts as soon as it is finished loading.
mouseover | The video starts when the mouse goes over the animation.

See also put_start

Up Top of Page

IHTMLImgElement::put_start

HRESULT put_start(
    BSTR v
);

Specifies when a video clip file should start playing.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying when to start the video. Can be one of these values:
fileopen | The video starts as soon as it is finished loading.
mouseover | The video starts when the mouse goes over the animation.

See also get_start


IHTMLInputButtonElement

This interface specifies a form input control.

IHTMLInputButtonElement Methods
get_type put_value get_value
put_name get_name put_status
get_status put_disabled get_disabled
get_form


IHTMLInputButtonElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the control type. The possible values depend on the element as listed in the following table.

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Value Property

*
  * Previous Topic: IHTMLInputButtonElement::put_value
  * Next Topic: IHTMLInputButtonElement::put_name

IHTMLInputButtonElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value. The purpose of the string depends on the type of control as described in the following table.

Control Type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also put_value

Up Top of Page

IHTMLInputButtonElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value. The purpose of the value depends on the type of control as described in the following table.

Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also get_value


Name Property

*
  * Previous Topic: IHTMLInputButtonElement::put_name
  * Next Topic: IHTMLInputButtonElement::put_status

IHTMLInputButtonElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the INPUT button control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLInputButtonElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the INPUT button control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Status Property

*
  * Previous Topic: IHTMLInputButtonElement::put_status
  * Next Topic: IHTMLInputButtonElement::put_disabled

IHTMLInputButtonElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the status of the INPUT button control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the status. Can be TRUE, FALSE, or NULL.

See also put_status

Up Top of Page

IHTMLInputButtonElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the status of the INPUT control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the status. Can be TRUE, FALSE, or NULL.

See also get_status


Disabled Property

*
  * Previous Topic: IHTMLInputButtonElement::put_disabled
  * Next Topic: IHTMLInputButtonElement::get_form

IHTMLInputButtonElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the INPUT button control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLInputButtonElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the INPUT button control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLInputButtonElement::get_form

HRESULT get_form(
     IHTMLFormElement **p
);

Retrieves a reference to the form on which the INPUT button control is embedded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLInputFileElement

This interface specifies a form input control.

IHTMLInputFileElement Methods
get_type put_name get_name
put_status get_status put_disabled
get_disabled get_form put_size
get_size put_maxLength get_maxLength
select put_onchange get_onchange
put_onselect get_onselect put_value
get_value


IHTMLInputFileElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the intrinsic-control type. The possible values depend on the element as listed in the following table.

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Name Property

*
  * Previous Topic: IHTMLInputFileElement::put_name
  * Next Topic: IHTMLInputFileElement::put_status

IHTMLInputFileElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLInputFileElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Status Property

*
  * Previous Topic: IHTMLInputFileElement::put_status
  * Next Topic: IHTMLInputFileElement::put_disabled

IHTMLInputFileElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the status of the INPUT file control.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a variable that receives the status.

See also put_status

Up Top of Page

IHTMLInputFileElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the status of the INPUT file control.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the status.

See also get_status


Disabled Property

*
  * Previous Topic: IHTMLInputFileElement::put_disabled
  * Next Topic: IHTMLInputFileElement::get_form

IHTMLInputFileElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the INPUT file control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLInputFileElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the INPUT file control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLInputFileElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


Size Property

*
  * Previous Topic: IHTMLInputFileElement::put_size
  * Next Topic: IHTMLInputFileElement::put_maxLength

IHTMLInputFileElement::get_size

HRESULT get_size(
    long *p
);

Retrieves the size of the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the size, in characters.

See also put_size

Up Top of Page

IHTMLInputFileElement::put_size

HRESULT put_size(
    long v
);

Sets the size of the control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the size, in characters.

See also get_size


MaxLength Property

*
  * Previous Topic: IHTMLInputFileElement::put_maxLength
  * Next Topic: IHTMLInputFileElement::select

IHTMLInputFileElement::get_maxLength

HRESULT get_maxLength(
    long *p
);

Retrieves the maximum number of characters that can be entered into the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the maximum number of characters.

This can be larger than the size of the textbox. When this occurs, the textbox should scroll accordingly as the user types. The default is there is no limit.

See also put_maxLength

Up Top of Page

IHTMLInputFileElement::put_maxLength

HRESULT put_maxLength(
    long v
);

Sets the maximum number of characters that can be entered into the control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the length.

This can be larger than the size of the control. When this occurs, the control scrolls accordingly as the user types. The default is there is no limit.

See also get_maxLength


IHTMLInputFileElement::select

HRESULT select(
    void
);

Highlights the input area of the INPUT file control.

  • Returns S_OK if successful, or an error value otherwise.

You can use the select method with the focus method to highlight a field and position the cursor for a user response.


Onchange Property

*
  * Previous Topic: IHTMLInputFileElement::put_onchange
  * Next Topic: IHTMLInputFileElement::put_onselect

IHTMLInputFileElement::get_onchange

HRESULT get_onchange(
    VARIANT *p
);

Retrieves the inline script associated with the onchange event for an INPUT type=file element. An onchange event occurs when the content of the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onchange

Up Top of Page

IHTMLInputFileElement::put_onchange

HRESULT put_onchange(
    VARIANT v
);

Sets the inline script associated with the onchange event for an INPUT type=file element. An onchange event occurs when the content of the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onchange


Onselect Property

*
  * Previous Topic: IHTMLInputFileElement::put_onselect
  * Next Topic: IHTMLInputFileElement::put_value

IHTMLInputFileElement::get_onselect

HRESULT get_onselect(
    VARIANT *p
);

Retrieves the inline script associated with the onselect event for an INPUT type=file element. An onselect event occurs at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onselect

Up Top of Page

IHTMLInputFileElement::put_onselect

HRESULT put_onselect(
    VARIANT v
);

Sets the inline script associated with the onselect event for an INPUT type=file element. An onselect event occurs at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onselect


Value Property

*
  * Previous Topic: IHTMLInputFileElement::put_value
  * Next Topic: IHTMLInputHiddenElement

IHTMLInputFileElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the value of the INPUT file control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value.

See also put_value

Up Top of Page

IHTMLInputFileElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the value of the INPUT file control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value.

See also get_value


IHTMLInputHiddenElement

This interface specifies a form input control.

IHTMLInputHiddenElement Methods
get_type put_value get_value
put_name get_name put_status
get_status put_disabled get_disabled
get_form createTextRange

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLInputHiddenElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. The possible values depend on the element as listed in the following table.

Element | Possible Value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field which you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | The same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, then that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength property.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Value Property

*
  * Previous Topic: IHTMLInputHiddenElement::put_value
  * Next Topic: IHTMLInputHiddenElement::put_name

IHTMLInputHiddenElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value. It can be any valid string. The purpose of the string depends on the type of control as described in the following table.

Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also put_value

Up Top of Page

IHTMLInputHiddenElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value. It can be any valid string. The purpose of the string depends on the type of control as described in the following table.

Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also get_value


Name Property

*
  * Previous Topic: IHTMLInputHiddenElement::put_name
  * Next Topic: IHTMLInputHiddenElement::put_status

IHTMLInputHiddenElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLInputHiddenElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Status Property

*
  * Previous Topic: IHTMLInputHiddenElement::put_status
  * Next Topic: IHTMLInputHiddenElement::put_disabled

IHTMLInputHiddenElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the value of a check box or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value.

See also put_status

Up Top of Page

IHTMLInputHiddenElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the value of a check box or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
v
Value of the check box or radio button.

See also get_status


Disabled Property

*
  * Previous Topic: IHTMLInputHiddenElement::put_disabled
  * Next Topic: IHTMLInputHiddenElement::get_form

IHTMLInputHiddenElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLInputHiddenElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLInputHiddenElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form.

Returns NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLInputHiddenElement::createTextRange

HRESULT createTextRange(
    IHTMLTxtRange **range
);

Creates a text range object for the element. You use a text range to examine and modify the text within the element.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a variable that receives an interface pointer to the text range.

See also IHTMLTxtRange


IHTMLInputImage

This interface specifies a form input control.

IHTMLInputImage Methods
get_type put_disabled get_disabled
put_border get_border put_vspace
get_vspace put_hspace get_hspace
put_alt get_alt put_src
get_src put_lowsrc get_lowsrc
get_vrml put_dynsrc get_dynsrc
get_readyState get_complete put_loop
get_loop put_align get_align
put_onload get_onload put_onerror
get_onerror put_onabort get_onabort
put_name get_name put_width
get_width put_height get_height
put_start get_start

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLInputImage::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type, which can be one of these values:

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field which you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | The same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, then that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength property.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Disabled Property

*
  * Previous Topic: IHTMLInputImage::put_disabled
  * Next Topic: IHTMLInputImage::put_border

IHTMLInputImage::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLInputImage::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


Border Property

*
  * Previous Topic: IHTMLInputImage::put_border
  * Next Topic: IHTMLInputImage::put_vspace

IHTMLInputImage::get_border

HRESULT get_border(
    VARIANT *p
);

Retrieves the current thickness of the border around the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border thickness.

See also put_border

Up Top of Page

IHTMLInputImage::put_border

HRESULT put_border(
    VARIANT v
);

Sets the thickness of the border around the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the border thickness.

See also get_border


Vspace Property

*
  * Previous Topic: IHTMLInputImage::put_vspace
  * Next Topic: IHTMLInputImage::put_hspace

IHTMLInputImage::get_vspace

HRESULT get_vspace(
    long *p
);

Retrieves the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the vertical margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_vspace

Up Top of Page

IHTMLInputImage::put_vspace

HRESULT put_vspace(
    long v
);

Sets the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_vspace


Hspace Property

*
  * Previous Topic: IHTMLInputImage::put_hspace
  * Next Topic: IHTMLInputImage::put_alt

IHTMLInputImage::get_hspace

HRESULT get_hspace(
    long *p
);

Retrieves the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_hspace

Up Top of Page

IHTMLInputImage::put_hspace

HRESULT put_hspace(
    long v
);

Sets the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_hspace


Alt Property

*
  * Previous Topic: IHTMLInputImage::put_alt
  * Next Topic: IHTMLInputImage::put_src

IHTMLInputImage::get_alt

HRESULT get_alt(
    BSTR *p
);

Retrieves the optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the optional text.

See also put_alt

Up Top of Page

IHTMLInputImage::put_alt

HRESULT put_alt(
    BSTR v
);

Indicates optional text as an alternative to the graphic for rendering in nongraphical environments. Alternate text should be provided whenever the graphic is not rendered. Alternate text is mandatory for Level 0 documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the optional text.

See also get_alt


Src Property

*
  * Previous Topic: IHTMLInputImage::put_src
  * Next Topic: IHTMLInputImage::put_lowsrc

IHTMLnputImage::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves the URL of the image.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_src

Up Top of Page

IHTMLInputImage::put_src

HRESULT put_src(
    BSTR v
);

Sets the URL of an image to be shown.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_src


Lowsrc Property

*
  * Previous Topic: IHTMLInputImage::put_lowsrc
  * Next Topic: IHTMLInputImage::put_vrml

IHTMLInputImage::get_lowsrc

HRESULT get_lowsrc(
    BSTR *p
);

Retrieves the URL of a lower-resolution image to display.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

Setting the SRC= attribute in code has the side-effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, you should alter the lowsrc property before setting the src property. If the URL in the src property refers to an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

See also put_lowsrc

Up Top of Page

IHTMLInputImage::put_lowsrc

HRESULT put_lowsrc(
    BSTR v
);

Specifies the URL of a lower-resolution image to display.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

Setting the SRC= attribute in code has the side-effect of actually starting to load the new URL into the image area (and aborting the transfer of any image data that is already loading into the same area). Therefore, you should alter the lowsrc property before setting the src property. If the URL in the src property refers to an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

See also get_lowsrc


Vrml Property

*
  * Previous Topic: IHTMLInputImage::put_vrml
  * Next Topic: IHTMLInputImage::put_dynsrc

IHTMLInputImage::get_vrml

HRESULT get_vrml(
    BSTR *p
);

Retrieves the URL of the VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

Up Top of Page

IHTMLInputImage::put_vrml

HRESULT put_vrml(
    BSTR v
);

Specifies the URL of a VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.


Dynsrc Property

*
  * Previous Topic: IHTMLInputImage::put_dynsrc
  * Next Topic: IHTMLInputImage::get_readyState

IHTMLInputImage::get_dynsrc

HRESULT get_dynsrc(
    BSTR *p
);

Retrieves the address of a video clip or VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the address.

See also put_dynsrc

Up Top of Page

IHTMLInputImage::put_dynsrc

HRESULT put_dynsrc(
    BSTR v
);

Sets the address of a video clip or VRML world to be displayed in the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the address.

See also get_dynsrc


IHTMLInputImage::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states it exposes.


IHTMLInputImage::get_complete

HRESULT get_complete(
    VARIANT_BOOL *p
);

Retrieves whether the specified element is fully loaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the element is fully loaded, or FALSE otherwise.


Loop Property

*
  * Previous Topic: IHTMLInputImage::put_loop
  * Next Topic: IHTMLInputImage::put_align

IHTMLInputImage::get_loop

HRESULT get_loop(
    VARIANT *p
);

Retrieves the number of times a video loops when activated.

  • Returns S_OK if successful, or an error value otherwise.
p
Value specifying the number of times to loop. If this parameter receives -1 (infinite), the video will loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also put_loop

Up Top of Page

IHTMLInputImage::put_loop

HRESULT put_loop(
    VARIANT v
);

Sets the number of times a video will loop when activated.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of times to loop. If this parameter is -1 (infinite), the video will loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also get_loop


Align Property

*
  * Previous Topic: IHTMLInputImage::put_align
  * Next Topic: IHTMLInputImage::put_onload

IHTMLInputImage::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLInputImage::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


Onload Property

*
  * Previous Topic: IHTMLInputImage::put_onload
  * Next Topic: IHTMLInputImage::put_onerror

IHTMLInputImage::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script associated with the onload event for an INPUT type=image element. An onload event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onload

Up Top of Page

IHTMLInputImage::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event for an INPUT type=image element. An onload event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onload


Onerror Property

*
  * Previous Topic: IHTMLInputImage::put_onerror
  * Next Topic: IHTMLInputImage::put_onabort

IHTMLInputImage::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event for an INPUT type=image element. An onerror event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onerror

Up Top of Page

IHTMLInputImage::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event for an INPUT type=image element. An onerror event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onerror


Onabort Property

*
  * Previous Topic: IHTMLInputImage::put_onabort
  * Next Topic: IHTMLInputImage::put_name

IHTMLInputImage::get_onabort

HRESULT get_onabort(
    VARIANT *p
);

Retrieves the inline script associated with the onabort event for an INPUT type=image element. An onabort event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the script.

See also put_onabort

Up Top of Page

IHTMLInputImage::put_onabort

HRESULT put_onabort(
    VARIANT v
);

Sets the inline script associated with the onabort event for an INPUT type=image element. An onabort event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the new script.

See also get_onabort


Name Property

*
  * Previous Topic: IHTMLInputImage::put_name
  * Next Topic: IHTMLInputImage::put_width

IHTMLInputImage::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the window or frame name, or one of these values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also put_name

Up Top of Page

IHTMLInputImage::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the frame so it can be targeted from links in other documents.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name. Either a window name or frame can be specified, or one of the following values:
window_name | String that specifies a frame.
_blank | Loads the link into a new, unnamed window.
_parent | Loads the link over the parent. If the frame has no parent, this refers to _self.
_self | Replaces the page with the specified link.
_top | Loads the link at the topmost level.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also get_name


Width Property

*
  * Previous Topic: IHTMLInputImage::put_width
  * Next Topic: IHTMLInputImage::put_height

IHTMLInputImage::get_width

HRESULT get_width(
    long *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLInputImage::put_width

HRESULT put_width(
    long v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Height Property

*
  * Previous Topic: IHTMLInputImage::put_height
  * Next Topic: IHTMLInputImage::put_start

IHTMLInputImage::get_height

HRESULT get_height(
    long *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLInputImage::put_height

HRESULT put_height(
    long v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


Start Property

*
  * Previous Topic: IHTMLInputImage::put_start
  * Next Topic: IHTMLInputTextElement

IHTMLInputImage::get_start

HRESULT get_start(
    BSTR *p
);

Retrieves when a video clip should start playing.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
fileopen | The video starts as soon as it is finished loading.
mouseover | The video starts when the mouse goes over the animation.

See also put_start

Up Top of Page

IHTMLInputImage::put_start

HRESULT put_start(
    BSTR v
);

Specifies when a video clip file should start playing.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying when to start the video. Can be one of these values:
fileopen | The video starts as soon as it is finished loading.
mouseover | The video starts when the mouse goes over the animation.

See also get_start


IHTMLInputTextElement

This interface specifies a form input control.

IHTMLInputTextElement Methods
get_type put_value get_value
put_name get_name put_status
get_status put_disabled get_disabled
get_form put_defaultValue get_defaultValue
put_size get_size put_maxLength
get_maxLength select put_onchange
get_onchange put_onselect get_onselect
put_readOnly get_readOnly createTextRange

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLInputTextElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. The possible values depend on the element as listed in the following table.

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Value Property

*
  * Previous Topic: IHTMLInputTextElement::put_value
  * Next Topic: IHTMLInputTextElement::put_name

IHTMLInputTextElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value. It can be any valid string. The purpose of the string depends on the type of control, as described in the following table.
Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also put_value

Up Top of Page

IHTMLInputTextElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value. It can be any valid string. The purpose of the string depends on the type of control, as described in the following table.
Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also get_value


Name Property

*
  * Previous Topic: IHTMLInputTextElement::put_name
  * Next Topic: IHTMLInputTextElement::put_status

IHTMLInputTextElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLInputTextElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Status Property

*
  * Previous Topic: IHTMLInputTextElement::put_status
  * Next Topic: IHTMLInputTextElement::put_disabled

IHTMLInputTextElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the value of a checkbox or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value.

See also put_status

Up Top of Page

IHTMLInputTextElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the value of a checkbox or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
v
Value of the check box or radio button.

See also get_status


Disabled Property

*
  * Previous Topic: IHTMLInputTextElement::put_disabled
  * Next Topic: IHTMLInputTextElement::get_form

IHTMLInputTextElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLInputTextElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLInputTextElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


DefaultValue Property

*
  * Previous Topic: IHTMLInputTextElement::put_defaultValue
  * Next Topic: IHTMLInputTextElement::put_size

IHTMLInputTextElement::get_defaultValue

HRESULT get_defaultValue(
    BSTR *p
);

Retrieves the initial contents of a password or text control or the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the initial contents.

This value can be changed programmatically but has no effect on the appearance, or on how forms are submitted.

See also put_defaultValue

Up Top of Page

IHTMLInputTextElement::put_defaultValue

HRESULT put_defaultValue(
    BSTR v
);

Sets the initial contents of a password or text control or the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the initial contents.

This value can be changed programmatically but has no effect on the appearance, or on how forms are submitted.

See also get_defaultValue


Size Property

*
  * Previous Topic: IHTMLInputTextElement::put_size
  * Next Topic: IHTMLInputTextElement::put_maxLength

IHTMLInputTextElement::get_size

HRESULT get_size(
    long *p
);

Retrieves the size of the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the size, in characters.

See also put_size

Up Top of Page

IHTMLInputTextElement::put_size

HRESULT put_size(
    long v
);

Sets the size of the control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the size, in characters.

See also get_size


MaxLength Property

*
  * Previous Topic: IHTMLInputTextElement::put_maxLength
  * Next Topic: IHTMLInputTextElement::select

IHTMLInputTextElement::get_maxLength

HRESULT get_maxLength(
    long *p
);

Retrieves the maximum number of characters that can be entered into a text control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the maximum number of characters.

This can be larger than the size of the text box. When this occurs, the text box should scroll accordingly as the user types. The default is there is no limit.

See also put_maxLength

Up Top of Page

IHTMLInputTextElement::put_maxLength

HRESULT put_maxLength(
    long v
);

Sets the maximum number of characters that can be entered into a text control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the maximum number of characters.

This can be larger than the size of the text box. When this occurs, the text box should scroll accordingly as the user types. The default is there is no limit.

See also get_maxLength


IHTMLInputTextElement::select

HRESULT select(
    void
);

Highlights the input area of a form element.

  • Returns S_OK if successful, or an error value otherwise.

You can use the select method with the focus method to highlight a field and position the cursor for a user response.


Onchange Property

*
  * Previous Topic: IHTMLInputTextElement::put_onchange
  * Next Topic: IHTMLInputTextElement::put_onselect

IHTMLInputTextElement::get_onchange

HRESULT get_onchange(
    VARIANT *p
);

Retrieves the inline script associated with the onchange event on the INPUT text element. This occurs when the contents of the object have changed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onchange

Up Top of Page

IHTMLInputTextElement::put_onchange

HRESULT put_onchange(
    VARIANT v
);

Sets the inline script associated with the onchange event on the INPUT text element. This occurs when the contents of the object have changed.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onchange


Onselect Property

*
  * Previous Topic: IHTMLInputTextElement::put_onselect
  * Next Topic: IHTMLInputTextElement::put_readOnly

IHTMLInputTextElement::get_onselect

HRESULT get_onselect(
    VARIANT *
);

Retrieves the inline script associated with the onselect event on the INPUT text element. This event fires at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onselect

Up Top of Page

IHTMLInputTextElement::put_onselect

HRESULT put_onselect(
    VARIANT v
);

Sets the inline script associated with the onselect event on the INPUT text element. This event fires at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onselect


ReadOnly Property

*
  * Previous Topic: IHTMLInputTextElement::put_readOnly
  * Next Topic: IHTMLInputTextElement::createTextRange

IHTMLInputTextElement::get_readOnly

HRESULT get_readOnly(
    VARIANT_BOOL *p
);

Determines whether the element's contents are read-only, meaning that the user cannot enter or edit text in the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the element is read-only, or FALSE if not.

This is different than disabled. Read-only still allows the element to receive the focus, while disabled does not allow the element to receive the focus.

The default value for this property is FALSE.

See also put_readOnly

Up Top of Page

IHTMLInputTextElement::put_readOnly

HRESULT put_readOnly(
    VARIANT_BOOL v
);

Specifies whether the element's contents are read-only, meaning that the user cannot enter or edit text in the control.

  • Returns S_OK if successful, or an error value otherwise.
v
Read-only flag. TRUE sets the element to read-only; FALSE does not.

This is different than disabled. Read-only still allows the element to receive the focus, while disabled does not allow the element to receive the focus.

The default value for this property is FALSE.

See also get_readOnly


IHTMLInputTextElement::createTextRange

HRESULT createTextRange(
    IHTMLTxtRange **range
);

Creates a text range object for the element. You use a text range to examine and modify the text within the element.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a variable that receives an interface pointer to the text range.

See also IHTMLTxtRange


IHTMLIsIndexElement

This interface indicates the document contains a searchable index.

To use the ISINDEX tag, the server must provide a search engine that supports this tag. The script to be executed on the server can be specified by the action property on this tag.

This element can be used only within the HEAD tag.

IHTMLIsIndexElement Methods


Prompt Property

*
  * Previous Topic: IHTMLIsIndexElement::put_prompt
  * Next Topic: IHTMLIsIndexElement::put_action

IHTMLIsIndexElement::get_prompt

HRESULT get_prompt(
    BSTR *p
);

Retrieves a prompt to be used instead of the ACTION.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the prompt.

See also put_prompt

Up Top of Page

IHTMLIsIndexElement::put_prompt

HRESULT put_prompt(
    BSTR v
);

Sets a prompt to be used instead of the ACTION.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the prompt.

See also get_prompt


Action Property

*
  * Previous Topic: IHTMLIsIndexElement::put_action
  * Next Topic: IHTMLLabelElement

IHTMLIsIndexElement::get_action

HRESULT get_action(
    BSTR *p
);

Retrieves the gateway program to which the string in the text box should be passed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the gateway program.

See also put_action

Up Top of Page

IHTMLIsIndexElement::put_action

HRESULT put_action(
    BSTR v
);

Sets the gateway program to which the string in the text box should be passed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the gateway program.

See also get_action


IHTMLLabelElement IHTMLLabelElement *
  * Previous Topic: IHTMLIsIndexElement::get_action
  * Next Topic: IHTMLLabelElement::put_htmlFor

IHTMLLabelElement

This interface specifies a label for a control-like element.

Labels cannot be nested.

IHTMLLabelElement Methods


HtmlFor Property

*
  * Previous Topic: IHTMLLabelElement::put_htmlFor
  * Next Topic: IHTMLLabelElement::put_accessKey

IHTMLLabelElement::get_htmlFor

HRESULT get_htmlFor(
    BSTR *p
);

Retrieves which control-like element to assign the given label element to. This property corresponds to the FOR= attribute in HTML.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the control-like element.

The FOR= attribute references the ID of another element. The FOR= attribute is optional when the label is implicitly defined. This is done by wrapping the label around the control the label is specified for.

See also put_htmlFor

Up Top of Page

IHTMLLabelElement::put_htmlFor

HRESULT put_htmlFor(
    BSTR v
);

Sets which control-like element to assign the given label element to. This property corresponds to the FOR= attribute in HTML.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the control-like element.

The FOR= attribute references the ID of another element. The FOR= attribute is optional when the label is implicitly defined. This is done by wrapping the label around the control the label is specified for.

See also get_htmlFor


AccessKey Property

*
  * Previous Topic: IHTMLLabelElement::put_accessKey
  * Next Topic: IHTMLLegendElement

IHTMLLabelElement::get_accessKey

HRESULT get_accessKey(
    BSTR *p
);

Retrieves the accelerator key for the element. Pressing CTRL+key selects this anchor element in the user's browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the key.

See also put_accessKey

Up Top of Page

IHTMLLabelElement::put_accessKey

HRESULT put_accessKey(
    BSTR v
);

Sets an accelerator key for the element. Pressing CTRL+key selects this anchor element in the user's browser.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the key.

See also get_accessKey


IHTMLLegendElement

This interface inserts a caption into the box drawn by the FIELDSET element. If given, this element must be the first element in FIELDSET.

This element is a block element.

IHTMLLegendElement Methods


Align Property

*
  * Previous Topic: IHTMLLegendElement::put_align
  * Next Topic: IHTMLLIElement

IHTMLLegendElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLLegendElement::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


IHTMLLIElement IHTMLLIElement *
  * Previous Topic: IHTMLLegendElement::get_align
  * Next Topic: IHTMLLIElement::put_type

IHTMLLIElement

This interface denotes one item of a list.

This element is a block element.

IHTMLLIElement Methods


Type Property

*
  * Previous Topic: IHTMLLIElement::put_type
  * Next Topic: IHTMLLIElement::put_value

IHTMLLIElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the current style of the list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these style values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also put_type

Up Top of Page

IHTMLLIElement::put_type

HRESULT put_type(
    BSTR v
);

Changes the style of the list.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the style. Can be one of these values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also get_type


Value Property

*
  * Previous Topic: IHTMLLIElement::put_value
  * Next Topic: IHTMLLinkElement

IHTMLLIElement::get_value

HRESULT get_value(
    long *p
);

Retrieves the value of a list item. In an ordered list, the value is the number that precedes the list item. This property has no visual effect on an unordered list item.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the item.

See also put_value

Up Top of Page

IHTMLLIElement::put_value

HRESULT put_value(
    long v
);

Sets the value of a list item. In an ordered list, the value is the number that precedes the list item. This property has no visual effect on an unordered list item.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the item number.

See also get_value


IHTMLLinkElement

This interface is used to specify a typed link between the document and some other resource.

This element can be used only within the HEAD tag.

IHTMLLinkElement Methods
put_href get_href put_rel
get_rel put_rev get_rev
put_type get_type get_readyState
put_onreadystatechange get_onreadystatechange put_onload
get_onload put_onerror get_onerror
get_styleSheet put_disabled get_disabled
put_media get_media

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Href Property

*
  * Previous Topic: IHTMLLinkElement::put_href
  * Next Topic: IHTMLLinkElement::put_rel

IHTMLLinkElement::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the destination URL or anchor point.

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's ID attribute.

See also put_href

Up Top of Page

IHTMLLinkElement::put_href

HRESULT put_href(
    BSTR v
);

Sets the destination URL or anchor point.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL or anchor point.

The HREF attribute on the anchor is a scriptable attribute. HREFs on anchors can jump to bookmarks or any element's ID attribute.

See also get_href


Rel Property

*
  * Previous Topic: IHTMLLinkElement::put_rel
  * Next Topic: IHTMLLinkElement::put_rev

IHTMLLinkElement::get_rel

HRESULT get_rel(
    BSTR *p
);

Retrieves the relationship(s) described by the hypertext link from the anchor to the target.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a variable that receives the relationship(s). This parameter receives a comma-separated list of relationship values.

Values and their semantics will be registered by the HTML registration authority. The default relationship, if none other is given, is void. The rel property is used only when the href property is present.

See also put_rel

Up Top of Page

IHTMLLinkElement::put_rel

HRESULT put_rel(
    BSTR v
);

Specifies the relationship(s) described by the hypertext link from the anchor to the target.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the relationship(s). This parameter is a comma-separated list of relationship values.

Values and their semantics will be registered by the HTML registration authority. The default relationship, if none other is given, is void. The rel property is used only when the href property is present.

See also get_rel


Rev Property

*
  * Previous Topic: IHTMLLinkElement::put_rev
  * Next Topic: IHTMLLinkElement::put_type

IHTMLLinkElement::get_rev

HRESULT get_rev(
     BSTR *p
);

Same as the rel property, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor can have both rel and rev properties.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the relationship(s). This parameter receives a comma-separated list of relationship values.

See also put_rev

Up Top of Page

IHTMLLinkElement::put_rev

HRESULT put_rev(
    BSTR v
);

Same as the rel property, but the semantics of the link type are in the reverse direction. A link from A to B with REL="X" expresses the same relationship as a link from B to A with REV="X". An anchor can have both rel and rev properties.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the relationship(s). This parameter is a comma-separated list of relationship values.

See also get_rev


Type Property

*
  * Previous Topic: IHTMLLinkElement::put_type
  * Next Topic: IHTMLLinkElement::get_readyState

IHTMLLinkElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the current style of the list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the list style. Can be one of these values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also put_type

Up Top of Page

IHTMLLinkElement::put_type

HRESULT put_type(
    BSTR v
);

Changes the style of the list.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the list style. Can be one of these values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also get_type


IHTMLLinkElement::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the ready state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states it exposes.


Onreadystatechange Property

*
  * Previous Topic: IHTMLLinkElement::put_onreadystatechange
  * Next Topic: IHTMLLinkElement::put_onload

IHTMLLinkElement::get_onreadystatechange

HRESULT get_onreadystatechange(
    VARIANT *p
);

Retrieves the inline script associated with the onreadystatechange event on the LINK element. This event occurs whenever the readyState for the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onreadystatechange

Up Top of Page

IHTMLLinkElement::put_onreadystatechange

HRESULT put_onreadystatechange(
    VARIANT v
);

Sets the inline script associated with the onreadystatechange event on the LINK element. This event occurs whenever the readyState for the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onreadystatechange


Onload Property

*
  * Previous Topic: IHTMLLinkElement::put_onload
  * Next Topic: IHTMLLinkElement::put_onerror

IHTMLLinkElement::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script associated with the onload event on the LINK element. This event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onload

Up Top of Page

IHTMLLinkElement::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event on the LINK element. This event occurs immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onload


Onerror Property

*
  * Previous Topic: IHTMLLinkElement::put_onerror
  * Next Topic: IHTMLLinkElement::get_styleSheet

IHTMLLinkElement::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event on the LINK element. An error event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onerror

Up Top of Page

IHTMLLinkElement::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event on the LINK element. An error event occurs when the loading of a document or image causes an error.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onerror


IHTMLLinkElement::get_styleSheet

HRESULT get_styleSheet(
    IHTMLStyleSheet **p
);

Retrieves an interface pointer that provides access to the style sheet object's properties and methods.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer. See IHTMLStyleSheet for details.


Disabled Property

*
  * Previous Topic: IHTMLLinkElement::put_disabled
  * Next Topic: IHTMLLinkElement::put_media

IHTMLLinkElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Returns a Boolean value indicating whether this link has been disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the element is read-only, or FALSE if not.

See also put_disabled

Up Top of Page

IHTMLLinkElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Sets the value of the link as being disabled or not.

  • Returns S_OK if successful, or an error value otherwise.
v
Disabled flag. TRUE sets the element to disabled; FALSE does not.

See also get_disabled


Media Property

*
  * Previous Topic: IHTMLLinkElement::put_media
  * Next Topic: IHTMLListElement

IHTMLLinkElement::get_media

HRESULT get_media(
    BSTR *p
);

Retrieves the inline script that indicates which media this LINK element applies to.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the media type.

See also put_media

Up Top of Page

IHTMLLinkElement::put_media

HRESULT put_media(
    BSTR v
);

Sets the inline script that indicates which media this LINK element applies to.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the media type.

See also get_media


IHTMLListElement

This interface provides access to the properties and methods that are common to the OL and UL elements, and is equivalent to the IHTMLElement interface. For more information and a listing of the available methods, see the reference section for the IHTMLElement interface.


IHTMLLocation

This interface contains information about the current URL.

IHTMLLocation Methods
put_href get_href put_protocol
get_protocol put_host get_host
put_hostname get_hostname put_port
get_port put_pathname get_pathname
put_search get_search put_hash
get_hash reload replace
assign toString

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Href Property

*
  * Previous Topic: IHTMLLocation::put_href
  * Next Topic: IHTMLLocation::put_protocol

IHTMLLocation::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the URL of the current browser location.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_href

Up Top of Page

IHTMLLocation::put_href

HRESULT put_href(
    BSTR v
);

Sets the entire URL for the browser. Setting this property causes the browser to navigate to the location specified by the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_href


Protocol Property

*
  * Previous Topic: IHTMLLocation::put_protocol
  * Next Topic: IHTMLLocation::put_host

IHTMLLocation::get_protocol

HRESULT get_protocol(
    BSTR *p
);

Retrieves the protocol portion of the URL that the browser uses to locate the item. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the protocol.

See also put_protocol

Up Top of Page

IHTMLLocation::put_protocol

HRESULT put_protocol(
    BSTR v
);

Sets the protocol portion of the URL that the browser uses to locate the item. The protocol portion, which indicates the access method, includes the initial substring of the URL up to and including the first colon.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the protocol.

See also get_protocol


Host Property

*
  * Previous Topic: IHTMLLocation::put_host
  * Next Topic: IHTMLLocation::put_hostname

IHTMLLocation::get_host

HRESULT get_host(
    BSTR *p
);

Retrieves the hostname part of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the host name. If no host name is available, this parameter receives an empty string.

See also put_host

Up Top of Page

IHTMLLocation::put_host

HRESULT put_host(
    BSTR v
);

Sets the hostname portion of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the host name.

See also get_host


Hostname Property

*
  * Previous Topic: IHTMLLocation::put_hostname
  * Next Topic: IHTMLLocation::put_port

IHTMLLocation::get_hostname

HRESULT get_hostname(
    BSTR *p
);

Retrieves the hostname part of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the host name. If no host name is available, this parameter receives an empty string.

See also put_hostname

Up Top of Page

IHTMLLocation::put_hostname

HRESULT put_hostname(
    BSTR v
);

Sets the hostname portion of the location or URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the host name.

See also get_hostname


Port Property

*
  * Previous Topic: IHTMLLocation::put_port
  * Next Topic: IHTMLLocation::put_pathname

IHTMLLocation::get_port

HRESULT get_port(
    BSTR *p
);

Retrieves the port number from the URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the port number. If no port is specified, this parameter receives an empty string.

See also put_port

Up Top of Page

IHTMLLocation::put_port

HRESULT put_port(
    BSTR v
);

Sets the port number in a URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the port number.

See also get_port


Pathname Property

*
  * Previous Topic: IHTMLLocation::put_pathname
  * Next Topic: IHTMLLocation::put_search

IHTMLLocation::get_pathname

HRESULT get_pathname(
    BSTR *p
);

Retrieves the file or object path from the URL for the current browser location.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the path.

See also put_pathname

Up Top of Page

IHTMLLocation::put_pathname

HRESULT put_pathname(
    BSTR v
);

Sets the file or object path of the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the path.

See also get_pathname


Search Property

*
  * Previous Topic: IHTMLLocation::put_search
  * Next Topic: IHTMLLocation::put_hash

IHTMLLocation::get_search

HRESULT get_search(
    BSTR *p
);

Retrieves the substring that follows the ? symbol in the current URL. This is the query string or form data.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the query string or form data.

See also put_search

Up Top of Page

IHTMLLocation::put_search

HRESULT put_search(
    BSTR v
);

Sets the substring that follows the ? symbol in the current URL. This is the query string or form data.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the query string or form data.

See also get_search


Hash Property

*
  * Previous Topic: IHTMLLocation::put_hash
  * Next Topic: IHTMLLocation::reload

IHTMLLocation::get_hash

HRESULT get_hash(
    BSTR *p
);

Retrieves the string following the # symbol in the current URL.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the hash portion of the URL. If the URL has no hash sting, this parameter receives and empty string.

This property is useful for moving to a bookmark within a document. Assigning an invalid value does not cause an error.

See also put_hash

Up Top of Page

IHTMLLocation::put_hash

HRESULT put_hash(
    BSTR v
);

Sets the string following the # symbol in the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the hash portion of the URL.

This property is useful for moving to a bookmark within a document. Assigning an invalid value does not cause an error.

See also get_hash


IHTMLLocation::reload

HRESULT reload(
     VARIANT_BOOL flag
);

Reloads the current page.

  • Returns S_OK if successful, or an error value otherwise.
flag
A Boolean value. TRUE sets the flag to reload the page, FALSE indicates not to reload the page.


IHTMLLocation::replace

HRESULT replace(
    BSTR bstr
);

Replaces the current document by loading the document at the given URL. This method also removes the current document from the browser's session history.

  • Returns S_OK if successful, or an error value otherwise.
bstr
String specifying the URL to insert into the session history.

Replacing a document causes it to no longer be accessible through the history object.

See also IOmHistory


IHTMLLocation::assign

HRESULT assign(
    BSTR bstr
);

Sets the current location to the given URL. This method loads the given document specified by the URL if it exists.

  • Returns S_OK if successful, or an error value otherwise.
bstr
String specifying the URL of the document to assign.


IHTMLLocation::toString

HRESULT toString(
    BSTR *string
);

Retrieves a string representation of the location object that is the href of the current browser location.

  • Returns S_OK if successful, or an error value otherwise.
string
Address of a string variable that receives the href.


IHTMLMapElement IHTMLMapElement *
  * Previous Topic: IHTMLLocation::toString
  * Next Topic: IHTMLMapElement::get_areas

IHTMLMapElement

Ths interface specifies a collection of hot spots for a client-side image map

IHTMLMapElement Methods


IHTMLMapElement::get_areas

HRESULT get_areas(
    IHTMLAreasCollection **p
);

Retrieves a collection of the AREA elements defined for the given MAP element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the collection object.

See also IHTMLAreasCollection


Name Property

*
  * Previous Topic: IHTMLMapElement::put_name
  * Next Topic: IHTMLMarqueeElement

IHTMLMapElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLMapElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


IHTMLMarqueeElement

This interface is used to specify a MARQUEE element. The MARQUEE tag enables you to create a scrolling text marquee, and control its content.

IHTMLMarqueeElement Methods
put_bgColor get_bgColor put_scrollDelay
get_scrollDelay put_direction get_direction
put_behavior get_behavior put_scrollAmount
get_scrollAmount put_loop get_loop
put_vspace get_vspace put_hspace
get_hspace put_onfinish get_onfinish
put_onstart get_onstart put_onbounce
get_onbounce put_width get_width
put_height get_height put_trueSpeed
get_trueSpeed start stop

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


BgColor Property

*
  * Previous Topic: IHTMLMarqueeElement::put_bgColor
  * Next Topic: IHTMLMarqueeElement::put_scrollDelay

IHTMLMarqueeElement::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the color value for the background color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLMarqueeElement::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color, which can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


ScrollDelay Property

*
  * Previous Topic: IHTMLMarqueeElement::put_scrollDelay
  * Next Topic: IHTMLMarqueeElement::put_direction

IHTMLMarqueeElement::get_scrollDelay

HRESULT get_scrollDelay(
    long *p
);

Retrieves the speed at which the MARQUEE scrolls.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll delay, in milliseconds.

See also put_scrollDelay

Up Top of Page

IHTMLMarqueeElement::put_scrollDelay

HRESULT put_scrollDelay(
    long v
);

Sets the speed at which the MARQUEE scrolls.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the scroll delay, in milliseconds.

See also get_scrollDelay


Direction Property

*
  * Previous Topic: IHTMLMarqueeElement::put_direction
  * Next Topic: IHTMLMarqueeElement::put_behavior

IHTMLMarqueeElement::get_direction

HRESULT get_direction(
    BSTR *p
);

Retrieves the current direction in which the text scrolls.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll direction. Can be one of these values:
down | The marquee scrolls down.
left | The marquee scrolls left. This is the default value.
right | The marquee scrolls right.
up | The marquee scrolls up.

See also put_direction

Up Top of Page

IHTMLMarqueeElement::put_direction

HRESULT put_direction(
    BSTR v
);

Sets the direction in which the text scrolls.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the scroll direction. Can be one of these values:
down | The marquee scrolls down.
left | The marquee scrolls left. This is the default value.
right | The marquee scrolls right.
up | The marquee scrolls up.

See also get_direction


Behavior Property

*
  * Previous Topic: IHTMLMarqueeElement::put_behavior
  * Next Topic: IHTMLMarqueeElement::put_scrollAmount

IHTMLMarqueeElement::get_behavior

HRESULT get_behavior(
    BSTR *p
);

Retrieves how the text scrolls in the marquee.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these strings:
alternate | The marquee alternates left and right.
scroll | The marquee is a scrolling marquee in the direction specified by the direction attribute. The text scrolls off the end and starts over.
slide | The marquee is a scrolling marquee in the direction specified by the direction attribute. The text scrolls to the end and stops.

See also put_behavior

Up Top of Page

IHTMLMarqueeElement::put_behavior

HRESULT put_behavior(
    BSTR v
);

Sets how the text scrolls in the MARQUEE.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the scrolling behavior. Can be one of these values:
alternate | The marquee alternates left and right.
scroll | The marquee is a scrolling marquee in the direction specified by the direction attribute. The text scrolls off the end and starts over.
slide | The marquee is a scrolling marquee in the direction specified by the direction attribute. The text scrolls to the end and stops.

See also get_behavior


ScrollAmount Property

*
  * Previous Topic: IHTMLMarqueeElement::put_scrollAmount
  * Next Topic: IHTMLMarqueeElement::put_loop

IHTMLMarqueeElement::get_scrollAmount

HRESULT get_scrollAmount(
    long *p
);

Retrieves the number of pixels the text scrolls between each subsequent drawing of the MARQUEE.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of pixels.

See also put_scrollAmount

Up Top of Page

IHTMLMarqueeElement::put_scrollAmount

HRESULT put_scrollAmount(
    long v
);

Sets the number of pixels the text scrolls between each subsequent drawing of the MARQUEE.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of pixels.

See also get_scrollAmount


Loop Property

*
  * Previous Topic: IHTMLMarqueeElement::put_loop
  * Next Topic: IHTMLMarqueeElement::put_vspace

IHTMLMarqueeElement::get_loop

HRESULT get_loop(
    long *p
);

Retrieves the number of times the MARQUEE will loop.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of times to loop. This parameter receives -1 if the marquee is set to loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also put_loop

Up Top of Page

IHTMLMarqueeElement::put_loop

HRESULT put_loop(
    long v
);

Sets the number of times the MARQUEE should loop.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of times to loop. If this parameter is -1 (infinite), the marquee will loop continuously.

Below are descriptions on how loop works for some boundary cases.
<BGSOUND src="file:///c:\win95\system\msremind.wav"> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP> | once
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=> | zero times
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=-1> | infinitely
<BGSOUND src="file:///c:\win95\system\msremind.wav" LOOP=0> | once

See also get_loop


Vspace Property

*
  * Previous Topic: IHTMLMarqueeElement::put_vspace
  * Next Topic: IHTMLMarqueeElement::put_hspace

IHTMLMarqueeElement::get_vspace

HRESULT get_vspace(
    long *p
);

Retrieves the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the vertical margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_vspace

Up Top of Page

IHTMLMarqueeElement::put_vspace

HRESULT put_vspace(
    long v
);

Sets the vertical margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_vspace


Hspace Property

*
  * Previous Topic: IHTMLMarqueeElement::put_hspace
  * Next Topic: IHTMLMarqueeElement::put_onfinish

IHTMLMarqueeElement::get_hspace

HRESULT get_hspace(
    long *p
);

Retrieves the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also put_hspace

Up Top of Page

IHTMLMarqueeElement::put_hspace

HRESULT put_hspace(
    long v
);

Sets the horizontal margins for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the horizontal margins.

Similar to border, except the margins are not painted with color when the element is a link.

See also get_hspace


Onfinish Property

*
  * Previous Topic: IHTMLMarqueeElement::put_onfinish
  * Next Topic: IHTMLMarqueeElement::put_onstart

IHTMLMarqueeElement::get_onfinish

HRESULT get_onfinish(
    VARIANT *p
);

Retrieves the inline script associated with the onfinish event on the MARQUEE element. This event is fired when the looping is complete.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onfinish

Up Top of Page

IHTMLMarqueeElement::put_onfinish

HRESULT put_onfinish(
    VARIANT v
);

Sets the inline script associated with the onfinish event on the MARQUEE element. This event is fired when the looping is complete.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onfinish


Onstart Property

*
  * Previous Topic: IHTMLMarqueeElement::put_onstart
  * Next Topic: IHTMLMarqueeElement::put_onbounce

IHTMLMarqueeElement::get_onstart

HRESULT get_onstart(
    VARIANT *p
);

Retrieves the inline script associated with the onstart event on the MARQUEE element. This event is fired when a loop begins, and when a bounce cycle begins for alternate behavior.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onstart

Up Top of Page

IHTMLMarqueeElement::put_onstart

HRESULT put_onstart(
    VARIANT v
);

Sets the inline script associated with the onstart event on the MARQUEE element. This event is fired when a loop begins, and when a bounce cycle begins for alternate behavior.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onstart


Onbounce Property

*
  * Previous Topic: IHTMLMarqueeElement::put_onbounce
  * Next Topic: IHTMLMarqueeElement::put_width

IHTMLMarqueeElement::get_onbounce

HRESULT get_onbounce(
    VARIANT *p
);

Retrieves the inline script associated with the onbounce event on the MARQUEE element. This event is fired when the behavior property of the MARQUEE element is set to "alternate", and the content of the marquee reaches the specified side.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onbounce

Up Top of Page

IHTMLMarqueeElement::put_onbounce

HRESULT put_onbounce(
    VARIANT v
);

Sets the inline script associated with the onbounce event on the MARQUEE element. This event is fired when the behavior property of the MARQUEE element is set to "alternate", and the content of the marquee reaches the specified side.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onbounce


Width Property

*
  * Previous Topic: IHTMLMarqueeElement::put_width
  * Next Topic: IHTMLMarqueeElement::put_height

IHTMLMarqueeElement::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

This read-only property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLMarqueeElement::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Height Property

*
  * Previous Topic: IHTMLMarqueeElement::put_height
  * Next Topic: IHTMLMarqueeElement::put_trueSpeed

IHTMLMarqueeElement::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLMarqueeElement::put_height

HRESULT put_height(
    VARIANT v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


TrueSpeed Property

*
  * Previous Topic: IHTMLMarqueeElement::put_trueSpeed
  * Next Topic: IHTMLMarqueeElement::start

IHTMLMarqueeElement::get_trueSpeed

HRESULT get_trueSpeed(
    VARIANT_BOOL *p
);

Retrieves whether the position of the marquee is calculated using the scrollDelay and scrollAmount properties, and the actual time elapsed from the last clock tick.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a boolean value that has one of the following meanings:
TRUE | The marquee advances the pixel value of scrollAmount per the number of milliseconds (ms) set for scrollDelay. For example, the marquee advances 10 pixels for every 6ms if scrollDelay is 6 and scrollAmount is 10.
FALSE | The marquee computes movement based on 60ms ticks of the clock. This means every scrollDelay value under 60 is essentially ignored, and the marquee advances the amount of scrollAmount each 60ms. For example, if scrollDelay is 6 and scrollAmount is 10, the marquee advances 10 pixels every 60ms.

By default, this property is FALSE.

See also put_trueSpeed

Up Top of Page

IHTMLMarqueeElement::put_trueSpeed

HRESULT put_trueSpeed(
    VARIANT_BOOL v
);

Sets whether the position of the marquee is calculated using the scrollDelay and scrollAmount properties, and the actual time elapsed from the last clock tick.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value that has one of the following meanings:
TRUE | The marquee advances the pixel value of scrollAmount per the number of milliseconds (ms) set for scrollDelay. For example, the marquee advances 10 pixels for every 6ms if scrollDelay is 6 and scrollAmount is 10.
FALSE | The marquee computes movement based on 60ms ticks of the clock. This means every scrollDelay value under 60 is essentially ignored, and the marquee advances the amount of scrollAmount each 60ms. For example, if scrollDelay is 6 and scrollAmount is 10, the marquee advances 10 pixels every 60ms.

By default, this property is FALSE.

See also get_trueSpeed


IHTMLMarqueeElement::start

HRESULT start(
    void
);

Begins scrolling the marquee.

  • Returns S_OK if successful, or an error value otherwise.

See also stop


IHTMLMarqueeElement::stop

HRESULT stop(
    void
);

Stops scrolling the marquee.

  • Returns S_OK if successful, or an error value otherwise.

See also start


IHTMLMetaElement

This interface provides support for client-pull.

This element can be used only within the HEAD tag.

IHTMLMetaElement Methods
put_httpEquiv get_httpEquiv put_content
get_content put_name get_name
put_url get_url put_charset
get_charset


HttpEquiv Property

*
  * Previous Topic: IHTMLMetaElement::put_httpEquiv
  * Next Topic: IHTMLMetaElement::put_content

IHTMLMetaElement::get_httpEquiv

HRESULT get_httpEquiv(
    BSTR *p
);

Binds the content of the element to an HTTP response header.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the HTTP response header.

If omitted, the name property should be used to identify the meta-information. The httpEquiv property is not case sensitive.

See also put_httpEquiv

Up Top of Page

IHTMLMetaElement::put_httpEquiv

HRESULT put_httpEquiv(
    BSTR v
);

Binds the content of the element to an HTTP response header.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the HTTP response header.

If omitted, the name property should be used to identify the meta-information. The httpEquiv property is not case sensitive.

See also get_httpEquiv


Content Property

*
  * Previous Topic: IHTMLMetaElement::put_content
  * Next Topic: IHTMLMetaElement::put_name

IHTMLMetaElement::get_content

HRESULT get_content(
    BSTR *p
);

Retrieves meta-information to be associated with the given name or HTTP response header.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the meta-information.

See also put_content

Up Top of Page

IHTMLMetaElement::put_content

HRESULT put_content(
    BSTR v
);

Sets meta-information to be associated with the given name or HTTP response header.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the meta-information.

See also get_content


Name Property

*
  * Previous Topic: IHTMLMetaElement::put_name
  * Next Topic: IHTMLMetaElement::put_url

IHTMLMetaElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLMetaElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Url Property

*
  * Previous Topic: IHTMLMetaElement::put_url
  * Next Topic: IHTMLMetaElement::put_charset

IHTMLMetaElement::get_url

HRESULT get_url(
    BSTR *p
);

Receives the URL that will be loaded after the specified time has elapsed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_url

Up Top of Page

IHTMLMetaElement::put_url

HRESULT put_url(
    BSTR v
);

Specifies a URL to load after the specified time has elapsed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_url


Charset Property

*
  * Previous Topic: IHTMLMetaElement::put_charset
  * Next Topic: IHTMLMimeTypesCollection

IHTMLMetaElement::get_charset

HRESULT get_charset(
    BSTR *p
);

Retrieves the character set of the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the character set.

See also put_charset

Up Top of Page

IHTMLMetaElement::put_charset

HRESULT put_charset(
    BSTR v
);

Sets the character set of the document.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the character set.

See also get_charset


IHTMLMimeTypesCollection

This interface exists for compatibility with other browsers.

Use IOmNavigator::get_mimeTypes to retrieve an interface pointer for a mime-types collection.

IHTMLMimeTypesCollection::get_length


IHTMLMimeTypesCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in the mime-types collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of elements.


IHTMLNextIdElement

This interface provides the ability access the methods associated with the NEXTID element.

The NEXTID element is a parameter read by and generated by text editing software to create unique identifiers.

This element can only be used within the HEAD tag.

IHTMLNextIdElement Methods


N Property

*
  * Previous Topic: IHTMLNextIdElement::put_n
  * Next Topic: IHTMLNoShowElement

IHTMLNextIdElement::get_n

HRESULT get_n(
    BSTR *p
);

Retrieves the value of the identifier name.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the identifier name.

See also put_n

Up Top of Page

IHTMLNextIdElement::put_n

HRESULT put_n(
    BSTR v
);

Sets the value of the identifier to the string passed in.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the identifier name.

See also get_n


IHTMLNoShowElement

This interface provides access to the properties and methods for this object and is equivalent to the IHTMLElement interface. For more information and a listing of the available methods, see the reference section for the IHTMLElement interface.


IHTMLObjectElement

This interface inserts an object onto the HTML page.

This element is a block element.

IHTMLObjectElement Methods
get_object get_classid get_data
get_recordset put_align get_align
put_name get_name put_codeBase
get_codeBase get_codeType put_code
get_code get_BaseHref put_type
get_type get_form put_width
get_width put_height get_height
get_readyState put_onreadystatechange get_onreadystatechange
put_onerror get_onerror put_altHtml
get_altHtml put_vspace get_vspace
put_hspace put_hspace get_hspace

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLObjectElement::get_object

HRESULT get_object(
    IDispatch **p
);

References the contained OBJECT. For instance, if the control's object model uses a conflicting name space, preceding the control's property with object resolves the conflict

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer for the element.


IHTMLObjectElement::get_classid

HRESULT get_classid(
    BSTR *p
);

Specifies the class identifier for the OBJECT.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the class identifier.

The format is: classid="clsid:controlspecificclsid "


IHTMLObjectElement::get_data

HRESULT get_data(
    BSTR *p
);

Retrieves a URL referencing the object's data.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.


IHTMLObjectElement::get_recordset

HRESULT get_recordset(
    IDispatch **p
);

Retrieves the recordset if the object is a data provider.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the recordset.


Align Property

*
  * Previous Topic: IHTMLObjectElement::put_align
  * Next Topic: IHTMLObjectElement::put_name

IHTMLObjectElement::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLObjectElement::put_align

HRESULT put_align(
    BSTR v
);

Specifies how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


Name Property

*
  * Previous Topic: IHTMLObjectElement::put_name
  * Next Topic: IHTMLObjectElement::put_codeBase

IHTMLObjectElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLObjectElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


CodeBase Property

*
  * Previous Topic: IHTMLObjectElement::put_codeBase
  * Next Topic: IHTMLObjectElement::put_codeType

IHTMLObjectElement::get_codeBase

HRESULT get_codeBase(
    BSTR *p
);

Retrieves a URL referencing where to find the implementation of the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives a string specifying the URL for the object implementation.

See also put_codeBase

Up Top of Page

IHTMLObjectElement::put_codeBase

HRESULT put_codeBase(
    BSTR v
);

Sets a URL referencing where to find the implementation of the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL for the object implementation.

See also get_codeBase


CodeType Property

*
  * Previous Topic: IHTMLObjectElement::put_codeType
  * Next Topic: IHTMLObjectElement::put_code

IHTMLObjectElement::get_codeType

HRESULT get_codeType(
    BSTR *p
);

Retrieves the Internet media type for the code associated with the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the Internet media type.

See also put_codeType

Up Top of Page

IHTMLObjectElement::put_codeType

HRESULT put_codeType(
    BSTR v
);

Sets the Internet media type for the code associated with the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the Internet media type.

See also get_codeType


Code Property

*
  * Previous Topic: IHTMLObjectElement::put_code
  * Next Topic: IHTMLObjectElement::get_BaseHref

IHTMLObjectElement::get_code

HRESULT get_code(
    BSTR *p
);

Retrieves a URL referencing where to find the implementation of the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL.

See also put_code

Up Top of Page

IHTMLObjectElement::put_code

HRESULT put_code(
    BSTR v
);

Sets a URL referencing where to find the implementation of the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_code


IHTMLObjectElement::get_BaseHref

HRESULT get_BaseHref(
    BSTR *p
);

Returns a string of the BASE href where the object tag can be found. This is often the base href of the document that the object is in, or the value set by a BASE tag.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the base href.

The BASE tag is used to ensure that your document's relative links are associated with the proper document path.

<BASE HREF="http://www.sample.com/hello.htm">


Type Property

*
  * Previous Topic: IHTMLObjectElement::put_type
  * Next Topic: IHTMLObjectElement::get_form

IHTMLObjectElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the MIME type of the object. This is used to retrieve a classid for the object when no CLASSID= attribute is given.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the MIME type.

See also put_type

Up Top of Page

IHTMLObjectElement::put_type

HRESULT put_type(
    BSTR v
);

Specifies the MIME type of the object. This is used to retrieve a classid for the object when no CLASSID= attribute is given.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the MIME type.

See also get_type


IHTMLObjectElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


Width Property

*
  * Previous Topic: IHTMLObjectElement::put_width
  * Next Topic: IHTMLObjectElement::put_height

IHTMLObjectElement::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLObjectElement::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


Height Property

*
  * Previous Topic: IHTMLObjectElement::put_height
  * Next Topic: IHTMLObjectElement::get_readyState

IHTMLObjectElement::get_height

HRESULT get_height(
     VARIANT *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLObjectElement::put_height

HRESULT put_height(
    VARIANT v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


IHTMLObjectElement::get_readyState

HRESULT get_readyState(
    long *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states it exposes.


Onreadystatechange Property

*
  * Previous Topic: IHTMLObjectElement::put_onreadystatechange
  * Next Topic: IHTMLObjectElement::put_onerror

IHTMLObjectElement::get_onreadystatechange

HRESULT get_onreadystatechange(
    VARIANT *p
);

Retrieves the inline script associated with the onreadystatechange event on the OBJECT element. This event is fired whenever the readyState for the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onreadystatechange

Up Top of Page

IHTMLObjectElement::put_onreadystatechange

HRESULT put_onreadystatechange(
    VARIANT v
);

Sets the inline script associated with the onreadystatechange event on the OBJECT element. This event is fired whenever the readyState for the object has changed.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onreadystatechange


Onerror Property

*
  * Previous Topic: IHTMLObjectElement::put_onerror
  * Next Topic: IHTMLObjectElement::put_altHtml

IHTMLObjectElement::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event on the OBJECT element. This error event occurs when the loading of the object causes an error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onerror

Up Top of Page

IHTMLObjectElement::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event on the OBJECT element. This error event occurs when the loading of the object causes an error.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onerror


AltHtml Property

*
  * Previous Topic: IHTMLObjectElement::put_altHtml
  * Next Topic: IHTMLObjectElement::put_vspace

IHTMLObjectElement::get_altHtml

HRESULT get_altHtml(
    BSTR *p
);

Returns the string of alternative text that would be displayed for the object if the object is unable to be instantiated, or the browser does not support objects.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the alternative text.

See also put_altHtml

Up Top of Page

IHTMLObjectElement::put_altHtml

HRESULT put_altHtml(
    BSTR v
);

Sets the string of alternative text that could be displayed instead of the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the alternate text.

See also get_altHtml


Vspace Property

*
  * Previous Topic: IHTMLObjectElement::put_vspace
  * Next Topic: IHTMLObjectElement::put_hspace

IHTMLObjectElement::get_vspace

HRESULT get_vspace(
    long *p
);

Returns the amount of vertical space defined in pixels for the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the vertical space.

See also put_vspace

Up Top of Page

IHTMLObjectElement::put_vspace

HRESULT put_vspace(
    long v
);

Sets the amount of vertical space defined in pixels for the object

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the amount of vertical space.

See also get_vspace


Hspace Property

*
  * Previous Topic: IHTMLObjectElement::put_hspace
  * Next Topic: IHTMLOListElement

IHTMLObjectElement::get_hspace

HRESULT get_hspace(
    long *p
);

Returns the amount of horizontal space defined in pixels for the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the horizontal space.

See also put_hspace

Up Top of Page

IHTMLObjectElement::put_hspace

HRESULT put_hspace(
    long v
);

Sets the amount of horizontal space defined in pixels for the object

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the amount of horizontal space.

See also get_hspace


IHTMLOListElement IHTMLOListElement *
  * Previous Topic: IHTMLObjectElement::get_hspace
  * Next Topic: IHTMLOListElement::put_compact

IHTMLOListElement

The interface draws lines of text as an ordered list.

This element is a block element.

IHTMLOListElement Methods


Compact Property

*
  * Previous Topic: IHTMLOListElement::put_compact
  * Next Topic: IHTMLOListElement::put_start

IHTMLOListElement::get_compact

HRESULT get_compact(
    VARIANT_BOOL *p
);

Determines if the list should be compacted to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a Boolean value specifying whether to compact the list of elements. If set to TRUE, the list is compacted; if set to FALSE, it' not.

The default value for this property is FALSE.

See also put_compact

Up Top of Page

IHTMLOListElement::put_compact

HRESULT put_compact(
    VARIANT_BOOL v
);

Specifies that the list should be compacted to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to compact the list of elements. If set to TRUE, the list is compacted; if set to FALSE, it's not.

The default value for this property is FALSE.

See also get_compact


Start Property

*
  * Previous Topic: IHTMLOListElement::put_start
  * Next Topic: IHTMLOListElement::put_type

IHTMLOListElement::get_start

HRESULT get_start(
    long *p
);

Retrieves the starting number for a list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of long integer value specifying the starting point of the list.

See also put_start

Up Top of Page

IHTMLOListElement::put_start

HRESULT put_start(
    long v
);

Sets the starting number for a list.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the starting point of the list.

See also get_start


Type Property

*
  * Previous Topic: IHTMLOListElement::put_type
  * Next Topic: IHTMLOpsProfile

IHTMLOListElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the current style of the list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these style values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also put_type

Up Top of Page

IHTMLOListElement::put_type

HRESULT put_type(
     BSTR v
);

Changes the style of the list.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the style. Can be one of these values:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also get_type


IHTMLOpsProfile

This interface provides methods that requests read access to a user's profile information, and to perform read actions on the userProfile element.

IHTMLOpsProfile Methods


IHTMLOpsProfile::clearRequest

HRESULT clearRequest(void);

Clears the user profile information request. All current user profile request information is removed from the request queue.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLOpsProfile::getAttribute

HRESULT getAttribute(
    BSTR name,
    BSTR *value
);

Returns the value of the named attribute for the user profile. If read access for this attribute is not already available, this method simply returns the NULL string.

  • Returns S_OK if successful, or an error value otherwise.
name
String value specifying the name for the user profile.
value
Address of a string variable that receives the value.


IHTMLOpsProfile::addReadRequest

HRESULT addReadRequest(
    BSTR name,
    VARIANT reserved,
    VARIANT_BOOL *success
);

Adds a name entry to the read request queue.

  • Returns S_OK if successful, or an error value otherwise.
name
String value containing the name to add the request queue.
reserved
Reserved; do not use.
success
Address of a variable that receives TRUE if the request was successfully added to the queue, or FALSE otherwise. This could mean that either the attribute name was not recognized or the attribute is already present in the request queue.

See also doReadRequest


IHTMLOpsProfile::doReadRequest

HRESULT doReadRequest(
    VARIANT usage,
    VARIANT fname,
    VARIANT domain,
    VARIANT path,
    VARIANT expire,
    VARIANT reserved
);

Performs the compound request accumulated in the read request queue.

  • Returns S_OK if successful, or an error value otherwise.
usage
Type of access requested. This usage code should be one of the 13 codes defined by the Internet Privacy Working Group (IPWG), as described in the following table.
Usage code | Meaning
0 | Used for system administration.
1 | Used for research and/or product development.
2 | Used for completion and support of current transaction.
3 | Used to customize the content and design of a site.
4 | Used to improve the content of a site including advertisements.
5 | Used for notifying visitors about updates to the site.
6 | Used for contacting visitors for marketing of services or products.
7 | Used for linking other collected information.
8 | Used by a site for other purposes.
9 | Disclosed to others for customization or improvement of the content and design of the site.
10 | Disclosed to others, who may contact you, for marketing of services and/or products.
11 | Disclosed to others, who may contact you, for marketing of services and/or products, but you will have the opportunity to ask a site not to do this.
12 | Disclosed to others for any other purpose.
fname
Optional. "Friendly name" of the party requesting access to private information. For security reasons, it is not enough for the user agent to display this friendly name to the end user. In addition to this friendly name, it is essential to display the URL that originates the script requesting profile access. If this script originates from a secure connection (for example, SSL), the SSL certificate can also be used to reliably identify the party requesting access.
domain
Optional. Which pages the user's choice will apply to in the future, besides the current one; the specification follows the cookie standard (RFC-2109 http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html).
path
Optional. Which pages the user's choice will apply to in the future, besides the current one; the specification follows the cookie standard (RFC-2109 http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html).
expire
Reserved; do not use.
reserved
Reserved; do not use.

See also addReadRequest


IHTMLOptionButtonElement

This interface specifies a form input control.

IHTMLOptionButtonElement Methods
put_value get_value get_type
put_name get_name put_checked
get_checked put_defaultChecked get_defaultChecked
put_onchange get_onchange put_disabled
get_disabled put_status get_status
put_indeterminate get_indeterminate get_form

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Value Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_value
  * Next Topic: IHTMLOptionButtonElement::get_type

IHTMLOptionButtonElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value. This read-write property can be any valid string. The purpose of the string depends on the type of control, as described in the following table.
Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also put_value

Up Top of Page

IHTMLOptionButtonElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the default or "selected" value of the given control.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value. The purpose of the string depends on the type of control, as described in the following table.
Control Type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also get_value


IHTMLOptionButtonElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. The possible values depend on the element as listed in the following table.

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Name Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_name
  * Next Topic: IHTMLOptionButtonElement::put_checked

IHTMLOptionButtonElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLOptionButtonElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Checked Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_checked
  * Next Topic: IHTMLOptionButtonElement::put_defaultChecked

IHTMLOptionButtonElement::get_checked

HRESULT get_checked(
    VARIANT_BOOL *p
);

Retrieves whether the given check box or radio button is selected.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the button is selected, or FALSE otherwise. The default value for this property is FALSE.

Check boxes that are not selected do not return their values when the form is submitted.

See also put_checked

Up Top of Page

IHTMLOptionButtonElement::put_checked

HRESULT put_checked(
    VARIANT_BOOL v
);

Sets whether the given check box or radio button is selected.

  • Returns S_OK if successful, or an error value otherwise.
v
Select flag. Set this parameter to TRUE to select the button, or FALSE otherwise.

Check boxes that are not selected do not return their values when the form is submitted.

See also get_checked


DefaultChecked Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_defaultChecked
  * Next Topic: IHTMLOptionButtonElement::put_onchange

IHTMLOptionButtonElement::get_defaultChecked

HRESULT get_defaultChecked(
    VARIANT_BOOL *p
);

Determines whether the check box or radio button is selected by default.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the button is selected by default, or FALSE otherwise.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

The default value for this property is TRUE.

See also put_defaultChecked

Up Top of Page

IHTMLOptionButtonElement::put_defaultChecked

HRESULT put_defaultChecked(
    VARIANT_BOOL v
);

Determines whether the check box or radio button is selected by default.

  • Returns S_OK if successful, or an error value otherwise.
v
Selection flag. Set this value to TRUE to select the button, or FALSE otherwise.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

See also get_defaultChecked


Onchange Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_onchange
  * Next Topic: IHTMLOptionButtonElement::put_disabled

IHTMLOptionButtonElement::get_onchange

HRESULT get_onchange(
    VARIANT *p
);

Retrieves the inline script associated with the onchange event on the OptionButtonElement. This event occurs when the contents of the object have changed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_onchange

Up Top of Page

IHTMLOptionButtonElement::put_onchange

HRESULT put_onchange(
    VARIANT v
);

Sets the inline script associated with the onchange event on the OptionButtonElement. This event occurs when the contents of the object have changed.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_onchange


Disabled Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_disabled
  * Next Topic: IHTMLOptionButtonElement::put_status

IHTMLOptionButtonElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLOptionButtonElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


Status Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_status
  * Next Topic: IHTMLOptionButtonElement::put_indeterminate

IHTMLOptionButtonElement::get_status

HRESULT get_status(
    VARIANT_BOOL *p
);

Retrieves the value of a check box or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a value that receives the status. It can be either TRUE or FALSE.

See also put_status

Up Top of Page

IHTMLOptionButtonElement::put_status

HRESULT put_status(
    VARIANT_BOOL v
);

Sets the value of a check box or radio button. This property is equivalent to the value property for check boxes and radio buttons.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the status. It can be either TRUE or FALSE.

See also get_status


Indeterminate Property

*
  * Previous Topic: IHTMLOptionButtonElement::put_indeterminate
  * Next Topic: IHTMLOptionButtonElement::get_form

IHTMLOptionButtonElement::get_indeterminate

HRESULT get_indeterminate(
    VARIANT_BOOL *p
);

Retrieves whether the check box is in the indeterminate state. An indeterminate check box has a dimmed background to represent an indeterminate state.

When indeterminate is set, the check box appears checked, but dimmed. The value of indeterminate is independent of the values for the checked and status properties.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a value that receives TRUE if the check box is indeterminate, or FALSE otherwise.

This does not change whether the check box is marked as checked, and is different than disabling the control. A check box in the indeterminate state can still receive the focus. When the user clicks an indeterminate button, the indeterminate state is turned off and the check box is appropriately checked or unchecked.

The default value for this property is FALSE.

See also put_indeterminate

Up Top of Page

IHTMLOptionButtonElement::put_indeterminate

HRESULT put_indeterminate(
    VARIANT_BOOL v
);

Changes the user interface of a check box to have a dimmed background to represent an indeterminate state.

When indeterminate is set, the check box appears checked, but dimmed. The value of indeterminate is independent of the values for the checked and status properties.

  • Returns S_OK if successful, or an error value otherwise.
v
Indeterminate flag. If TRUE, the check box is indeterminate.

This does not change whether the check box is marked as checked, and is different than disabling the control. A check box in the indeterminate state can still receive the focus. When the user clicks an indeterminate button, the indeterminate state is turned off and the check box is appropriately checked or unchecked.

The default value for this property is FALSE.

See also get_indeterminate


IHTMLOptionButtonElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLOptionElement

This interface denotes one choice in a SELECT block.

This element is a block element.

IHTMLOptionElement Methods
put_selected get_selected put_value
get_value put_defaultSelected get_defaultSelected
put_index get_index put_text
get_text get_form

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Selected Property

*
  * Previous Topic: IHTMLOptionElement::put_selected
  * Next Topic: IHTMLOptionElement::put_value

IHTMLOptionElement::get_selected

HRESULT get_selected(
    VARIANT_BOOL *p
);

Indicates whether this item is the default.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the item is the default, or FALSE if not.

This attribute is used to determine whether a value is submitted with the form. If the value of the control matches the default value, the control's value is not submitted. The value is only submitted when the control's value does not match the default value. Therefore, changing this value changes the rule for whether the value is submitted with the form.

The first item is selected by default.

See also put_selected

Up Top of Page

IHTMLOptionElement::put_selected

HRESULT put_selected(
    VARIANT_BOOL v
);

Indicates whether this item is the default.

  • Returns S_OK if successful, or an error value otherwise.
v
Selected flag. Setting this parameter to TRUE selects the item; setting it to FALSE deselects it.

This attribute is used to determine whether a value is submitted with the form. If the value of the control matches the default value, the control's value is not submitted. The value is only submitted when the control's value does not match the default value. Therefore, changing this value changes the rule for whether the value is submitted with the form.

The first item is selected by default.

See also get_selected


Value Property

*
  * Previous Topic: IHTMLOptionElement::put_value
  * Next Topic: IHTMLOptionElement::put_defaultSelected

IHTMLOptionElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the value of the given control. The value is submitted to the server as a name/value pair.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a variable that receives the value. It can be any valid string. The purpose of the string depends on the type of control, as described in the following table.
Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also put_value

Up Top of Page

IHTMLOptionElement::put_value

HRESULT put_value(
    BSTR v
);

Specifies the value of the given control. The value is submitted to the server as a name/value pair.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value. It can be any valid string. The purpose of the string depends on the type of control, as described in the following table.
Control type | Description
checkbox | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
file | The value, a file name, typed by the user into the control. Unlike other controls, this value is read-only.
hidden | The control submits this value when the form is submitted.
OPTION | The "selected" value. The containing list box control submits this value only if the user has selected the option.
password | The default value. The control displays this value when it is first created and when the user clicks the reset button.
radio | The "selected" value. The control submits this value only if the user has selected the control. Otherwise, the control submits no value.
reset | The button label. If not set, the label defaults to "Reset".
submit | The button label. If not set, the label defaults to "Submit".
text | The default value. The control displays this value when it is first created and when the user clicks the reset button.

See also get_value


DefaultSelected Property

*
  * Previous Topic: IHTMLOptionElement::put_defaultSelected
  * Next Topic: IHTMLOptionElement::put_index

IHTMLOptionElement::get_defaultSelected

HRESULT get_defaultSelected(
    VARIANT_BOOL *p
);

Determines whether the option is selected by default.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a variable that receives TRUE if the option is selected by default, or FALSE if not.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

The default value for this property is TRUE.

See also put_defaultSelected

Up Top of Page

IHTMLOptionElement::put_defaultSelected

HRESULT put_defaultSelected(
    VARIANT_BOOL v
);

Specifies whether the option is selected by default.

  • Returns S_OK if successful, or an error value otherwise.
v
Selection flag. TRUE selects the option; FALSE deselects it.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

The default value for this property is TRUE.

See also get_defaultSelected


Index Property

*
  * Previous Topic: IHTMLOptionElement::put_index
  * Next Topic: IHTMLOptionElement::put_text

IHTMLOptionElement::get_index

HRESULT get_index(
    LONG *p
);

Retrieves the ordinal position of the option in the list box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the ordinal position.

You can assign a value to this property without generating a syntax error, but the value is not stored.

See also put_index

Up Top of Page

IHTMLOptionElement::put_index

HRESULT put_index(
    LONG v
);

Sets the ordinal position of the option in the list box.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the ordinal position.

You can assign a value to this property without generating a syntax error, but the value is not stored.

See also get_index


Text Property

*
  * Previous Topic: IHTMLOptionElement::put_text
  * Next Topic: IHTMLOptionElement::get_form

IHTMLOptionElement::get_text

HRESULT get_text(
    BSTR *p
);

Retrieves the text string specified by the OPTION tag.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the string.

Assigning a value to the text property changes the text property internally but does not cause the listed value to change. Submitting the form submits the internally stored value, not the one displayed.

See also put_text

Up Top of Page

IHTMLOptionElement::put_text

HRESULT put_text(
    BSTR v
);

Sets the text string specified by the OPTION tag.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text.

Assigning a value to the text property changes the text property internally but does not cause the listed value to change. Submitting the form submits the internally stored value, not the one displayed.

See also get_text


IHTMLOptionElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLOptionElementFactory

This interface creates new instances of the OPTION element.

Use IHTMLWindow2::get_Option to retrieve a pointer to this interface.

IHTMLOptionElementFactory::create


IHTMLOptionElementFactory::create

HRESULT create(
    VARIANT text,
    VARIANT value,
    VARIANT defaultselected,
    VARIANT selected,
    IHTMLOptionElement **__MIDL_0017
);

Creates a new instance of the OPTION element. You can add the element to a SELECT block by using the IHTMLSelectElement::add method.

  • Returns S_OK if successful, or an error value otherwise.
text
Value or string specifying the text of the element.
value
String specifying the value of the element.
defaultselected
Value indicating whether this option is selected by default. If TRUE, this option is selected by default; otherwise, it isn't.
selected
Value indicating whether this is the default option in the SELECT block. If TRUE, this option is the default; otherwise, it isn't.
__MIDL_0017
Address of a variable that receives an interface pointer for the new OPTION element.

See also IHTMLOptionElement, IHTMLSelectElement::add


IHTMLOptionsHolder

This interface provides the access methods to pass and control the contents and characteristics of a dialog window.

This object is a container for various options that can to be passed as arguments into a dialog windows presented from the browser.

IHTMLOptionsHolder Methods
get_document get_fonts put_execArg
get_execArg put_errorLine get_errorLine
put_errorCharacter get_errorCharacter put_errorCode
get_errorCode put_errorMessage get_errorMessage
put_errorDebug get_errorDebug put_productVersion
get_productVersion get_unsecuredWindowOfDocument put_findText
get_findText sizes openfiledlg
savefiledlg choosecolordlg showSecurityInfo

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLOptionsHolder::get_document

HRESULT get_document(
    IHTMLDocument2 **p
);

Returns a pointer to the document that the dialog is parented by.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the IHTMLDocument2 object.


IHTMLOptionsHolder::get_fonts

HRESULT get_fonts(
    IHTMLFontNamesCollection **p
);

Returns a IHTMLFontNamesCollection pointer for a collection of all the system-supported fonts.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the IHTMLFontNamesCollection object.


ExecArg Property

*
  * Previous Topic: IHTMLOptionsHolder::put_execArg
  * Next Topic: IHTMLOptionsHolder::put_errorLine

IHTMLOptionsHolder::get_execArg

HRESULT get_execArg(
    VARIANT *p
);

Retrieves the variant argument of any additional parameters that were passed in.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the arguments.

See also put_execArg

Up Top of Page

IHTMLOptionsHolder::put_execArg

HRESULT put_execArg(
    VARIANT v
);

Sets the variant argument; this allows additional user-data parameters to be passed in.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_execArg


ErrorLine Property

*
  * Previous Topic: IHTMLOptionsHolder::put_errorLine
  * Next Topic: IHTMLOptionsHolder::put_errorCharacter

IHTMLOptionsHolder::get_errorLine

HRESULT get_errorLine(
    long *p
);

Retrieves the inline script associated with the onerror event on the IHTMLOptionsHolder element. This value indicates the line number that an error occurred at and is generally used to report script errors.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also put_errorLine

Up Top of Page

IHTMLOptionsHolder::put_errorLine

HRESULT put_errorLine(
    long v
);

Sets the inline script associated with the onerror event on the IHTMLOptionsHolder element. This value indicates the line number that an error occurred at and is generally used to report script errors.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

For more information on inline script, see Attaching an Event Handler in the Understanding the Event Model documentation.

See also get_errorLine


ErrorCharacter Property

*
  * Previous Topic: IHTMLOptionsHolder::put_errorCharacter
  * Next Topic: IHTMLOptionsHolder::put_errorCode

IHTMLOptionsHolder::get_errorCharacter

HRESULT get_errorCharacter(
    long *p
);

Retrieves the count of the character on the line where an error occurred.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the error code.

See also put_errorCharacter

Up Top of Page

IHTMLOptionsHolder::put_errorCharacter

HRESULT put_errorCharacter(
    long v
);

Sets the count of the character on the line where an error occurred.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the error code.

See also get_errorCharacter


ErrorCode Property

*
  * Previous Topic: IHTMLOptionsHolder::put_errorCode
  * Next Topic: IHTMLOptionsHolder::put_errorMessage

IHTMLOptionsHolder::get_errorCode

HRESULT get_errorCode(
    long *p
);

Retrieves the current error code for the error being reported.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the error code.

See also put_errorCode

Up Top of Page

IHTMLOptionsHolder::put_errorCode

HRESULT put_errorCode(
    long v
);

Sets the error code for the error being reported.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the error code.

See also get_errorCode


ErrorMessage Property

*
  * Previous Topic: IHTMLOptionsHolder::put_errorMessage
  * Next Topic: IHTMLOptionsHolder::put_errorDebug

IHTMLOptionsHolder::get_errorMessage

HRESULT get_errorMessage(
    BSTR *p
);

Retrieves the string text of the error message to be displayed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the error text.

See also put_errorMessage

Up Top of Page

IHTMLOptionsHolder::put_errorMessage

HRESULT put_errorMessage(
    BSTR v
);

Sets the string text for the error message to be displayed.

  • Returns S_OK if successful, or an error value otherwise.
v
String variable specifying the error text.

See also get_errorMessage


ErrorDebug Property

*
  * Previous Topic: IHTMLOptionsHolder::put_errorDebug
  * Next Topic: IHTMLOptionsHolder::put_productVersion

IHTMLOptionsHolder::get_errorDebug

HRESULT get_errorDebug(
    VARIANT_BOOL *p
);

Retrieves the Boolean value indicating whether to debug this error.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE to debug this error, or FALSE to not.

See also put_errorDebug

Up Top of Page

IHTMLOptionsHolder::put_errorDebug

HRESULT put_errorDebug(
    VARIANT_BOOL v
);

Set the Boolean value indicating whether to debug this error or not.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to debug this error. If set to TRUE, the error is debugged; if FALSE, it is not.

See also get_errorDebug


ProductVersion Property

*
  * Previous Topic: IHTMLOptionsHolder::put_productVersion
  * Next Topic: IHTMLOptionsHolder::get_unsecuredWindowOfDocument

IHTMLOptionsHolder::get_productVersion

HRESULT get_productVersion(
    BSTR *p
);

Retrieves the string indicating the product version information.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the product version information.

See also put_productVersion

Up Top of Page

IHTMLOptionsHolder::put_productVersion

HRESULT put_productVersion(
    BSTR v
);

Sets the string indicating the product version information.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the product version information.

See also get_productVersion


IHTMLOptionsHolder::get_unsecuredWindowOfDocument

HRESULT get_unsecuredWindowOfDocument(
    IHTMLWindow2 **p
);

Retrieves the IHTMLWindow2 interface pointer to the parent document's window. This in not wrapped by a security proxy, thus is not considered secure.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer for the IHTMLWindow2 interface.


FindText Property

*
  * Previous Topic: IHTMLOptionsHolder::put_findText
  * Next Topic: IHTMLOptionsHolder::sizes

IHTMLOptionsHolder::get_findText

HRESULT get_findText(
    BSTR *p
);

Retrieves the text used in a find operation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that contains the text used for the search operation.

See also put_findText

Up Top of Page

IHTMLOptionsHolder::put_findText

HRESULT put_findText(
    BSTR v
);

Sets the text with which to seed a find operation.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the text used for the search operation.

See also get_findText


IHTMLOptionsHolder::sizes

HRESULT sizes(
    BSTR fontName,
    IHTMLFontSizesCollection **pSizesCollection
);

Receives the IHTMLFontSizesCollection pointer to a collection of the sizes available for the font that is passed in as a parameter.

  • Returns S_OK if successful, or an error value otherwise.
fontName
String value specifying the name of the font from which to obtain the font size information.
pSizesCollection
Address of a variable that receives the interface pointer for the IHTMLFontSizesCollection element.


IHTMLOptionsHolder::openfiledlg

HRESULT openfiledlg(
    VARIANT initFile,
    VARIANT initDir,
    VARIANT filter,
    VARIANT title,
    BSTR *pathName
);

Opens the system open file dialog window.

  • Returns S_OK if successful, or an error value otherwise.
initFile
VARIANT structure containing the initial file name to open.
initDir
VARIANT structure containing the initial directory to open.
filter
VARIANT structure containing the filters to use in opening the file.
title
VARIANT structure containing the initial title for the file dialog window.
pathName
String variable specifying the path for the file to be opened.

See also savefiledlg


IHTMLOptionsHolder::savefiledlg

HRESULT savefiledlg(
    VARIANT initFile,
    VARIANT initDir,
    VARIANT filter,
    VARIANT title,
    BSTR *pathName
);

Opens the system save file dialog.

  • Returns S_OK if successful, or an error value otherwise.
initFile
VARIANT structure containing the file name to save the file.
initDir
VARIANT structure containing the directory to save the file.
filter
VARIANT structure containing the filters to use in saving the file.
title
VARIANT structure containing the initial title for the file dialog window.
pathName
String variable specifying the path for the file to be saved.


IHTMLOptionsHolder::choosecolordlg

HRESULT choosecolordlg(
    VARIANT initColor,
    long *rgbColor
);

Opens the system color picker dialog box.

  • Returns S_OK if successful, or an error value otherwise.
initColor
VARIANT containing the name of the color in the color picker. For a complete list of colors, see Color Table.
rgbColor
Long integer specifying the value of the color in the color picker. For a complete list of colors, see Color Table.


IHTMLOptionsHolder::showSecurityInfo

HRESULT showSecurityInfo(
    void
);

Opens the Internet security information dialog box for the zone based on the document's URL.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLParaElement IHTMLParaElement *
  * Previous Topic: IHTMLOptionsHolder::showSecurityInfo
  * Next Topic: IHTMLParaElement::put_align

IHTMLParaElement

This interface denotes a paragraph.

This element is a block element.

IHTMLParaElement Methods


Align Property

*
  * Previous Topic: IHTMLParaElement::put_align
  * Next Topic: IHTMLPhraseElement

IHTMLParaElement::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also put_align

Up Top of Page

IHTMLParaElement::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Align to the center.
left | Align to the left edge.
right | Align to the right edge.

See also get_align


IHTMLPhraseElement

This interface provides access to the properties and methods for this object and is equivalent to the IHTMLElement interface. For more information and a listing of the available methods, see the reference section for the IHTMLElement interface.


IHTMLPluginsCollection

This interface provides access to a zero-based collection of all the EMBED elements in an HTML document. The elements are in the same order as they appear in the document. Use the IOmNavigator::get_plugins property to retrieve an interface pointer of this type.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be referenced only by ordinal position.

IHTMLPluginsCollection Methods


IHTMLPluginsCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in the collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of elements.


IHTMLPluginsCollection::refresh

HRESULT refresh(
    VARIANT_BOOL reload
);

Refreshes the content of the collection.

  • Returns S_OK if successful, or an error value otherwise.
reload
Boolean value specifying whether to reload the document.


IHTMLRuleStyle

This interface provides access to the methods that are returned when you access style property of a rule. This serves the same purpose as IHTMLStyle but in the context of a particular rule.

IHTMLRuleStyle Methods
put_fontFamily get_fontFamily put_fontStyle
get_fontStyle put_fontVariant get_fontVariant
put_fontWeight get_fontWeight put_fontSize
get_fontSize put_font get_font
put_color get_color put_background
get_background put_backgroundColor get_backgroundColor
put_backgroundImage get_backgroundImage put_backgroundRepeat
get_backgroundRepeat put_backgroundAttachment get_backgroundAttachment
put_backgroundPosition get_backgroundPosition put_backgroundPositionX
get_backgroundPositionX put_backgroundPositionY get_backgroundPositionY
put_wordSpacing get_wordSpacing put_letterSpacing
get_letterSpacing put_textDecoration get_textDecoration
put_textDecorationNone get_textDecorationNone put_textDecorationUnderline
get_textDecorationUnderline put_textDecorationOverline get_textDecorationOverline
put_textDecorationLineThrough get_textDecorationLineThrough put_textDecorationBlink
get_textDecorationBlink put_verticalAlign get_verticalAlign
put_textTransform get_textTransform put_textAlign
get_textAlign put_textIndent get_textIndent
put_lineHeight get_lineHeight put_marginTop
get_marginTop put_marginRight get_marginRight
put_marginBottom get_marginBottom put_marginLeft
get_marginLeft put_margin get_margin
put_paddingTop get_paddingTop put_paddingRight
get_paddingRight put_paddingBottom get_paddingBottom
put_paddingLeft get_paddingLeft put_padding
get_padding put_border get_border
put_borderTop get_borderTop put_borderRight
get_borderRight put_borderBottom get_borderBottom
put_borderLeft get_borderLeft put_borderColor
get_borderColor put_borderTopColor get_borderTopColor
put_borderRightColor get_borderRightColor put_borderBottomColor
get_borderBottomColor put_borderLeftColor get_borderLeftColor
put_borderWidth get_borderWidth put_borderTopWidth
get_borderTopWidth put_borderRightWidth get_borderRightWidth
put_borderBottomWidth get_borderBottomWidth put_borderLeftWidth
get_borderLeftWidth put_borderStyle get_borderStyle
put_borderTopStyle get_borderTopStyle put_borderRightStyle
get_borderRightStyle put_borderBottomStyle get_borderBottomStyle
put_borderLeftStyle get_borderLeftStyle put_width
get_width put_height get_height
put_styleFloat get_styleFloat put_clear
get_clear put_display get_display
put_visibility get_visibility put_listStyleType
get_listStyleType put_listStylePosition get_listStylePosition
put_listStyleImage get_listStyleImage put_listStyle
get_listStyle put_whiteSpace get_whiteSpace
put_top get_top put_left
get_left get_position put_zIndex
get_zIndex put_overflow get_overflow
put_pageBreakBefore get_pageBreakBefore put_pageBreakAfter
get_pageBreakAfter put_cssText get_cssText
put_cursor get_cursor put_clip
get_clip put_filter get_filter
setAttribute getAttribute removeAttribute

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


FontFamily Property

*
  * Previous Topic: IHTMLRuleStyle::put_fontFamily
  * Next Topic: IHTMLRuleStyle::put_fontStyle

IHTMLRuleStyle::get_fontFamily

HRESULT get_fontFamily(
    BSTR *p
);

Retrieves the value of the CSS font-family attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See font-family for details. This parameter receives NULL if the attribute is not set.

See also put_fontFamily

Up Top of Page

IHTMLRuleStyle::put_fontFamily

HRESULT put_fontFamily(
    BSTR v
);

Sets the value of the CSS font-family attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font family, or NULL to remove the attribute. See font-family for details.

See also get_fontFamily


FontStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_fontStyle
  * Next Topic: IHTMLRuleStyle::put_fontVariant

IHTMLRuleStyle::get_fontStyle

HRESULT get_fontStyle(
    BSTR *p
);

Retrieves the value of the CSS font-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
italic
oblique
See font-style for details. This parameter receives NULL if the attribute is not set.

See also put_fontStyle

Up Top of Page

IHTMLRuleStyle::put_fontStyle

HRESULT put_fontStyle(
    BSTR v
);

Sets the value of the CSS font-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font style, or NULL to remove the attribute. The font style can be one of these strings:
normal
italic
oblique
See font-style for details.

See also get_fontStyle


FontVariant Property

*
  * Previous Topic: IHTMLRuleStyle::put_fontVariant
  * Next Topic: IHTMLRuleStyle::put_fontWeight

IHTMLRuleStyle::get_fontVariant

HRESULT get_fontVariant(
    BSTR *p
);

Retrieves the value of the CSS font-variant attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
small-caps
See font-variant for details. This parameter receives NULL if the attribute is not set.

See also put_fontVariant

Up Top of Page

IHTMLRuleStyle::put_fontVariant

HRESULT put_fontVariant(
    BSTR v
);

Sets the value of the CSS font-variant attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font variation, or NULL to remove the attribute. The font variation can be one of these strings:
normal
small-caps
See font-variant for details.

See also get_fontVariant


FontWeight Property

*
  * Previous Topic: IHTMLRuleStyle::put_fontWeight
  * Next Topic: IHTMLRuleStyle::put_fontSize

IHTMLRuleStyle::get_fontWeight

HRESULT get_fontWeight(
    BSTR *p
);

Retrieves the value of the CSS font-weight attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900
See font-weight for details. This parameter receives NULL if the attribute is not set.

See also put_fontWeight

Up Top of Page

IHTMLRuleStyle::put_fontWeight

HRESULT put_fontWeight(
    BSTR v
);

Sets the value of the CSS font-weight attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font weight, or NULL to remove the attribute. The font weight can be one of these strings:
normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900
See font-weight for details.

See also get_fontWeight


FontSize Property

*
  * Previous Topic: IHTMLRuleStyle::put_fontSize
  * Next Topic: IHTMLRuleStyle::put_font

IHTMLRuleStyle::get_fontSize

HRESULT get_fontSize(
    VARIANT *p
);

Retrieves the value of the CSS font-size attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See font-size for details. This parameter receives NULL if the attribute is not set.

See also put_fontSize

Up Top of Page

IHTMLRuleStyle::put_fontSize

HRESULT put_fontSize(
    VARIANT v
);

Sets the value of the CSS font-size attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font size, or NULL to remove the attribute. See font-size for details.

See also get_fontSize


Font Property

*
  * Previous Topic: IHTMLRuleStyle::put_font
  * Next Topic: IHTMLRuleStyle::put_color

IHTMLRuleStyle::get_font

HRESULT get_font(
    BSTR *p
);

Retrieves the values of the CSS font-style, font-variant, font-weight, font-size, line-height, and font-family attributes for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the values of the font-related CSS attributes. See font for details. This parameter receives NULL if no font-related CSS attributes are set for the element.

See also put_font

Up Top of Page

IHTMLRuleStyle::put_font

HRESULT put_font(
    BSTR v
);

Sets the value of the CSS font-style, font-variant, font-weight, font-size, line-height, and font-family attributes for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying values for one or more font attributes. This parameter has the following format:
[<font-style> || <font-variant> || <font-weight>] <font-size> /
[<line-height>] <font-family>
See font for details.

See also get_font


Color Property

*
  * Previous Topic: IHTMLRuleStyle::put_color
  * Next Topic: IHTMLRuleStyle::put_background

IHTMLRuleStyle::get_color

HRESULT get_color(
    VARIANT *p
);

Retrieves the value of the CSS color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See color for details. This parameter receives NULL if the attribute is not set.

See also put_color

Up Top of Page

IHTMLRuleStyle::put_color

HRESULT put_color(
    VARIANT v
);

Sets the CSS color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color, or NULL to remove the attribute. The color can be one of the color names or values given in the Color Table reference documentation. See color for details.

See also get_color


Background Property

*
  * Previous Topic: IHTMLRuleStyle::put_background
  * Next Topic: IHTMLRuleStyle::put_backgroundColor

IHTMLRuleStyle::get_background

HRESULT get_background(
    BSTR *p
);

Retrieves the value of the CSS background attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background for details. This parameter receives NULL if the attribute is not set.

See also put_background

Up Top of Page

IHTMLRuleStyle::put_background

HRESULT put_background(
    BSTR v
);

Sets the value of the CSS background attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute, or NULL to remove it. See background for details.

See also get_background


BackgroundColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundColor
  * Next Topic: IHTMLRuleStyle::put_backgroundImage

IHTMLRuleStyle::get_backgroundColor

HRESULT get_backgroundColor(
    VARIANT *p
);

Retrieves the value of the CSS background-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-color for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundColor

Up Top of Page

IHTMLRuleStyle::put_backgroundColor

HRESULT put_backgroundColor(
    VARIANT v
);

Sets the CSS background-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the background color, or NULL to remove the attribute. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_backgroundColor


BackgroundImage Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundImage
  * Next Topic: IHTMLRuleStyle::put_backgroundRepeat

IHTMLRuleStyle::get_backgroundImage

HRESULT get_backgroundImage(
    BSTR *p
);

Retrieves the value of the CSS background-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundImage

Up Top of Page

IHTMLRuleStyle::put_backgroundImage

HRESULT put_backgroundImage(
    BSTR v
);

Sets a CSS background-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL of the background image, or NULL to remove the attribute. See background-image for details.

See also get_backgroundImage


BackgroundRepeat Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundRepeat
  * Next Topic: IHTMLRuleStyle::put_backgroundAttachment

IHTMLRuleStyle::get_backgroundRepeat

HRESULT get_backgroundRepeat(
    BSTR *p
);

Retrieves the value of the CSS background-repeat attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
norepeat | Do not repeat.
repeaty | Repeat vertically.
repeat | Repeat both horizontally and vertically.
repeatx | Repeat horizontally.
See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundRepeat

Up Top of Page

IHTMLRuleStyle::put_backgroundRepeat

HRESULT put_backgroundRepeat(
    BSTR v
);

Sets the value of the CSS background-repeat attribute for the element. The attribute determines whether and how the background image, if any, is repeated.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether and how the image is repeated, or NULL to remove the attribute. Can be one of these strings:
norepeat | Do not repeat.
repeaty | Repeat vertically.
repeat | Repeat both horizontally and vertically.
repeatx | Repeat horizontally.
See background-repeat for details.

See also get_backgroundRepeat


BackgroundAttachment Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundAttachment
  * Next Topic: IHTMLRuleStyle::put_backgroundPosition

IHTMLRuleStyle::get_backgroundAttachment

HRESULT get_backgroundAttachment(
    BSTR *p
);

Retrieves the value of the CSS background-attachment attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
fixed | Background image remains fixed.
scroll | Background image scrolls with text.
See background-attachment for details.

See also put_backgroundAttachment

Up Top of Page

IHTMLRuleStyle::put_backgroundAttachment

HRESULT put_backgroundAttachment(
    BSTR v
);

Sets the value of the CSS background-attachment attribute for the element. If the element has a background image, this attribute determines if the image is fixed with regard to the text of the element, or if it scrolls with the text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute, or NULL to remove it. Can be one of these strings:
fixed | Background image remains fixed.
scroll | Background image scrolls with text.
See background-attachment for details.

See also get_backgroundAttachment


BackgroundPosition Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundPosition
  * Next Topic: IHTMLRuleStyle::put_backgroundPositionX

IHTMLRuleStyle::get_backgroundPosition

HRESULT get_backgroundPosition(
    BSTR *p
);

Retrieves the value of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-position for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundPosition

Up Top of Page

IHTMLRuleStyle::put_backgroundPosition

HRESULT put_backgroundPosition(
    BSTR v
);

Sets the value of the CSS background-position attribute for the element. The attribute determines the initial position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the initial background position, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPosition


BackgroundPositionX Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundPositionX
  * Next Topic: IHTMLRuleStyle::put_backgroundPositionY

IHTMLRuleStyle::get_backgroundPositionX

HRESULT get_backgroundPositionX(
    VARIANT *p
);

Retrieves the x-coordinate of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the x-coordinate. See background-image for details. This parameter receives NULL if the parameter is not set.

See also put_backgroundPositionX

Up Top of Page

IHTMLRuleStyle::put_backgroundPositionX

HRESULT put_backgroundPositionX(
    VARIANT v
);

Sets the x-coordinate of the CSS background-position attribute for the element. The attribute determines the initial horizontal position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the x-coordinate, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPositionX


BackgroundPositionY Property

*
  * Previous Topic: IHTMLRuleStyle::put_backgroundPositionY
  * Next Topic: IHTMLRuleStyle::put_wordSpacing

IHTMLRuleStyle::get_backgroundPositionY

HRESULT get_backgroundPositionY(
    VARIANT *p
);

Retrieves the y-coordinate of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the y-coordinate. See background-position for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundPositionY

Up Top of Page

IHTMLRuleStyle::put_backgroundPositionY

HRESULT put_backgroundPositionY(
    VARIANT v
);

Sets the y-coordinate of the CSS background-position attribute for the element. The attribute determines the initial vertical position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the y-coordinate, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPositionY


WordSpacing Property

*
  * Previous Topic: IHTMLRuleStyle::put_wordSpacing
  * Next Topic: IHTMLRuleStyle::put_letterSpacing

IHTMLRuleStyle::get_wordSpacing

HRESULT get_wordSpacing(
    VARIANT *p
);

Retrieves the value of the CSS word-spacing attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set.

See also put_wordSpacing

Up Top of Page

IHTMLRuleStyle::put_wordSpacing

HRESULT put_wordSpacing(
    VARIANT v
);

Sets the value of the CSS word-spacing attribute for the element. The attribute determines the amount of space to add to the default space between words in the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of space to add. A negative value is valid. Set this parameter to NULL to remove the attribute.

See also get_wordSpacing


LetterSpacing Property

*
  * Previous Topic: IHTMLRuleStyle::put_letterSpacing
  * Next Topic: IHTMLRuleStyle::put_textDecoration

IHTMLRuleStyle::get_letterSpacing

HRESULT get_letterSpacing(
    VARIANT *p
);

Retrieves the value of the CSS letter-spacing for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. See letter-spacing for details.

See also put_letterSpacing

Up Top of Page

IHTMLRuleStyle::put_letterSpacing

HRESULT put_letterSpacing(
    VARIANT v
);

Sets the value of the CSS letter-spacing attribute for the element. The attribute determines the amount of space to add to the default space between letters in the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of space to add. A negative value is valid. Set this parameter to NULL to remove the attribute. See letter-spacing for details.

See also get_letterSpacing


TextDecoration Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecoration
  * Next Topic: IHTMLRuleStyle::put_textDecorationNone

IHTMLRuleStyle::get_textDecoration

HRESULT get_textDecoration(
    BSTR *p
);

Retrieves the value of the CSS text-decoration attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. See text-decoration for details.

See also put_textDecoration

Up Top of Page

IHTMLRuleStyle::put_textDecoration

HRESULT put_textDecoration(
    BSTR v
);

Sets the value of the CSS text-decoration attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the text decorations. Can be "none" or one of the following strings:
underline
overline
line-through
Set this parameter to NULL to remove the attribute. See text-decoration for details.

See also get_textDecoration


TextDecorationNone Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecorationNone
  * Next Topic: IHTMLRuleStyle::put_textDecorationUnderline

IHTMLRuleStyle::get_textDecorationNone

HRESULT get_textDecorationNone(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "none".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "none", or FALSE if not. See text-decoration for details.

See also put_textDecorationNone

Up Top of Page

IHTMLRuleStyle::put_textDecorationNone

HRESULT put_textDecorationNone(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "none", or removes the "none" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "none"; FALSE removes the "none" value from the attribute. See text-decoration for details.

See also get_textDecorationNone


TextDecorationUnderline Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecorationUnderline
  * Next Topic: IHTMLRuleStyle::put_textDecorationOverline

IHTMLRuleStyle::get_textDecorationUnderline

HRESULT get_textDecorationUnderline(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "underline".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "underline", or FALSE if not. See text-decoration for details.

See also put_textDecorationUnderline

Up Top of Page

IHTMLRuleStyle::put_textDecorationUnderline

HRESULT put_textDecorationUnderline(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "underline", or removes the "underline" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "underline"; FALSE removes the "underline" value from the attribute. See text-decoration for details.

See also get_textDecorationUnderline


TextDecorationOverline Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecorationOverline
  * Next Topic: IHTMLRuleStyle::put_textDecorationLineThrough

IHTMLRuleStyle::get_textDecorationOverline

HRESULT get_textDecorationOverline(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "overline".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "overline", or FALSE if not. See text-decoration for details.

See also put_textDecorationOverline

Up Top of Page

IHTMLRuleStyle::put_textDecorationOverline

HRESULT put_textDecorationOverline(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "overline", or removes the "overline" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "overline"; FALSE removes the "overline" value from the attribute. See text-decoration for details.

See also get_textDecorationOverline


TextDecorationLineThrough Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecorationLineThrough
  * Next Topic: IHTMLRuleStyle::put_textDecorationBlink

IHTMLRuleStyle::get_textDecorationLineThrough

HRESULT get_textDecorationLineThrough(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "line-through".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "line-through", or FALSE if not. See text-decoration for details.

See also put_textDecorationLineThrough

Up Top of Page

IHTMLRuleStyle::put_textDecorationLineThrough

HRESULT put_textDecorationLineThrough(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "line-through", or removes the "line-through" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "line-through"; FALSE removes the "line-through" value from the attribute. See text-decoration for details.

See also get_textDecorationLineThrough


TextDecorationBlink Property

*
  * Previous Topic: IHTMLRuleStyle::put_textDecorationBlink
  * Next Topic: IHTMLRuleStyle::put_verticalAlign

IHTMLRuleStyle::get_textDecorationBlink

HRESULT get_textDecorationBlink(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "blink".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "blink", or FALSE if not. See text-decoration for details.

See also put_textDecorationBlink

Up Top of Page

IHTMLRuleStyle::put_textDecorationBlink

HRESULT put_textDecorationBlink(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "blink", or removes the "blink" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "blink"; FALSE removes the "blink" value from the attribute. See text-decoration for details.

See also get_textDecorationBlink


VerticalAlign Property

*
  * Previous Topic: IHTMLRuleStyle::put_verticalAlign
  * Next Topic: IHTMLRuleStyle::put_textTransform

IHTMLRuleStyle::get_verticalAlign

HRESULT get_verticalAlign(
    VARIANT *p
);

Retrieves the value of the CSS vertical-align attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. Can be one of these strings:
baseline
middle
sub
super
text-top
text-bottom
top
bottom
See vertical-align for details.

See also put_verticalAlign

Up Top of Page

IHTMLRuleStyle::put_verticalAlign

HRESULT put_verticalAlign(
    VARIANT v
);

Sets the value of the CSS vertical-align attribute for the element. The attribute determines the vertical positioning of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the vertical alignment. Can be a percentage (either positive or negative) of the line height of the element, or one of the values below. These values are relative to the parent element;
baseline
middle
sub
super
text-top
text-bottom
These values are relative to the formatted line of which the element is a part:
top
bottom
Set this parameter to NULL to remove the attribute. See vertical-align for details.

See also get_verticalAlign


TextTransform Property

*
  * Previous Topic: IHTMLRuleStyle::put_textTransform
  * Next Topic: IHTMLRuleStyle::put_textAlign

IHTMLRuleStyle::get_textTransform

HRESULT get_textTransform(
    BSTR *p
);

Retrieves the value of the CSS text-transform attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
capitalize | First letter in the text is capitalized.
lowercase | All letters in the text are converted to lowercase.
uppercase | All letters in the text are converted to uppercase.
See text-transform for details. This parameter receives NULL if the attribute is not set.

See also put_textTransform

Up Top of Page

IHTMLRuleStyle::put_textTransform

HRESULT put_textTransform(
    BSTR v
);

Sets the value of the CSS text-transform attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text transformation, or NULL to remove the attribute. Can be one of these strings:
capitalize | First letter in the text is capitalized.
lowercase | All letters in the text are converted to lowercase.
uppercase | All letters in the text are converted to uppercase.
See text-transform for details.

See also get_textTransform


TextAlign Property

*
  * Previous Topic: IHTMLRuleStyle::put_textAlign
  * Next Topic: IHTMLRuleStyle::put_textIndent

IHTMLRuleStyle::get_textAlign

HRESULT get_textAlign(
    BSTR *p
);

Retrieves the value of the CSS text-align attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
center
justify
See text-align for details. This parameter receives NULL if the attribute is not set.

See also put_textAlign

Up Top of Page

IHTMLRuleStyle::put_textAlign

HRESULT put_textAlign(
    BSTR v
);

Sets the value of the CSS text-align attribute for the element. The attribute determines the alignment of the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text alignment, or NULL to remove the attribute. Can be one of these strings:
left
right
center
justify
See text-align for details.

See also get_textAlign


TextIndent Property

*
  * Previous Topic: IHTMLRuleStyle::put_textIndent
  * Next Topic: IHTMLRuleStyle::put_lineHeight

IHTMLRuleStyle::get_textIndent

HRESULT get_textIndent(
    VARIANT *p
);

Retrieves the value of the CSS text-indent attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See text-indent for details. This parameter receives NULL if the attribute is not set.

See also put_textIndent

Up Top of Page

IHTMLRuleStyle::put_textIndent

HRESULT put_textIndent(
    VARIANT v
);

Sets the value of the CSS text-indent attribute for the element. The attribute determines the amount of indention before the element's first line of formatted text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of indention, or NULL to remove the attribute. The amount can be positive or negative. See text-indent for details.

See also get_textIndent


LineHeight Property

*
  * Previous Topic: IHTMLRuleStyle::put_lineHeight
  * Next Topic: IHTMLRuleStyle::put_marginTop

IHTMLRuleStyle::get_lineHeight

HRESULT get_lineHeight(
    VARIANT *p
);

Retrieves the value of the CSS line-height attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See line-height for details. This parameter receives NULL if the attribute is not set.

See also put_lineHeight

Up Top of Page

IHTMLRuleStyle::put_lineHeight

HRESULT put_lineHeight(
    VARIANT v
);

Sets the value of the CSS line-height attribute for the element. The attribute determines the distance between the baselines of subsequent lines of text. Use a negative line height to achieve various shadowing effects.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the line height. The height can be positive or negative. Set this parameter to NULL to remove the attribute.

See also get_lineHeight


MarginTop Property

*
  * Previous Topic: IHTMLRuleStyle::put_marginTop
  * Next Topic: IHTMLRuleStyle::put_marginRight

IHTMLRuleStyle::get_marginTop

HRESULT get_marginTop(
    VARIANT *p
);

Retrieves the value of the CSS margin-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-top for details. This parameter receives NULL if the attribute is not set.

See also put_marginTop

Up Top of Page

IHTMLRuleStyle::put_marginTop

HRESULT put_marginTop(
    VARIANT v
);

Sets the value of the CSS margin-top attribute for the element. The attribute determines the height of the top margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the top margin. The height can be positive or negative. See margin-top for details. Set this parameter to NULL to remove the attribute.

See also get_marginTop


MarginRight Property

*
  * Previous Topic: IHTMLRuleStyle::put_marginRight
  * Next Topic: IHTMLRuleStyle::put_marginBottom

IHTMLRuleStyle::get_marginRight

HRESULT get_marginRight(
    VARIANT *p
);

Retrieves the value of the CSS margin-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-right for details. This parameter receives NULL if the attribute is not set.

See also put_marginRight

Up Top of Page

IHTMLRuleStyle::put_marginRight

HRESULT put_marginRight(
    VARIANT v
);

Sets the value of the CSS margin-right attribute for the element. The attribute determines the width of the right margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the width of the right margin. The width can be positive or negative. See margin-right for details. Set this parameter to NULL to remove the attribute.

See also get_marginRight


MarginBottom Property

*
  * Previous Topic: IHTMLRuleStyle::put_marginBottom
  * Next Topic: IHTMLRuleStyle::put_marginLeft

IHTMLRuleStyle::get_marginBottom

HRESULT get_marginBottom(
    VARIANT *p
);

Retrieves the value of the CSS margin-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_marginBottom

Up Top of Page

IHTMLRuleStyle::put_marginBottom

HRESULT put_marginBottom(
    VARIANT v
);

Sets the value of the CSS margin-bottom attribute for the element. The attribute determines the height of the bottom margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the height of the bottom margin. The height can be positive or negative. See margin-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_marginBottom


MarginLeft Property

*
  * Previous Topic: IHTMLRuleStyle::put_marginLeft
  * Next Topic: IHTMLRuleStyle::put_margin

IHTMLRuleStyle::get_marginLeft

HRESULT get_marginLeft(
    VARIANT *p
);

Retrieves the value of the CSS margin-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-left for details. This parameter receives NULL if the attribute is not set.

See also put_marginLeft

Up Top of Page

IHTMLRuleStyle::put_marginLeft

HRESULT put_marginLeft(
    VARIANT v
);

Sets the value of the CSS margin-left attribute for the element. The attribute determines the width of the left margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the width of the left margin. The width can be positive or negative. See margin-left for details. Set this parameter to NULL to remove the attribute.

See also get_marginLeft


Margin Property

*
  * Previous Topic: IHTMLRuleStyle::put_margin
  * Next Topic: IHTMLRuleStyle::put_paddingTop

IHTMLRuleStyle::get_margin

HRESULT get_margin(
    BSTR *p
);

Retrieves the value of the CSS margin attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the top, right, bottom, and left margins, in that order. See margin for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the get_marginTop, get_marginRight, get_marginBottom, and get_marginLeft functions.

See also put_margin

Up Top of Page

IHTMLRuleStyle::put_margin

HRESULT put_margin(
    BSTR v
);

Sets the value of the CSS margin attribute for the element. The attribute sets the top, right, bottom, and left margins for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String that specifies the top, right, bottom, and left margins, in that order. See margin for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the put_marginTop, put_marginRight, put_marginBottom, and put_marginLeft functions.

See also get_margin


PaddingTop Property

*
  * Previous Topic: IHTMLRuleStyle::put_paddingTop
  * Next Topic: IHTMLRuleStyle::put_paddingRight

IHTMLRuleStyle::get_paddingTop

HRESULT get_paddingTop(
    VARIANT *p
);

Retrieves the value of the CSS padding-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-top for details. This parameter receives NULL if the attribute is not set.

See also put_paddingTop

Up Top of Page

IHTMLRuleStyle::put_paddingTop

HRESULT put_paddingTop(
    VARIANT v
);

Sets the value of the CSS padding-top attribute for the element. The attribute determines the amount of space between the border and the top of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of top padding. See padding-top for details. Set this parameter to NULL to remove the attribute.

See also get_paddingTop


PaddingRight Property

*
  * Previous Topic: IHTMLRuleStyle::put_paddingRight
  * Next Topic: IHTMLRuleStyle::put_paddingBottom

IHTMLRuleStyle::get_paddingRight

HRESULT get_paddingRight(
    VARIANT *p
);

Retrieves the value of the CSS padding-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-right for details. This parameter receives NULL if the attribute is not set.

See also put_paddingRight

Up Top of Page

IHTMLRuleStyle::put_paddingRight

HRESULT put_paddingRight(
    VARIANT v
);

Sets the value of the CSS padding-right attribute for the element. The attribute determines the amount of space between the border and the right of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of right padding. See padding-right for details. Set this parameter to NULL to remove the attribute.

See also get_paddingRight


PaddingBottom Property

*
  * Previous Topic: IHTMLRuleStyle::put_paddingBottom
  * Next Topic: IHTMLRuleStyle::put_paddingLeft

IHTMLRuleStyle::get_paddingBottom

HRESULT get_paddingBottom(
    VARIANT *p
);

Retrieves the value of the CSS padding-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_paddingBottom

Up Top of Page

IHTMLRuleStyle::put_paddingBottom

HRESULT put_paddingBottom(
    VARIANT v
);

Sets the value of the CSS padding-bottom attribute for the element. The attribute determines the amount of space between the border and the bottom of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of bottom padding. See padding-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_paddingBottom


PaddingLeft Property

*
  * Previous Topic: IHTMLRuleStyle::put_paddingLeft
  * Next Topic: IHTMLRuleStyle::put_padding

IHTMLRuleStyle::get_paddingLeft

HRESULT get_paddingLeft(
    VARIANT *p
);

Retrieves the value of the CSS padding-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-left for details. This parameter receives NULL if the attribute is not set.

See also put_paddingLeft

Up Top of Page

IHTMLRuleStyle::put_paddingLeft

HRESULT put_paddingLeft(
    VARIANT v
);

Sets the value of the CSS padding-left attribute for the element. The attribute determines the amount of space between the border and the left of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of left padding. See padding-left for details. Set this parameter to NULL to remove the attribute.

See also get_paddingLeft


Padding Property

*
  * Previous Topic: IHTMLRuleStyle::put_padding
  * Next Topic: IHTMLRuleStyle::put_border

IHTMLRuleStyle::get_padding

HRESULT get_padding(
    BSTR *p
);

Retrieves the value of the CSS padding attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the amount of top, right, bottom, and left padding, in that order. If this parameter specifies only one value, it applies to all sides. If it specifies two or three, the missing values are taken from the opposite side. See padding for details. This parameter receives NULL if the attribute is not set.

This function combines the functionality of the get_paddingTop, get_paddingRight, get_paddingBottom, and get_paddingLeft functions.

See also put_padding

Up Top of Page

IHTMLRuleStyle::put_padding

HRESULT put_padding(
    BSTR v
);

Sets the value of the CSS padding attribute for the element. The attibute determines the amount of space between the border and the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String that specifies the amount of top, right, bottom, and left padding, in that order. See padding for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the put_paddingTop, put_paddingRight, put_paddingBottom, and put_paddingLeft functions.

See also get_padding


Border Property

*
  * Previous Topic: IHTMLRuleStyle::put_border
  * Next Topic: IHTMLRuleStyle::put_borderTop

IHTMLRuleStyle::get_border

HRESULT get_border(
    BSTR *p
);

Retrieves the value of the CSS border attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the border. See border for details. This parameter receives NULL if the attribute is not set.

See also put_border

Up Top of Page

IHTMLRuleStyle::put_border

HRESULT put_border(
    BSTR v
);

Sets the value of the CSS border attribute for the element. The attribute describes the color, style, and width of the border to display around the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying values that describe the border. See border for details. Set this parameter to NULL to remove the attribute.

See also get_border


BorderTop Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderTop
  * Next Topic: IHTMLRuleStyle::put_borderRight

IHTMLRuleStyle::get_borderTop

HRESULT get_borderTop(
    BSTR *p
);

Retrieves the value of the CSS border-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the top border. See border-top for details. This parameter receives NULL if the attribute is not set.

See also put_borderTop

Up Top of Page

IHTMLRuleStyle::put_borderTop

HRESULT put_borderTop(
    BSTR v
);

Sets the value of the CSS border-top attribute for the element. The attribute determines the width, style, and color of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-top for details. Set this parameter to NULL to remove the attribute.

See also get_borderTop


BorderRight Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderRight
  * Next Topic: IHTMLRuleStyle::put_borderBottom

IHTMLRuleStyle::get_borderRight

HRESULT get_borderRight(
    BSTR *p
);

Retrieves the value of the CSS border-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the right border. See border-right for details. This parameter receives NULL if the attribute is not set.

See also put_borderRight

Up Top of Page

IHTMLRuleStyle::put_borderRight

HRESULT put_borderRight(
    BSTR v
);

Sets the value of the CSS border-right attribute for the element. The attribute determines the width, style, and color of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-right for details. Set this parameter to NULL to remove the attribute.

See also get_borderRight


BorderBottom Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderBottom
  * Next Topic: IHTMLRuleStyle::put_borderLeft

IHTMLRuleStyle::get_borderBottom

HRESULT get_borderBottom(
    BSTR *p
);

Retrieves the value of the CSS border-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the bottom border. See border-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottom

Up Top of Page

IHTMLRuleStyle::put_borderBottom

HRESULT put_borderBottom(
    BSTR v
);

Sets the value of the CSS border-bottom attribute for the element. The attribute determines the width, style, and color of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_borderBottom


BorderLeft Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderLeft
  * Next Topic: IHTMLRuleStyle::put_borderColor

IHTMLRuleStyle::get_borderLeft

HRESULT get_borderLeft(
    BSTR *p
);

Retrieves the value of the CSS border-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the left border. See border-left for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeft

Up Top of Page

IHTMLRuleStyle::put_borderLeft

HRESULT put_borderLeft(
    BSTR v
);

Sets the value of the CSS border-left attribute for the element. The attribute determines the width, style, and color of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-left for details. Set this parameter to NULL to remove the attribute.

See also get_borderLeft


BorderColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderColor
  * Next Topic: IHTMLRuleStyle::put_borderTopColor

IHTMLRuleStyle::get_borderColor

HRESULT get_borderColor(
    BSTR *p
);

Retrieves the value of the CSS border-color attribute of the element. The border color must be used with the border property, except for frames. The color can be one of the color names or values given in the Color Table reference documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border color values. See border-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderColor

Up Top of Page

IHTMLRuleStyle::put_borderColor

HRESULT put_borderColor(
    BSTR v
);

Sets the value of the CSS border-color attribute for the element. The attribute determines the color of the element's four borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. Set this parameter to NULL to remove the attribute. See border-left for details.

See also get_borderColor


BorderTopColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderTopColor
  * Next Topic: IHTMLRuleStyle::put_borderRightColor

IHTMLRuleStyle::get_borderTopColor

HRESULT get_borderTopColor(
    VARIANT *p
);

Retrieves the value of the CSS border-top-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-top-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopColor

Up Top of Page

IHTMLRuleStyle::put_borderTopColor

HRESULT put_borderTopColor(
    VARIANT v
);

Sets the value of the CSS border-top-color attribute for the element. The attribute determines the color of the element's top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. Set this parameter to NULL to remove the attribute. See border-top-color for details.

See also get_borderTopColor


BorderRightColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderRightColor
  * Next Topic: IHTMLRuleStyle::put_borderBottomColor

IHTMLRuleStyle::get_borderRightColor

HRESULT get_borderRightColor(
    VARIANT *p
);

Retrieves the value of the CSS border-right-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-right-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightColor

Up Top of Page

IHTMLRuleStyle::put_borderRightColor

HRESULT put_borderRightColor(
    VARIANT v
);

Sets the value of the CSS border-right-color attribute for the element. The attribute determines the color of the element's right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. Set this parameter to NULL to remove the attribute. See border-right-color for details.

See also get_borderRightColor


BorderBottomColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderBottomColor
  * Next Topic: IHTMLRuleStyle::put_borderLeftColor

IHTMLRuleStyle::get_borderBottomColor

HRESULT get_borderBottomColor(
    VARIANT *p
);

Retrieves the value of the CSS border-bottom-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-bottom-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomColor

Up Top of Page

IHTMLRuleStyle::put_borderBottomColor

HRESULT put_borderBottomColor(
    VARIANT v
);

Sets the value of the CSS border-bottom-color attribute for the element. The attribute determines the color of the element's bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. Set this parameter to NULL to remove the attribute. See border-bottom-color for details.

See also get_borderBottomColor


BorderLeftColor Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderLeftColor
  * Next Topic: IHTMLRuleStyle::put_borderWidth

IHTMLRuleStyle::get_borderLeftColor

HRESULT get_borderLeftColor(
    VARIANT *p
);

Retrieves the value of the CSS border-left-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-left-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftColor

Up Top of Page

IHTMLRuleStyle::put_borderLeftColor

HRESULT put_borderLeftColor(
    VARIANT v
);

Sets the value of the CSS border-left-color attribute for the element. The attribute determines the color of the element's left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. Set this parameter to NULL to remove the attribute. See border-left-color for details.

See also get_borderLeftColor


BorderWidth Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderWidth
  * Next Topic: IHTMLRuleStyle::put_borderTopWidth

IHTMLRuleStyle::get_borderWidth

HRESULT get_borderWidth(
    BSTR *p
);

Retrieves the value of the CSS border-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border widths. See border-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderWidth

Up Top of Page

IHTMLRuleStyle::put_borderWidth

HRESULT put_borderWidth(
    BSTR v
);

Sets the value of the CSS border-width attribute for the element. The attribute determines the width of the left, right, top, and bottom borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border widths. Set this parameter to NULL to remove the attribute. See border-width for details.

See also get_borderWidth


BorderTopWidth Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderTopWidth
  * Next Topic: IHTMLRuleStyle::put_borderRightWidth

IHTMLRuleStyle::get_borderTopWidth

HRESULT get_borderTopWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-top-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-top-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopWidth

Up Top of Page

IHTMLRuleStyle::put_borderTopWidth

HRESULT put_borderTopWidth(
    VARIANT v
);

Sets the value of the CSS border-top-width attribute for the element. The attribute determines the width of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. Set this parameter to NULL to remove the attribute. See border-top-width for details.

See also get_borderTopWidth


BorderRightWidth Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderRightWidth
  * Next Topic: IHTMLRuleStyle::put_borderBottomWidth

IHTMLRuleStyle::get_borderRightWidth

HRESULT get_borderRightWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-right-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-right-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightWidth

Up Top of Page

IHTMLRuleStyle::put_borderRightWidth

HRESULT put_borderRightWidth(
    VARIANT v
);

Sets the value of the CSS border-right-width attribute for the element. The attribute determines the width of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. Set this parameter to NULL to remove the attribute. See border-right-width for details.

See also get_borderRightWidth


BorderBottomWidth Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderBottomWidth
  * Next Topic: IHTMLRuleStyle::put_borderLeftWidth

IHTMLRuleStyle::get_borderBottomWidth

HRESULT get_borderBottomWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-bottom-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-bottom-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomWidth

Up Top of Page

IHTMLRuleStyle::put_borderBottomWidth

HRESULT put_borderBottomWidth(
    VARIANT v
);

Sets the value of the CSS border-bottom-width attribute for the element. The attribute determines the width of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. Set this parameter to NULL to remove the attribute. See border-bottom-width for details.

See also get_borderBottomWidth


BorderLeftWidth Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderLeftWidth
  * Next Topic: IHTMLRuleStyle::put_borderStyle

IHTMLRuleStyle::get_borderLeftWidth

HRESULT get_borderLeftWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-left-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-left-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftWidth

Up Top of Page

IHTMLRuleStyle::put_borderLeftWidth

HRESULT put_borderLeftWidth(
    VARIANT v
);

Sets the value of the CSS border-left-width attribute for the element. The attribute determines the width of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. Set this parameter to NULL to remove the attribute. See border-left-width for details.

See also get_borderLeftWidth


BorderStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderStyle
  * Next Topic: IHTMLRuleStyle::put_borderTopStyle

IHTMLRuleStyle::get_borderStyle

HRESULT get_borderStyle(
    BSTR *p
);

Retrieves the value of the CSS border-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border styles. See border-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderStyle

Up Top of Page

IHTMLRuleStyle::put_borderStyle

HRESULT put_borderStyle(
    BSTR v
);

Sets the value of the CSS border-style attribute for the element. The attribute determines the style of the left, right, top, and bottom borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border styles. Set this parameter to NULL to remove the attribute. See border-width for details.

See also get_borderStyle


BorderTopStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderTopStyle
  * Next Topic: IHTMLRuleStyle::put_borderRightStyle

IHTMLRuleStyle::get_borderTopStyle

HRESULT get_borderTopStyle(
    BSTR *p
);

Retrieves the value of the CSS border-top-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-top-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopStyle

Up Top of Page

IHTMLRuleStyle::put_borderTopStyle

HRESULT put_borderTopStyle(
    BSTR v
);

Sets the value of the CSS border-top-style attribute for the element. The attribute determines the style of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. Set this parameter to NULL to remove the attribute. See border-top-style for details.

See also get_borderTopStyle


BorderRightStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderRightStyle
  * Next Topic: IHTMLRuleStyle::put_borderBottomStyle

IHTMLRuleStyle::get_borderRightStyle

HRESULT get_borderRightStyle(
    BSTR *p
);

Retrieves the value of the CSS border-right-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-right-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightStyle

Up Top of Page

IHTMLRuleStyle::put_borderRightStyle

HRESULT put_borderRightStyle(
    BSTR v
);

Sets the value of the CSS border-right-style attribute for the element. The attribute determines the style of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. Set this parameter to NULL to remove the attribute. See border-right-style for details.

See also get_borderRightStyle


BorderBottomStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderBottomStyle
  * Next Topic: IHTMLRuleStyle::put_borderLeftStyle

IHTMLRuleStyle::get_borderBottomStyle

HRESULT get_borderBottomStyle(
    BSTR *p
);

Retrieves the value of the CSS border-bottom-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-bottom-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomStyle

Up Top of Page

IHTMLRuleStyle::put_borderBottomStyle

HRESULT put_borderBottomStyle(
    BSTR v
);

Sets the value of the CSS border-bottom-style attribute for the element. The attribute determines the style of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. Set this parameter to NULL to remove the attribute. See border-bottom-style for details.

See also get_borderBottomStyle


BorderLeftStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_borderLeftStyle
  * Next Topic: IHTMLRuleStyle::put_width

IHTMLRuleStyle::get_borderLeftStyle

HRESULT get_borderLeftStyle(
    BSTR *p
);

Retrieves the value of the CSS border-left-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-left-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftStyle

Up Top of Page

IHTMLRuleStyle::put_borderLeftStyle

HRESULT put_borderLeftStyle(
    BSTR v
);

Sets the value of the CSS border-left-style attribute for the element. The attribute determines the style of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. Set this parameter to NULL to remove the attribute. See border-left-style for details.

See also get_borderLeftStyle


Width Property

*
  * Previous Topic: IHTMLRuleStyle::put_width
  * Next Topic: IHTMLRuleStyle::put_height

IHTMLRuleStyle::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the value of the CSS width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width. See width for details. This parameter receives NULL if the attribute is not set.

See also put_height

Up Top of Page

IHTMLRuleStyle::put_width

HRESULT put_width(
    VARIANT v
);

Sets the value of the CSS width attribute for the element. The attribute determines the element's width.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the width, which consists of a floating-point number and a units designator. See width for details. Set this parameter to NULL to remove the attribute.

See also get_width


Height Property

*
  * Previous Topic: IHTMLRuleStyle::put_height
  * Next Topic: IHTMLRuleStyle::put_styleFloat

IHTMLRuleStyle::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the value of the CSS height attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height. See height for details. This parameter receives NULL if the attribute is not set.

See also put_height

Up Top of Page

IHTMLRuleStyle::put_height

HRESULT put_height(
    VARIANT v
);

Sets the value of the CSS height attribute for the element. The attribute determines the element's height.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the height, which consists of a floating-point number and a units designator. See height for details. Set this parameter to NULL to remove the attribute.

See also get_height


StyleFloat Property

*
  * Previous Topic: IHTMLRuleStyle::put_styleFloat
  * Next Topic: IHTMLRuleStyle::put_clear

IHTMLRuleStyle::get_styleFloat

HRESULT get_styleFloat(
    BSTR *p
);

Retrieves the value of the CSS float attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
none
See height for details. This parameter receives NULL if the attribute is not set.

See also put_styleFloat

Up Top of Page

IHTMLRuleStyle::put_styleFloat

HRESULT put_styleFloat(
    BSTR v
);

Sets the value of the CSS float attribute for the element. The attribute determines whether the element floats, causing text to flow around it.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
left
right
none
Set this parameter to NULL to remove the attribute. See float for details.

See also get_styleFloat


Clear Property

*
  * Previous Topic: IHTMLRuleStyle::put_clear
  * Next Topic: IHTMLRuleStyle::put_display

IHTMLRuleStyle::get_clear

HRESULT get_clear(
    BSTR *p
);

Retrieves the value of the CSS clear attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
both
See clear for details. This parameter receives NULL if the attribute is not set.

See also put_clear

Up Top of Page

IHTMLRuleStyle::put_clear

HRESULT put_clear(
    BSTR v
);

Sets the value of the CSS clear attribute for the element. The attribute determines whether the element allows floating elements (typically images) on its left and right sides. More specifically, the attribute specifies the sides where floating elements are not allowed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the sides where floating elements may not appear. Can be one of these strings:
left
right
both
Set this parameter to NULL to remove the attribute. See clear for details.

See also get_clear


Display Property

*
  * Previous Topic: IHTMLRuleStyle::put_display
  * Next Topic: IHTMLRuleStyle::put_visibility

IHTMLRuleStyle::get_display

HRESULT get_display(
    BSTR *p
);

Retrieves the value of the display attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The variable receives "none" if the element is not being rendered, or NULL if it is. See display for details.

See also put_display

Up Top of Page

IHTMLRuleStyle::put_display

HRESULT put_display(
    BSTR v
);

Sets the value of the CSS display attribute for the element. The attribute determines whether the element is rendered.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether to render the element. If this parameter is "none", the element is not rendered; if NULL, it is rendered. See display for details.

Although you can apply the display attribute to parts of a table (such as a TR or TD element), changing the property has no effect on those parts. However, you can dynamically control the rendering of the entire table by applying the attribute to the TABLE element.

See also get_display


Visibility Property

*
  * Previous Topic: IHTMLRuleStyle::put_visibility
  * Next Topic: IHTMLRuleStyle::put_listStyleType

IHTMLRuleStyle::get_visibility

HRESULT get_visibility(
    BSTR *p
);

Retrieves the value of the visibility attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
visible
hidden
inherit
The variable receives NULL if the attribute is not set. See visibility for details.

See also put_visibility

Up Top of Page

IHTMLRuleStyle::put_visibility

HRESULT put_visibility(
    BSTR v
);

Sets the value of the CSS visibility attribute for the element. The attribute determines whether the content of the element is visible.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether the element is visible. Can be one of these strings:
visible
hidden
inherit
Set this parameter to NULL to remove the attribute. See visibility for details.

Space is reserved for the element's content regardless of the value of the visibility attribute.

See also get_visibility


ListStyleType Property

*
  * Previous Topic: IHTMLRuleStyle::put_listStyleType
  * Next Topic: IHTMLRuleStyle::put_listStylePosition

IHTMLRuleStyle::get_listStyleType

HRESULT get_listStyleType(
    BSTR *p
);

Retrieves the value of the CSS list-style-type attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
disk
circle
square
decimal
lower-roman
upper-roman
lower-alpha
upper-alpha
none
The variable receives NULL if the attribute is not set. See list-style-type for details.

The list-style-type attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStyleType

Up Top of Page

IHTMLRuleStyle::put_listStyleType

HRESULT put_listStyleType(
    BSTR v
);

Sets the value of the CSS list-style-type attribute for the element. The attribute determines the appearance of the list-item marker if the list-style-image is set to "none" or if the image pointed to by the URL cannot be displayed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
disk
circle
square
decimal
lower-roman
upper-roman
lower-alpha
upper-alpha
none
Set this parameter to NULL to remove the attribute. See list-style-type for details.

The list-style-type attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStyleType


ListStylePosition Property

*
  * Previous Topic: IHTMLRuleStyle::put_listStylePosition
  * Next Topic: IHTMLRuleStyle::put_listStyleImage

IHTMLRuleStyle::get_listStylePosition

HRESULT get_listStylePosition(
    BSTR *p
);

Retrieves the value of the CSS list-style-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
inside
outside
The variable receives NULL if the attribute is not set. See list-style-position for details.

The list-style-position attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStylePosition

Up Top of Page

IHTMLRuleStyle::put_listStylePosition

HRESULT put_listStylePosition(
    BSTR v
);

Sets the value of the CSS list-style-position attribute for the element. The attribute determines how the list-item marker is drawn with regard to the content.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
inside
outside
Set this parameter to NULL to remove the attribute. See list-style-position for details.

The list-style-position attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStylePosition


ListStyleImage Property

*
  * Previous Topic: IHTMLRuleStyle::put_listStyleImage
  * Next Topic: IHTMLRuleStyle::put_listStyle

IHTMLRuleStyle::get_listStyleImage

HRESULT get_listStyleImage(
    BSTR *p
);

Retrieves the value of the CSS list-style-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be either "none" or the URL of an image used as the list-item marker. The variable receives NULL if the attribute is not set. See list-style-image for details.

The list-style-image attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStyleImage

Up Top of Page

IHTMLRuleStyle::put_listStyleImage

HRESULT put_listStyleImage(
    BSTR v
);

Sets the value of the CSS list-style-image attribute for the element. The attribute sets the image to use as the list-item marker. When the image is available, it replaces the marker.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be either "none" or the URL of an image. Set this parameter to NULL to remove the attribute. See list-style-image for details.

The list-style-image attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStyleImage


ListStyle Property

*
  * Previous Topic: IHTMLRuleStyle::put_listStyle
  * Next Topic: IHTMLRuleStyle::put_whiteSpace

IHTMLRuleStyle::get_listStyle

HRESULT get_listStyle(
    BSTR *p
);

Retrieves the value of the CSS list-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The variable receives NULL if the attribute is not set. See list-style for details.

The list-style attribute is applicable only on elements that have the display attribute set to "list-item".

This function combines the functionality of the get_listStyleType, get_listStyleImage, and get_listStylePosition functions.

See also put_listStyle

Up Top of Page

IHTMLRuleStyle::put_listStyle

HRESULT put_listStyle(
    BSTR v
);

Sets the value of the CSS list-style attribute for the element. The attribute determines how a list-item marker is drawn.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the values of the attribute. Set this parameter to NULL to remove the attribute. See list-style for details.

The list-style attribute is applicable only on elements that have the display attribute set to "list-item". This property can be set on any element and is inherited down the tree. In HTML, this is typically the case for the LI element.

This function combines the functionality of the put_listStyleType, put_listStyleImage, and put_listStylePosition functions.

If no type or position is specified, the default type is "disk" and the default position is "outside".

See also get_listStyle


WhiteSpace Property

*
  * Previous Topic: IHTMLRuleStyle::put_whiteSpace
  * Next Topic: IHTMLRuleStyle::put_top

IHTMLRuleStyle::get_whiteSpace

HRESULT get_whiteSpace(
    BSTR *p
);

Retrieves the value of the CSS white-space attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal | Consecutive white-space characters are replaced with a single space.
nowrap | Linebreak characters are preserved, but consecutive spaces and tab characters are replaced with a single space.
pre | All white-space characters (including line breaks) are preserved.
The variable receives NULL if the attribute is not set.

See also put_whiteSpace

Up Top of Page

IHTMLRuleStyle::put_whiteSpace

HRESULT put_whiteSpace(
    BSTR v
);

Sets the CSS white-space attribute for the element. The attribute determines whether and how white-space characters in the element are displayed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
normal | Consecutive white-space characters are replaced with a single space.
nowrap | Linebreak characters are preserved, but consecutive spaces and tab characters are replaced with a single space.
pre | All white-space characters (including line breaks) are preserved.
Set this parameter to NULL to remove the attribute.

See also get_whiteSpace


Top Property

*
  * Previous Topic: IHTMLRuleStyle::put_top
  * Next Topic: IHTMLRuleStyle::put_left

IHTMLRuleStyle::get_top

HRESULT get_top(
    VARIANT *p
);

Retrieves the value of the CSS top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The value is a string consisting of a floating-point number and a units designator. The variable receives NULL if the attribute is not set. See top for details.

See also put_top

Up Top of Page

IHTMLRuleStyle::put_top

HRESULT put_top(
    VARIANT v
);

Sets the value of the CSS top attribute for the element. The attribute determines the top position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value consisting of a floating-point number and a units designator. Set this parameter to NULL to remove the attribute. See top for details.

See also get_top


Left Property

*
  * Previous Topic: IHTMLRuleStyle::put_left
  * Next Topic: IHTMLRuleStyle::get_position

IHTMLRuleStyle::get_left

HRESULT get_left(
    VARIANT *p
);

Retrieves the value of the CSS left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The value is a string consisting of a floating-point number and a units designator. The variable receives NULL if the attribute is not set. See left for details.

See also put_left

Up Top of Page

IHTMLRuleStyle::put_left

HRESULT put_left(
    VARIANT v
);

Sets the value of the CSS left attribute for the element. The attribute determines the left position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value consisting of a floating-point number and a units designator. Set this parameter to NULL to remove the attribute. See left for details.

See also get_left


IHTMLRuleStyle::get_position

HRESULT get_position(
    BSTR *p
);

Retrieves the value of the CSS position attribute for the element. The attribute specifies whether the element can be positioned and, if so, the position of the element relative to its parent object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
absolute | The element is placed relative to the document.
relative | The element is placed relative to its parent object.
static | The element cannot be positioned.
This variable receives NULL if the attribute is not set. See position for details.

The position attribute is not inherited.


ZIndex Property

*
  * Previous Topic: IHTMLRuleStyle::put_zIndex
  * Next Topic: IHTMLRuleStyle::put_overflow

IHTMLRuleStyle::get_zIndex

HRESULT get_zIndex(
    VARIANT *p
);

Retrieves the value of the CSS z-index attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the z-index. The variable receives a positive value if the element is positioned above the text, and a negative value if it is below. The variable receives NULL if the attribute is not set. See z-index for details.

See also put_zIndex

Up Top of Page

IHTMLRuleStyle::put_zIndex

HRESULT put_zIndex(
    VARIANT v
);

Sets the value of the CSS z-index attribute for the element. The attribute determines whether the element is positioned above or below the text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the z-index. A positive value positions the element above the text, and a negative value positions it below. Set this parameter to NULL to remove the attribute. See z-index for details.

See also get_zIndex


Overflow Property

*
  * Previous Topic: IHTMLRuleStyle::put_overflow
  * Next Topic: IHTMLRuleStyle::put_pageBreakBefore

IHTMLRuleStyle::get_overflow

HRESULT get_overflow(
    BSTR *p
);

Retrieves the value of the CSS overflow attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
none
clip
scroll
The variable receives NULL if the attribute is not set. See overflow for details.

See also put_overflow

Up Top of Page

IHTMLRuleStyle::put_overflow

HRESULT put_overflow(
    BSTR v
);

Sets the value of the CSS overflow attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
none
clip
scroll
Set this parameter to NULL to remove the attribute. See overflow for details.

See also get_overflow


PageBreakBefore Property

*
  * Previous Topic: IHTMLRuleStyle::put_pageBreakBefore
  * Next Topic: IHTMLRuleStyle::put_pageBreakAfter

IHTMLRuleStyle::get_pageBreakBefore

HRESULT get_pageBreakBefore(
    BSTR *p
);

Retrieves the value of the CSS page-break-before attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
auto | Insert a page break before the element only if necessary.
always | Always insert a page break before the element.
left | Insert one or two page breaks before the element until a blank left page is reached.
right | Insert one or two page breaks before the element until a blank right page is reached.
The variable receives NULL if the attribute is not set. See page-break-before for details.

See also put_pageBreakBefore

Up Top of Page

IHTMLRuleStyle::put_pageBreakBefore

HRESULT put_pageBreakBefore(
    BSTR v
);

Sets the value of the CSS page-break-before attribute for the element. The attribute determines whether a page break occurs before the element, and on what page the subsequent content should resume.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
auto | Insert a page break before the element only if necessary.
always | Always insert a page break before the element.
left | Insert one or two page breaks before the element until a blank left page is reached.
right | Insert one or two page breaks before the element until a blank right page is reached.
See page-break-before for details.

See also get_pageBreakBefore


PageBreakAfter Property

*
  * Previous Topic: IHTMLRuleStyle::put_pageBreakAfter
  * Next Topic: IHTMLRuleStyle::put_cssText

IHTMLRuleStyle::get_pageBreakAfter

HRESULT get_pageBreakAfter(
    BSTR *p
);

Retrieves the value of the CSS page-break-after attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
auto | Insert a page break after the element only if necessary.
always | Always insert a page break after the element.
left | Insert one or two page breaks after the element until a blank left page is reached.
right | Insert one or two page breaks after the element until a blank right page is reached.
The variable receives NULL if the attribute is not set. See page-break-after for details.

See also put_pageBreakAfter

Up Top of Page

IHTMLRuleStyle::put_pageBreakAfter

HRESULT put_pageBreakAfter(
    BSTR v
);

Sets the value of the CSS page-break-after attribute for the element. The attribute determines whether a page break occurs after the element and on what page the subsequent content should resume.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
auto | Insert a page break after the element only if necessary.
always | Always insert a page break after the element.
left | Insert one or two page breaks after the element until a blank left page is reached.
right | Insert one or two page breaks after the element until a blank right page is reached.
See page-break-after for details.

See also get_pageBreakAfter


CssText Property

*
  * Previous Topic: IHTMLRuleStyle::put_cssText
  * Next Topic: IHTMLRuleStyle::put_cursor

IHTMLRuleStyle::get_cssText

HRESULT get_cssText(
    BSTR *p
);

Retrieves the persisted representation of the style rule.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the style rule.

See also put_cssText

Up Top of Page

IHTMLRuleStyle::put_cssText

HRESULT put_cssText(
    BSTR v
);

Sets the persisted representation of the style rule.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the style rule.

See also get_cssText


Cursor Property

*
  * Previous Topic: IHTMLRuleStyle::put_cursor
  * Next Topic: IHTMLRuleStyle::put_clip

IHTMLRuleStyle::get_cursor

HRESULT get_cursor(
    BSTR *p
);

Retrieves the value of the CSS cursor attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See cursor for details. This variable receives NULL if the attribute is not set.

See also put_cursor

Up Top of Page

IHTMLRuleStyle::put_cursor

HRESULT put_cursor(
    BSTR v
);

Sets the value of the CSS cursor attribute for the element. The attribute determines the type of cursor to display when the mouse is over the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the cursor type. Can be one of these values:
auto | Browser determines the cursor to display based on the current context.
crosshair | A simple crosshair.
default | The platform-dependent default cursor (typically an arrow).
hand | A hand.
move | A four-directional arrow typically used to indicate an object to be moved.
*-resize | An arrow cursor typically used to indicate the edge of an object to be moved during a resize operation.
text | Typically an I-bar used to indicate editable text.
wait | Typically a watch or hourglass used to indicate that the program is busy and the user should wait.

See also get_cursor


Clip Property

*
  * Previous Topic: IHTMLRuleStyle::put_clip
  * Next Topic: IHTMLRuleStyle::put_filter

IHTMLRuleStyle::get_clip

HRESULT get_clip(
    BSTR *p
);

Retrieves the value of the CSS clip attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the coordinates of the clipping area. This variable receives NULL if the attribute is not set. See clip for details.

See also put_clip

Up Top of Page

IHTMLRuleStyle::put_clip

HRESULT put_clip(
    BSTR v
);

Sets the value of the CSS clip attribute for the element. The attribute determines which part of the element is visible. Any part of the element that is outside the clipping area is transparent.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the coordinates of the clipping area. Each coordinate can be a length value or "auto". Set this parameter to NULL to remove the attribute. See clip for details.

See also get_clip


Filter Property

*
  * Previous Topic: IHTMLRuleStyle::put_filter
  * Next Topic: IHTMLRuleStyle::setAttribute

IHTMLRuleStyle::get_filter

HRESULT get_filter(
    BSTR *p
);

Retrieves a filter or collection of filters for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the filter.

See also put_filter

Up Top of Page

IHTMLRuleStyle::put_filter

HRESULT put_filter(
    BSTR v
);

Sets a filter or collection of filters for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the filter.

See also get_filter


IHTMLRuleStyle::setAttribute

HRESULT setAttribute(
    BSTR strAttributeName,
    VARIANT AttributeValue,
    LONG lFlags
);

Sets the value of the given attribute. If the attribute is not already present, the method adds the attribute to the element and sets the value.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to set.
AttributeValue
String, number, or Boolean value to assign to the attribute.
lFlags
Long integer value that specifies the flags.

See also getAttribute


IHTMLRuleStyle::getAttribute

HRESULT getAttribute(
    BSTR strAttributeName,
    LONG lFlags,
    VARIANT *AttributeValue
);

Retrieves the value of the given attribute.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to retrieve.
lFlags
Long integer that receives the flags.
AttributeValue
Address of a variable that receives a string, number, or Boolean value as defined by the attribute. If the attribute is not present, this method returns NULL.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and lFlags is FALSE, this method retrieves values only for the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

See also setAttribute


IHTMLRuleStyle::removeAttribute

HRESULT removeAttribute(
    BSTR strAttributeName,
    LONG lFlags,
    VARIANT_BOOL *pfSuccess
);

Removes the given attribute from the element.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to remove.
lFlags
Long integer that contains the flags.
pfSuccess
Address of a variable that receives TRUE if the function succeeds, or FALSE otherwise.

See also setAttribute, getAttribute


IHTMLScreen

This interface supplies information about the client's screen and rendering capabilities.

IHTMLScreen Methods
get_colorDepth put_bufferDepth get_bufferDepth
get_width get_height put_updateInterval
get_updateInterval get_availHeight get_availWidth
get_fontSmoothingEnabled


IHTMLScreen::get_colorDepth

HRESULT get_colorDepth(
    long *p
) ;

Retrieves the bits-per-pixel used for colors on the destination device or buffer. Script programmers use this value when deciding how best to use colors.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color depth.

The value of this read-only property depends on the bufferDepth property. If bufferDepth is 0 or -1, colorDepth is equal to the bits-per-pixel value for the screen or printer. If bufferDepth is non-zero, colorDepth is equal to bufferDepth.


BufferDepth Property

*
  * Previous Topic: IHTMLScreen::put_bufferDepth
  * Next Topic: IHTMLScreen::get_width

IHTMLScreen::get_bufferDepth

HRESULT get_bufferDepth(
    long *p
);

Retrieves an offscreen bitmap buffer.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the buffer depth. Can be one of these values:
0 | No explicit buffering. The colorDepth property is set to the screen depth.
-1 | Perform buffering at the screen depth. The colorDepth property is set to the screen depth.
1, 4, 8, 15, 16, 24, or 32 | Perform buffering using the given bits-per-pixel. The colorDepth is also set to this value. The value 15 specifies 16 bits-per-pixel, in which only 15 bits are used in a 5-5-5 layout of RGB values.

Nonsupported values cause bufferDepth to be set to -1. When bufferDepth is -1 and the user changes system settings that affect the screen depth, the buffer depth is automatically updated to the new depth. This is not the case if you set bufferDepth to a specific value.

See also put_bufferDepth

Up Top of Page

IHTMLScreen::put_bufferDepth

HRESULT put_bufferDepth(
    long v
);

Sets an offscreen bitmap buffer.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the buffer depth. Can be one of these values:
0 | No explicit buffering. The colorDepth property is set to the screen depth.
-1 | Perform buffering at the screen depth. The colorDepth property is set to the screen depth.
1, 4, 8, 15, 16, 24, or 32 | Perform buffering using the given bits-per-pixel. The colorDepth is also set to this value. The value 15 specifies 16 bits-per-pixel, in which only 15 bits are used in a 5-5-5 layout of RGB values.

Nonsupported values cause bufferDepth to be set to -1. When bufferDepth is -1 and the user changes system settings that affect the screen depth, the buffer depth is automatically updated to the new depth. This is not the case if you set bufferDepth to a specific value.

See also get_bufferDepth


IHTMLScreen::get_width

HRESULT get_width(
    long *p
);

Retrieves the horizontal resolution of the screen, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the horizontal resolution.

See also get_height


IHTMLScreen::get_height

HRESULT get_height(
    long *p
);

Retrieves the vertical resolution of the screen, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the vertical resolution.

See also get_width


UpdateInterval Property

*
  * Previous Topic: IHTMLScreen::put_updateInterval
  * Next Topic: IHTMLScreen::get_availHeight

IHTMLScreen::get_updateInterval

HRESULT get_updateInterval(
    long *p
);

Retrieves the update interval for the screen. The interval causes invalidations to the window to be buffered and then drawn in the given millisecond intervals. The purpose is to limit excessive invalidations that reduce the overall painting performance, which can happen if there is an overabundance of flipbook-style animations occurring at once.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of milliseconds between updates to the screen. This parameter receives zero (0) if the update interval is disabled.

See also put_updateInterval

Up Top of Page

IHTMLScreen::put_updateInterval

HRESULT put_updateInterval(
    long v
);

Sets the update interval for the screen. The interval causes invalidation's to the window to be buffered and then drawn in the given millisecond intervals. The purpose is to limit excessive invalidation's that reduce the overall painting performance, which can happen if there is an overabundance of flipbook-style animation's occurring at once.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of milliseconds between updates to the screen. A value of zero disables the update interval.

Use this property judiciously—a value too small or too large will adversely affect the page rendering response.

See also get_updateInterval


IHTMLScreen::get_availHeight

HRESULT get_availHeight(
    long *p
);

Retrieves the height of the working area of the system's screen.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height value.

See also get_availWidth


IHTMLScreen::get_availWidth

HRESULT get_availWidth(
    long *p
);

Retrieves the width of the working area of the system's screen.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width value.

See also get_availHeight


IHTMLScreen::get_fontSmoothingEnabled

HRESULT get_fontSmoothingEnabled(
    VARIANT_BOOL *p
);

Retrieves a Boolean of the system setting indicating whether font smoothing is enabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if font smothing is enabled, or FALSE otherwise.


IHTMLScriptElement

This interface specifies a script for the page that will be interpreted by a script engine.

Code within the SCRIPT block that is not contained within a function is executed immediately as the page is loaded. To keep scripts from being displayed on down-level browsers, the SCRIPT block should be nested within a comment block.

This element is a block element.

IHTMLScriptElement Methods
put_src get_src put_htmlFor
get_htmlFor put_event get_event
put_text get_text put_defer
get_defer get_readyState put_onerror
get_onerror put_type get_type

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Src Property

*
  * Previous Topic: IHTMLScriptElement::put_src
  * Next Topic: IHTMLScriptElement::put_htmlFor

IHTMLScriptElement::get_src

HRESULT get_src(
    BSTR *p
);

Retrieves an external file that contains the source code.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL of the external file.

A script can contain an external reference as well as code within the block. The code specified by src --> precedes the code contained within the document.

See also put_src

Up Top of Page

IHTMLScriptElement::put_src

HRESULT put_src(
    BSTR v
);

Specifies an external file that contains the source code.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL of the external file.

A script can contain an external reference as well as code within the block. The code specified by src precedes the code contained within the document.

See also get_src


HtmlFor Property

*
  * Previous Topic: IHTMLScriptElement::put_htmlFor
  * Next Topic: IHTMLScriptElement::put_event

IHTMLScriptElement::get_htmlFor

HRESULT get_htmlFor(
    BSTR *p
);

Retrieves which element is being bound to the event script. This htmlFor property corresponds to the HTML FOR= attribute.

For more information on inline script, see Attaching an Event Handler in the Event Model documantation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the element name.

See also put_htmlFor

Up Top of Page

IHTMLScriptElement::put_htmlFor

HRESULT put_htmlFor(
    BSTR v
);

Sets which element is being bound to the event script. This htmlFor property corresponds to the HTML FOR= attribute.

For more information on inline script, see Attaching an Event Handler in the Event Model documantation.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the element name.

See also get_htmlFor


Event Property

*
  * Previous Topic: IHTMLScriptElement::put_event
  * Next Topic: IHTMLScriptElement::put_text

IHTMLScriptElement::get_event

HRESULT get_event(
    BSTR *p
);

Retrieves the event for which the script is being written.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the event.

See also put_event

Up Top of Page

IHTMLScriptElement::put_event

HRESULT put_event(
    BSTR v
);

Sets the event for which the script is being written.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the event.

See also get_event


Text Property

*
  * Previous Topic: IHTMLScriptElement::put_text
  * Next Topic: IHTMLScriptElement::put_defer

IHTMLScriptElement::get_text

HRESULT get_text(
    BSTR *p
);

Retrieves the text contained within the SCRIPT element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the text.

See also put_text

Up Top of Page

IHTMLScriptElement::put_text

HRESULT put_text(
    BSTR v
);

Retrieves the text contained within the SCRIPT element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text.

See also get_text


Defer Property

*
  * Previous Topic: IHTMLScriptElement::put_defer
  * Next Topic: IHTMLScriptElement::get_readyState

IHTMLScriptElement::get_defer

HRESULT get_defer(
    VARIANT_BOOL *p
);

Retrieves the Boolean value indicating whether this script's execution is deferred until the document completes loading.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the script execution is deferred, or FALSE if not.

See also put_defer

Up Top of Page

IHTMLScriptElement::put_defer

HRESULT put_defer(
    VARIANT_BOOL v
);

Sets the Boolean value indicating whether this script's execution is deferred until the document completes loading.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether the script's execution is deferred until after the document has completed loading. If TRUE, the script execution is deferred; otherwise, the script will execute.

See also get_defer


IHTMLScriptElement::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
unitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states it exposes.


Onerror Property

*
  * Previous Topic: IHTMLScriptElement::put_onerror
  * Next Topic: IHTMLScriptElement::put_type

IHTMLScriptElement::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event on the script element.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the onerror script.

See also put_onerror

Up Top of Page

IHTMLScriptElement::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event on the script element.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the onerror script to be set.

See also get_onerror


Type Property

*
  * Previous Topic: IHTMLScriptElement::put_type
  * Next Topic: IHTMLSelectElement

IHTMLScriptElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the string that represents the language that the current script was written in. The default language is JScript.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string that receives the language type. The possible scripting languages include the following:
JScript | Specifies that the script is written in JScript.
Jscript | Specifies the language as JScript.
vbs | Specifies the language as VBScript.
vbscript | Specifies that the script is written in VBScript.

This is an HTML 4.0 attribute and is equivalent to the language property.

See also put_type

Up Top of Page

IHTMLScriptElement::put_type

HRESULT put_type(
    BSTR v
);

Indicates the type script of the scripting language as a string for the IHTMLScriptElement object. The contents of this script is read only, and can be modified only at design time.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the script type.

See also get_type


IHTMLSelectElement

This interface provides access to the properties and methods of the SELECT element.

IHTMLSelectElement Methods
put_size get_size put_multiple
get_multiple put_name get_name
get_options put_onchange get_onchange
put_selectedIndex get_selectedIndex get_type
put_value get_value put_disabled
get_disabled get_form add
remove put_length get_length
get__newEnum item tags

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Size Property

*
  * Previous Topic: IHTMLSelectElement::put_size
  * Next Topic: IHTMLSelectElement::put_multiple

IHTMLSelectElement::get_size

HRESULT get_size(
    long *p
);

Retrieves the number of rows in the list box.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of rows.

See also put_size

Up Top of Page

IHTMLSelectElement::put_size

HRESULT put_size(
   long v
);

Specifies the number of rows in the list box.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of rows.

See also get_size


Multiple Property

*
  * Previous Topic: IHTMLSelectElement::put_multiple
  * Next Topic: IHTMLSelectElement::put_name

IHTMLSelectElement::get_multiple

HRESULT get_multiple(
    VARIANT_BOOL *p
);

Determines whether multiple items in the list can be selected.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if multiple items can be selected, or FALSE if not.

The default value for this property is FALSE.

See also put_multiple

Up Top of Page

IHTMLSelectElement::put_multiple

HRESULT put_multiple(
    VARIANT_BOOL v
);

Specifies whether multiple items in the list can be selected.

  • Returns S_OK if successful, or an error value otherwise.
v
Multiple-items flag. If TRUE, multiple items can be selected; if FALSE, they cannot.

The default value for this property is FALSE.

See also get_multiple


Name Property

*
  * Previous Topic: IHTMLSelectElement::put_name
  * Next Topic: IHTMLSelectElement::get_options

IHTMLSelectElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLSelectElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the control, bookmark, or application.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the control when submitting a form. The NAME is not the value that is displayed for the button, reset, and submit objects. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


IHTMLSelectElement::get_options

HRESULT get_options(
    IDispatch **p
);

Retrieves an interface pointer for a collection of OPTION elements in a SELECT object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.


Onchange Property

*
  * Previous Topic: IHTMLSelectElement::put_onchange
  * Next Topic: IHTMLSelectElement::put_selectedIndex

IHTMLSelectElement::get_onchange

HRESULT get_onchange(
    VARIANT *p
);

Retrieves the inline script associated with the onchange event on the SELECT element. This occurs when the contents of the object have changed.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onchange

Up Top of Page

IHTMLSelectElement::put_onchange

HRESULT put_onchange(
    VARIANT v
);

Sets the inline script associated with the onchange event on the SELECT element. This occurs when the contents of the object have changed.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onchange


SelectedIndex Property

*
  * Previous Topic: IHTMLSelectElement::put_selectedIndex
  * Next Topic: IHTMLSelectElement::get_type

IHTMLSelectElement::get_selectedIndex

HRESULT get_selectedIndex(
    long *p
);

Retreives the index of the selected item in the list box or drop-down list associated with the select object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the index of the selected item.

Options in a select object are indexed in the order in which they are defined, starting with an index of 0. You can set the selectedIndex property at any time. The display of the select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value.

In general, the selectedIndex property is more useful for select objects that are created without the multiple attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the select object.

The selected property of the select object's options array is more useful for select objects that are created with the multiple attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

See also put_selectedIndex

Up Top of Page

IHTMLSelectElement::put_selectedIndex

HRESULT put_selectedIndex(
    long v
);

Selects an item in the list box or drop-down list associated with the select object.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the zero-based index of the item to select.

Options in a select object are indexed in the order in which they are defined, starting with an index of 0. You can set the selectedIndex property at any time. The display of the select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value.

In general, the selectedIndex property is more useful for select objects that are created without the multiple attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the select object.

The selected property of the select object's options array is more useful for select objects that are created with the multiple attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

See also get_selectedIndex


IHTMLSelectElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the type. The possible values depend on the element, as listed in the following table.
Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the FORM, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Value Property

*
  * Previous Topic: IHTMLSelectElement::put_value
  * Next Topic: IHTMLSelectElement::put_disabled

IHTMLSelectElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the value of the object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value.

See also put_value

Up Top of Page

IHTMLSelectElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the value of the object.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value.

See also get_value


Disabled Property

*
  * Previous Topic: IHTMLSelectElement::put_disabled
  * Next Topic: IHTMLSelectElement::get_form

IHTMLSelectElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLSelectElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLSelectElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


IHTMLSelectElement::add

HRESULT add(
    IHTMLElement *element,
    VARIANT before
);

Adds an OPTION element to a SELECT block.

  • Returns S_OK if successful, or an error value otherwise.
element
Interface pointer to the OPTION element to add.
before
Zero-based index specifying the position of the OPTION element within the SELECT block.

See also remove


IHTMLSelectElement::remove

HRESULT remove(
    long index
);

Removes the given element from the SELECT block.

  • Returns S_OK if successful, or an error value otherwise.
index
Zero-based index of the item to remove.

See also add


Length Property

*
  * Previous Topic: IHTMLSelectElement::put_length
  * Next Topic: IHTMLSelectElement::get__newEnum

IHTMLSelectElement::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in the SELECT block.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of elements.

See also put_length

Up Top of Page

IHTMLSelectElement::put_length

HRESULT put_length(
    long v
);

Sets the number of elements in the SELECT block.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of elements.

See also get_length


IHTMLSelectElement::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Retrieves an enumerator interface which can be used to iterate through the options collection of the select element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the enumerator interface pointer.


IHTMLSelectElement::item

HRESULT item(
    VARIANT name,
    VARIANT index,
    IDispatch **pdisp
);

Retrieves an interface pointer for an element in a SELECT block.

  • Returns S_OK if successful, or an error value otherwise.
name
Number or string specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter contains a string, the method returns a collection of elements, where the value of the NAME or ID= property for each element is equal to the string.
index
Number specifying the position of an element to retrieve. This parameter is used when name is a string. The method uses the string to construct a collection of all elements that have a NAME or ID= equal to the string, then retrieves from this collection the element at the position specified by index.
pdisp
Address of a variable that receives an interface pointer to the element object.


IHTMLSelectElement::tags

HRESULT tags(
    VARIANT tagName,
    IDispatch **pdisp
);

Retrieves a collection of all elements in the given collection that have the given HTML tag name.

  • Returns S_OK if successful, or an error value otherwise.
tagName
String specifying the tag name.
pdisp
Address of a variable that receives an interface pointer to the collection.

This method returns an empty collection if no elements having the given name are found. Use the length property on the collection to determine the number of elements it contains.


IHTMLSelectionObject

This interface provides the access methods for the selection object representing the active selection, a highlighted block of text and/or other elements in the document upon which a user or a script can carry out some action. You typically use the selection object as input from the user identifying what portion of the document to act on, or as output to the user showing the results of an action.

Users and scripts both can create selections. Users create selections by dragging the mouse over a portion of the document. Scripts create them by calling the select method on a text range or similar object. You can retrieve the active selection by applying the selection keyword to the document object. To carry out work on a selection, you can create a text range object from the selection by using the createRange method.

A document can have only one selection at a time. The selection has a type that determines whether it is empty or contains a contiguous block of consecutive text and/or elements. Although an empty selection contains nothing, it is useful for marking a position in the document.

IHTMLSelectionObject Methods


IHTMLSelectionObject::createRange

HRESULT createRange(
    IDispatch **range
);

Creates a text range from the current selection.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a variable that receives an interface pointer for the range.

See also IHTMLTxtRange


IHTMLSelectionObject::empty

HRESULT empty(void);

Deselects the current selection, sets the selection type to "none", and sets the item property to NULL.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLSelectionObject::clear IHTMLSelectionObject::clear *
  * Previous Topic: IHTMLSelectionObject::empty
  * Next Topic: IHTMLSelectionObject::get_type

IHTMLSelectionObject::clear

HRESULT clear(
    void
);

Clears the contents of the selection.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLSelectionObject::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of selection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. Can be one of these values:
None | The selection is an insertion point (no text is selected).
Text | The selection is a text selection.


IHTMLSpanElement

This interface provides access to the properties and methods for this object and is equivalent to the IHTMLElement interface. For more information and a listing of the available methods, see the reference section for the IHTMLElement interface.


IHTMLSpanFlow

This interface has no structural role or established rendering convention. It allows users to define their own method of rendering using style sheets.

IHTMLSpanFlow Methods


Align Property

*
  * Previous Topic: IHTMLSpanFlow::put_align
  * Next Topic: IHTMLStyle

IHTMLSpanFlow::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also put_align

Up Top of Page

IHTMLSpanFlow::put_align

HRESULT put_align(
    BSTR v
);

Sets how the element is aligned with adjacent text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
absbottom | Aligns the bottom of the element with the absolute bottom of the surrounding text. The absolute bottom is equal to the baseline of the text minus the height of the largest descender in the text.
absmiddle | Aligns the middle of the element with the middle of the surrounding text. The absolute middle is the midpoint between the absolute bottom and texttop of the surrounding text.
baseline | Aligns the bottom of the element with the baseline of the surrounding text.
bottom | Aligns the bottom of the element with the bottom of the surrounding text. The bottom is equal to the baseline minus the standard height of a descender in the text.
left | Aligns the element to the left of the surrounding text. All preceding and subsequent text flows to the right of the element. This is the default value.
middle | Aligns the middle of the element with the surrounding text.
right | Aligns the element to the right of the surrounding text. All subsequent text flows to the left of the element.
texttop | Aligns the top of the element with the absolute top of the surrounding text. The absolute top is the baseline plus the height of the largest ascender in the text.
top | Aligns the top of the element with the top of the text. The top of the text is the baseline plus the standard height of an ascender in the text.

For the INPUT element, this attribute applies only to the image type. It is undefined for all other types.

See also get_align


IHTMLStyle

This interface provides access to the methods that are returned when you access the style object. A style object represents the current settings of all possible inline styles for a given element. Inline styles are CSS style assignments that an author applies directly to individual HTML elements using the STYLE attribute. You use the style object to examine these assignments and either make new assignments or change existing ones.

You retrieve the style object by using the IHTMLElement::get_style function. You retrieve the current setting for an inline style by calling member functions of the style object.

The style object does not give access to the style assignments in style sheets. To obtain information about styles in style sheets, you must use the IHTMLStyleSheetsCollection interface to gain access to the individual style sheets defined in the document.

IHTMLStyle Methods
put_fontFamily get_fontFamily put_fontStyle
get_fontStyle put_fontVariant get_fontVariant
put_fontWeight get_fontWeight put_fontSize
get_fontSize put_font get_font
put_color get_color put_background
get_background put_backgroundColor get_backgroundColor
put_backgroundImage get_backgroundImage put_backgroundRepeat
get_backgroundRepeat put_backgroundAttachment get_backgroundAttachment
put_backgroundPosition get_backgroundPosition put_backgroundPositionX
get_backgroundPositionX put_backgroundPositionY get_backgroundPositionY
put_wordSpacing get_wordSpacing put_letterSpacing
get_letterSpacing put_textDecoration get_textDecoration
put_textDecorationNone get_textDecorationNone put_textDecorationUnderline
get_textDecorationUnderline put_textDecorationOverline get_textDecorationOverline
put_textDecorationLineThrough get_textDecorationLineThrough put_textDecorationBlink
get_textDecorationBlink put_verticalAlign get_verticalAlign
put_textTransform get_textTransform put_textAlign
get_textAlign put_textIndent get_textIndent
put_lineHeight get_lineHeight put_marginTop
get_marginTop put_marginRight get_marginRight
put_marginBottom get_marginBottom put_marginLeft
get_marginLeft put_margin get_margin
put_paddingTop get_paddingTop put_paddingRight
get_paddingRight put_paddingBottom get_paddingBottom
put_paddingLeft get_paddingLeft put_padding
get_padding put_border get_border
put_borderTop get_borderTop put_borderRight
get_borderRight put_borderBottom get_borderBottom
put_borderLeft get_borderLeft put_borderColor
get_borderColor put_borderTopColor get_borderTopColor
put_borderRightColor get_borderRightColor put_borderBottomColor
get_borderBottomColor put_borderLeftColor get_borderLeftColor
put_borderWidth get_borderWidth put_borderTopWidth
get_borderTopWidth put_borderRightWidth get_borderRightWidth
put_borderBottomWidth get_borderBottomWidth put_borderLeftWidth
get_borderLeftWidth put_borderStyle get_borderStyle
put_borderTopStyle get_borderTopStyle put_borderRightStyle
get_borderRightStyle put_borderBottomStyle get_borderBottomStyle
put_borderLeftStyle get_borderLeftStyle put_width
get_width put_height get_height
put_styleFloat get_styleFloat put_clear
get_clear put_display get_display
put_visibility get_visibility put_listStyleType
get_listStyleType put_listStylePosition get_listStylePosition
put_listStyleImage get_listStyleImage put_listStyle
get_listStyle put_whiteSpace get_whiteSpace
put_top get_top put_left
get_left get_position put_zIndex
get_zIndex put_overflow get_overflow
put_pageBreakBefore get_pageBreakBefore put_pageBreakAfter
get_pageBreakAfter put_cssText get_cssText
put_pixelTop get_pixelTop put_pixelLeft
get_pixelLeft put_pixelWidth get_pixelWidth
put_pixelHeight get_pixelHeight put_posTop
get_posTop put_posLeft get_posLeft
put_posWidth get_posWidth put_posHeight
get_posHeight put_cursor get_cursor
put_clip get_clip put_filter
get_filter setAttribute getAttribute
removeAttribute toString

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Background Property

*
  * Previous Topic: IHTMLStyle
  * Next Topic: IHTMLStyle::get_backgroundAttachment

IHTMLStyle::get_background

HRESULT get_background(
    BSTR *p
);

Retrieves the value of the CSS background attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background for details. This parameter receives NULL if the attribute is not set.

See also put_background

Up Top of Page

IHTMLStyle::put_background

HRESULT put_background(
    BSTR v
);

Sets the value of the CSS background attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute, or NULL to remove it. See background for details.

See also get_background


BackgroundAttachment Property

*
  * Previous Topic: IHTMLStyle::get_background
  * Next Topic: IHTMLStyle::get_backgroundColor

IHTMLStyle::get_backgroundAttachment

HRESULT get_backgroundAttachment(
    BSTR *p
);

Retrieves the value of the CSS background-attachment attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
fixed | Background image remains fixed.
scroll | Background image scrolls with text.
See background-attachment for details.

See also put_backgroundAttachment

Up Top of Page

IHTMLStyle::put_backgroundAttachment

HRESULT put_backgroundAttachment(
    BSTR v
);

Sets the value of the CSS background-attachment attribute for the element. If the element has a background image, this attribute determines if the image is fixed with regard to the text of the element, or if it scrolls with the text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute, or NULL to remove it. Can be one of these strings:
fixed | Background image remains fixed.
scroll | Background image scrolls with text.
See background-attachment for details.

See also get_backgroundAttachment


BackgroundColor Property

*
  * Previous Topic: IHTMLStyle::get_backgroundAttachment
  * Next Topic: IHTMLStyle::get_backgroundImage

IHTMLStyle::get_backgroundColor

HRESULT get_backgroundColor(
    VARIANT *p
);

Retrieves the value of the CSS background-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-color for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundColor

Up Top of Page

IHTMLStyle::put_backgroundColor

HRESULT put_backgroundColor(
    VARIANT v
);

Sets the CSS background-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the background color, or NULL to remove the attribute. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_backgroundColor


BackgroundImage Property

*
  * Previous Topic: IHTMLStyle::get_backgroundColor
  * Next Topic: IHTMLStyle::get_backgroundPosition

IHTMLStyle::get_backgroundImage

HRESULT get_backgroundImage(
    BSTR *p
);

Retrieves the value of the CSS background-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundImage

Up Top of Page

IHTMLStyle::put_backgroundImage

HRESULT put_backgroundImage(
    BSTR v
);

Sets a CSS background-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL of the background image, or NULL to remove the attribute. See background-image for details.

See also get_backgroundImage


BackgroundPosition Property

*
  * Previous Topic: IHTMLStyle::get_backgroundImage
  * Next Topic: IHTMLStyle::get_backgroundPositionX

IHTMLStyle::get_backgroundPosition

HRESULT get_backgroundPosition(
    BSTR *p
);

Retrieves the value of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundPosition

Up Top of Page

IHTMLStyle::put_backgroundPosition

HRESULT put_backgroundPosition(
    BSTR v
);

Sets the value of the CSS background-position attribute for the element. The attribute determines the initial position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the initial background position, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPosition


BackgroundPositionX Property

*
  * Previous Topic: IHTMLStyle::get_backgroundPosition
  * Next Topic: IHTMLStyle::get_backgroundPositionY

IHTMLStyle::get_backgroundPositionX

HRESULT get_backgroundPositionX(
    VARIANT *p
);

Retrieves the x-coordinate of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the x-coordinate. See background-image for details. This parameter receives NULL if the parameter is not set.

See also put_backgroundPositionX

Up Top of Page

IHTMLStyle::put_backgroundPositionX

HRESULT put_backgroundPositionX(
    VARIANT v
);

Sets the x-coordinate of the CSS background-position attribute for the element. The attribute determines the initial horizontal position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the x-coordinate, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPositionX


BackgroundPositionY Property

*
  * Previous Topic: IHTMLStyle::get_backgroundPositionX
  * Next Topic: IHTMLStyle::get_backgroundRepeat

IHTMLStyle::get_backgroundPositionY

HRESULT get_backgroundPositionY(
    VARIANT *p
);

Retrieves the y-coordinate of the CSS background-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the y-coordinate. See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundPositionY

Up Top of Page

IHTMLStyle::put_backgroundPositionY

HRESULT put_backgroundPositionY(
    VARIANT v
);

Sets the y-coordinate of the CSS background-position attribute for the element. The attribute determines the initial vertical position of the background image, if any.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the y-coordinate, or NULL to remove the attribute. See background-position for details.

See also get_backgroundPositionY


BackgroundRepeat Property

*
  * Previous Topic: IHTMLStyle::get_backgroundPositionY
  * Next Topic: IHTMLStyle::get_border

IHTMLStyle::get_backgroundRepeat

HRESULT get_backgroundRepeat(
    BSTR *p
);

Retrieves the value of the CSS background-repeat attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
norepeat | Do not repeat.
repeaty | Repeat vertically.
repeat | Repeat both horizontally and vertically.
repeatx | Repeat horizontally.
See background-image for details. This parameter receives NULL if the attribute is not set.

See also put_backgroundRepeat

Up Top of Page

IHTMLStyle::put_backgroundRepeat

HRESULT put_backgroundRepeat(
    BSTR v
);

Sets the value of the CSS background-repeat attribute for the element. The attribute determines whether and how the background image, if any, is repeated.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether and how the image is repeated, or NULL to remove the attribute. Can be one of these strings:
norepeat | Do not repeat.
repeaty | Repeat vertically.
repeat | Repeat both horizontally and vertically.
repeatx | Repeat horizontally.
See background-repeat for details.

See also get_backgroundRepeat


Border Property

*
  * Previous Topic: IHTMLStyle::get_backgroundRepeat
  * Next Topic: IHTMLStyle::get_borderBottom

IHTMLStyle::get_border

HRESULT get_border(
    BSTR *p
);

Retrieves the value of the CSS border attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the border. See border for details. This parameter receives NULL if the attribute is not set.

See also put_border

Up Top of Page

IHTMLStyle::put_border

HRESULT put_border(
    BSTR v
);

Sets the value of the CSS border attribute for the element. The attribute describes the color, style, and width of the border to display around the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying values that describe the border. See border for details. Set this parameter to NULL to remove the attribute.

See also get_border


BorderBottom Property

*
  * Previous Topic: IHTMLStyle::get_border
  * Next Topic: IHTMLStyle::get_borderBottomColor

IHTMLStyle::get_borderBottom

HRESULT get_borderBottom(
    BSTR *p
);

Retrieves the value of the CSS border-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the bottom border. See border-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottom

Up Top of Page

IHTMLStyle::put_borderBottom

HRESULT put_borderBottom(
    BSTR v
);

Sets the value of the CSS border-bottom attribute for the element. The attribute determines the width, style, and color of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_borderBottom


BorderBottomColor Property

*
  * Previous Topic: IHTMLStyle::get_borderBottom
  * Next Topic: IHTMLStyle::get_borderBottomStyle

IHTMLStyle::get_borderBottomColor

HRESULT get_borderBottomColor(
    VARIANT *p
);

Retrieves the value of the CSS border-bottom-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-bottom-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomColor

Up Top of Page

IHTMLStyle::put_borderBottomColor

HRESULT put_borderBottomColor(
    VARIANT v
);

Sets the value of the CSS border-bottom-color attribute for the element. The attribute determines the color of the element's bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. See border-bottom-color for details. Set this parameter to NULL to remove the attribute.

See also get_borderBottomColor


BorderBottomStyle Property

*
  * Previous Topic: IHTMLStyle::get_borderBottomColor
  * Next Topic: IHTMLStyle::get_borderBottomWidth

IHTMLStyle::get_borderBottomStyle

HRESULT get_borderBottomStyle(
    BSTR *p
);

Retrieves the value of the CSS border-bottom-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-bottom-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomStyle

Up Top of Page

IHTMLStyle::put_borderBottomStyle

HRESULT put_borderBottomStyle(
    BSTR v
);

Sets the value of the CSS border-bottom-style attribute for the element. The attribute determines the style of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. See border-bottom-style for details. Set this parameter to NULL to remove the attribute.

See also get_borderBottomStyle


BorderBottomWidth Property

*
  * Previous Topic: IHTMLStyle::get_borderBottomStyle
  * Next Topic: IHTMLStyle::get_borderColor

IHTMLStyle::get_borderBottomWidth

HRESULT get_borderBottomWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-bottom-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-bottom-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderBottomWidth

Up Top of Page

IHTMLStyle::put_borderBottomWidth

HRESULT put_borderBottomWidth(
    VARIANT v
);

Sets the value of the CSS border-bottom-width attribute for the element. The attribute determines the width of the bottom border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. See border-bottom-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderBottomWidth


BorderColor Property

*
  * Previous Topic: IHTMLStyle::get_borderBottomWidth
  * Next Topic: IHTMLStyle::get_borderLeft

IHTMLStyle::get_borderColor

HRESULT get_borderColor(
    BSTR *p
);

Retrieves the value of the CSS border-color attribute of the element and must be used with the border property, except for frames. The color can be one of the color names or values given in the Color Table reference documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border color values. See border-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderColor

Up Top of Page

IHTMLStyle::put_borderColor

HRESULT put_borderColor(
    BSTR v
);

Sets the value of the CSS border-color attribute for the element. The attribute determines the color of the element's four borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. See border-left for details. Set this parameter to NULL to remove the attribute.

See also get_borderColor


BorderLeft Property

*
  * Previous Topic: IHTMLStyle::get_borderColor
  * Next Topic: IHTMLStyle::get_borderLeftColor

IHTMLStyle::get_borderLeft

HRESULT get_borderLeft(
    BSTR *p
);

Retrieves the value of the CSS border-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the left border. See border-left for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeft

Up Top of Page

IHTMLStyle::put_borderLeft

HRESULT put_borderLeft(
    BSTR v
);

Sets the value of the CSS border-left attribute for the element. The attribute determines the width, style, and color of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-left for details. Set this parameter to NULL to remove the attribute.

See also get_borderLeft


BorderLeftColor Property

*
  * Previous Topic: IHTMLStyle::get_borderLeft
  * Next Topic: IHTMLStyle::get_borderLeftStyle

IHTMLStyle::get_borderLeftColor

HRESULT get_borderLeftColor(
    VARIANT *p
);

Retrieves the value of the CSS border-left-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-left-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftColor

Up Top of Page

IHTMLStyle::put_borderLeftColor

HRESULT put_borderLeftColor(
    VARIANT v
);

Sets the value of the CSS border-left-color attribute for the element. The attribute determines the color of the element's left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. See border-left-color for details. Set this parameter to NULL to remove the attribute.

See also get_borderLeftColor


BorderLeftStyle Property

*
  * Previous Topic: IHTMLStyle::get_borderLeftColor
  * Next Topic: IHTMLStyle::get_borderLeftWidth

IHTMLStyle::get_borderLeftStyle

HRESULT get_borderLeftStyle(
    BSTR *p
);

Retrieves the value of the CSS border-left-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-left-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftStyle

Up Top of Page

IHTMLStyle::put_borderLeftStyle

HRESULT put_borderLeftStyle(
    BSTR v
);

Sets the value of the CSS border-left-style attribute for the element. The attribute determines the style of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. See border-left-style for details. Set this parameter to NULL to remove the attribute.

See also get_borderLeftStyle


BorderLeftWidth Property

*
  * Previous Topic: IHTMLStyle::get_borderLeftStyle
  * Next Topic: IHTMLStyle::get_borderRight

IHTMLStyle::get_borderLeftWidth

HRESULT get_borderLeftWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-left-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-left-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderLeftWidth

Up Top of Page

IHTMLStyle::put_borderLeftWidth

HRESULT put_borderLeftWidth(
    VARIANT v
);

Sets the value of the CSS border-left-width attribute for the element. The attribute determines the width of the left border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. See border-left-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderLeftWidth


BorderRight Property

*
  * Previous Topic: IHTMLStyle::get_borderLeftWidth
  * Next Topic: IHTMLStyle::get_borderRightColor

IHTMLStyle::get_borderRight

HRESULT get_borderRight(
    BSTR *p
);

Retrieves the value of the CSS border-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the right border. See border-right for details. This parameter receives NULL if the attribute is not set.

See also put_borderRight

Up Top of Page

IHTMLStyle::put_borderRight

HRESULT put_borderRight(
    BSTR v
);

Sets the value of the CSS border-right attribute for the element. The attribute determines the width, style, and color of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-right for details. Set this parameter to NULL to remove the attribute.

See also get_borderRight


BorderRightColor Property

*
  * Previous Topic: IHTMLStyle::get_borderRight
  * Next Topic: IHTMLStyle::get_borderRightStyle

IHTMLStyle::get_borderRightColor

HRESULT get_borderRightColor(
    VARIANT *p
);

Retrieves the value of the CSS border-right-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-right-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightColor

Up Top of Page

IHTMLStyle::put_borderRightColor

HRESULT put_borderRightColor(
    VARIANT v
);

Sets the value of the CSS border-right-color attribute for the element. The attribute determines the color of the element's right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. See border-right-color for details. Set this parameter to NULL to remove the attribute.

See also get_borderRightColor


BorderRightStyle Property

*
  * Previous Topic: IHTMLStyle::get_borderRightColor
  * Next Topic: IHTMLStyle::get_borderRightWidth

IHTMLStyle::get_borderRightStyle

HRESULT get_borderRightStyle(
    BSTR *p
);

Retrieves the value of the CSS border-right-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-right-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightStyle

Up Top of Page

IHTMLStyle::put_borderRightStyle

HRESULT put_borderRightStyle(
    BSTR v
);

Sets the value of the CSS border-right-style attribute for the element. The attribute determines the style of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. See border-right-style for details. Set this parameter to NULL to remove the attribute.

See also get_borderRightStyle


BorderRightWidth Property

*
  * Previous Topic: IHTMLStyle::get_borderRightStyle
  * Next Topic: IHTMLStyle::get_borderStyle

IHTMLStyle::get_borderRightWidth

HRESULT get_borderRightWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-right-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-right-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderRightWidth

Up Top of Page

IHTMLStyle::put_borderRightWidth

HRESULT put_borderRightWidth(
    VARIANT v
);

Sets the value of the CSS border-right-width attribute for the element. The attribute determines the width of the right border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. See border-right-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderRightWidth


BorderStyle Property

*
  * Previous Topic: IHTMLStyle::get_borderRightWidth
  * Next Topic: IHTMLStyle::get_borderTop

IHTMLStyle::get_borderStyle

HRESULT get_borderStyle(
    BSTR *p
);

Retrieves the value of the CSS border-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border styles. See border-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderStyle

Up Top of Page

IHTMLStyle::put_borderStyle

HRESULT put_borderStyle(
    BSTR v
);

Sets the value of the CSS border-style attribute for the element. The attribute determines the style of the left, right, top, and bottom borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border styles. See border-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderStyle


BorderTop Property

*
  * Previous Topic: IHTMLStyle::get_borderStyle
  * Next Topic: IHTMLStyle::get_borderTopColor

IHTMLStyle::get_borderTop

HRESULT get_borderTop(
    BSTR *p
);

Retrieves the value of the CSS border-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives values that describe the top border. See border-top for details. This parameter receives NULL if the attribute is not set.

See also put_borderTop

Up Top of Page

IHTMLStyle::put_borderTop

HRESULT put_borderTop(
    BSTR v
);

Sets the value of the CSS border-top attribute for the element. The attribute determines the width, style, and color of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width, style, and color. See border-top for details. Set this parameter to NULL to remove the attribute.

See also get_borderTop


BorderTopColor Property

*
  * Previous Topic: IHTMLStyle::get_borderTop
  * Next Topic: IHTMLStyle::get_borderTopStyle

IHTMLStyle::get_borderTopColor

HRESULT get_borderTopColor(
    VARIANT *p
);

Retrieves the value of the CSS border-top-color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color value. See border-top-color for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopColor

Up Top of Page

IHTMLStyle::put_borderTopColor

HRESULT put_borderTopColor(
    VARIANT v
);

Sets the value of the CSS border-top-color attribute for the element. The attribute determines the color of the element's top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border color, which can be one of the color names or values given in the Color Table reference documentation. See border-top-color for details. Set this parameter to NULL to remove the attribute.

See also get_borderTopColor


BorderTopStyle Property

*
  * Previous Topic: IHTMLStyle::get_borderTopColor
  * Next Topic: IHTMLStyle::get_borderTopWidth

IHTMLStyle::get_borderTopStyle

HRESULT get_borderTopStyle(
    BSTR *p
);

Retrieves the value of the CSS border-top-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border style. See border-top-style for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopStyle

Up Top of Page

IHTMLStyle::put_borderTopStyle

HRESULT put_borderTopStyle(
    BSTR v
);

Sets the value of the CSS border-top-style attribute for the element. The attribute determines the style of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border style. See border-top-style for details. Set this parameter to NULL to remove the attribute.

See also get_borderTopStyle


BorderTopWidth Property

*
  * Previous Topic: IHTMLStyle::get_borderTopStyle
  * Next Topic: IHTMLStyle::get_borderWidth

IHTMLStyle::get_borderTopWidth

HRESULT get_borderTopWidth(
    VARIANT *p
);

Retrieves the value of the CSS border-top-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border width. See border-top-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderTopWidth

Up Top of Page

IHTMLStyle::put_borderTopWidth

HRESULT put_borderTopWidth(
    VARIANT v
);

Sets the value of the CSS border-top-width attribute for the element. The attribute determines the width of the top border.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border width. See border-top-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderTopWidth


BorderWidth Property

*
  * Previous Topic: IHTMLStyle::get_borderTopWidth
  * Next Topic: IHTMLStyle::get_clear

IHTMLStyle::get_borderWidth

HRESULT get_borderWidth(
    BSTR *p
);

Retrieves the value of the CSS border-width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the border widths. See border-width for details. This parameter receives NULL if the attribute is not set.

See also put_borderWidth

Up Top of Page

IHTMLStyle::put_borderWidth

HRESULT put_borderWidth(
    BSTR v
);

Sets the value of the CSS border-width attribute for the element. The attribute determines the width of the left, right, top, and bottom borders.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the border widths. See border-width for details. Set this parameter to NULL to remove the attribute.

See also get_borderWidth


Clear Property

*
  * Previous Topic: IHTMLStyle::get_borderWidth
  * Next Topic: IHTMLStyle::get_clip

IHTMLStyle::get_clear

HRESULT get_clear(
    BSTR *p
);

Retrieves the value of the CSS clear attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
both
See clear for details. This parameter receives NULL if the attribute is not set.

See also put_clear

Up Top of Page

IHTMLStyle::put_clear

HRESULT put_clear(
    BSTR v
);

Sets the value of the CSS clear attribute for the element. The attribute determines whether the element allows floating elements (typically images) on its left and right sides. More specifically, the attribute specifies the sides where floating elements are not allowed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the sides where floating elements cannot appear. Can be one of these strings:
left
right
both
See clear for details. Set this parameter to NULL to remove the attribute.

See also get_clear


Clip Property

*
  * Previous Topic: IHTMLStyle::get_clear
  * Next Topic: IHTMLStyle::get_color

IHTMLStyle::get_clip

HRESULT get_clip(
    BSTR *p
);

Retrieves the value of the CSS clip attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the coordinates of the clipping area. This variable receives NULL if the attribute is not set. See clip for details.

See also put_clip

Up Top of Page

IHTMLStyle::put_clip

HRESULT put_clip(
    BSTR v
);

Sets the value of the CSS clip attribute for the element. The attribute determines which part of the element is visible. Any part of the element that is outside the clipping area is transparent.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the coordinates of the clipping area. Each coordinate can be a length value or "auto". See clip for details. Set this parameter to NULL to remove the attribute.

See also get_clip


Color Property

*
  * Previous Topic: IHTMLStyle::get_clip
  * Next Topic: IHTMLStyle::get_cssText

IHTMLStyle::get_color

HRESULT get_color(
    VARIANT *p
);

Retrieves the value of the CSS color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See color for details. This parameter receives NULL if the attribute is not set.

See also put_color

Up Top of Page

IHTMLStyle::put_color

HRESULT put_color(
    VARIANT v
);

Sets the CSS color attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color, or NULL to remove the attribute. See color for details. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_color


CssText Property

*
  * Previous Topic: IHTMLStyle::get_color
  * Next Topic: IHTMLStyle::get_cursor

IHTMLStyle::get_cssText

HRESULT get_cssText(
    BSTR *p
);

Retrieves the persisted representation of the style rule.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the style rule.

See also put_cssText

Up Top of Page

IHTMLStyle::put_cssText

HRESULT put_cssText(
    BSTR v
);

Sets the persisted representation of the style rule.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the style rule.

See also get_cssText


Cursor Property

*
  * Previous Topic: IHTMLStyle::get_cssText
  * Next Topic: IHTMLStyle::get_display

IHTMLStyle::get_cursor

HRESULT get_cursor(
    BSTR *p
);

Retrieves the value of the CSS cursor attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See cursor for details. This variable receives NULL if the attribute is not set.

See also put_cursor

Up Top of Page

IHTMLStyle::put_cursor

HRESULT put_cursor(
    BSTR v
);

Sets the value of the CSS cursor attribute for the element. The attribute determines the type of cursor to display when the mouse is over the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the cursor type. Can be one of these values:
auto | The UA determines the cursor to display based on the current context.
crosshair | A simple crosshair.
default | The platform-dependent default cursor (typically an arrow).
hand | A hand.
move | A four-directional arrow typically used to indicate an object to be moved.
*-resize | An arrow cursor typically used to indicate the edge of an object to be moved during a resize operation.
text | Typically an I-bar used to indicate editable text.
wait | Typically a watch or hourglass used to indicate that the program is busy and the user should wait.

See also get_cursor


Display Property

*
  * Previous Topic: IHTMLStyle::get_cursor
  * Next Topic: IHTMLStyle::get_filter

IHTMLStyle::get_display

HRESULT get_display(
    BSTR *p
);

Retrieves the value of the display attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The variable receives "none" if the element is not being rendered, or NULL if it is. See display for details.

See also put_display

Up Top of Page

IHTMLStyle::put_display

HRESULT put_display(
    BSTR v
);

Sets the value of the CSS display attribute for the element. The attribute determines whether the element is rendered.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether to render the element. If this parameter is "none", the element is not rendered; if NULL, it is rendered. See display for details.

Although you can apply the display attribute to parts of a table (such as a TR or TD element), changing the property has no effect on those parts. However, you can dynamically control the rendering of the entire table by applying the attribute to the TABLE element.

See also get_display


Filter Property

*
  * Previous Topic: IHTMLStyle::get_display
  * Next Topic: IHTMLStyle::get_font

IHTMLStyle::get_filter

HRESULT get_filter(
    BSTR *p
);

Retrieves a filter or collection of filters for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the filter.

See also put_filter

Up Top of Page

IHTMLStyle::put_filter

HRESULT put_filter(
    BSTR v
);

Sets a filter or collection of filters for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the filter.

See also get_filter


Font Property

*
  * Previous Topic: IHTMLStyle::get_filter
  * Next Topic: IHTMLStyle::get_fontFamily

IHTMLStyle::get_font

HRESULT get_font(
    BSTR *p
);

Retrieves the values of the CSS font-style, font-variant, font-weight, font-size, line-height, and font-family attributes for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the values of the font-related CSS attributes. See font for details. This parameter receives NULL if no font-related CSS attributes are set for the element.

See also put_font

Up Top of Page

IHTMLStyle::put_font

HRESULT put_font(
    BSTR v
);

Sets the value of the CSS font-style, font-variant, font-weight, font-size, line-height, and font-family attributes for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying values for one or more font attributes. This parameter has the following format:
[<font-style> || <font-variant> || <font-weight>] <font-size> /
[<line-height>] <font-family>
See font for details.

See also get_font


FontFamily Property

*
  * Previous Topic: IHTMLStyle::get_font
  * Next Topic: IHTMLStyle::get_fontSize

IHTMLStyle::get_fontFamily

HRESULT get_fontFamily(
    BSTR *p
);

Retrieves the value of the CSS font-family attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See font-family for details. This parameter receives NULL if the attribute is not set.

See also put_fontFamily

Up Top of Page

IHTMLStyle::put_fontFamily

HRESULT put_fontFamily(
    BSTR v
);

Sets the value of the CSS font-family attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font family, or NULL to remove the attribute. See font-family for details.

See also get_fontFamily


FontSize Property

*
  * Previous Topic: IHTMLStyle::get_fontFamily
  * Next Topic: IHTMLStyle::get_fontStyle

IHTMLStyle::get_fontSize

HRESULT get_fontSize(
    VARIANT *p
);

Retrieves the value of the CSS font-size attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See font-size for details. This parameter receives NULL if the attribute is not set.

See also put_fontSize

Up Top of Page

IHTMLStyle::put_fontSize

HRESULT put_fontSize(
    VARIANT v
);

Sets the value of the CSS font-size attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font size, or NULL to remove the attribute. See font-size for details.

See also get_fontSize


FontStyle Property

*
  * Previous Topic: IHTMLStyle::get_fontSize
  * Next Topic: IHTMLStyle::get_fontVariant

IHTMLStyle::get_fontStyle

HRESULT get_fontStyle(
    BSTR *p
);

Retrieves the value of the CSS font-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
italic
oblique
See font-style for details. This parameter receives NULL if the attribute is not set.

See also put_fontStyle

Up Top of Page

IHTMLStyle::put_fontStyle

HRESULT put_fontStyle(
    BSTR v
);

Sets the value of the CSS font-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font style, or NULL to remove the attribute. The font style can be one of these strings:
normal
italic
oblique
See font-style for details.

See also get_fontStyle


FontVariant Property

*
  * Previous Topic: IHTMLStyle::get_fontStyle
  * Next Topic: IHTMLStyle::get_fontWeight

IHTMLStyle::get_fontVariant

HRESULT get_fontVariant(
    BSTR *p
);

Retrieves the value of the CSS font-variant attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
small-caps
See font-variant for details. This parameter receives NULL if the attribute is not set.

The default value for this property is 1.

See also put_fontVariant

Up Top of Page

IHTMLStyle::put_fontVariant

HRESULT put_fontVariant(
    BSTR v
);

Sets the value of the CSS font-variant attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font variation, or NULL to remove the attribute. The font variation can be one of these strings:
normal
small-caps
See font-variant for details.

The default value for the font-variant attribute is "normal".

See also get_fontVariant


FontWeight Property

*
  * Previous Topic: IHTMLStyle::get_fontVariant
  * Next Topic: IHTMLStyle::get_height

IHTMLStyle::get_fontWeight

HRESULT get_fontWeight(
    BSTR *p
);

Retrieves the value of the CSS font-weight attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900
See font-weight for details. This parameter receives NULL if the attribute is not set.

See also put_fontWeight

Up Top of Page

IHTMLStyle::put_fontWeight

HRESULT put_fontWeight(
    BSTR v
);

Sets the value of the CSS font-weight attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the font weight, or NULL to remove the attribute. The font weight can be one of these strings:
normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900
See font-weight for details.

See also get_fontWeight


Height Property

*
  * Previous Topic: IHTMLStyle::get_fontWeight
  * Next Topic: IHTMLStyle::get_left

IHTMLStyle::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the value of the CSS height attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height. See height for details. This parameter receives NULL if the attribute is not set.

See also put_height

Up Top of Page

IHTMLStyle::put_height

HRESULT put_height(
    VARIANT v
);

Sets the value of the CSS height attribute for the element. The attribute determines the element's height.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the height, which consists of a floating-point number and a units designator. See height for details. Set this parameter to NULL to remove the attribute.

See also get_height


Left Property

*
  * Previous Topic: IHTMLStyle::get_height
  * Next Topic: IHTMLStyle::get_letterSpacing

IHTMLStyle::get_left

HRESULT get_left(
    VARIANT *p
);

Retrieves the value of the CSS left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The value is a string consisting of a floating-point number and a units designator. The variable receives NULL if the attribute is not set. See left for details.

See also put_left

Up Top of Page

IHTMLStyle::put_left

HRESULT put_left(
    VARIANT v
);

Sets the value of the CSS left attribute for the element. The attribute determines the left position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value consisting of a floating-point number and a units designator. See left for details. Set this parameter to NULL to remove the attribute.

See also get_left


LetterSpacing Property

*
  * Previous Topic: IHTMLStyle::get_left
  * Next Topic: IHTMLStyle::get_lineHeight

IHTMLStyle::get_letterSpacing

HRESULT get_letterSpacing(
    VARIANT *p
);

Retrieves the value of the CSS letter-spacing for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. See letter-spacing for details.

See also put_letterSpacing

Up Top of Page

IHTMLStyle::put_letterSpacing

HRESULT put_letterSpacing(
    VARIANT v
);

Sets the value of the CSS letter-spacing attribute for the element. The attribute determines the amount of space to add to the default space between letters in the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of space to add. A negative value is valid. See letter-spacing for details. Set this parameter to NULL to remove the attribute.

See also get_letterSpacing


LineHeight Property

*
  * Previous Topic: IHTMLStyle::get_letterSpacing
  * Next Topic: IHTMLStyle::get_listStyle

IHTMLStyle::get_lineHeight

HRESULT get_lineHeight(
    VARIANT *p
);

Retrieves the value of the CSS line-height attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See line-height for details. The variable receives NULL if the attribute is not set.

See also put_lineHeight

Up Top of Page

IHTMLStyle::put_lineHeight

HRESULT put_lineHeight(
    VARIANT v
);

Sets the value of the CSS line-height attribute for the element. The attribute determines the distance between the baselines of subsequent lines of text. Use a negative line height to achieve various shadowing effects.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the line height. The height can be positive or negative. Set this parameter to NULL to remove the attribute.

See also get_lineHeight


ListStyle Property

*
  * Previous Topic: IHTMLStyle::get_lineHeight
  * Next Topic: IHTMLStyle::get_listStyleImage

IHTMLStyle::get_listStyle

HRESULT get_listStyle(
    BSTR *p
);

Retrieves the value of the CSS list-style attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See list-style for details. The variable receives NULL if the attribute is not set.

The list-style attribute is applicable only on elements that have the display attribute set to "list-item".

This function combines the functionality of the get_listStyleType, get_listStyleImage, and get_listStylePosition functions.

See also put_listStyle

Up Top of Page

IHTMLStyle::put_listStyle

HRESULT put_listStyle(
    BSTR v
);

Sets the value of the CSS list-style attribute for the element. The attribute determines how a list-item marker is drawn.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the values of the attribute. See list-style for details. Set this parameter to NULL to remove the attribute.

The list-style attribute is applicable only on elements that have the display attribute set to "list-item". This property can be set on any element and is inherited down the tree. In HTML, this is typically the case for the LI element.

This function combines the functionality of the put_listStyleType, put_listStyleImage, and put_listStylePosition functions.

If no type or position is specified, the default type is "disk" and the default position is "outside".

See also get_listStyle


ListStyleImage Property

*
  * Previous Topic: IHTMLStyle::get_listStyle
  * Next Topic: IHTMLStyle::get_listStylePosition

IHTMLStyle::get_listStyleImage

HRESULT get_listStyleImage(
    BSTR *p
);

Retrieves the value of the CSS list-style-image attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be either "none" or the URL of the image used as the list-item marker. See list-style-image for details. The variable receives NULL if the attribute is not set.

The list-style-image attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStyleImage

Up Top of Page

IHTMLStyle::put_listStyleImage

HRESULT put_listStyleImage(
    BSTR v
);

Sets the value of the CSS list-style-image attribute for the element. The attribute sets the image to use as the list-item marker. When the image is available, it replaces the marker.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be either "none" or the URL of an image. See list-style-image for details. Set this parameter to NULL to remove the attribute.

The list-style-image attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStyleImage


ListStylePosition Property

*
  * Previous Topic: IHTMLStyle::get_listStyleImage
  * Next Topic: IHTMLStyle::get_listStyleType

IHTMLStyle::get_listStylePosition

HRESULT get_listStylePosition(
    BSTR *p
);

Retrieves the value of the CSS list-style-position attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
inside
outside
See list-style-position for details. The variable receives NULL if the attribute is not set.

The list-style-position attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStylePosition

Up Top of Page

IHTMLStyle::put_listStylePosition

HRESULT put_listStylePosition(
    BSTR v
);

Sets the value of the CSS list-style-position attribute for the element. The attribute determines how the list-item marker is drawn with regard to the content.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
inside
outside
See list-style-position for details. Set this parameter to NULL to remove the attribute.

The list-style-position attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStylePosition


ListStyleType Property

*
  * Previous Topic: IHTMLStyle::get_listStylePosition
  * Next Topic: IHTMLStyle::get_margin

IHTMLStyle::get_listStyleType

HRESULT get_listStyleType(
    BSTR *p
);

Retrieves the value of the CSS list-style-type attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
disk
circle
square
decimal
lower-roman
upper-roman
lower-alpha
upper-alpha
none
See list-style-type for details. The variable receives NULL if the attribute is not set.

The list-style-type attribute is applicable only on elements that have the display attribute set to "list-item".

See also put_listStyleType

Up Top of Page

IHTMLStyle::put_listStyleType

HRESULT put_listStyleType(
    BSTR v
);

Sets the value of the CSS list-style-type attribute for the element. The attribute determines the appearance of the list-item marker if the list-style-image is set to "none" or if the image pointed to by the URL cannot be displayed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
disk
circle
square
decimal
lower-roman
upper-roman
lower-alpha
upper-alpha
none
See list-style-type for details. Set this parameter to NULL to remove the attribute.

The list-style-type attribute is applicable only on elements that have the display attribute set to "list-item".

See also get_listStyleType


Margin Property

*
  * Previous Topic: IHTMLStyle::get_listStyleType
  * Next Topic: IHTMLStyle::get_marginBottom

IHTMLStyle::get_margin

HRESULT get_margin(
    BSTR *p
);

Retrieves the value of the CSS margin attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the top, right, bottom, and left margins, in that order. See margin for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the get_marginTop, get_marginRight, get_marginBottom, and get_marginLeft functions.

See also put_margin

Up Top of Page

IHTMLStyle::put_margin

HRESULT put_margin(
    BSTR v
);

Sets the value of the CSS margin attribute for the element. The attribute sets the top, right, bottom, and left margins for the text of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String that specifies the top, right, bottom, and left margins, in that order. See margin for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the put_marginTop, put_marginRight, put_marginBottom, and put_marginLeft functions.

See also get_margin


MarginBottom Property

*
  * Previous Topic: IHTMLStyle::get_margin
  * Next Topic: IHTMLStyle::get_marginLeft

IHTMLStyle::get_marginBottom

HRESULT get_marginBottom(
    VARIANT *p
);

Retrieves the value of the CSS margin-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_marginBottom

Up Top of Page

IHTMLStyle::put_marginBottom

HRESULT put_marginBottom(
    VARIANT v
);

Sets the value of the CSS margin-bottom attribute for the element. The attribute determines the height of the bottom margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the height of the bottom margin. The height can be positive or negative. See margin-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_marginBottom


MarginLeft Property

*
  * Previous Topic: IHTMLStyle::get_marginBottom
  * Next Topic: IHTMLStyle::get_marginRight

IHTMLStyle::get_marginLeft

HRESULT get_marginLeft(
    VARIANT *p
);

Retrieves the value of the CSS margin-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-left for details. This parameter receives NULL if the attribute is not set.

See also put_marginLeft

Up Top of Page

IHTMLStyle::put_marginLeft

HRESULT put_marginLeft(
    VARIANT v
);

Sets the value of the CSS margin-left attribute for the element. The attribute determines the width of the left margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the width of the left margin. The width can be positive or negative. See margin-left for details. Set this parameter to NULL to remove the attribute.

See also get_marginLeft


MarginRight Property

*
  * Previous Topic: IHTMLStyle::get_marginLeft
  * Next Topic: IHTMLStyle::get_marginTop

IHTMLStyle::get_marginRight

HRESULT get_marginRight(
    VARIANT *p
);

Retrieves the value of the CSS margin-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-right for details. This parameter receives NULL if the attribute is not set.

See also put_marginRight

Up Top of Page

IHTMLStyle::put_marginRight

HRESULT put_marginRight(
    VARIANT v
);

Sets the value of the CSS margin-right attribute for the element. The attribute determines the width of the right margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the width of the right margin. The width can be positive or negative. See margin-right for details. Set this parameter to NULL to remove the attribute.

See also get_marginRight


MarginTop Property

*
  * Previous Topic: IHTMLStyle::get_marginRight
  * Next Topic: IHTMLStyle::get_overflow

IHTMLStyle::get_marginTop

HRESULT get_marginTop(
    VARIANT *p
);

Retrieves the value of the CSS margin-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See margin-top for details. This parameter receives NULL if the attribute is not set.

See also put_marginTop

Up Top of Page

IHTMLStyle::put_marginTop

HRESULT put_marginTop(
    VARIANT v
);

Sets the value of the CSS margin-top attribute for the element. The attribute determines the height of the top margin for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the top margin. The height can be positive or negative. See margin-top for details. Set this parameter to NULL to remove the attribute.

See also get_marginTop


Overflow Property

*
  * Previous Topic: IHTMLStyle::get_marginTop
  * Next Topic: IHTMLStyle::get_padding

IHTMLStyle::get_overflow

HRESULT get_overflow(
    BSTR *p
);

Retrieves the value of the CSS overflow attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
none
clip
scroll
See overflow for details. The variable receives NULL if the attribute is not set.

See also put_overflow

Up Top of Page

IHTMLStyle::put_overflow

HRESULT put_overflow(
    BSTR v
);

Sets the value of the CSS overflow attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
none
clip
scroll
See overflow for details. Set this parameter to NULL to remove the attribute.

See also get_overflow


Padding Property

*
  * Previous Topic: IHTMLStyle::get_overflow
  * Next Topic: IHTMLStyle::get_paddingBottom

IHTMLStyle::get_padding

HRESULT get_padding(
    BSTR *p
);

Retrieves the value of the CSS padding attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the amount of top, right, bottom, and left padding, in that order. If this parameter specifies only one value, it applies to all sides. If it specifies two or three, the missing values are taken from the opposite side. See padding for details. This parameter receives NULL if the attribute is not set.

This function combines the functionality of the get_paddingTop, get_paddingRight, get_paddingBottom, and get_paddingLeft functions.

See also put_padding

Up Top of Page

IHTMLStyle::put_padding

HRESULT put_padding(
    BSTR v
);

Sets the value of the CSS padding attribute for the element. The attibute determines the amount of space between the border and the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String that specifies the amount of top, right, bottom, and left padding, in that order. See padding for details. Set this parameter to NULL to remove the attribute.

This function combines the functionality of the put_paddingTop, put_paddingRight, put_paddingBottom, and put_paddingLeft functions.

See also get_padding


PaddingBottom Property

*
  * Previous Topic: IHTMLStyle::get_padding
  * Next Topic: IHTMLStyle::get_paddingLeft

IHTMLStyle::get_paddingBottom

HRESULT get_paddingBottom(
    VARIANT *p
);

Retrieves the value of the CSS padding-bottom attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-bottom for details. This parameter receives NULL if the attribute is not set.

See also put_paddingBottom

Up Top of Page

IHTMLStyle::put_paddingBottom

HRESULT put_paddingBottom(
    VARIANT v
);

Sets the value of the CSS padding-bottom attribute for the element. The attribute determines the amount of space between the border and the bottom of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of bottom padding. See padding-bottom for details. Set this parameter to NULL to remove the attribute.

See also get_paddingBottom


PaddingLeft Property

*
  * Previous Topic: IHTMLStyle::get_paddingBottom
  * Next Topic: IHTMLStyle::get_paddingRight

IHTMLStyle::get_paddingLeft

HRESULT get_paddingLeft(
    VARIANT *p
);

Retrieves the value of the CSS padding-left attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-left for details. This parameter receives NULL if the attribute is not set.

See also put_paddingLeft

Up Top of Page

IHTMLStyle::put_paddingLeft

HRESULT put_paddingLeft(
    VARIANT v
);

Sets the value of the CSS padding-left attribute for the element. The attribute determines the amount of space between the border and the left of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of left padding. See padding-left for details. Set this parameter to NULL to remove the attribute.

See also get_paddingLeft


PaddingRight Property

*
  * Previous Topic: IHTMLStyle::get_paddingLeft
  * Next Topic: IHTMLStyle::get_paddingTop

IHTMLStyle::get_paddingRight

HRESULT get_paddingRight(
    VARIANT *p
);

Retrieves the value of the CSS padding-right attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-right for details. This parameter receives NULL if the attribute is not set.

See also put_paddingRight

Up Top of Page

IHTMLStyle::put_paddingRight

HRESULT put_paddingRight(
    VARIANT v
);

Sets the value of the CSS padding-right attribute for the element. The attribute determines the amount of space between the border and the right of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of right padding. See padding-right for details. Set this parameter to NULL to remove the attribute.

See also get_paddingRight


PaddingTop Property

*
  * Previous Topic: IHTMLStyle::get_paddingRight
  * Next Topic: IHTMLStyle::get_pageBreakAfter

IHTMLStyle::get_paddingTop

HRESULT get_paddingTop(
    VARIANT *p
);

Retrieves the value of the CSS padding-top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See padding-top for details. This parameter receives NULL if the attribute is not set.

See also put_paddingTop

Up Top of Page

IHTMLStyle::put_paddingTop

HRESULT put_paddingTop(
    VARIANT v
);

Sets the value of the CSS padding-top attribute for the element. The attribute determines the amount of space between the border and the top of the element's content.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of top padding. See padding-top for details. Set this parameter to NULL to remove the attribute.

See also get_paddingTop


PageBreakAfter Property

*
  * Previous Topic: IHTMLStyle::get_paddingTop
  * Next Topic: IHTMLStyle::get_pageBreakBefore

IHTMLStyle::get_pageBreakAfter

HRESULT get_pageBreakAfter(
    BSTR *p
);

Retrieves the value of the CSS page-break-after attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
auto | Insert a page break after the element only if necessary.
always | Always insert a page break after the element.
left | Insert one or two page breaks after the element until a blank left page is reached.
right | Insert one or two page breaks after the element until a blank right page is reached.
See page-break-after for details. The variable receives NULL if the attribute is not set.

See also put_pageBreakAfter

Up Top of Page

IHTMLStyle::put_pageBreakAfter

HRESULT put_pageBreakAfter(
    BSTR v
);

Sets the value of the CSS page-break-after attribute for the element. The attribute determines whether a page break occurs after the element and on what page the subsequent content should resume.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
auto | Insert a page break after the element only if necessary.
always | Always insert a page break after the element.
left | Insert one or two page breaks after the element until a blank left page is reached.
right | Insert one or two page breaks after the element until a blank right page is reached.
See page-break-after for details.

See also get_pageBreakAfter


PageBreakBefore Property

*
  * Previous Topic: IHTMLStyle::get_pageBreakAfter
  * Next Topic: IHTMLStyle::get_pixelHeight

IHTMLStyle::get_pageBreakBefore

HRESULT get_pageBreakBefore(
    BSTR *p
);

Retrieves the value of the CSS page-break-before attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
auto | Insert a page break before the element only if necessary.
always | Always insert a page break before the element.
left | Insert one or two page breaks before the element until a blank left page is reached.
right | Insert one or two page breaks before the element until a blank right page is reached.
See page-break-before for details. The variable receives NULL if the attribute is not set.

See also put_pageBreakBefore

Up Top of Page

IHTMLStyle::put_pageBreakBefore

HRESULT put_pageBreakBefore(
    BSTR v
);

Sets the value of the CSS page-break-before attribute for the element. The attribute determines whether a page break occurs before the element, and on what page the subsequent content should resume.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
auto | Insert a page break before the element only if necessary.
always | Always insert a page break before the element.
left | Insert one or two page breaks before the element until a blank left page is reached.
right | Insert one or two page breaks before the element until a blank right page is reached.
See page-break-before for details.

See also get_pageBreakBefore


PixelHeight Property

*
  * Previous Topic: IHTMLStyle::get_pageBreakBefore
  * Next Topic: IHTMLStyle::get_pixelLeft

IHTMLStyle::get_pixelHeight

HRESULT get_pixelHeight(
    long *p
);

Retrieves the height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height.

Unlike the height attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also put_pixelHeight

Up Top of Page

IHTMLStyle::put_pixelHeight

HRESULT put_pixelHeight(
    long v
);

Sets the height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the height. Setting this property changes the height without changing the units designator.

Unlike the height attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also get_pixelHeight


PixelLeft Property

*
  * Previous Topic: IHTMLStyle::get_pixelHeight
  * Next Topic: IHTMLStyle::get_pixelTop

IHTMLStyle::get_pixelLeft

HRESULT get_pixelLeft(
    long *p
);

Retrieves the left position of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the left position.

Unlike the left attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also put_pixelLeft

Up Top of Page

IHTMLStyle::put_pixelLeft

HRESULT put_pixelLeft(
    long v
);

Sets the left position of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the left position. Setting this property changes the value of the left position without changing the units designator.

Unlike the left attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also get_pixelLeft


PixelTop Property

*
  * Previous Topic: IHTMLStyle::get_pixelLeft
  * Next Topic: IHTMLStyle::get_pixelWidth

IHTMLStyle::get_pixelTop

HRESULT get_pixelTop(
   long *p
);

Retrieves the top position of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the top position.

Unlike the top attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also put_pixelTop

Up Top of Page

IHTMLStyle::put_pixelTop

HRESULT put_pixelTop(
    long v
);

Sets the top position of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the top position. Setting this property changes the value of the top position without changing the units designator.

Unlike the top attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also get_pixelTop


PixelWidth Property

*
  * Previous Topic: IHTMLStyle::get_pixelTop
  * Next Topic: IHTMLStyle::get_posHeight

IHTMLStyle::get_pixelWidth

HRESULT get_pixelWidth(
    long *p
);

Retrieves the width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width.

Unlike the width attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also put_pixelWidth

Up Top of Page

IHTMLStyle::put_pixelWidth

HRESULT put_pixelWidth(
    long v
);

Sets the width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the width. Setting this property changes the width without changing the units designator.

Unlike the width attribute, this attribute's value is an integer, not a string, and is always interpreted in pixels.

See also get_pixelWidth


PosHeight Property

*
  * Previous Topic: IHTMLStyle::get_pixelWidth
  * Next Topic: IHTMLStyle::get_position

IHTMLStyle::get_posHeight

HRESULT get_posHeight(
    float *p
);

Retrieves the height of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the height position.

Unlike the height property, this property's value is a floating-point number, not a string.

See also put_posHeight

Up Top of Page

IHTMLStyle::put_posHeight

HRESULT put_posHeight(
    float v
);

Sets the height of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Floating-point value specifying the height of the element.

Setting this property changes the value of the height but leaves the units designator for the property unchanged.

Unlike the height property, this property's value is a floating-point number, not a string.

See also get_posHeight


IHTMLStyle::get_position

HRESULT get_position(
    BSTR *p
);

Retrieves the value of the CSS position attribute for the element. The attribute specifies whether the element can be positioned and, if so, the position of the element relative to its parent object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
absolute | The element is placed relative to the document.
relative | The element is placed relative to its parent object.
static | The element cannot be positioned.
See position for details. This variable receives NULL if the attribute is not set.

The position attribute is not inherited.


PosLeft Property

*
  * Previous Topic: IHTMLStyle::get_position
  * Next Topic: IHTMLStyle::get_posTop

IHTMLStyle::get_posLeft

HRESULT get_posLeft(
    float *p
) ;

Retrieves the left position of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the left position.

Unlike the left property, this property's value is a floating-point number, not a string.

See also put_posLeft

Up Top of Page

IHTMLStyle::put_posLeft

HRESULT put_posLeft(
    float v
);

Sets the left position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Floating-point value specifying the left position.

Setting this property changes the value of the left position but leaves the units designator for the property unchanged.

Unlike the left property, this property's value is a floating-point number, not a string.

See also get_posLeft


PosTop Property

*
  * Previous Topic: IHTMLStyle::get_posLeft
  * Next Topic: IHTMLStyle::get_posWidth

IHTMLStyle::get_posTop

HRESULT get_posTop(
    float *p
);

Retrieves the top position of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the top position.

Unlike the top property, this property's value is a floating-point number, not a string.

See also put_posTop

Up Top of Page

IHTMLStyle::put_posTop

HRESULT put_posTop(
    float v
);

Sets the top position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Floating-point value specifying the top position.

Setting this property changes the value of the top position but leaves the units designator for the property unchanged.

Unlike the top property, this property's value is a floating-point number, not a string.

See also get_posTop


PosWidth Property

*
  * Previous Topic: IHTMLStyle::get_posTop
  * Next Topic: IHTMLStyle::get_styleFloat

IHTMLStyle::get_posWidth

HRESULT get_posWidth(
    float *p
);

Retrieves the width position of the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width position.

Unlike the width property, this property's value is a floating-point number, not a string.

See also put_posWidth

Up Top of Page

IHTMLStyle::put_posWidth

HRESULT put_posWidth(
    float v
);

Sets the width of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Floating-point value specifying the width of the element.

Setting this property changes the value of the width but leaves the units designator for the property unchanged.

Unlike the width property, this property's value is a floating-point number, not a string.

See also get_posWidth


StyleFloat Property

*
  * Previous Topic: IHTMLStyle::get_posWidth
  * Next Topic: IHTMLStyle::get_textAlign

IHTMLStyle::get_styleFloat

HRESULT get_styleFloat(
    BSTR *p
);

Retrieves the value of the CSS float attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
none
See height for details. This parameter receives NULL if the attribute is not set.

See also put_styleFloat

Up Top of Page

IHTMLStyle::put_styleFloat

HRESULT put_styleFloat(
    BSTR v
);

Sets the value of the CSS float attribute for the element. The attribute determines whether the element floats, causing text to flow around it.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
left
right
none
See float for details. Set this parameter to NULL to remove the attribute.

See also get_styleFloat


TextAlign Property

*
  * Previous Topic: IHTMLStyle::get_styleFloat
  * Next Topic: IHTMLStyle::get_textDecoration

IHTMLStyle::get_textAlign

HRESULT get_textAlign(
    BSTR *p
);

Retrieves the value of the CSS text-align attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
left
right
center
justify
See text-align for details. This parameter receives NULL if the attribute is not set.

See also put_textAlign

Up Top of Page

IHTMLStyle::put_textAlign

HRESULT put_textAlign(
    BSTR v
);

Sets the value of the CSS text-align attribute for the element. The attribute determines the alignment of the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text alignment, or NULL to remove the attribute. Can be one of these strings:
left
right
center
justify
See text-align for details.

See also get_textAlign


TextDecoration Property

*
  * Previous Topic: IHTMLStyle::get_textAlign
  * Next Topic: IHTMLStyle::get_textDecorationBlink

IHTMLStyle::get_textDecoration

HRESULT get_textDecoration(
    BSTR *p
);

Retrieves the value of the CSS text-decoration attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. See text-decoration for details.

See also put_textDecoration

Up Top of Page

IHTMLStyle::put_textDecoration

HRESULT put_textDecoration(
    BSTR v
);

Sets the value of the CSS text-decoration attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the text decorations. Can be "none" or one of the following strings:
underline
overline
line-through
See text-decoration for details. Set this parameter to NULL to remove the attribute.

See also get_textDecoration


TextDecorationBlink Property

*
  * Previous Topic: IHTMLStyle::get_textDecoration
  * Next Topic: IHTMLStyle::get_textDecorationLineThrough

IHTMLStyle::get_textDecorationBlink

HRESULT get_textDecorationBlink(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "blink".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "blink", or FALSE if not. See text-decoration for details.

See also put_textDecorationBlink

Up Top of Page

IHTMLStyle::put_textDecorationBlink

HRESULT put_textDecorationBlink(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "blink", or removes the "blink" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "blink"; FALSE removes the "blink" value from the attribute. See text-decoration for details.

See also get_textDecorationBlink


TextDecorationLineThrough Property

*
  * Previous Topic: IHTMLStyle::get_textDecorationBlink
  * Next Topic: IHTMLStyle::get_textDecorationNone

IHTMLStyle::get_textDecorationLineThrough

HRESULT get_textDecorationLineThrough(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "line-through".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "line-through", or FALSE if not. See text-decoration for details.

See also put_textDecorationLineThrough

Up Top of Page

IHTMLStyle::put_textDecorationLineThrough

HRESULT put_textDecorationLineThrough(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "line-through", or removes the "line-through" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "line-through"; FALSE removes the "line-through" value from the attribute. See text-decoration for details.

See also get_textDecorationLineThrough


TextDecorationNone Property

*
  * Previous Topic: IHTMLStyle::get_textDecorationLineThrough
  * Next Topic: IHTMLStyle::get_textDecorationOverline

IHTMLStyle::get_textDecorationNone

HRESULT get_textDecorationNone(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "none".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "none", or FALSE if not. See text-decoration for details.

See also put_textDecorationNone

Up Top of Page

IHTMLStyle::put_textDecorationNone

HRESULT put_textDecorationNone(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "none", or removes the "none" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "none"; FALSE removes the "none" value from the attribute. See text-decoration for details.

See also get_textDecorationNone


TextDecorationOverline Property

*
  * Previous Topic: IHTMLStyle::get_textDecorationNone
  * Next Topic: IHTMLStyle::get_textDecorationUnderline

IHTMLStyle::get_textDecorationOverline

HRESULT get_textDecorationOverline(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "overline".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "overline", or FALSE if not. See text-decoration for details.

See also put_textDecorationOverline

Up Top of Page

IHTMLStyle::put_textDecorationOverline

HRESULT put_textDecorationOverline(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "overline", or removes the "overline" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "overline"; FALSE removes the "overline" value from the attribute. See text-decoration for details.

See also get_textDecorationOverline


TextDecorationUnderline Property

*
  * Previous Topic: IHTMLStyle::get_textDecorationOverline
  * Next Topic: IHTMLStyle::get_textIndent

IHTMLStyle::get_textDecorationUnderline

HRESULT get_textDecorationUnderline(
    VARIANT_BOOL *p
);

Retrieves whether the element's CSS text-decoration attribute has a value of "underline".

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "underline", or FALSE if not. See text-decoration for details.

See also put_textDecorationUnderline

Up Top of Page

IHTMLStyle::put_textDecorationUnderline

HRESULT put_textDecorationUnderline(
    VARIANT_BOOL v
);

Sets the value of the element's CSS text-decoration attribute to "underline", or removes the "underline" value from the attribute.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value. TRUE sets the attribute to "underline"; FALSE removes the "underline" value from the attribute. See text-decoration for details.

See also get_textDecorationUnderline


TextIndent Property

*
  * Previous Topic: IHTMLStyle::get_textDecorationUnderline
  * Next Topic: IHTMLStyle::get_textTransform

IHTMLStyle::get_textIndent

HRESULT get_textIndent(
    VARIANT *p
);

Retrieves the value of the CSS text-indent attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. See text-indent for details. This parameter receives NULL if the attribute is not set.

See also put_textIndent

Up Top of Page

IHTMLStyle::put_textIndent

HRESULT put_textIndent(
    VARIANT v
);

Sets the value of the CSS text-indent attribute for the element. The attribute determines the amount of indention before the element's first line of formatted text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of indention, or NULL to remove the attribute. The amount can be positive or negative. See text-indent for details.

See also get_textIndent


TextTransform Property

*
  * Previous Topic: IHTMLStyle::get_textIndent
  * Next Topic: IHTMLStyle::get_top

IHTMLStyle::get_textTransform

HRESULT get_textTransform(
    BSTR *p
);

Retrieves the value of the CSS text-transform attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
capitalize | First letter in the text is capitalized.
lowercase | All letters in the text are converted to lowercase.
uppercase | All letters in the text are converted to uppercase.
See text-transform for details. This parameter receives NULL if the attribute is not set.

See also put_textTransform

Up Top of Page

IHTMLStyle::put_textTransform

HRESULT put_textTransform(
    BSTR v
);

Sets the value of the CSS text-transform attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text transformation, or NULL to remove the attribute. Can be one of these strings:
capitalize | First letter in the text is capitalized.
lowercase | All letters in the text are converted to lowercase.
uppercase | All letters in the text are converted to uppercase.
See text-transform for details.

See also get_textTransform


Top Property

*
  * Previous Topic: IHTMLStyle::get_textTransform
  * Next Topic: IHTMLStyle::get_verticalAlign

IHTMLStyle::get_top

HRESULT get_top(
    VARIANT *p
);

Retrieves the value of the CSS top attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute. The value is a string consisting of a floating-point number and a units designator. See top for details. The variable receives NULL if the attribute is not set.

See also put_top

Up Top of Page

IHTMLStyle::put_top

HRESULT put_top(
    VARIANT v
);

Sets the value of the CSS top attribute for the element. The attribute determines the top position of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value consisting of a floating-point number and a units designator. See top for details. Set this parameter to NULL to remove the attribute.

See also get_top


VerticalAlign Property

*
  * Previous Topic: IHTMLStyle::get_top
  * Next Topic: IHTMLStyle::get_visibility

IHTMLStyle::get_verticalAlign

HRESULT get_verticalAlign(
    VARIANT *p
);

Retrieves the value of the CSS vertical-align attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set. Can be one of these strings:
baseline
middle
sub
super
text-top
text-bottom
top
bottom
See vertical-align for details.

See also put_verticalAlign

Up Top of Page

IHTMLStyle::put_verticalAlign

HRESULT put_verticalAlign(
    VARIANT v
);

Sets the value of the CSS vertical-align attribute for the element. The attribute determines the vertical positioning of the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the vertical alignment. Can be a percentage (either positive or negative) of the line height of the element, or one of the values below. These values are relative to the parent element:
baseline
middle
sub
super
text-top
text-bottom
These values are relative to the formatted line of which the element is a part:
top
bottom
See vertical-align for details. Set this parameter to NULL to remove the attribute.

See also get_verticalAlign


Visibility Property

*
  * Previous Topic: IHTMLStyle::get_verticalAlign
  * Next Topic: IHTMLStyle::get_whiteSpace

IHTMLStyle::get_visibility

HRESULT get_visibility(
    BSTR *p
);

Retrieves the value of the visibility attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
visible
hidden
inherit
See visibility for details. The variable receives NULL if the attribute is not set.

See also put_visibility

Up Top of Page

IHTMLStyle::put_visibility

HRESULT put_visibility(
    BSTR v
);

Sets the value of the CSS visibility attribute for the element. The attribute determines whether the content of the element is visible.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying whether the element is visible. Can be one of these strings:
visible
hidden
inherit
See visibility for details. Set this parameter to NULL to remove the attribute.

Space is reserved for the element's content regardless of the value of the visibility attribute.

See also get_visibility


WhiteSpace Property

*
  * Previous Topic: IHTMLStyle::get_visibility
  * Next Topic: IHTMLStyle::get_width

IHTMLStyle::get_whiteSpace

HRESULT get_whiteSpace(
    BSTR *p
);

Retrieves the value of the CSS white-space attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, which can be one of these strings:
normal | Consecutive white-space characters are replaced with a single space.
nowrap | Linebreak characters are preserved, but consecutive spaces and tab characters are replaced with a single space.
pre | All white-space characters (including line breaks) are preserved.
The variable receives NULL if the attribute is not set.

See also put_whiteSpace

Up Top of Page

IHTMLStyle::put_whiteSpace

HRESULT put_whiteSpace(
    BSTR v
);

Sets the CSS white-space attribute for the element. The attribute determines whether and how white-space characters in the element are displayed.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the value of the attribute. Can be one of these strings:
normal | Consecutive white-space characters are replaced with a single space.
nowrap | Linebreak characters are preserved, but consecutive spaces and tab characters are replaced with a single space.
pre | All white-space characters (including line breaks) are preserved.
Set this parameter to NULL to remove the attribute.

See also get_whiteSpace


Width Property

*
  * Previous Topic: IHTMLStyle::get_whiteSpace
  * Next Topic: IHTMLStyle::get_wordSpacing

IHTMLStyle::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the value of the CSS width attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the width. See width for details. This parameter receives NULL if the attribute is not set.

See also put_width

Up Top of Page

IHTMLStyle::put_width

HRESULT put_width(
   VARIANT v
);

Sets the value of the CSS width attribute for the element. The attribute determines the element's width.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the width, which consists of a floating-point number and a units designator. See width for details. Set this parameter to NULL to remove the attribute.

See also get_width


WordSpacing Property

*
  * Previous Topic: IHTMLStyle::get_width
  * Next Topic: IHTMLStyle::get_zIndex

IHTMLStyle::get_wordSpacing

HRESULT get_wordSpacing(
    VARIANT *p
);

Retrieves the value of the CSS word-spacing attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the value of the attribute, or NULL if the attribute is not set.

See also put_wordSpacing

Up Top of Page

IHTMLStyle::put_wordSpacing

HRESULT put_wordSpacing(
    VARIANT v
);

Sets the value of the CSS word-spacing attribute for the element. The attribute determines the amount of space to add to the default space between words in the element's text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the amount of space to add. A negative value is valid. Set this parameter to NULL to remove the attribute.

See also get_wordSpacing


ZIndex Property

*
  * Previous Topic: IHTMLStyle::get_wordSpacing
  * Next Topic: IHTMLStyle::getAttribute

IHTMLStyle::get_zIndex

HRESULT get_zIndex(
    VARIANT *p
);

Retrieves the value of the CSS z-index attribute for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the z-index. The variable receives a positive value if the element is positioned above the text, and a negative value if it is below. See z-index for details. The variable receives NULL if the attribute is not set.

See also put_zIndex

Up Top of Page

IHTMLStyle::put_zIndex

HRESULT put_zIndex(
    VARIANT v
);

Sets the value of the CSS z-index attribute for the element. The attribute determines whether the element is positioned above or below the text.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the z-index. A positive value positions the element above the text, and a negative value positions it below. See z-index for details. Set this parameter to NULL to remove the attribute.

See also get_zIndex


IHTMLStyle::getAttribute

HRESULT getAttribute(
    BSTR strAttributeName,
    LONG fFlags,
    VARIANT *AttributeValue
);

Retrieves the value of the given attribute.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to retrieve.
fFlags
Long integer that receives the flags.
AttributeValue
Address of a variable that receives a string, number, or Boolean value as defined by the attribute. If the attribute is not present, this method returns NULL.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fFlags is FALSE, this method retrieves values only for the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

See also setAttribute


IHTMLStyle::removeAttribute

HRESULT removeAttribute(
    BSTR strAttributeName,
    VARIANT_BOOL fCaseSensitive,
    VARIANT_BOOL *pfSuccess
);

Removes the given attribute from the element.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to remove.
fCaseSensitive
Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in strAttributeName must match exactly those in the attribute name.
pfSuccess
Address of a variable that receives TRUE if the function succeeds, or FALSE otherwise.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fCaseSensitive is false, this method removes only the last attribute (the last to be created with this name). All other attributes of the same name are ignored.

See also getAttribute, setAttribute


IHTMLStyle::setAttribute

HRESULT setAttribute(
    BSTR strAttributeName,
    VARIANT AttributeValue,
    VARIANT_BOOL fCaseSensitive
);

Sets the value of the given attribute. If the attribute is not already present, the method adds the attribute to the element and sets the value.

  • Returns S_OK if successful, or an error value otherwise.
strAttributeName
String specifying the name of the attribute to set.
AttributeValue
String, number, or Boolean value to assign to the attribute.
fCaseSensitive
Boolean value specifying whether to use a case-sensitive search to locate the attribute. If TRUE, the uppercase and lowercase letters in strAttributeName must match exactly those in the attribute name.

Be careful when spelling attribute names. If fCaseSensitive is TRUE and strAttributeName does not have the same uppercase and lowercase letters as the attribute, this method creates a new attribute.

If two or more attributes have the same name (differing only in uppercase and lowercase letters) and fCaseSensitive is FALSE, this method assigns values only to the first attribute (the first to be created with this name). All other attributes of the same name are ignored.

See also getAttribute


IHTMLStyle::toString

HRESULT toString(
   BSTR *String
);

Retrieves a string representation of the style object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a variable that receives the string representation.


IHTMLStyleElement

This interface specifies the style sheet for the page.

This element can be used only within either the HEAD or BODY element.

IHTMLStyleElement Methods
put_type get_type get_readyState
put_onreadystatechange get_onreadystatechange put_onload
get_onload put_onerror get_onerror
get_styleSheet put_disabled get_disabled
put_media get_media

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Disabled Property

*
  * Previous Topic: IHTMLStyleElement
  * Next Topic: IHTMLStyleElement::get_media

IHTMLStyleElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Retrieves the Boolean value that determines whether this style element is disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the style element is enabled, or FALSE otherwise.

See also put_disabled

Up Top of Page

IHTMLStyleElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Sets the Boolean value that determines whether this style element is disabled.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the status of the StyleElement. This parameter is TRUE if the style element is disabled, or FALSE otherwise. See STYLE for details.

See also get_disabled


Media Property

*
  * Previous Topic: IHTMLStyleElement::get_disabled
  * Next Topic: IHTMLStyleElement::get_onerror

IHTMLStyleElement::get_media

HRESULT get_media(
    BSTR *p
);

Retrieves the string that indicates which media this style element applies to.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string that receives the media type.

See also put_media

Up Top of Page

IHTMLStyleElement::put_media

HRESULT put_media(
    BSTR v
);

Sets the inline script that indicates which media this style element applies to.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the type of media for this style element.

See also get_media, IHTMLLinkElement


Onerror Property

*
  * Previous Topic: IHTMLStyleElement::get_media
  * Next Topic: IHTMLStyleElement::get_onload

IHTMLStyleElement::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event on the style element. This error event occurs when the loading of a document or image causes an error.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the error script. See onerror for more information.

See also put_onerror

Up Top of Page

IHTMLStyleElement::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event on the style element. This error event occurs when the loading of a document or image causes an error.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set. See onerror for more information.

See also get_onerror


Onload Property

*
  * Previous Topic: IHTMLStyleElement::get_onerror
  * Next Topic: IHTMLStyleElement::get_onreadystatechange

IHTMLStyleElement::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the script associated with the onload event on the STYLE element. Occurs immediately after the browser loads the given object.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onload

Up Top of Page

IHTMLStyleElement::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the script associated with the onload event on the STYLE element. Occurs immediately after the browser loads the given object.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onload


Onreadystatechange Property

*
  * Previous Topic: IHTMLStyleElement::get_onload
  * Next Topic: IHTMLStyleElement::get_readyState

IHTMLStyleElement::get_onreadystatechange

HRESULT get_onreadystatechange(
    VARIANT *p
);

Retrieves the script associated with the onreadystatechange event on the STYLE element.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onreadystatechange

Up Top of Page

IHTMLStyleElement::put_onreadystatechange

HRESULT put_onreadystatechange(
    VARIANT v
);

Sets the script associated with the onreadystatechange event on the STYLE element.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onreadystatechange


IHTMLStyleElement::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Retrieves the current state of an object being downloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the current state. Can be one of these values:
complete | The object is completely loaded.
interactive | The object can be interacted with even though it is not fully loaded.
loading | The object is currently being loaded.
uninitialized | The object is not created. Usually when the object is being downloaded.

Each object can independently determine which of the states it exposes.


IHTMLStyleElement::get_styleSheet

HRESULT get_styleSheet(
    IHTMLStyleSheet **p
);

Retrieves an interface pointer that provides access to the style sheet object's properties and methods.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IHTMLStyleSheet


Type Property

*
  * Previous Topic: IHTMLStyleElement::get_styleSheet
  * Next Topic: IHTMLStyleElement::put_disabled

IHTMLStyleElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the CSS language in which the style sheet is written.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the CSS language. It can be any string, including an empty string. Valid style sheets are typically set to "text/css".

See also put_type

Up Top of Page

IHTMLStyleElement::put_type

HRESULT put_type(
    BSTR v
);

Sets the CSS language in which the style sheet is written.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the CSS language. It can be any string, including an empty string. Valid style sheets are typically set to "text/css".

See also get_type


IHTMLStyleSheet

This interface provides access to an object representing a single style sheet in the document.

The styleSheet object represents an instance of the STYLE or LINK tag with a relationship (rel attribute) of the STYLESHEET object.

You use the object to retrieve information about the style sheet, such as the URL of the source file for the style sheet and the element in the document that owns (defines) the style sheet. You also use the object to modify the style sheet.

You retrieve a pointer to the style sheet object by using the IHTMLDocument2::get_styleSheets method. You can retrieve a collection of all styleSheets in the document by using the IHTMLStyleSheet::get_imports method. Each item in the collection is a style sheet. A style sheet object is available for a style sheet only if it is included in a document with a STYLE or LINK element, or with an @import statement in the STYLE element.

IHTMLStyleSheet Methods
put_title get_title get_parentStyleSheet
get_owningElement put_disabled get_disabled
get_readOnly get_imports put_href
get_href get_type get_id
addImport addRule removeImport
removeRule put_media get_media
get_cssText get_rules

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLStyleSheet::addImport

HRESULT addImport(
    BSTR bstrURL,
    long lIndex,
long *plIndex
);

Adds a style sheet to the imports collection for the given style sheet.

  • Returns S_OK if successful, or an error value otherwise.
bstrURL
String specifying the location of the source file for the style sheet.
lIndex
Integer specifying the requested position of the style sheet in the collection. The position is zero-based.
plIndex
Address of a variable that receives an integer index value specifying the position of the imported style sheet in the imports collection.


IHTMLStyleSheet::addRule

HRESULT addRule(
    BSTR bstrSelector,
    BSTR bstrStyle,
    long lIndex,
    long *plNewIndex
);

Creates a new style rule using the given selector and style assignment.

  • Returns S_OK if successful, or an error value otherwise.
bstrSelector
String specifying the selector for the new rule.
bstrStyle
String specifying the style assignments for this style rule.
lIndex
Zero-based position in the style sheet where the style rule is to be placed.
plNewIndex
Address of a variable that receives the new zero-based index of the style rule.


IHTMLStyleSheet::get_cssText

HRESULT get_cssText(
    BSTR *p
);

Retrieves a string of the rules set in the style sheet defined in the CSS format as it would look, if the style sheet were saved.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the rules set.


Disabled Property

*
  * Previous Topic: IHTMLStyleSheet::get_cssText
  * Next Topic: IHTMLStyleSheet::get_href

IHTMLStyleSheet::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the style sheet is enabled or disabled. "False" for style sheets that do not specify a title and that are not currently selected.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the style sheet is enabled, or FALSE otherwise. This parameter receives FALSE if the style sheet does not specify a title or is not currently selected.

The value of this property can change per media-dependent style sheets. The application of individual style sheets can be turned on and off dynamically. Note that the value of this property is also controlled by whether titled style sheets are applied.

See also put_disabled

Up Top of Page

IHTMLStyleSheet::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the style sheet.

  • Returns S_OK if successful, or an error value otherwise.
v
TRUE to enable the style sheet, or FALSE to disable it.

See also get_disabled


Href Property

*
  * Previous Topic: IHTMLStyleSheet::get_disabled
  * Next Topic: IHTMLStyleSheet::get_id

IHTMLStyleSheet::get_href

HRESULT get_href(
    BSTR *p
);

Retrieves the URL of a linked style sheet.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string that receives the URL. If the style sheet is a STYLE element, this parameter receives NULL.

See also put_href

Up Top of Page

IHTMLStyleSheet::put_href

HRESULT put_href(
    BSTR v
);

Sets the URL of a linked styleSheet; that is, it is part of a LINK element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

See also get_href


IHTMLStyleSheet::get_id

HRESULT get_id(
    BSTR *p
);

Retrieves the identifier of the style sheet.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the identifier.


IHTMLStyleSheet::get_imports

HRESULT get_imports(
    IHTMLStyleSheetsCollection **p
);

Retrieves a zero-based collection of all the imported style sheets defined for the given styleSheet object. An imported style sheet is one that is brought into the document using the CSS @import attribute.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives a pointer to the collection. See IHTMLStyleSheetsCollection for details.


Media Property

*
  * Previous Topic: IHTMLStyleSheet::get_imports
  * Next Topic: IHTMLStyleSheet::get_owningElement

IHTMLStyleSheet::get_media

HRESULT get_media(
    BSTR *p
);

Receives the string that indicates which media this style applies to.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a sting variable that receives the media type.

See also put_media

Up Top of Page

IHTMLStyleSheet::put_media

HRESULT put_media(
    BSTR v
);

Sets the string that indicates which media this style element applies to. See IHTMLLinkElement::put_media for values.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the media type for the styleSheet element.

See also get_media


IHTMLStyleSheet::get_owningElement

HRESULT get_owningElement(
    IHTMLElement **p
);

Retrieves the element that is next in the HTML hierarchy. This usually contains the STYLE or LINK that defined the style sheet.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the element.

See also IHTMLElement


IHTMLStyleSheet::get_parentStyleSheet

HRESULT get_parentStyleSheet(
    IHTMLStyleSheet **p
);

Retrieves an interface pointer to the styleSheet object that imported the current style sheet. This property is intended for imported styleSheets.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the parent style sheet. This parameter receives NULL if the style sheet is part of a LINK or STYLE element.


IHTMLStyleSheet::get_readOnly

HRESULT get_readOnly(
    VARIANT_BOOL *p
);

Indicates whether the rule object can be edited.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the rule object can be edited, or FALSE if not.


IHTMLStyleSheet::get_rules

HRESULT get_rules(
    IHTMLStyleSheetRulesCollection **p
);

Retrieves an IHTMLStyleSheetRulesCollection pointer to the collection of the rules in this styleSheet. If there are no rules, the length of the collection returned is zero.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to IHTMLStyleSheetRulesCollection.


Title Property

*
  * Previous Topic: IHTMLStyleSheet::get_rules
  * Next Topic: IHTMLStyleSheet::get_type

IHTMLStyleSheet::get_title

HRESULT get_title(
    BSTR *p
);

Retrieves the title of the styleSheet.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the title. This parameter receives FALSE if the style sheet has no title or the title is not currently selected.

The application of individual style sheets can be turned on and off dynamically. Note that the value of this property is also controlled by whether titled style sheets are applied.

See also put_title

Up Top of Page

IHTMLStyleSheet::put_title

HRESULT put_title(
    BSTR v
);

Sets the title of the styleSheet element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the title.

See also get_title


IHTMLStyleSheet::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the CSS language the style sheet is written in.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. It can be any string, including an empty string. Currently, style sheets having any type other than "text/css" are not supported.


IHTMLStyleSheet::removeImport

HRESULT removeImport(
    long lIndex
);

Removes the imported style sheet by ordinal position in the imports collection based on the value of the index passed in.

  • Returns S_OK if successful, or an error value otherwise.
lIndex
Long integer value indicating which imported style sheet to remove.


IHTMLStyleSheet::removeRule

HRESULT removeRule(
    long lIndex
);

Removes the rule by ordinal position based on the value of the index passed in. The rule is deleted from the style sheet, and the document is updated to reflect any changes.

  • Returns S_OK if successful, or an error value otherwise.
lIndex
Long integer value indicating which style rule to remove.


IHTMLStyleSheetRule

This interface provides access to the methods that are returned when you access styleSheet object.

This object is returned from the rules collection of a styleSheet. It represents a particular rule in a style sheet.

IHTMLStyleSheetRule Methods


IHTMLStyleSheetRule::get_readOnly

HRESULT get_readOnly(
    VARIANT_BOOL *p
);

Retrieves a Boolean value that indicates whether this rule is readOnly.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the attribute has a value of "readOnly", or FALSE if not. See readOnly for details.


SelectorText Property

*
  * Previous Topic: IHTMLStyleSheetRule::get_readOnly
  * Next Topic: IHTMLStyleSheetRule::get_style

IHTMLStyleSheetRule::get_selectorText

HRESULT get_selectorText(
    BSTR *p
);

Retrieves the selection string for the style sheet rule.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the selection text.

See also put_selectorText

Up Top of Page

IHTMLStyleSheetRule::put_selectorText

HRESULT put_selectorText(
    BSTR v
);

Currently not implemented.

See also get_selectorText


IHTMLStyleSheetRule::get_style

HRESULT get_style(
    IHTMLRuleStyle **p
);

Retrieves an IHTMLRuleStyle pointer to the styleSheet object that contains this rule.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an IHTMLRuleStyle interface pointer to the styleSheet object.


IHTMLStyleSheetRulesCollection

This interface provides the abilities to obtain the number of styleSheets in the collection, and access a single styleSheet element from the collection.

A collection of the rules in a styleSheet element. This is returned from the style sheets rules property.

IHTMLStyleSheetRulesCollection Methods


IHTMLStyleSheetRulesCollection::get_length

HRESULT get_length(
    long *p
);

Returns the number of elements in a collection. This method provides the same capabilities as the length property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a value that receives the number of elements in the collection. This is an integer value or a string specifying the index value of the style sheet to retrieve. Integer indexes are zero-based, meaning the first style sheet in the collection has index 0.


IHTMLStyleSheetRulesCollection::item

HRESULT item(
    long index,
    IHTMLStyleSheetRule **ppHTMLStyleSheetRule
);

Retrieves an element or a collection from the given collection. The index parameter determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
index
Value that contains the number specifying the position of an element to retrieve.
ppHTMLStyleSheetRule
Address of a pointer to the IHTMLStyleSheetRule interface of the styleSheets element.


IHTMLStyleSheetsCollection

This interface provides the abilities to obtain the number of styleSheets in the collection, and to iterate through the styleSheets collection of the STYLE element.

A zero-based collection of style sheets is exposed from the document object. Each style sheet object represents an individual style sheet that is defined for the document. This object represents instances of the LINK and STYLE elements with a relationship (rel attribute) of STYLESHEET.

Imported style sheets are contained within a STYLE element and are accessible through the IHTMLStyleSheet::get_imports method.

IHTMLStyleSheetsCollection Methods


IHTMLStyleSheetsCollection::get_length

HRESULT get_length(
    long *p
);

Retrieves the number of elements in a collection.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer variable that receives the length.

This property is read-write on the areas and the options collection for image maps and select boxes, respectively. This allows a developer to shrink the collection.


IHTMLStyleSheetsCollection::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Retrieves an enumerator interface which can be used to iterate through the styleSheets collection of the STYLE element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to an IUnknown interface.


IHTMLStyleSheetsCollection::item

HRESULT item(
    VARIANT *pvarIndex,
    VARIANT *pvarResult
);

Retrieves an styleSheet element or a collection of styleSheets. The index determines which action to take.

  • Returns S_OK if successful, or an error value otherwise.
pvarIndex
Address of a VARIANT structure specifying the element or collection to retrieve. If this parameter is a number, the method returns the element in the collection at the given position, where the first element has value 0, the second has 1, and so on. If this parameter is a string, the method returns a collection of elements, where the value of the name or id property for each element is equal to the string.
pvarResult
Address of a VARIANT structure that receives an element object or a collection of element objects if successful, or NULL otherwise.


IHTMLTable

This interface is used to specify that the contained content is organized into a table with rows and columns.

Valid tags within a table include:

  • TR
  • CAPTION
  • THEAD
  • TBODY
  • TFOOT
  • COLGROUP
  • COL

This element is a block element.

IHTMLTable Methods
put_cols get_cols put_border
get_border put_frame get_frame
put_rules get_rules put_cellSpacing
get_cellSpacing put_cellPadding get_cellPadding
put_background get_background put_bgColor
get_bgColor put_borderColor get_borderColor
put_borderColorLight get_borderColorLight put_borderColorDark
get_borderColorDark put_align get_align
refresh get_rows put_width
get_width put_height get_height
put_dataPageSize get_dataPageSize nextPage
previousPage get_tHead get_tFoot
get_tBodies get_caption createTHead
deleteTHead createTFoot deleteTFoot
createCaption deleteCaption insertRow
deleteRow get_readyState put_onreadystatechange
get_onreadystatechange


IHTMLTable::createCaption

HRESULT createCaption(
    IHTMLTableCaption **caption
);

Creates a table caption. If no caption exists, this creates an empty table caption and adds it to the table, and returns a pointer to it. If captions already exist, this method returns a pointer to the first one in the list.

  • Returns S_OK if successful, or an error value otherwise.
caption
Address of a pointer to a variable of IHTMLTableCaption type.

See also deleteCaption


IHTMLTable::createTFoot

HRESULT createTFoot(
    IDispatch **foot
);

Creates a TFoot for the table. If a table foot already exists, this returns a pointer to it. Otherwise, an empty foot is created and added to a table, and a pointer to the empty foot is returned.

  • Returns S_OK if successful, or an error value otherwise.
foot
Address of a pointer to an IDispatch interface.

See also deleteTFoot


IHTMLTable::createTHead

HRESULT createTHead(
    IDispatch **head
);

Creates a THead for the table. When a table head already exists, this will return a pointer to it. If a table head doesn't exist, an empty table head is created and the pointer to that is returned.

  • Returns S_OK if successful, or an error value otherwise.
head
Address of a pointer to an IDispatch interface.

See also deleteTHead


IHTMLTable::deleteCaption

HRESULT deleteCaption(
    void
);

Deletes the caption from a table. If there are multiple captions in the table, this method deletes the first caption and all its contents from the table.

  • Returns S_OK if successful, or an error value otherwise.

See also createCaption


IHTMLTable::deleteRow

HRESULT deleteRow(
    long index
);

Removes the row indicated by the value of the zero-based index parameter from this table section.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value specifying the index position in the table.

See also insertRow


IHTMLTable::deleteTFoot

HRESULT deleteTFoot(
    void
);

Deletes a TFoot from the table. If there is a foot, this removes it and all its contents from the table. If multiple TFoots are defined, the next one in source order is promoted as the TFoot of the table.

  • Returns S_OK if successful, or an error value otherwise.

See also createTFoot


IHTMLTable::deleteTHead

HRESULT deleteTHead(
    void
);

Deletes a THead from the table. If there is a head, this method removes it and all its contents from the table. If other THeads had been defined, the next one in source order is now promoted to the THead of the table.

  • Returns S_OK if successful, or an error value otherwise.

See also createTHead


Align Property

*
  * Previous Topic: IHTMLTable::deleteTHead
  * Next Topic: IHTMLTable::get_background

IHTMLTable::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves how the table should be aligned.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives one of these values:
center | Aligns to the center.
left | Aligns to the left edge. This is the default value.
right | Aligns to the right edge.

See also put_align

Up Top of Page

IHTMLTable::put_align

HRESULT put_align(
    BSTR v
);

Sets how the table should be aligned.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Aligns to the center.
left | Aligns to the left edge. This is the default value.
right | Aligns to the right edge.

See also get_align


Background Property

*
  * Previous Topic: IHTMLTable::get_align
  * Next Topic: IHTMLTable::get_bgColor

IHTMLTable::get_background

HRESULT get_background(
    BSTR *p
);

Retrieves the current background picture for the table, if any. The picture is tiled behind the text and graphics in the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the URL of the background picture.

See also put_background

Up Top of Page

IHTMLTable::put_background

HRESULT put_background(
    BSTR v
);

Sets a background picture for the table. The picture is tiled behind the text and graphics in the table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL of the background picture.

See also get_background


BgColor Property

*
  * Previous Topic: IHTMLTable::get_background
  * Next Topic: IHTMLTable::get_border

IHTMLTable::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the current background color of the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLTable::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color of the table.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


Border Property

*
  * Previous Topic: IHTMLTable::get_bgColor
  * Next Topic: IHTMLTable::get_borderColor

IHTMLTable::get_border

HRESULT get_border(
    VARIANT *p
);

Retrieves the border color and must be used with the border property, except for frames. The color can be one of the color names or values given in the Color Table reference documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives one of the color names or values given in the Color Table reference documentation.

See also put_border

Up Top of Page

IHTMLTable::put_border

HRESULT put_border(
    VARIANT v
);

Sets the border color and must be used with the border property, except for frames.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or numeric value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_border


BorderColor Property

*
  * Previous Topic: IHTMLTable::get_border
  * Next Topic: IHTMLTable::get_borderColorDark

IHTMLTable::get_borderColor

HRESULT get_borderColor(
    VARIANT *p
);

Retrieves the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColor

Up Top of Page

IHTMLTable::put_borderColor

HRESULT put_borderColor(
    VARIANT v
);

Sets the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColor


BorderColorDark Property

*
  * Previous Topic: IHTMLTable::get_borderColor
  * Next Topic: IHTMLTable::get_borderColorLight

IHTMLTable::get_borderColorDark

HRESULT get_borderColorDark(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorDark

Up Top of Page

IHTMLTable::put_borderColorDark

HRESULT put_borderColorDark(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorDark


BorderColorLight Property

*
  * Previous Topic: IHTMLTable::get_borderColorDark
  * Next Topic: IHTMLTable::get_caption

IHTMLTable::get_borderColorLight

HRESULT get_borderColorLight(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorLight

Up Top of Page

IHTMLTable::put_borderColorLight

HRESULT put_borderColorLight(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorLight


IHTMLTable::get_caption

HRESULT get_caption(
    IHTMLTableCaption **p
);

Returns an IHTMLTableCaption pointer to the first caption in the table. If the table does not contain a caption, NULL is returned.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLTableCaption interface of the element.


CellPadding Property

*
  * Previous Topic: IHTMLTable::get_caption
  * Next Topic: IHTMLTable::get_cellSpacing

IHTMLTable::get_cellPadding

HRESULT get_cellPadding(
    VARIANT *p
);

Retrieves the amount of space between the border of the cell and the contents of the cell.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the cell padding.

See also put_cellPadding

Up Top of Page

IHTMLTable::put_cellPadding

HRESULT put_cellPadding(
    VARIANT v
);

Sets the amount of space between the border of the cell and the contents of the cell.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains either a string or value specifying the cell padding.

See also get_cellPadding


CellSpacing Property

*
  * Previous Topic: IHTMLTable::get_cellPadding
  * Next Topic: IHTMLTable::get_cols

IHTMLTable::get_cellSpacing

HRESULT get_cellSpacing(
    VARIANT *p
);

Retrieves the amount of space between cells in a table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the cell spacing.

See also put_cellSpacing

Up Top of Page

IHTMLTable::put_cellSpacing

HRESULT put_cellSpacing(
    VARIANT v
);

Sets the amount of space between cells in a table.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing either a string or value specifying the cell spacing.

See also get_cellSpacing


Cols Property

*
  * Previous Topic: IHTMLTable::get_cellSpacing
  * Next Topic: IHTMLTable::get_dataPageSize

IHTMLTable::get_cols

HRESULT get_cols(
    long *p
);

Retrieves the number of columns in the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the number of columns.

See also put_cols

Up Top of Page

IHTMLTable::put_cols

HRESULT put_cols(
    long v
);

Sets the number of columns in the table.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the number of columns.

Providing this number can speed up the processing of the table.

See also get_cols


DataPageSize Property

*
  * Previous Topic: IHTMLTable::get_cols
  * Next Topic: IHTMLTable::get_frame

IHTMLTable::get_dataPageSize

HRESULT get_dataPageSize(
    long *p
);

Retrieves the number of records displayed in a databound repeated table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the number of records.

Use the nextPage and previousPage methods to display the subsequent and previous number of records in the table.

See also put_dataPageSize

Up Top of Page

IHTMLTable::put_dataPageSize

HRESULT put_dataPageSize(
    long v
);

Sets the number of records displayed in a databound repeated table.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the number of records to display.

Use the nextPage and previousPage methods to display the subsequent and previous number of records in the table.

See also get_dataPageSize


Frame Property

*
  * Previous Topic: IHTMLTable::get_dataPageSize
  * Next Topic: IHTMLTable::get_height

IHTMLTable::get_frame

HRESULT get_frame(
    BSTR *p
);

Retrieves a description of the border frame around the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
above | Displays a border on the top side of the border frame.
below | Displays a border on the bottom side of the table frame.
border | Displays a border on all sides of the table frame.
box | Displays a border on all sides of the table frame.
insides | Displays a border on the top and bottom sides of the table frame.
lhs | Displays a border on the left side of the table frame.
rhs | Displays a border on the right side of the table frame.
void | Removes all outside table borders.
vsides | Displays a border on the left and right sides of the table frame.

The default value for this property is "void".

See also put_frame

Up Top of Page

IHTMLTable::put_frame

HRESULT put_frame(
    BSTR v
);

Sets the appearance of the border frame around the table.

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the appearance of the border frame. Can be one of these strings:
above | Displays a border on the top side of the border frame.
below | Displays a border on the bottom side of the table frame.
border | Displays a border on all sides of the table frame.
box | Displays a border on all sides of the table frame.
insides | Displays a border on the top and bottom sides of the table frame.
lhs | Displays a border on the left side of the table frame.
rhs | Displays a border on the right side of the table frame.
void | Removes all outside table borders.
vsides | Displays a border on the left and right sides of the table frame.

The default value for this property is "void".

See also get_frame


Height Property

*
  * Previous Topic: IHTMLTable::get_frame
  * Next Topic: IHTMLTable::get_onreadystatechange

IHTMLTable::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the height of the table, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height, in pixels, represented by that percentage.

See also put_height

Up Top of Page

IHTMLTable::put_height

HRESULT put_height(
    VARIANT v
);

Sets the height of the table, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


Onreadystatechange Property

*
  * Previous Topic: IHTMLTable::get_height
  * Next Topic: IHTMLTable::get_readyState

IHTMLTable::get_onreadystatechange

HRESULT get_onreadystatechange(
    VARIANT *p
);

Retrieves the inline script associated with the onreadystatechange event for the table element. This script is executed when the onreadystatechange event is fired.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onreadystatechange

Up Top of Page

IHTMLTable::put_onreadystatechange

HRESULT put_onreadystatechange(
    VARIANT v
);

Sets the inline script associated with the onreadystatechange event for the table element. This script is executed when the onreadystatechange event is fired.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onreadystatechange


IHTMLTable::get_readyState

HRESULT get_readyState(
    BSTR *p
);

Returns the readyState enumeration string for the table's current ready state.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the enumeration.


IHTMLTable::get_rows

HRESULT get_rows(
    IHTMLElementCollection **p
);

Retrieves a collection of all rows in the table. This is a collection of all the TR elements defined in the THEAD, TBODY, and TFOOT elements of the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the table.


Rules Property

*
  * Previous Topic: IHTMLTable::get_rows
  * Next Topic: IHTMLTable::get_tBodies

IHTMLTable::get_rules

HRESULT get_rules(
    BSTR *p
);

Retrieves which dividing lines are displayed (inner borders).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
all | Displays a border on all rows and columns.
cols | Displays borders between all table columns.
groups | Displays horizontal borders between all table groups. Groups are specified by the THEAD, TBODY, TFOOT, and COLGROUP elements.
none | Removes all interior table borders.
rows | Displays horizontal borders between all table rows.

See also put_rules

Up Top of Page

IHTMLTable::put_rules

HRESULT put_rules(
    BSTR v
);

Specifies which dividing lines are displayed (inner borders).

  • Returns S_OK if successful, or an error value otherwise.
v
String value specifying the dividing rules. Can be one of these values:
all | Displays a border on all rows and columns.
cols | Displays borders between all table columns.
groups | Displays horizontal borders between all table groups. Groups are specified by the THEAD, TBODY, TFOOT, and COLGROUP elements.
none | Removes all interior table borders.
rows | Displays horizontal borders between all table rows.

See also get_rules


IHTMLTable::get_tBodies

HRESULT get_tBodies(
    IHTMLElementCollection **p
);

Returns an IHTMLTableSection pointer to all the table bodies in this table. The length of this collection is the count of bodies returned.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the table.


IHTMLTable::get_tFoot

HRESULT get_tFoot(
    IHTMLTableSection **p
);

Returns an IHTMLTableSection pointer to the foot section of a table. It returns NULL if there isn't one. If multiple table foots are listed in an HTML document, only the first one is treated as the foot of the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLTableSection interface of the table.

See also get_tHead


IHTMLTable::get_tHead

HRESULT get_tHead(
    IHTMLTableSection **p
);

Returns an IHTMLTableSection pointer to the head section of a table. It returns NULL if there isn't one. If multiple table heads are listed in an HTML document, only the first one is treated as the head of the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLTableSection interface of the table.

See also get_tFoot


Width Property

*
  * Previous Topic: IHTMLTable::get_tHead
  * Next Topic: IHTMLTable::insertRow

IHTMLTable::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the width of the table, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the width.

This read-only property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLTable::put_width

HRESULT put_width(
    VARIANT v
);

Sets the width of the table, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


IHTMLTable::insertRow

HRESULT insertRow(
    long index,
    IDispatch **row
);

Inserts an empty row into the table section. The row is added at the position indicated by the zero-based index provided. For example, passing in 1 adds the row between 0 and 1, thus becoming the row with index 1. Passing in -1 or the size of the collection causes the row to be appended.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value that contains the index of the table row position.
row
Address of a pointer to an IDispatch interface.

See also deleteRow


IHTMLTable::nextPage

HRESULT nextPage(
    void
);

Displays the next block of records in a repeated databound table. The number of records is determined by the dataPageSize property on the TABLE element.

  • Returns S_OK if successful, or an error value otherwise.

See also previousPage


IHTMLTable::previousPage

HRESULT previousPage(void);

Displays the previous block of records in a repeated databound table. The number of records is determined by the dataPageSize property on the TABLE element.

  • Returns S_OK if successful, or an error value otherwise.

See also nextPage


IHTMLTable::refresh

HRESULT refresh(
    void
);

Refreshes the content of the table.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLTableCaption

This interface specifies a caption for a table.

This element is a block element.

IHTMLTableCaption Methods


Align Property

*
  * Previous Topic: IHTMLTableCaption
  * Next Topic: IHTMLTableCaption::get_vAlign

IHTMLTableCaption::get_align

HRESULT get_align(
    BSTR *p
);

Retrieves the alignment of the caption.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives on of these values:
bottom | Aligns bottom center.
center | Centers the caption.
left | Left aligns.
right | Right aligns.
top | Aligns top-center.

See also put_align

Up Top of Page

IHTMLTableCaption::put_align

HRESULT put_align(
    BSTR v
);

Sets the alignment of the caption.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
bottom | Aligns bottom center.
center | Centers the caption.
left | Left aligns.
right | Right aligns.
top | Aligns top-center.

See also get_align


VAlign Property

*
  * Previous Topic: IHTMLTableCaption::get_align
  * Next Topic: IHTMLTableCaption::put_align

IHTMLTableCaption::get_vAlign

HRESULT get_vAlign(
    BSTR *p
);

Retrieves whether the caption appears at the top or bottom.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
bottom | Places the caption at the bottom of the table.
top | Places the caption at the top of the table. This is the default value for this property.

See also put_vAlign

Up Top of Page

IHTMLTableCaption::put_vAlign

HRESULT put_vAlign(
    BSTR v
);

Sets whether the caption appears at the top or bottom.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the caption placement. Can be one of these strings:
bottom | Places the caption at the bottom of the table.
top | Places the caption at the top of the table. This is the default value for this property.

See also get_vAlign


IHTMLTableCell

This interface specifies a cell in a table.

This element is a block element.

IHTMLTableCell Methods
put_rowSpan get_rowSpan put_colSpan
get_colSpan put_align get_align
put_vAlign get_vAlign put_bgColor
get_bgColor put_noWrap get_noWrap
put_background get_background put_borderColor
get_borderColor put_borderColorLight get_borderColorLight
put_borderColorDark get_borderColorDark put_width
get_width put_height get_height
get_cellIndex


Align Property

*
  * Previous Topic: IHTMLTableCell
  * Next Topic: IHTMLTableCell::get_background

IHTMLTableCell::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also put_align

Up Top of Page

IHTMLTableCell::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string specifying the alignment. Can be one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also get_align


Background Property

*
  * Previous Topic: IHTMLTableCell::get_align
  * Next Topic: IHTMLTableCell::get_bgColor

IHTMLTableCell::get_background

HRESULT get_background(
    BSTR *p
);

Retrieves a background picture for the cell. The picture is tiled behind the text and graphics in the table cell.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the URL of the background picture.

See also put_background

Up Top of Page

IHTMLTableCell::put_background

HRESULT put_background(
    BSTR v
);

Sets a background picture for the cell. The picture is tiled behind the text and graphics in the table cell.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string specifying the URL of the background picture.

See also get_background


BgColor Property

*
  * Previous Topic: IHTMLTableCell::get_background
  * Next Topic: IHTMLTableCell::get_borderColor

IHTMLTableCell::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLTableCell::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


BorderColor Property

*
  * Previous Topic: IHTMLTableCell::get_bgColor
  * Next Topic: IHTMLTableCell::get_borderColorDark

IHTMLTableCell::get_borderColor

HRESULT get_borderColor(
    VARIANT *p
);

Retrieves the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColor

Up Top of Page

IHTMLTableCell::put_borderColor

HRESULT put_borderColor(
    VARIANT v
);

Sets the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColor


BorderColorDark Property

*
  * Previous Topic: IHTMLTableCell::get_borderColor
  * Next Topic: IHTMLTableCell::get_borderColorLight

IHTMLTableCell::get_borderColorDark

HRESULT get_borderColorDark(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorDark

Up Top of Page

IHTMLTableCell::put_borderColorDark

HRESULT put_borderColorDark(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string or value specifying the color for borderColorDark. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorDark


BorderColorLight Property

*
  * Previous Topic: IHTMLTableCell::get_borderColorDark
  * Next Topic: IHTMLTableCell::get_cellIndex

IHTMLTableCell::get_borderColorLight

HRESULT get_borderColorLight(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorLight

Up Top of Page

IHTMLTableCell::put_borderColorLight

HRESULT put_borderColorLight(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the string or value specifying the color for borderColorLight. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorLight


IHTMLTableCell::get_cellIndex

HRESULT get_cellIndex(
    long *p
);

Retrieves the cell index value.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the cell index value.


ColSpan Property

*
  * Previous Topic: IHTMLTableCell::get_cellIndex
  * Next Topic: IHTMLTableCell::get_height

IHTMLTableCell::get_colSpan

HRESULT get_colSpan(
    long *p
);

Retrieves how many columns in the TABLE this cell spans.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer receiving the number of columns spanned.

See also put_colSpan

Up Top of Page

IHTMLTableCell::put_colSpan

HRESULT put_colSpan(
    long v
);

Sets how many columns in the TABLE this cell should span.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the number of columns to span.

See also get_colSpan


Height Property

*
  * Previous Topic: IHTMLTableCell::get_colSpan
  * Next Topic: IHTMLTableCell::get_noWrap

IHTMLTableCell::get_height

HRESULT get_height(
    VARIANT *p
);

Retrieves the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also put_height

Up Top of Page

IHTMLTableCell::put_height

HRESULT put_height(
    VARIANT v
);

Sets the calculated height of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the value specifying the height.

If the value of the corresponding HTML attribute was set using a percentage, this property specifies the height in pixels represented by that percentage.

See also get_height


NoWrap Property

*
  * Previous Topic: IHTMLTableCell::get_height
  * Next Topic: IHTMLTableCell::get_rowSpan

IHTMLTableCell::get_noWrap

HRESULT get_noWrap(
    VARIANT_BOOL *p
);

Determines whether automatic word wrapping is enabled or disabled for the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if automatic word-wrapping is enabled for the element, or FALSE otherwise. The default value for this property is FALSE.

See also put_noWrap

Up Top of Page

IHTMLTableCell::put_noWrap

HRESULT put_noWrap(
    VARIANT_BOOL v
);

Enables or disables automatic word wrapping for the element.

  • Returns S_OK if successful, or an error value otherwise.
v
Word-wrap flag. If TRUE, the browser performs automatic word wrapping on the element. If FALSE, it doesn't. The default value for this property is FALSE.

See also get_noWrap


RowSpan Property

*
  * Previous Topic: IHTMLTableCell::get_noWrap
  * Next Topic: IHTMLTableCell::get_vAlign

IHTMLTableCell::get_rowSpan

HRESULT get_rowSpan(
    long *p
);

Retrieves how many rows in a TABLE this cell spans.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer receiving the number of rows spanned.

See also put_rowSpan

Up Top of Page

IHTMLTableCell::put_rowSpan

HRESULT put_rowSpan(
    long v
);

Sets how many rows in a TABLE this cell should span.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer value specifying the number of rows to span.

See also get_rowSpan


VAlign Property

*
  * Previous Topic: IHTMLTableCell::get_rowSpan
  * Next Topic: IHTMLTableCell::get_width

IHTMLTableCell::get_vAlign

HRESULT get_vAlign(
    BSTR *p
);

Retrieves how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also put_vAlign

Up Top of Page

IHTMLTableCell::put_vAlign

HRESULT put_vAlign(
    BSTR v
);

Sets how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the vertical alignment. Can be one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also get_vAlign


Width Property

*
  * Previous Topic: IHTMLTableCell::get_vAlign
  * Next Topic: IHTMLTableCell::put_align

IHTMLTableCell::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLTableCell::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


IHTMLTableCol

This interface is used to specify column-based defaults for the table properties.

This element is a block element.

IHTMLTableCol Methods
put_span get_span put_width
get_width put_align get_align
put_vAlign get_vAlign

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Align Property

*
  * Previous Topic: IHTMLTableCol
  * Next Topic: IHTMLTableCol::get_vAlign

IHTMLTableCol::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also put_align

Up Top of Page

IHTMLTableCol::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also get_align


VAlign Property

*
  * Previous Topic: IHTMLTableCol::get_align
  * Next Topic: IHTMLTableCol::get_span

IHTMLTableCol::get_vAlign

HRESULT get_vAlign(
    BSTR *p
);

Retrieves how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also put_vAlign

Up Top of Page

IHTMLTableCol::put_vAlign

HRESULT put_vAlign(
    BSTR v
);

Sets how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the vertical alignment. Can be one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also get_vAlign


Span Property

*
  * Previous Topic: IHTMLTableCol::get_vAlign
  * Next Topic: IHTMLTableCol::get_width

IHTMLTableCol::get_span

HRESULT get_span(
    long *p
);

Retrieves the number of columns in the group.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the number of columns.

This attribute should be ignored if the COLGROUP element contains one or more COL elements. The purpose of this attribute is to provide a more convenient way of grouping columns without the need to specify COL elements.

See also put_span

Up Top of Page

IHTMLTableCol::put_span

HRESULT put_span(
    long v
);

Sets how many columns are in the group.

  • Returns S_OK if successful, or an error value otherwise.
v
Number of columns in the group.

This attribute should be ignored if the COLGROUP element contains one or more COL elements. The purpose of this attribute is to provide a more convenient way of grouping columns without the need to specify COL elements.

See also get_span


Width Property

*
  * Previous Topic: IHTMLTableCol::get_span
  * Next Topic: IHTMLTableCol::put_align

IHTMLTableCol::get_width

HRESULT get_width(
    VARIANT *p
);

Retrieves the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also put_width

Up Top of Page

IHTMLTableCol::put_width

HRESULT put_width(
    VARIANT v
);

Sets the calculated width of the element, in pixels.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the width.

This property is an integer value. Although an HTML author can specify the width as a percentage, this property always specifies the width in pixels.

See also get_width


IHTMLTableRow

This interface specifies a row in a table.

Within a row, the following tags are valid:

  • TD
  • TH

This element is a block element.

IHTMLTableRow Methods
put_align get_align put_vAlign
get_vAlign put_bgColor get_bgColor
put_borderColor get_borderColor put_borderColorLight
get_borderColorLight put_borderColorDark get_borderColorDark
get_rowIndex get_sectionRowIndex get_cells
insertCell deleteCell

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLTableRow::deleteCell

HRESULT deleteCell(
    long index
);

Removes a cell and all its contents from the row.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value specifying the row position index to be deleted.

See also insertCell


Align Property

*
  * Previous Topic: IHTMLTableRow::deleteCell
  * Next Topic: IHTMLTableRow::get_bgColor

IHTMLTableRow::get_align

HRESULT get_align(
    BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also put_align

Up Top of Page

IHTMLTableRow::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also get_align


BgColor Property

*
  * Previous Topic: IHTMLTableRow::get_align
  * Next Topic: IHTMLTableRow::get_borderColor

IHTMLTableRow::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLTableRow::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


BorderColor Property

*
  * Previous Topic: IHTMLTableRow::get_bgColor
  * Next Topic: IHTMLTableRow::get_borderColorDark

IHTMLTableRow::get_borderColor

HRESULT get_borderColor(
    VARIANT *p
);

Retrieves the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColor

Up Top of Page

IHTMLTableRow::put_borderColor

HRESULT put_borderColor(
    VARIANT v
);

Sets the border color and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColor


BorderColorDark Property

*
  * Previous Topic: IHTMLTableRow::get_borderColor
  * Next Topic: IHTMLTableRow::get_borderColorLight

IHTMLTableRow::get_borderColorDark

HRESULT get_borderColorDark(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorDark

Up Top of Page

IHTMLTableRow::put_borderColorDark

HRESULT put_borderColorDark(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorLight, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the string specifying the color value. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorDark


BorderColorLight Property

*
  * Previous Topic: IHTMLTableRow::get_borderColorDark
  * Next Topic: IHTMLTableRow::get_cells

IHTMLTableRow::get_borderColorLight

HRESULT get_borderColorLight(
    VARIANT *p
);

Retrieves independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_borderColorLight

Up Top of Page

IHTMLTableRow::put_borderColorLight

HRESULT put_borderColorLight(
    VARIANT v
);

Sets independent border color control over one of the two colors used to draw a 3-D border, opposite of borderColorDark, and must be used with the border property.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure containing the string specifying the color value. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_borderColorLight


IHTMLTableRow::get_cells

HRESULT get_cells(
    IHTMLElementCollection **p
);

Retrieves a collection of all cells in the row of a table. This is a collection of TH and TD elements.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the collection.


IHTMLTableRow::get_rowIndex

HRESULT get_rowIndex(
   long *p
);

Returns the zero-based position index of this row relative to the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the position index value.


IHTMLTableRow::get_sectionRowIndex

HRESULT get_sectionRowIndex(
    long *p
);

Returns the zero-based index of this row with respect to the section that this is in (that is, the rowIndex of the first row in this section).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a long integer that receives the section row index value.


VAlign Property

*
  * Previous Topic: IHTMLTableRow::get_sectionRowIndex
  * Next Topic: IHTMLTableRow::insertCell

IHTMLTableRow::get_vAlign

HRESULT get_vAlign(
    BSTR *p
);

Retrieves how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also get_vAlign

Up Top of Page

IHTMLTableRow::put_vAlign

HRESULT put_vAlign(
    BSTR v
);

Sets how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the vertical alignment. Can be one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also get_vAlign


IHTMLTableRow::insertCell

HRESULT insertCell(
    long index
);

Inserts an empty cell into this row. The cell is inserted at the zero-based index passed into the table. If -1, or the size of the cells collection for this row is passed in, the cell is appended and a pointer to the cell created is returned.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer specifying the index value for the table cell.

See also deleteCell


IHTMLTableSection

This interface is used to designate rows as the body of the table.

This element is exposed for all tables, even if the table did not explicitly define a TBODY element.

This element is a block element.

IHTMLTableSection Methods
put_align get_align put_vAlign
get_vAlign put_bgColor get_bgColor
get_rows insertRow
deleteRow


IHTMLTableSection::deleteRow

HRESULT deleteRow(
    long index
);

Removes the row indicated by the value of the index parameter from this table section.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer value that specifies the position of the row.

See also insertRow


BgColor Property

*
  * Previous Topic: IHTMLTableSection::deleteRow
  * Next Topic: IHTMLTableSection::get_rows

IHTMLTableSection::get_bgColor

HRESULT get_bgColor(
    VARIANT *p
);

Retrieves the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that receives the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also put_bgColor

Up Top of Page

IHTMLTableSection::put_bgColor

HRESULT put_bgColor(
    VARIANT v
);

Sets the background color behind the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the color. The color can be one of the color names or values given in the Color Table reference documentation.

See also get_bgColor


IHTMLTableSection::get_rows

HRESULT get_rows(
    IHTMLElementCollection **p
);

Returns a zero-based collection of the rows in this section of the table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLElementCollection interface of the table.


Align Property

*
  * Previous Topic: IHTMLTableSection::get_rows
  * Next Topic: IHTMLTableSection::get_vAlign

IHTMLTableSection::get_align

HRESULT get_align(
   BSTR *p
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also put_align

Up Top of Page

IHTMLTableSection::put_align

HRESULT put_align(
    BSTR v
);

Displays the element left flush, right flush, or centered relative to the display or table.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the alignment. Can be one of these values:
center | Aligns to the center.
left | Aligns to the left edge.
right | Aligns to the right edge.

See also get_align


VAlign Property

*
  * Previous Topic: IHTMLTableSection::get_align
  * Next Topic: IHTMLTableSection::insertRow

IHTMLTableSection::get_vAlign

HRESULT get_vAlign(
    BSTR *p
);

Retrieves how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also put_vAlign

Up Top of Page

IHTMLTableSection::put_vAlign

HRESULT put_vAlign(
    BSTR v
);

Sets how the text and other content of an element is vertically aligned within the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the vertical alignment. Can be one of these strings:
baseline | Aligns the baseline of the first line of text with the baselines in adjacent elements.
bottom | Aligns the text at the bottom of the element.
middle | Aligns the text in the middle of the element. This is the default value for this property.
top | Aligns the text at the top of the element.

See also get_vAlign


IHTMLTableSection::insertRow

HRESULT insertRow(
    long index,
    IDispatch **row
);

Inserts an empty row into this table section. The row is added at the position indicated by the index provided. For example, passing in 1 adds the row between 0 and 1, thus becoming the row with index 1. Passing in -1 or the size of the collection causes the row to be appended.

  • Returns S_OK if successful, or an error value otherwise.
index
Long integer that contains the value specifying the position in the table.
row
Address of a pointer to an IDispatch interface.

See also deleteRow


IHTMLTextAreaElement

This interface specifies a multiline text input control.

The default font is fixed pitch.

IHTMLTextAreaElement Methods
get_type put_value get_value
put_name get_name put_status
get_status put_disabled get_disabled
get_form put_defaultValue get_defaultValue
select put_onchange get_onchange
put_onselect get_onselect put_readOnly
get_readOnly put_rows get_rows
put_cols get_cols put_wrap
get_wrap createTextRange

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLTextAreaElement::createTextRange

HRESULT createTextRange(
    IHTMLTxtRange **range
);

Creates a text range object for the element. You use a text range to examine and modify the text within the element.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a variable that receives an interface pointer to the text range.

See also IHTMLTxtRange


Cols Property

*
  * Previous Topic: IHTMLTextAreaElement::createTextRange
  * Next Topic: IHTMLTextAreaElement::get_defaultValue

IHTMLTextAreaElement::get_cols

HRESULT get_cols(
    long *p
);

Retrieves the width, in columns (characters), of a TEXTAREA control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of columns.

See also put_cols

Up Top of Page

IHTMLTextAreaElement::put_cols

HRESULT put_cols(
    long v
);

Sets the width, in columns (characters), of the TEXTAREA control.

  • Returns S_OK if successful, or an error value otherwise.
v
Long integer that receives the number of columns.

See also get_cols


DefaultValue Property

*
  * Previous Topic: IHTMLTextAreaElement::get_cols
  * Next Topic: IHTMLTextAreaElement::get_disabled

IHTMLTextAreaElement::get_defaultValue

HRESULT get_defaultValue(
    BSTR *p
);

Retrieves the default value of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the default value.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

See also put_defaultValue

Up Top of Page

IHTMLTextAreaElement::put_defaultValue

HRESULT put_defaultValue(
    BSTR v
);

Sets the default value of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the default value.

This value can be changed programmatically but has no effect on the appearance nor on how forms are submitted.

See also get_defaultValue


Disabled Property

*
  * Previous Topic: IHTMLTextAreaElement::get_defaultValue
  * Next Topic: IHTMLTextAreaElement::get_form

IHTMLTextAreaElement::get_disabled

HRESULT get_disabled(
    VARIANT_BOOL *p
);

Determines whether the control is enabled or disabled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the control is disabled, or FALSE otherwise.

The default value for this property is FALSE.

See also put_disabled

Up Top of Page

IHTMLTextAreaElement::put_disabled

HRESULT put_disabled(
    VARIANT_BOOL v
);

Enables or disables the control. A disabled control appears dimmed and does not respond to user input.

  • Returns S_OK if successful, or an error value otherwise.
v
Boolean value specifying whether to disable the control. If TRUE, the control is disabled; otherwise, it is enabled.

The default value for this property is FALSE.

See also get_disabled


IHTMLTextAreaElement::get_form

HRESULT get_form(
    IHTMLFormElement **p
);

Retrieves a reference to the form the element is embedded on.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the form element. This parameter receives NULL if the element is not on a form.

See also IHTMLFormElement


Name Property

*
  * Previous Topic: IHTMLTextAreaElement::get_form
  * Next Topic: IHTMLTextAreaElement::get_onchange

IHTMLTextAreaElement::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the name.

The name is used to bind the value of the control when submitting a form. The name is not the value that is displayed in the entry field of the element. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also put_name

Up Top of Page

IHTMLTextAreaElement::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name is used to bind the value of the element when submitting a form. The name is not the value that is displayed in the entry field of the element. Submitting the form submits the internally stored value, not the one displayed.

JScript allows the name to be changed at run time. This does not change the name in the programming model, in the collection of elements, but does change the name used for submitting elements.

See also get_name


Onchange Property

*
  * Previous Topic: IHTMLTextAreaElement::get_name
  * Next Topic: IHTMLTextAreaElement::get_onselect

IHTMLTextAreaElement::get_onchange

HRESULT get_onchange(
    VARIANT *p
);

Retrieves the inline script associated with the onchange event for the TEXTAREA element. The onchange event occurs when the contents of the object have changed.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onchange

Up Top of Page

IHTMLTextAreaElement::put_onchange

HRESULT put_onchange(
    VARIANT v
);

Sets the inline script associated with the onchange event for the TEXTAREA element. The onchange event occurs when the contents of the object have changed.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onchange


Onselect Property

*
  * Previous Topic: IHTMLTextAreaElement::get_onchange
  * Next Topic: IHTMLTextAreaElement::get_readOnly

IHTMLTextAreaElement::get_onselect

HRESULT get_onselect(
    VARIANT *p
);

Retrieves the inline script associated with the onselect event for the TEXTAREA element. The onselect event fires at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onselect

Up Top of Page

IHTMLTextAreaElement::put_onselect

HRESULT put_onselect(
    VARIANT v
);

Sets the inline script associated with the onselect event for the TEXTAREA element. The onselect event fires at the beginning of a user-initiated select. This event can be canceled, and it participates in the bubbling model.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onselect


ReadOnly Property

*
  * Previous Topic: IHTMLTextAreaElement::get_onselect
  * Next Topic: IHTMLTextAreaElement::get_rows

IHTMLTextAreaElement::get_readOnly

HRESULT get_readOnly(
    VARIANT_BOOL *p
);

Determines whether the element's contents are read-only, meaning that the user cannot enter or edit text in the control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the element is read-only, or FALSE if not.

This is different than disabled. Read-only still allows the element to receive the focus, while disabled does not allow the element to receive the focus.

The default value for this property is FALSE.

See also put_readOnly

Up Top of Page

IHTMLTextAreaElement::put_readOnly

HRESULT put_readOnly(
    VARIANT_BOOL v
);

Specifies whether the element's contents are read-only, meaning that the user cannot enter or edit text in the control.

  • Returns S_OK if successful, or an error value otherwise.
v
Read-only flag. TRUE sets the element to read-only; FALSE does not.

This is different than disabled. Read-only still allows the element to receive the focus, while disabled does not allow the element to receive the focus.

The default value for this property is FALSE.

See also get_readOnly


Rows Property

*
  * Previous Topic: IHTMLTextAreaElement::get_readOnly
  * Next Topic: IHTMLTextAreaElement::get_status

IHTMLTextAreaElement::get_rows

HRESULT get_rows(
    long *p
);

Retrieves the height, in rows, of the TEXTAREA control.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of rows.

See also put_rows

Up Top of Page

IHTMLTextAreaElement::put_rows

HRESULT put_rows(
    long v
);

Sets the height, in rows, of the TEXTAREA control.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the number of rows.

See also get_rows


Status Property

*
  * Previous Topic: IHTMLTextAreaElement::get_rows
  * Next Topic: IHTMLTextAreaElement::get_type

IHTMLTextAreaElement::get_status

HRESULT get_status(
    VARIANT *p
);

Retrieves the status of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the status. It can be TRUE, FALSE, or NULL.

See also put_status

Up Top of Page

IHTMLTextAreaElement::put_status

HRESULT put_status(
    VARIANT v
);

Sets the status of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the status. Can be TRUE, FALSE, or NULL.

See also get_status


IHTMLTextAreaElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the type of intrinsic control represented by the given element object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the type. The possible values depend on the element, as listed in the following table.

Element | Possible value | Description
INPUT | checkbox | Used for simple Boolean attributes or for attributes that can take multiple values at the same time. It is represented by a number of check box fields, each of which has the same name. Each selected check box generates a separate name/value pair in the submitted data, even if this results in duplicate names. The default value for check boxes is on.
file | A file upload element.
hidden | No field is presented to the user, but the content of the field is sent with the submitted form. This value can be used to transmit state information about client/server interaction.
image | An image field that you can click, causing the form to be immediately submitted. The coordinates of the selected point are measured in pixel units from the upper-left corner of the image, and are returned (along with the other contents of the form) in two name/value pairs. The x-coordinate is submitted under the name of the field with .x appended, and the y-coordinate is submitted under the name of the field with .y appended. Any value property is ignored. The image itself is specified by the SRC attribute, exactly as for the Image element.
password | Same as the TEXT attribute, except that text is not displayed as the user enters it.
radio | Used for attributes that accept a single value from a set of alternatives. Each radio-button field in the group should be given the same name. Only the selected radio button in the group generates a name/value pair in the submitted data. Radio buttons require an explicit value property.
reset | reset is a button that when clicked resets the form's fields to their specified initial values. The label to be displayed on the button can be specified just as for the submit button.
submit | submit is a button that when clicked submits the form. You can use the value attribute to provide a non-editable label to be displayed on the button. The default label is application-specific. If a submit button is clicked to submit the form, and that button has a name attribute specified, that button contributes a name/value pair to the submitted data. Otherwise, a submit button makes no contribution to the submitted data.
text | Used for a single-line text-entry field. Use in conjunction with the size and maxLength properties.
SELECT | select-multiple | Specifies a multiple-select list box.
select-one | Specifies a single-select list box.
TEXTAREA | textarea | Used for multiple-line text-entry fields. Use in conjunction with the size and maxLength properties.


Value Property

*
  * Previous Topic: IHTMLTextAreaElement::get_type
  * Next Topic: IHTMLTextAreaElement::get_wrap

IHTMLTextAreaElement::get_value

HRESULT get_value(
    BSTR *p
);

Retrieves the current text from the entry field of the TEXTAREA element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the text.

See also put_value

Up Top of Page

IHTMLTextAreaElement::put_value

HRESULT put_value(
    BSTR v
);

Sets the text entry field of the TEXTAREA element, replacing any existing text.

  • Returns S_OK if successful, or an error value otherwise.
v
String to place in the entry field of the element.

See also get_value


Wrap Property

*
  * Previous Topic: IHTMLTextAreaElement::get_value
  * Next Topic: IHTMLTextAreaElement::put_cols

IHTMLTextAreaElement::get_wrap

HRESULT get_wrap(
    BSTR *p
);

Retrieves how word-wrapping is handled in the element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives one of these strings:
off | Word-wrapping is disabled. The lines appear exactly as the user types them. This is the default value for this property.
physical | The text is displayed and submitted word-wrapped.
virtual | The text is displayed word-wrapped but is submitted as typed.

See also put_wrap

Up Top of Page

IHTMLTextAreaElement::put_wrap

HRESULT put_wrap(
    BSTR v
);

Specifies how to handle word-wrapping in the element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying one of these values:
off | Word-wrapping is disabled. The lines appear exactly as the user types them. This is the default value for this property.
physical | The text is displayed and submitted word-wrapped.
virtual | The text is displayed word-wrapped but is submitted as typed.

See also get_wrap


IHTMLTextAreaElement::select

HRESULT select(
    void
);

Highlights the input area of a form element.

  • Returns S_OK if successful, or an error value otherwise.

You can use the select method with the focus method to highlight a field and position the cursor for a user response.


IHTMLTextContainer

This interface provides access to properties and methods that are common to the BODY, BUTTON, CAPTION, DIV, MARQUEE, TABLE, and TEXTAREA elements.

IHTMLTextContainer Methods
createControlRange get_scrollHeight get_scrollWidth
put_scrollTop get_scrollTop put_scrollLeft
get_scrollLeft put_onscroll get_onscroll

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLTextContainer::createControlRange

HRESULT createControlRange(
    IDispatch **range
);

Creates a selection range object for control-based selection rather than text-based selection. If there are currently controls selected in the text container, the control range is initialized with them; otherwise, it is created empty and controls need to be explicitly added to it. This is opposite of the text range, which defaults to the whole text container if there is no selection. This returns an IHTMLControlRange object.

  • Returns S_OK if successful, or an error value otherwise.
range
Address of a pointer to a variable of IDispatch type.


Onscroll Property

*
  * Previous Topic: IHTMLTextContainer::createControlRange
  * Next Topic: IHTMLTextContainer::get_scrollHeight

IHTMLTextContainer::get_onscroll

HRESULT get_onscroll(
    VARIANT *p
);

Occurs when the scroll box is repositioned. The default action of this event is to scroll.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onscroll

Up Top of Page

IHTMLTextContainer::put_onscroll

HRESULT put_onscroll(
    VARIANT v
);

Occurs when the scroll box is repositioned. The default action of this event is to scroll.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onscroll


IHTMLTextContainer::get_scrollHeight

HRESULT get_scrollHeight(
    long *p
);

Retrieves the element's scrolling height, in pixels. This is the distance between the top and bottom edges of the element's visible content. The physical height of the content, including nonvisible content, can be obtained with the IHTMLElement::get_offsetHeight property.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll height.

This property is read-only on HTML documents, and read-write on fixed regions.

See also get_scrollWidth


ScrollLeft Property

*
  * Previous Topic: IHTMLTextContainer::get_scrollHeight
  * Next Topic: IHTMLTextContainer::get_scrollTop

IHTMLTextContainer::get_scrollLeft

HRESULT get_scrollLeft(
    long *p
);

Retrieves the distance, in pixels, between the left edge of the element and the leftmost portion of the element that is currently visible in the window. This is equal to the horizontal distance that the content of the element has been scrolled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll-left distance.

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollWidth if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not support scroll bars. For these elements, setting the property has no effect.

See also put_scrollLeft

Up Top of Page

IHTMLTextContainer::put_scrollLeft

HRESULT put_scrollLeft(
    long v
);

Sets the distance, in pixels, between the left edge of the element and the leftmost portion of the element that is currently visible in the window. This is equal to the horizontal distance that the content of the element has been scrolled.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the scroll-left distance.

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollWidth if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not support scroll bars. For these elements, setting the property has no effect.

See also get_scrollLeft


ScrollTop Property

*
  * Previous Topic: IHTMLTextContainer::get_scrollLeft
  * Next Topic: IHTMLTextContainer::get_scrollWidth

IHTMLTextContainer::get_scrollTop

HRESULT get_scrollTop(
    long *p
);

Retrieves the distance, in pixels, between the top of the element and the topmost portion of the content that is currently visible in the window. This is equal to the vertical distance that the content of the element has been scrolled.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll top distance.

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollHeight if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not have scroll bars. For these elements, setting the property has no effect.

See also put_scrollTop

Up Top of Page

IHTMLTextContainer::put_scrollTop

HRESULT put_scrollTop(
    long v
);

Sets the distance, in pixels, between the top of the element and the topmost portion of the content that is currently visible in the window. This is equal to the vertical distance that the content of the element has been scrolled.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying the scroll top distance.

This read-write property is always a nonnegative integer. Although it can be set to any positive or negative value, the property is set to zero if the assigned value is less than zero, and is set to the value of scrollHeight if the assigned value is greater than this. The default value is zero.

This property is always zero for elements that do not have scroll bars. For these elements, setting the property has no effect.

See also get_scrollTop


IHTMLTextContainer::get_scrollWidth

HRESULT get_scrollWidth(
    long *p
);

Retrieves the element's scrolling width, in pixels. This is the distance between the left and right edges of the element's visible content.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the scroll width.

This property is read-only on HTML documents, and read-write on fixed regions.

See also get_scrollHeight


IHTMLTextElement

This interface provides access to the properties and methods for this object and is equivalent to the IHTMLElement interface. See the reference section for the IHTMLElement interface for more information and a listing of the available methods.


IHTMLTextRangeMetrics

The IHTMLTextRangeMetrics interface exposes information about the position of a TextRange. This enables greater control and definition of any given object on a page, thereby providing enhanced accessibility support to users.

IHTMLTextRangeMetrics Methods

get_boundingHeight | Retrieves the height of the rectangle that bounds the TextRange.
get_boundingLeft | Retrieves the left coordinate of the rectangle that bounds the TextRange.
get_boundingTop | Retrieves the top coordinate of the rectangle that bounds the TextRange.
get_boundingWidth | Retrieves the width of the rectangle that bounds the TextRange.
get_offsetLeft | Retrieves the calculated left position of the rectangle bounding the TextRange.
get_offsetTop | Retrieves the calculated top position of the rectangle bounding the TextRange.

Implemented In

MSHTML Object Model


IHTMLTextRangeMetrics::get_boundingHeight

Retrieves the height of the rectangle that bounds the TextRange.

Syntax

HRESULT get_boundingHeight(
    long *p
);

Parameters

p
[out] Address of a variable that receives the height of the rectangle that bounds the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingLeft, IHTMLTextRangeMetrics::get_boundingTop, IHTMLTextRangeMetrics::get_boundingWidth, IHTMLTextRangeMetrics::get_offsetLeft, IHTMLTextRangeMetrics::get_offsetTop


IHTMLTextRangeMetrics::get_boundingLeft

Retrieves the left coordinate of the rectangle that bounds the TextRange.

Syntax

HRESULT get_boundingLeft(
    long *p
);

Parameters

p
[out] Address of a variable that receives the left coordinate of the rectangle that bounds the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingHeight, IHTMLTextRangeMetrics::get_boundingTop, IHTMLTextRangeMetrics::get_boundingWidth, IHTMLTextRangeMetrics::get_offsetLeft, IHTMLTextRangeMetrics::get_offsetTop


IHTMLTextRangeMetrics::get_boundingTop

Retrieves the top coordinate of the rectangle that bounds the TextRange.

Syntax

HRESULT get_boundingTop(
    long *p
);

Parameters

p
[out] Address of a variable that receives the top coordinate of the rectangle that bounds the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingHeight, IHTMLTextRangeMetrics::get_boundingLeft, IHTMLTextRangeMetrics::get_boundingWidth, IHTMLTextRangeMetrics::get_offsetLeft, IHTMLTextRangeMetrics::get_offsetTop


IHTMLTextRangeMetrics::get_boundingWidth

Retrieves the width of the rectangle that bounds the TextRange.

Syntax

HRESULT get_boundingWidth(
    long *p
);

Parameters

p
[out] Address of a variable that receives the width of the rectangle that bounds the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingHeight, IHTMLTextRangeMetrics::get_boundingLeft, IHTMLTextRangeMetrics::get_boundingTop, IHTMLTextRangeMetrics::get_offsetLeft, IHTMLTextRangeMetrics::get_offsetTop


IHTMLTextRangeMetrics::offsetLeft

IHTMLTextElement IHTMLTextElement *
  * Previous Topic: IHTMLTextRangeMetrics::get_boundingWidth
  * Next Topic: IHTMLTextRangeMetrics::get_offsetTop

IHTMLTextRangeMetrics::get_offsetLeft

Returns the calculated left position of the rectangle bounding the TextRange, in pixels, based on the offset parent.

Syntax

HRESULT get_offsetLeft(
    long *p
);

Parameters

p
[out] Address of a variable that receives the calculated left position of the rectangle bounding the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingHeight, IHTMLTextRangeMetrics::get_boundingLeft, IHTMLTextRangeMetrics::get_boundingTop, IHTMLTextRangeMetrics::get_boundingWidth, IHTMLTextRangeMetrics::get_offsetTop


IHTMLTextRangeMetrics::get_offsetTop

Returns the calculated top position of the rectangle bounding the TextRange, in pixels, based on the offset parent.

Syntax

HRESULT get_offsetTop(
    long * p
);

Parameters

p
[out] Address of a variable that receives the calculated top position of the rectangle bounding the TextRange.

Return Value

Returns S_OK if successful, or an error code otherwise.

See Also

IHTMLTextRangeMetrics, IHTMLTextRangeMetrics::get_boundingHeight, IHTMLTextRangeMetrics::get_boundingLeft, IHTMLTextRangeMetrics::get_boundingTop, IHTMLTextRangeMetrics::get_boundingWidth, IHTMLTextRangeMetrics::get_offsetLeft


IHTMLTitleElement

This interface identifies the contents of the document in a global context.

This element can be only used within the HEAD element.

This element is a block element.

IHTMLTitleElement Methods


Text Property

*
  * Previous Topic: IHTMLTitleElement
  * Next Topic: IHTMLTitleElement::put_text

IHTMLTitleElement::get_text

HRESULT get_text(
    BSTR *p
);

Retrieves the text contained within the TITLE element.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the text.

See also put_text

Up Top of Page

IHTMLTitleElement::put_text

HRESULT put_text(
    BSTR v
);

Retrieves the text contained within the TITLE element.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text.

See also get_text


IHTMLTxtRange

This interface provides the ability to access the text range object in an HTML element. You use this interface to retrieve and modify text in an element, to locate specific strings in the text, and to carry out commands that affect the appearance of the text.

You retrieve a text range object by using the createTextRange method of the IHTMLBodyElement, IHTMLInputHiddenElement, IHTMLInputTextElement, IHTMLTextAreaElement, or IHTMLButtonElement interface. You can modify the extent of the text range by moving its start and end positions with methods such as move, moveToElementText, and findText. Within the text range, you can retrieve and modify plain text or HTML text. These forms of text are identical except that HTML text includes HTML tags; plain text does not.

IHTMLTxtRange Methods
get_htmlText put_text get_text
parentElement duplicate inRange
isEqual scrollIntoView collapse
expand move moveStart
moveEnd select pasteHTML
moveToElementText setEndPoint compareEndPoints
findText moveToPoint getBookmark
moveToBookmark queryCommandSupported queryCommandEnabled
queryCommandState queryCommandIndeterm queryCommandText
queryCommandValue execCommand execCommandShowHelp

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLTxtRange::collapse

HRESULT collapse(
    VARIANT_BOOL Start
);

Creates an empty range either at the beginning or end of the current range.

  • Returns S_OK if successful, or an error value otherwise.
Start
Boolean value specifying where to create the empty range. TRUE creates an empty range at the beginning of the current range; FALSE creates it at the end.

See also expand


IHTMLTxtRange::compareEndPoints

HRESULT compareEndPoints(
    BSTR how,
    IHTMLTxtRange *SourceRange,
    long *ret
);

Compares two end points and returns -1, 0, or 1 for less than, equal, or greater than, respectively.

  • Returns S_OK if successful, or an error value otherwise.
how
String describing the end points to compare. Can be one of these values:
StartToEnd | Compares the start point of the current range to the end point of the given range.
StartToStart | Compares the start point of the current range to the start point of the given range.
EndToStart | Compares the end point of the current range to the start point of the given range.
EndToEnd | Compares the end point of the current range to the end point of the given range.
SourceRange
Interface pointer of the range object against which the current range is to be compared.
ret
Address of a variable that receives the result of the comparison. Can be one of these values:
-1 | The end point of SourceRange is less than that of the current range.
0 | The end point of SourceRange is equal to that of the current range.
1 | The end point of SourceRange is greater than that of the current range.

See also setEndPoint


IHTMLTxtRange::duplicate

HRESULT duplicate(
    IHTMLTxtRange **Duplicate
);

Creates a duplicate of the range.

  • Returns S_OK if successful, or an error value otherwise.
Duplicate
Address of a variable that receives an interface pointer for the duplicate range.

See also IHTMLTxtRange


IHTMLTxtRange::execCommand

HRESULT execCommand(
    BSTR cmdID,
    VARIANT_BOOL showUI,
    VARIANT value,
    VARIANT_BOOL *pfRet
);

Executes the given command over the current selection or text range.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
showUI
Flag specifying whether to display a user interface if the command supports one. If TRUE, the command displays a user interface, if applicable; otherwise, it doesn't.
value
Value to pass to the command. Possible values depend on the value of cmdID.
pfRet
Address of a variable that receives TRUE if the function is successful, or FALSE otherwise.

See also execCommandShowHelp


IHTMLTxtRange::execCommandShowHelp

HRESULT execCommandShowHelp(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Displays help information for the given command identifier.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if successful, or FALSE otherwise.

See also execCommand


IHTMLTxtRange::expand

HRESULT expand(
    BSTR Unit,
    VARIANT_BOOL *Success
);

Expands the range so that partial units are completed contained.

  • Returns S_OK if successful, or an error value otherwise.
Unit
String specifying the unit by which to expand the range. Can be one of these values:
Character | Expands a character.
Word | Expands a word. A word is a collection of characters terminated by a space or other white space character, such as a tab or return character.
Sentence | Expands a sentence. A sentence is a collection of words terminated by a punctuation character, such as a period.
Textedit | Expands to enclose the entire range.
Success
Address of a variable that receives TRUE if the the range was successfully expanded, or FALSE if not.

See also collapse


IHTMLTxtRange::findText

HRESULT findText(
    BSTR String,
    long count,
    long Flags,
    VARIANT_BOOL *Success
);

Searches for text in the given range. Positions the start and end points of the range to encompass the search string.

  • Returns S_OK if successful, or an error value otherwise.
String
String specifying the text to find.
count
Long integer that receives the count.
Flags
Long integer that receives the search flags.
Success
Address of a variable that receives TRUE if the text is found, or FALSE if not.


IHTMLTxtRange::get_htmlText

HRESULT get_htmlText(
    BSTR *p
);

Retrieves the HTML source as a valid HTML fragment.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the HTML source.

This property corresponds to the fragment portion of the CF_HTML clipboard format. For more information about CF_HTML, see HTML Clipboard Format.

See also put_text


Text Property

*
  * Previous Topic: IHTMLTxtRange::get_htmlText
  * Next Topic: IHTMLTxtRange::getBookmark

IHTMLTxtRange::get_text

HRESULT get_text(
    BSTR *p
);

Retrieves the text contained within the range.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the text.

The text is formatted within the current context of the document.

Up Top of Page

IHTMLTxtRange::put_text

HRESULT put_text(
    BSTR v
);

Sets the text contained within the range.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the text.

The text is formatted within the current context of the document.

See also get_text


IHTMLTxtRange::getBookmark

HRESULT getBookmark(
    BSTR *Bookmark
);

Retrieves a bookmark (opaque string) that can be used with moveToBookmark to return to the same range.

  • Returns S_OK if successful, or an error value otherwise.
Bookmark
Address of a variable that receives the bookmark if successful, or NULL otherwise.

See also moveToBookmark


IHTMLTxtRange::inRange

HRESULT inRange(
    IHTMLTxtRange *Range,
    VARIANT_BOOL *InRange
);

Determines whether the specified range is within or equal to the current range.

  • Returns S_OK if successful, or an error value otherwise.
Range
Interface pointer of the range to test.
InRange
Address of a variable that receives TRUE if Range is within the current range, or FALSE if not.

See also IHTMLTxtRange


IHTMLTxtRange::isEqual

HRESULT isEqual(
    IHTMLTxtRange *Range,
    VARIANT_BOOL *IsEqual
);

Determines whether the specified range is equal to the current range.

  • Returns S_OK if successful, or an error value otherwise.
Range
Interface pointer of the range to test.
IsEqual
Address of a variable that receives TRUE if Range is equal to the current range, or FALSE if not.

See also inRange


IHTMLTxtRange::move

HRESULT move(
    BSTR Unit,
    long Count,
    long *ActualCount
);

Collapses the given text range and moves the empty range by the given number of units.

  • Returns S_OK if successful, or an error value otherwise.
Unit
String specifying the units to move. Can be one of these values:
Character | Moves one or more characters.
Word | Moves one or more words. A word is a collection of characters terminated by a space or other white space character.
Sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
Textedit | Moves to the start or end of the original range.
Count
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also moveStart


IHTMLTxtRange::moveEnd

HRESULT moveEnd(
    BSTR Unit,
    long Count,
    long *ActualCount
);

Changes the scope of the range by moving the end position of the range.

  • Returns S_OK if successful, or an error value otherwise.
Unit
String specifying the units to move. Can be one of these values:
Character | Moves one or more characters.
Word | Moves one or more words. A word is a collection of characters terminated by a space or other white space character.
Sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
Textedit | Moves to the start or end of the original range.
Count
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also move, moveStart


IHTMLTxtRange::moveStart

HRESULT moveStart(
    BSTR Unit,
    long Count,
    long *ActualCount
);

Changes the scope of the range by moving the start position of the range.

  • Returns S_OK if successful, or an error value otherwise.
Unit
String specifying the units to move. Can be one of these values:
Character | Moves one or more characters.
Word | Moves one or more words. A word is a collection of characters terminated by a space or other white space character.
Sentence | Moves one or more sentences. A sentence is a collection of words terminated by a punctuation character, such as a period.
Textedit | Moves to the start or end of the original range.
Count
Integer specifying the number of units to move. This can be positive or negative.
ActualCount
Address of a variable that receives the actual number of units moved.

See also move, moveEnd


IHTMLTxtRange::moveToBookmark

HRESULT moveToBookmark(
    BSTR Bookmark,
    VARIANT_BOOL *Success
);

Moves to a bookmark. Bookmarks are opaque strings that are created with the getBookmark method.

  • Returns S_OK if successful, or an error value otherwise.
Bookmark
String specifying the bookmark.
Success
Address of a variable that receives TRUE if successful, or FALSE otherwise.

See also getBookmark


IHTMLTxtRange::moveToElementText

HRESULT moveToElementText(
    IHTMLElement *element
);

Moves the text range so that the start and end positions of the range encompass the text in the given element.

  • Returns S_OK if successful, or an error value otherwise.
element
Interface pointer of an element.

See also IHTMLElement


IHTMLTxtRange::moveToPoint

HRESULT moveToPoint(
    long x,
    long y
);

Moves the start and end positions of the text range to the given point. The coordinates of the point must be in pixels and be relative to the upper-left corner of the window. The resulting text range is empty, but can be expanded and moved using methods such as expand and moveEnd.

  • Returns S_OK if successful, or an error value otherwise.
x
Integer specifying the x-coordinate, in pixels.
y
Integer specifying the y-coordinate, in pixels.


IHTMLTxtRange::parentElement

HRESULT parentElement(
    IHTMLElement **Parent
);

Retrieves the parent element for the given text range. The parent element is the element that completely encloses the text in the range.

  • Returns S_OK if successful, or an error value otherwise.
Parent
Address of a variable that receives an interface pointer for the parent element.

If the text range spans text in more than one element, the method returns the smallest element that encloses all the elements. When you insert text into a range that spans multiple elements, the text is placed within the parent element rather than in any of the contained elements.

See also IHTMLElement


IHTMLTxtRange::pasteHTML

HRESULT pasteHTML(
    BSTR html
);

Pastes HTML text into the given text range. The text completely replaces any previous text and HTML elements in the range.

  • Returns S_OK if successful, or an error value otherwise.
html
String specifying the HTML text to paste.

Although this method never fails, it might alter the HTML text to make it fit the given text range. For example, attempting to paste a table cell into a text range that does not contain a table might cause the method to insert a TABLE element. For predictable results, you should paste only well-formed HTML text that is appropriate for the given text range.

You cannot use this method while the document is loading. Wait for the onload event before attempting to use it.


IHTMLTxtRange::queryCommandEnabled

HRESULT queryCommandEnabled(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is currently available.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the command is available, or FALSE otherwise.

See also queryCommandSupported


IHTMLTxtRange::queryCommandIndeterm

HRESULT queryCommandIndeterm(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is in the indeterminate state.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the given command is in the indeterminate state, or FALSE otherwise.


IHTMLTxtRange::queryCommandState

HRESULT queryCommandState(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Retrieves the current status of the given command. The status indicates whether the command has been carried out on the object.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the given command has been carried out, FALSE if it has not, or NULL if the function cannot determine the status of the command.


IHTMLTxtRange::queryCommandSupported

HRESULT queryCommandSupported(
    BSTR cmdID,
    VARIANT_BOOL *pfRet
);

Determines whether the given command is supported.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pfRet
Address of a variable that receives TRUE if the command is supported, or FALSE otherwise.

See also queryCommandEnabled


IHTMLTxtRange::queryCommandText

HRESULT queryCommandText(
    BSTR cmdID,
    BSTR *pcmdText
);

Returns the string associated with a command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdText
Address of a string variable that receives the command text.

See also queryCommandValue


IHTMLTxtRange::queryCommandValue

HRESULT queryCommandValue(
    BSTR cmdID,
    VARIANT *pcmdValue
);

Retrieves the current value of the given command.

  • Returns S_OK if successful, or an error value otherwise.
cmdID
Identifier of a command. Can be any command identifier given in the list of Command Identifiers.
pcmdValue
Address of a variable that receives a string representing the command value. If the command is not supported, this variable receives NULL.

See also queryCommandText


IHTMLTxtRange::scrollIntoView

HRESULT scrollIntoView(
    VARIANT_BOOL fStart
);

Scrolls the range into view, aligning it at either the top or bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
fStart
Boolean value specifying the alignment of the range. TRUE aligns the range at the top of the window; FALSE aligns it at the bottom.

Depending on the size of the given object and the current window, this method might not be able to put the item at the very top or very bottom, but will always position the object as close to the requested position as possible.


IHTMLTxtRange::select

HRESULT select(
    void
);

Makes the active selection equal to the current object.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLTxtRange::setEndPoint

HRESULT setEndPoint(
    BSTR how,
    IHTMLTxtRange *SourceRange
);

Sets the end point of one range based on the end point of another.

  • Returns S_OK if successful, or an error value otherwise.
how
String describing the end points. Can be one of these values:
StartToEnd | Sets the start point of the current range to the end point of the given range.
StartToStart | Sets the start point of the current range to the start point of the given range.
EndToStart | Sets the end point of the current range to the start point of the given range.
EndToEnd | Sets the end point of the current range to the end point of the given range.
SourceRange
Interface pointer of the range object to be used for setting the end point of the current range.

See also compareEndPoints


IHTMLUListElement IHTMLUListElement *
  * Previous Topic: IHTMLTxtRange::setEndPoint
  * Next Topic: IHTMLUListElement::get_compact

IHTMLUListElement

This interface draws lines of text as a bulleted list.

This element is a block element.

IHTMLUListElement Methods


Compact Property

*
  * Previous Topic: IHTMLUListElement
  * Next Topic: IHTMLUListElement::get_type

IHTMLUListElement::get_compact

HRESULT get_compact(
    VARIANT_BOOL *p
);

Determines whether the list is to be compacted to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the list is being compacted, or FALSE otherwise. The default value for this property is FALSE.

See also put_compact

Up Top of Page

IHTMLUListElement::put_compact

HRESULT put_compact(
    VARIANT_BOOL v
);

Specifies whether to compact the list to remove extra space between list elements.

  • Returns S_OK if successful, or an error value otherwise.
v
Compact flag. Set this parameter to TRUE to compact the list, or FALSE otherwise. The default value for this property is FALSE.

See also get_compact


Type Property

*
  * Previous Topic: IHTMLUListElement::get_compact
  * Next Topic: IHTMLUListElement::put_compact

IHTMLUListElement::get_type

HRESULT get_type(
    BSTR *p
);

Retrieves the current style of the list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the style. Can be one of these strings:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also put_type

Up Top of Page

IHTMLUListElement::put_type

HRESULT put_type(
    BSTR v
);

Changes the style of the list.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the list style. Can be one of these strings:
1 | Use numbers. This is the default value.
a | Use small letters.
A | Use large letters.
i | Use small roman numerals.
I | Use large roman numerals.

See also get_type


IHTMLUnknownElement

This interface provides access to the properties, and methods for this object and is equivalent to the IHTMLElement interface. For more information and a listing of the available methods, see the reference section for the IHTMLElement interface.


IHTMLWindow2

This interface provides access to the window object which represents an open window in the browser. You use the window object to retrieve information about the state of the window and to gain access to the document in the window, to the events that occur in the window, and to features of the browser that affect the window.

Typically, the browser creates one window object when it opens an HTML document. However, if a document defines one or more frames (that is, contains one or more FRAME or IFRAME tags), the browser creates one window object for the original document and one additional window object for each frame. These additional objects are child windows of the original window and can be affected by actions that occur in the original. For example, closing the original window causes all child windows to close. You can also create new windows (and corresponding window objects) by using methods such as open and showModalDialog.

IHTMLWindow2 Methods
get_frames put_defaultStatus get_defaultStatus
put_status get_status setTimeout
clearTimeout alert confirm
prompt get_Image get_location
get_history close put_opener
get_opener get_navigator put_name
get_name get_parent open
get_self get_top get_window
navigate put_onfocus get_onfocus
put_onblur get_onblur put_onload
get_onload put_onbeforeunload get_onbeforeunload
put_onunload get_onunload put_onhelp
get_onhelp put_onerror get_onerror
put_onresize get_onresize put_onscroll
get_onscroll get_document get_event
get__newEnum showModalDialog showHelp
get_screen get_Option focus
get_closed blur scroll
get_clientInformation setInterval clearInterval
put_offscreenBuffering get_offscreenBuffering execScript
toString scrollBy scrollTo
moveTo moveBy resizeTo
resizeBy get_external

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IHTMLWindow2::alert

HRESULT alert(
    BSTR message
);

Displays an Alert dialog box with a message and an OK button.

  • Returns S_OK if successful, or an error value otherwise.
message
String specifying the message to display in the dialog box.

The title bar of the Alert dialog box cannot be changed.

See also confirm, prompt


IHTMLWindow2::blur

HRESULT blur(
    void
);

Causes the window to lose focus and fires the onblur event.

  • Returns S_OK if successful, or an error value otherwise.

See also focus


IHTMLWindow2::clearInterval

HRESULT clearInterval(
    long timerID
);

Cancels a repeated evaluation of an expression that was set with the setInterval method.

  • Returns S_OK if successful, or an error value otherwise.
timerID
Specifies a time-out identifier returned by a previous call to the setInterval method.

See also setInterval


IHTMLWindow2::clearTimeout

HRESULT clearTimeout(
    long timerID
);

Cancels a time-out that was set with the setTimeout method.

  • Returns S_OK if successful, or an error value otherwise.
timerID
Specifies a time-out identifier returned by a previous call to the setTimeout method.

See also setTimeout


IHTMLWindow2::close

HRESULT close(
    void
);

Closes the current browser window.

  • Returns S_OK if successful, or an error value otherwise.


IHTMLWindow2::confirm

HRESULT confirm(
    BSTR message,
    VARIANT_BOOL *confirmed
);

Displays a Confirm dialog box with the specified message, and OK and Cancel buttons.

  • Returns S_OK if successful, or an error value otherwise.
message
String specifying the message to display in the dialog box.
confirmed
Address of a variable that receives TRUE if the message is confirmed, or FALSE otherwise.

The title bar of the confirm dialog box cannot be changed.

See also alert, prompt


IHTMLWindow2::execScript

HRESULT execScript(
    BSTR code,
    BSTR language,
    VARIANT *pvarRet
);

Executes the specified script.

  • Returns S_OK if successful, or an error value otherwise.
code
String specifying the script code to execute.
language
String specifying the language in which the code is executed. The default is JScript.
pvarRet
Address of a variable that receives the return value from the script code.


IHTMLWindow2::focus

HRESULT focus(
    void
);

Causes the window to receive the input focus and execute the code, if any, associated with the onfocus event.

  • Returns S_OK if successful, or an error value otherwise.

See also blur


IHTMLWindow2::get__newEnum

HRESULT get__newEnum(
    IUnknown **p
);

Returns an OLE enumeration interface. This will enumerate over the frames collection of this window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to an IUnknown interface.


IHTMLWindow2::get_clientInformation

HRESULT get_clientInformation(
    IOmNavigator **p
);

Retrieves an interface pointer to a navigator object that represents the browser. The object provides information about the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IOmNavigator


IHTMLWindow2::get_closed

HRESULT get_closed(
    VARIANT_BOOL *p
);

Retrieves a value indicating whether the window is closed.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the window is closed, or FALSE otherwise.


DefaultStatus Property

*
  * Previous Topic: IHTMLWindow2::get_closed
  * Next Topic: IHTMLWindow2::get_document

IHTMLWindow2::get_defaultStatus

HRESULT get_defaultStatus(
    BSTR *p
);

Retrieves the default message displayed in the status bar at the bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the default status message.

Do not confuse the defaultStatus property with the status property retrieved by the get_status method. The status property reflects a priority or transient message in the status bar, such as the message that appears when an onmouseover event occurs over an anchor.

See also put_defaultStatus

Up Top of Page

IHTMLWindow2::put_defaultStatus

HRESULT put_defaultStatus(
    BSTR v
);

Sets the default message displayed in the status bar at the bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the status message.

See also get_defaultStatus


IHTMLWindow2::get_document

HRESULT get_document(
    IHTMLDocument2 **p
);

Retrieves an interface pointer to the document object for the document that the browser is displaying.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IHTMLDocument2


IHTMLWindow2::get_event

HRESULT get_event(
    IHTMLEventObj **p
);

Retrieves an interface pointer to the event object that contains information relevant to the most recent event.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IHTMLEventObj


IHTMLWindow2::get_external

HRESULT get_external(
    IDispatch **p
);

Retrieves external access to an additional object model provided by host applications of the Internet Explorer browser components.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

In the Internet Explorer stand-alone browser, no external object model is available. In a hosting scenario where it is available, the object model is defined by the application hosting the Internet Explorer components, and the hosting application should be referred to for documentation. For further details on how to implement extensions to the object model, see the Internet Client SDK documentation on "Reusing the WebBrowser and MSHTML".


IHTMLWindow2::get_frames

HRESULT get_frames(
    IHTMLFramesCollection2 **p
);

Retrieves an interface pointer to a zero-based collection of all the FRAME elements in an HTML document, if the document contains the FRAMESET element. If the document contains the BODY element, this is a collection of all IFRAME elements in the document. In either case, the elements are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be only referenced by ordinal position.


IHTMLWindow2::get_history

HRESULT get_history(
    IOmHistory **p
);

Retrieves an interface pointer to a history object that contains information about all the URLs that the client has visited.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.


IHTMLWindow2::get_Image

HRESULT get_Image(
    IHTMLImageElementFactory **p
);

Returns an IHTMLImageElementFactory pointer that is used to create an offscreen image.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an IHTMLImageElementFactory interface pointer.


IHTMLWindow2::get_location

HRESULT get_location(
    IHTMLLocation **p
);

Retrieves an interface pointer to a location object. The object contains information about the current location (full URL) of the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.


Name Property

*
  * Previous Topic: IHTMLWindow2::get_location
  * Next Topic: IHTMLWindow2::get_navigator

IHTMLWindow2::get_name

HRESULT get_name(
    BSTR *p
);

Retrieves the name of the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the name.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also put_name

Up Top of Page

IHTMLWindow2::put_name

HRESULT put_name(
    BSTR v
);

Sets the name of the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the name.

The name property on the window comes from the FRAME definition. There is no other way to persist a window name in HTML.

See also get_name


IHTMLWindow2::get_navigator

HRESULT get_navigator(
    IOmNavigator **p
);

Retrieves an interface pointer to a navigator object that represents the browser. The object provides information about the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IOmNavigator


OffscreenBuffering Property

*
  * Previous Topic: IHTMLWindow2::get_navigator
  * Next Topic: IHTMLWindow2::get_onbeforeunload

IHTMLWindow2::get_offscreenBuffering

HRESULT get_offscreenBuffering(
    VARIANT *p
);

Determines whether an offscreen buffer is being used.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives a value indicating if a buffer is being used.

See also put_offscreenBuffering

Up Top of Page

IHTMLWindow2::put_offscreenBuffering

HRESULT put_offscreenBuffering(
    VARIANT v
);

Specifies whether to use an offscreen buffer.

  • Returns S_OK if successful, or an error value otherwise.
v
Value specifying whether to use an offscreen buffer.

See also get_offscreenBuffering


Onbeforeunload Property

*
  * Previous Topic: IHTMLWindow2::get_offscreenBuffering
  * Next Topic: IHTMLWindow2::get_onblur

IHTMLWindow2::get_onbeforeunload

HRESULT get_onbeforeunload(
    VARIANT *p
);

Retrieves the inline script associated with the onbeforeunload event before a window element is unloaded. This event is fired before the onunload event. It provides an opportunity to warn the user if the window is currently in an unsaved state and the information will be lost.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

The handler for this event should return NULL if doing the unload is safe, or a text string to prompt the user to decide to cancel or continue with the unload operation. Only the user's response to the warning can stop the new navigation causing the unload; the event handler itself cannot unilaterally block the operation. If the handler returns a non-NULL string, a modal dialog box appears that displays the explanatory string. The dialog box shows three buttons with the message for user action:

  • Continue—the unload operation proceeds.
  • Cancel—the navigation causing the unload is immediately canceled.
  • Help—(strongly recommended)—displays additional explanatory text, such as "This operation may cause existing content information to be lost. Choose Continue if this is OK, or Cancel to retain the information."

In the case of frames, the full sequence of onbeforeunload events are fired on each frame in the same order, depth-first, that onunload events are about to be fired. A dialog box is presented for each event handler that returns a non-NULL string. The first Cancel response stops the potential navigation, in which case no unload occurs. If there is no Cancel response, the unload proceeds and onunload events fire.

See also put_onbeforeunload

Up Top of Page

IHTMLWindow2::put_onbeforeunload

HRESULT put_onbeforeunload(
    VARIANT v
);

Sets the inline script associated with the onbeforeunload event before a window element is unloaded. This event is fired before the onunload event. It provides an opportunity to warn the user if the window is currently in an unsaved state and the information will be lost.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

The handler for this event should return NULL if doing the unload is safe, or a text string to prompt the user to decide to cancel or continue with the unload operation. Only the user's response to the warning can stop the new navigation causing the unload; the event handler itself cannot unilaterally block the operation. If the handler returns a non-NULL string, a modal dialog box appears that displays the explanatory string. The dialog box shows three buttons with the message for user action:

  • Continue—the unload operation proceeds.
  • Cancel—the navigation causing the unload is immediately canceled.
  • Help—(strongly recommended)—displays additional explanatory text, such as "This operation may cause existing content information to be lost. Choose Continue if this is OK, or Cancel to retain the information."

In the case of frames, the full sequence of onbeforeunload events is fired on each frame in the same order, depth-first, that onunload events are about to be fired. A dialog box is presented for each event handler that returns a non-NULL string. The first Cancel response stops the potential navigation, in which case no unload occurs. If there is no Cancel response, the unload proceeds and onunload events fire.

See also get_onbeforeunload


Onblur Property

*
  * Previous Topic: IHTMLWindow2::get_onbeforeunload
  * Next Topic: IHTMLWindow2::get_onerror

IHTMLWindow2::get_onblur

HRESULT get_onblur(
    VARIANT *p
);

Retrieves the inline script associated with the onblur event when the window element loses the focus.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that contains the script.

See also put_onblur

Up Top of Page

IHTMLWindow2::put_onblur

HRESULT put_onblur(
    VARIANT v
);

Sets the inline script associated with the onblur event when the window element loses the focus.

For more information on inline script, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onblur


Onerror Property

*
  * Previous Topic: IHTMLWindow2::get_onblur
  * Next Topic: IHTMLWindow2::get_onfocus

IHTMLWindow2::get_onerror

HRESULT get_onerror(
    VARIANT *p
);

Retrieves the inline script associated with the onerror event on the window element.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
Address of a VARIANT structure that contains the onerror script.

See also put_onerror

Up Top of Page

IHTMLWindow2::put_onerror

HRESULT put_onerror(
    VARIANT v
);

Sets the inline script associated with the onerror event on the window element.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the onerror script to be set.

See also get_onerror


Onfocus Property

*
  * Previous Topic: IHTMLWindow2::get_onerror
  * Next Topic: IHTMLWindow2::get_onhelp

IHTMLWindow2::get_onfocus

HRESULT get_onfocus(
    VARIANT *p
);

Retrieves the inline script associated with the onfocus event on the window element.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the onfocus script.

See also put_onfocus

Up Top of Page

IHTMLWindow2::put_onfocus

HRESULT put_onfocus(
    VARIANT v
);

Sets the inline script associated with the onfocus event on the window element. This script is executed when the window receives focus.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the onfocus script to be set.

See also get_onfocus


Onhelp Property

*
  * Previous Topic: IHTMLWindow2::get_onfocus
  * Next Topic: IHTMLWindow2::get_onload

IHTMLWindow2::get_onhelp

HRESULT get_onhelp(
    VARIANT *p
);

Retrieves the inline script associated with the onhelp event on the window element.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the onhelp script.

This script is executed when the user presses the F1 key or clicks the Help button in the browser. The default action of this event is to display the help information for the browser.

See also put_onhelp

Up Top of Page

IHTMLWindow2::put_onhelp

HRESULT put_onhelp(
    VARIANT v
);

Sets the inline script associated with the onhelp event on the window element. This script is executed when the user presses the F1 key or clicks the help button in the browser.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the onhelp script to be set.

See also get_onhelp


Onload Property

*
  * Previous Topic: IHTMLWindow2::get_onhelp
  * Next Topic: IHTMLWindow2::get_onresize

IHTMLWindow2::get_onload

HRESULT get_onload(
    VARIANT *p
);

Retrieves the inline script that is executed immediately after the browser loads the given object.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onload

Up Top of Page

IHTMLWindow2::put_onload

HRESULT put_onload(
    VARIANT v
);

Sets the inline script associated with the onload event on the window element. This script is executed immediately after the browser loads the given object.

For more information on inline scripts, see Attaching an Event Handler in the Event Model documentation.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the onload script to be set.

See also get_onload


Onresize Property

*
  * Previous Topic: IHTMLWindow2::get_onload
  * Next Topic: IHTMLWindow2::get_onscroll

IHTMLWindow2::get_onresize

HRESULT get_onresize(
    VARIANT *p
);

Retrieves the inline script that is executed when the object is resized.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onresize

Up Top of Page

IHTMLWindow2::put_onresize

HRESULT put_onresize(
    VARIANT v
);

Specifies code to execute whenever the window is resized.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onresize


Onscroll Property

*
  * Previous Topic: IHTMLWindow2::get_onresize
  * Next Topic: IHTMLWindow2::get_onunload

IHTMLWindow2::get_onscroll

HRESULT get_onscroll(
    VARIANT *p
);

Retrieves the inline script that is executed when the scroll box is repositioned. The default action of this event is to scroll.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onscroll

Up Top of Page

IHTMLWindow2::put_onscroll

HRESULT put_onscroll(
    VARIANT v
);

Specifies code to execute when the scroll box is repositioned. The default action of this event is to scroll.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onscroll


Onunload Property

*
  * Previous Topic: IHTMLWindow2::get_onscroll
  * Next Topic: IHTMLWindow2::get_opener

IHTMLWindow2::get_onunload

HRESULT get_onunload(
    VARIANT *p
);

Retrieves the inline script that is executed immediately before the page is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a VARIANT structure that contains the script.

See also put_onunload

Up Top of Page

IHTMLWindow2::put_onunload

HRESULT put_onunload(
    VARIANT v
);

Specifies code to execute immediately before the page is unloaded.

  • Returns S_OK if successful, or an error value otherwise.
v
VARIANT structure that contains the script to be set.

See also get_onunload


Opener Property

*
  * Previous Topic: IHTMLWindow2::get_onunload
  * Next Topic: IHTMLWindow2::get_Option

IHTMLWindow2::get_opener

HRESULT get_opener(
    VARIANT *p
);

Retrieves a reference to the window that created the current window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the reference to the creating window.

See also put_opener

Up Top of Page

IHTMLWindow2::put_opener

HRESULT put_opener(
    VARIANT v
);

Sets a reference to the window that created the current window.

  • Returns S_OK if successful, or an error value otherwise.
v
String or value specifying the reference to the creating window.

See also get_opener


IHTMLWindow2::get_Option

HRESULT get_Option(
    IHTMLOptionElementFactory **p
);

Retrieves an interface pointer to a factory object that you can use to create OPTION elements. You can add the elements to a SELECT block by using the IHTMLSelectElement::add method.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IHTMLOptionElementFactory, IHTMLSelectElement::add


IHTMLWindow2::get_parent

HRESULT get_parent(
    IHTMLWindow2 **p
);

Retrieves an interface pointer to the parent object in the object hierarchy.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable the receives the interface pointer.

In a FRAMESET and FRAME relationship, this function retrieves an object representing the FRAMESET window. On a document, the parent is the window.


IHTMLWindow2::get_screen

HRESULT get_screen(
    IHTMLScreen **p
);

Retrieves an interface pointer to a screen object that provides information about the client's screen and rendering abilities

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

See also IHTMLScreen


IHTMLWindow2::get_self

HRESULT get_self(
    IHTMLWindow2 **p
);

Retrieves an interface pointer to the current window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

Use the self property to disambiguate a window property from a form of the same name.


Status Property

*
  * Previous Topic: IHTMLWindow2::get_self
  * Next Topic: IHTMLWindow2::get_top

IHTMLWindow2::get_status

HRESULT get_status(
    BSTR *p
);

Retrieves the message displayed in the status bar at the bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the status message.

Do not confuse the status property with the defaultStatus property retrieved by the get_defaultStatus method. The status property reflects a priority or transient message in the status bar, such as the message that appears when an onmouseover event occurs over an anchor.

See also put_status

Up Top of Page

IHTMLWindow2::put_status

HRESULT put_status(
    BSTR v
);

Sets the message displayed in the status bar at the bottom of the window.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the status message.

See also get_status


IHTMLWindow2::get_top

HRESULT get_top(
    IHTMLWindow2 **p
);

Retrieves an interface pointer to the topmost ancestor window, which is the current window's own parent.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.


IHTMLWindow2::get_window

HRESULT get_window(
    IHTMLWindow2 **p
);

Retrieves an interface pointer to the current window.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

Use the self property to disambiguate a window property from a form of the same name.


IHTMLWindow2::moveBy IHTMLWindow2::moveBy *
  * Previous Topic: IHTMLWindow2::get_window
  * Next Topic: IHTMLWindow2::moveTo

IHTMLWindow2::moveBy

HRESULT moveBy(
    long x,
    long y
);

Currently not implemented, and has no effect when called.


IHTMLWindow2::moveTo

HRESULT moveTo(
    long x,
    long y
);

Currently not implemented, and has no effect when called.

See also scrollBy


IHTMLWindow2::navigate

HRESULT navigate(
    BSTR url
);

Causes the browser to browse to the location specified by the URL.

  • Returns S_OK if successful, or an error value otherwise.
v
String specifying the URL.

This method performs the same action as the IHTMLLocation::put_href method.


IHTMLWindow2::open

HRESULT open(
    BSTR url,
    BSTR name,
    BSTR features,
    VARIANT_BOOL replace,
    IHTMLWindow2 **pomWindowResult
);

Opens a new Web browser window.

  • Returns S_OK if successful, or an error value otherwise.
url
String specifying the URL of the document to display in the new window.
name
String specifying the name of the new window.
features
String specifying the ornaments to add to the new window. This parameter is a list of items separated by semicolons. Each item consists of an option and a value, separated by a colon (for example, "fullscreen:yes;toolbar:yes"). The following table lists the supported options.

Attribute | Values | Description
fullscreen | yes/no/1/0 | Browser displays in full-screen (true) or normal window (false) mode.
toolbar | yes/no/1/0 | Browser toolbar (Back and Forward buttons, and so on)
location | yes/no/1/0 | Input field for entering URLs directly into the browser.
directories | yes/no/1/0 | Directory buttons.
status | yes/no/1/0 | Status line at bottom of window.
menubar | yes/no/1/0 | Menu bar.
scrollbars | yes/no/1/0 | Horizontal and vertical scroll bars are enabled.
resizable | yes/no/1/0 | Do resize handles appear at the edge.
width | pixel | Width of window; defaults to pixels.
height | pixel | Height of window; defaults to pixels.
top | pixel | Top position, in pixels, in relation to the desktop.
left | pixel | Left position, in pixels, in relation to the desktop.

replace
Replace history flag. If TRUE, the URL that is loaded into the new page replaces the current entry in the window's browsing history. If FALSE, a new entry is created in the window's browsing history.
pomWindowResult
Address of a variable that receives an interface pointer to the new window object.


IHTMLWindow2::prompt

HRESULT prompt(
    BSTR message,
    BSTR defstr,
    VARIANT *textdata
);

Displays a Prompt dialog box with a message, an input field, and OK and Cancel buttons.

  • Returns S_OK if successful, or an error value otherwise.
message
String specifying the message to display in the dialog box.
defstr
String specifying the default value of the input field. If this parameter is NULL, the dialog box displays the value <undefined>.
textdata
Address of a variable that receives the text that the user enters into the input field.

The title bar of the prompt dialog box cannot be changed.

See also alert, confirm


IHTMLWindow2::resizeBy

HRESULT resizeBy(
    long x,
    long y
);

Currently not implemented, and has no effect when called.

See also resizeTo


IHTMLWindow2::resizeTo

HRESULT resizeTo(
    long x,
    long y
);

Currently not implemented, and has no effect when called.

See also resizeBy


IHTMLWindow2::scroll

HRESULT scroll(
    long x,
    long y
);

Scrolls the window to the specified x and y offset relative to the entire document.

  • Returns S_OK if successful, or an error value otherwise.
x
Value specifying the x offset.
y
Value specifying the y offset.


IHTMLWindow2::scrollBy

HRESULT scrollBy(
    long x,
    long y
);

Scrolls the document horizontally by the x value provided, and scrolls the document vertically by the y value provided.

  • Returns S_OK if successful, or an error value otherwise.
x
Long integer that contains the value for the x direction scroll distance.
y
Long integer that contains the value for the y direction scroll distance.

See also scrollTo


IHTMLWindow2::scrollTo

HRESULT scrollTo(
    long x,
    long y
);

Given the area specified as (X,Y) in document coordinates, scrolls the document to that position.

  • Returns S_OK if successful, or an error value otherwise.
x
Long integer that contains the value for the x direction scroll position coordinate.
y
Long integer that contains the value for the y direction scroll position coordinate.


IHTMLWindow2::setInterval

HRESULT setInterval(
    BSTR expression,
    long msec,
    VARIANT *language,
    long *timerID
);

Calls a function repeatedly, or evaluates an expression after a specified number of milliseconds has elapsed.

  • Returns S_OK if successful, or an error value otherwise.
expression
String specifying the code to be executed repeatedly at the specified interval.
msec
Numeric value or numeric string specifying the time-out interval, in milliseconds.
language
String specifying the language that the code is executed in.
timerID
Address of a variable that receives a time-out identifier. This identifier is used only to cancel the evaluation with the clearInterval method.

See also clearInterval


IHTMLWindow2::setTimeout

HRESULT setTimeout(
    BSTR expression,
    long msec,
    VARIANT *language,
    long *timerID
);

Evaluates an expression after a specified number of milliseconds has elapsed.

  • Returns S_OK if successful, or an error value otherwise.
expression
String specifying the code to be executed repeatedly at the specified interval.
msec
Numeric value or numeric string specifying the time-out interval, in milliseconds.
language
String specifying the language that the code is executed in.
timerID
Address of a variable that receives a time-out identifier. This identifier is used only to cancel the evaluation with the clearTimeout method.

See also clearTimeout


IHTMLWindow2::showHelp

HRESULT showHelp(
    BSTR helpURL,
    VARIANT helpArg,
    BSTR features
);

Displays a help file.

  • Returns S_OK if successful, or an error value otherwise.
helpURL
String specifying the URL of the help file.
helpArg
String or value specifying the programmer-defined arguments to pass to the dialog box.
features
Reserved; do not use.


IHTMLWindow2::showModalDialog

HRESULT showModalDialog(
    BSTR dialog,
    VARIANT *varArgIn,
    VARIANT *varOptions,
    VARIANT *varArgOut
);

Displays an HTML dialog box.

  • Returns S_OK if successful, or an error value otherwise.
dialog
String specifying the URL of the dialog box.
varArgIn
Address of a variable that contains programmer-defined arguments to pass into the dialog box.
varOptions
String specifying the attributes of the dialog box. This parameter is a list of items separated by semicolons. Each item consists of an option and a value, separated by a colon (for example, "dialogWidth:200;dialogHeight:100"). The following table lists the supported options.

Attribute | Values | IE3/IE4 | Description
dialogWidth | pixel | IE3/IE4 | Sets the width of the window, in pixels.
dialogHeight | pixel | IE3/IE4 | Sets the height of the window, in pixels.
dialogTop | pixel | IE3/IE4 | Sets the top position of the window, in pixels, relative to the desktop.
dialogLeft | pixel | IE3/IE4 | Sets the left position of the window, in pixels, relative to the desktop.
center | yes/no/1/0 | Not yet implemented in IE4. | Centered relative to the desktop.
font | font-family | Not yet implemented in IE4.
font-size | Not yet implemented in IE4.
font-weight | Not yet implemented in IE4.
font-style | Not yet implemented in IE4. | Describes the font and font attributes. The syntax should look like CSS. For example, font:3;font-size:4. To define multiple font values, use multiple font attributes.
edgeStyle | raised/sunken | Not yet implemented in IE4. | Sets the style of the window border.
borderSize | thick/thin | Not yet implemented in IE4. | Sets the thickness of the window border.
help | yes/no/1/0 | Not yet implemented in IE4. | Determines whether the help icon appears in the title bar
min | yes/no/1/0 | Not yet implemented in IE4. | Determines whether the minimize button appears in the title bar.
max | yes/no/1/0 | Not yet implemented in IE4. | Determines whether the maximize button appears in the title bar.
system menu | yes/no/1/0 | Not yet implemented in IE4. | Determines whether the system menu is available from the border icon.
sync | yes/no/1/0 | Not yet implemented in IE4.

varArgOut
Address of a variable that receives a return value from the dialog box. For more information, see IHTMLDialog::put_returnValue and IHTMLDialog::get_returnValue.


IHTMLWindow2::toString

HRESULT toString(
    BSTR *String
);

Retrieves a string representation of the window object.

  • Returns S_OK if successful, or an error value otherwise.
String
Address of a variable that receives the string representation.


IOmHistory

This interface provides the ability to access the history object for the client. The history object contains information on the URLs that the client has visited.

IOmHistory Methods


IOmHistory::back

HRESULT back(
    VARIANT *pvargdistance
);

Loads the previous URL in the History list.

  • Returns S_OK if successful, or an error value otherwise.
pvargdistance
Address of a VARIANT structure that contains the script.

This method performs the same action as a user clicking the Back button in the browser. Trying to go past the beginning of the history does not generate an error. Instead, the browser remains at the current page.

See also forward


IOmHistory::forward

HRESULT forward(
    VARIANT *pvargdistance
);

Loads the next URL in the History list.

  • Returns S_OK if successful, or an error value otherwise.
pvargdistance
Address of a VARIANT structure that contains the script.

This method performs the same action as a user clicking the Forward button in the browser. Trying to go past the end of the history does not generate an error. Instead, the browser remains at the current page.

See also back


IOmHistory::get_length

HRESULT get_length(
    short *p
);

Retrieves the number of elements in the History list.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the number of items.


IOmHistory::go

HRESULT go(
    VARIANT *pvargdistance
);

Loads a URL in the History list.

  • Returns S_OK if successful, or an error value otherwise.
pvargdistance
Address of a VARIANT structure that contains the script.

Trying to go past the beginning or end of the history does not generate an error. Instead, the browser remains at the current page.


IOmNavigator

This interface provides access to an object that contains information about the browser.

IOmNavigator Methods
get_appCodeName get_appName get_appVersion
get_userAgent javaEnabled taintEnabled
get_mimeTypes get_plugins get_cookieEnabled
get_opsProfile toString get_cpuClass
get_systemLanguage get_browserLanguage get_userLanguage
get_platform get_appMinorVersion get_connectionSpeed
get_onLine get_userProfile

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


IOmNavigator::get_appCodeName

HRESULT get_appCodeName(
    BSTR *p
);

Retrieves the code name of the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the code name.


IOmNavigator::get_appMinorVersion

HRESULT get_appMinorVersion(
    BSTR *p
);

Returns a string of the minor version number of the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the minor version number.


IOmNavigator::get_appName

HRESULT get_appName(
    BSTR *p
);

Retrieves the application name of the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the application name.


IOmNavigator::get_appVersion

HRESULT get_appVersion(
    BSTR *p
);

Retrieves the version of the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the version information.


IOmNavigator::get_browserLanguage

HRESULT get_browserLanguage(
    BSTR *p
);

Currently not implemented.


*
  * Previous Topic: IOmNavigator::get_browserLanguage
  * Next Topic: IOmNavigator::get_cookieEnabled

IOmNavigator::get_connectionSpeed

HRESULT get_connectionSpeed(
    long *p
);

Currently not implemented.


IOmNavigator::get_cookieEnabled

HRESULT get_cookieEnabled(
    VARIANT_BOOL *p
);

Determines whether client-side cookies are enabled in the browser.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if client-side cookies are enabled, or FALSE otherwise.


IOmNavigator::get_cpuClass

HRESULT get_cpuClass(
    BSTR *p
);

Returns a string of the CPU class (for example, "x86", "Alpha", "Other").

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the cpuClass value.


IOmNavigator::get_mimeTypes

HRESULT get_mimeTypes(
    IHTMLMimeTypesCollection **p
);

Retrieves an empty collection for Internet Explorer 4.0. This property exists for compatibility with other browsers.

  • Returns S_OK if successful, or an error value otherwise.
enabled
Address of a variable that receives an interface pointer for the collection.

See also IHTMLMimeTypesCollection


IOmNavigator::get_onLine

HRESULT get_onLine(
    VARIANT_BOOL *p
);

Returns a Boolean indicating whether the browser is running online or offline.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives TRUE if the browser is running online, or FALSE otherwise.


IOmNavigator::get_platform

HRESULT get_platform(
    BSTR *p
);

Returns a string indicating which platform the browser is currently running on (for example, "Win32", "Win16", "WinCE", and so on).

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the operating platform type.


IOmNavigator::get_opsProfile

HRESULT get_opsProfile(
    IHTMLOpsProfile **p
);

Returns an IHTMLOpsProfile interface pointer.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives an interface pointer to the IHTMLOpsProfile object.

The IHTMLOpsProfile element is a profile object that stores various types of information about the user. This information is taken from the Address Book.


IOmNavigator::get_plugins

HRESULT get_plugins(
    IHTMLPluginsCollection **p
);

Retrieves an interface pointer to a zero-based collection of all the EMBED elements in an HTML document. The elements are in the same order as they appear in the document.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a variable that receives the interface pointer.

The collection is indexed first by name, then by ID. If duplicate names are found, a collection of those named items is returned. The resulting collection can be referenced only by ordinal position.

See also IHTMLPluginsCollection


IOmNavigator::get_systemLanguage

HRESULT get_systemLanguage(
    BSTR *p
);

Returns a string of the default language the system is running with.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the system language information.


IOmNavigator::get_userAgent

HRESULT get_userAgent(
    BSTR *p
);

Retrieves a string that represents the user-agent header sent in the HTTP protocol from the client to the server.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the user-agent header.


IOmNavigator::get_userLanguage

HRESULT get_userLanguage(
    BSTR *p
);

Returns a string indicating the language that the user is running by default.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a string variable that receives the user language.


IOmNavigator::get_userProfile

HRESULT get_userProfile(
    IHTMLOpsProfile **p
);

Alias for the IHTMLOpsProfile interface.

  • Returns S_OK if successful, or an error value otherwise.
p
Address of a pointer to the IHTMLOpsProfile interface element.

The IHTMLOpsProfile element is a profile object that stores various types of information about the user. This information is taken from the Address Book.


IOmNavigator::javaEnabled

HRESULT javaEnabled(
    VARIANT_BOOL *enabled
);

Returns whether Java is enabled.

  • Returns S_OK if successful, or an error value otherwise.
enabled
Address of a variable that receives TRUE if Java is enabled, or FALSE otherwise.


IOmNavigator::taintEnabled

HRESULT taintEnabled(
    VARIANT_BOOL *enabled
);

Determines whether data tainting is enabled.

  • Returns S_OK if successful, or an error value otherwise.
enabled
Address of a variable that receives TRUE if data tainting is enabled, or FALSE otherwise.

This method always returns FALSE for Internet Explorer 4.0. Data tainting is not supported.


IOmNavigator::toString

HRESULT toString(
    BSTR *string
);

Returns a string representation of the navigation object.

  • Returns S_OK if successful, or an error value otherwise.
string
Address of a string variable that represents the navigation object.


Interfaces and Scripting Objects

The following table lists the C/C++ object model interfaces, and identifies which scripting objects most closely match these interfaces.
Interface | Object
ICSSFilter | No matching object.
ICSSFilterSite | No matching object.
IHTMLAnchorElement A
IHTMLAreaElement AREA
IHTMLAreasCollection areas
IHTMLBaseElement BASE
IHTMLBaseFontElement BASEFONT
IHTMLBGsound BGSOUND
IHTMLBlockElement | No matching object.
IHTMLBodyElement BODY
IHTMLBRElement BR
IHTMLButtonElement BUTTON
IHTMLCommentElement COMMENT
IHTMLControlElement | No matching object.
IHTMLControlRange | No matching object.
IHTMLDatabinding | No matching object.
IHTMLDDElement DD
IHTMLDialog window
IHTMLDivElement DIV
IHTMLDivPosition | No matching object.
IHTMLDListElement DL
IHTMLDocument document
IHTMLDocument2 document
IHTMLDTElement DT
IHTMLElement | All element objects.
IHTMLElementCollection elements
IHTMLEmbedElement | No matching object.
IHTMLEventObj event
IHTMLFieldSetElement FIELDSET
IHTMLFiltersCollection filters
IHTMLFontElement FONT
IHTMLFontNamesCollection | No matching object.
IHTMLFontSizesCollection | No matching object.
IHTMLFormElement FORM
IHTMLFrameBase | No matching object.
IHTMLFrameElement FRAME
IHTMLFramesCollection2 frames
IHTMLFrameSetElement FRAMESET
IHTMLHeaderElement | H1 through H6
IHTMLHRElement HR
IHTMLIFrameElement IFRAME
IHTMLImageElementFactory | No matching object.
IHTMLImgElement | Common properties of IMG and INPUT of type image
IHTMLInputButtonElement | INPUT of type reset or submit
IHTMLInputFileElement | INPUT of type file
IHTMLInputHiddenElement | INPUT of type hidden
IHTMLInputImage | INPUT of type image
IHTMLInputTextElement | INPUT of type text
IHTMLIsIndexElement ISINDEX
IHTMLLabelElement LABEL
IHTMLLegendElement LEGEND
IHTMLLIElement LI
IHTMLLinkElement LINK
IHTMLListElement | Common properties of OL and UL
IHTMLLocation location
IHTMLMapElement MAP
IHTMLMarqueeElement MARQUEE
IHTMLMetaElement META
IHTMLMimeTypesCollection | No matching object.
IHTMLNextIdElement NEXTID
IHTMLNoShowElement | No matching object.
IHTMLObjectElement OBJECT
IHTMLOListElement OL
IHTMLOpsProfile userProfile
IHTMLOptionButtonElement | INPUT of type radio
IHTMLOptionElement OPTION
IHTMLOptionElementFactory | No matching object.
IHTMLOptionsHolder | No matching object.
IHTMLParaElement P
IHTMLPhraseElement | No matching object.
IHTMLPluginsCollection EMBED
IHTMLRuleStyle style
IHTMLScreen screen
IHTMLScriptElement SCRIPT
IHTMLSelectElement SELECT
IHTMLSelectionObject selection
IHTMLSpanFlow SPAN
IHTMLStyle style
IHTMLStyleElement STYLE
IHTMLStyleSheet styleSheet
IHTMLStyleSheetRule styleSheet
IHTMLStyleSheetRulesCollection styleSheets
IHTMLStyleSheetsCollection styleSheets
IHTMLTable TABLE
IHTMLTableCaption CAPTION
IHTMLTableCell | TD and TH
IHTMLTableCol | COL and COLGROUP
IHTMLTableRow TR
IHTMLTableSection | TBODY, THEAD, and TFOOT
IHTMLTextAreaElement TEXTAREA
IHTMLTextContainer | No matching object.
IHTMLTextElement | No matching object.
IHTMLTitleElement TITLE
IHTMLTxtRange TextRange
IHTMLUListElement UL
IHTMLUnknownElement | No matching object.
IHTMLWindow2 window
IOmHistory history
IOmNavigator navigator

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


Reusing the WebBrowser and MSHTML

This document describes how to reuse the WebBrowser Control and MSHTML.DLL components of Internet Explorer 4.0 as part of an application. Typical examples of such reuse include browsers, rich content viewers, HTML parsers, and HTML dialogs.

Overview

HTML Dialog Boxes

Reusing the WebBrowser Control

Reusing MSHTML

Advanced Hosting Interfaces

Dependencies

Licensing and Distribution


Overview

This document explains the architecture of Microsoft® Internet Explorer 4.0. The document also provides information you'll find helpful when reusing these components.

Architectural Overview

Choosing the Correct Component For Reuse

Providing Extra Control

Controlling the Context Menus

Extending the Dynamic HTML Object Model

Download Control

Security Manager

Architectural Overview

Internet Explorer 4.0 uses ActiveX™ Controls and Active Document interfaces to connect components. The following diagram provides a high-level overview.

Internet Explorer 4.0 Architecture.

At the top level is IExplore.exe, a surprisingly small application that is instantiated when the Internet Explorer 4.0 browser is loaded. This executable uses Internet Explorer 4.0 components to perform the navigation, history maintenance, favorites maintenance, HTML parsing and rendering, and so on, while it supplies the toolbar and frame for the stand-alone browser. This executable directly hosts the Shdocvw.dll component.

Shdocvw.dll in turn hosts the Mshtml.dll component, as well as any other Active Document component (such as a Microsoft® Office application) that can be loaded in-place in the browser when the user navigates to a specific document type. Shdocvw.dll supplies the functionality associated with navigation, in-place linking, favorites and history management, and PICS support. This DLL also exposes interfaces to its host to allow it to be hosted separately as an ActiveX control. The Shdocvw.dll component is more frequently referred to as the WebBrowser control. In-place linking refers to the ability to click a link in the HTML of the loaded document and load a new HTML document in the same instance of the WebBrowser control. If only Mshtml.dll is being hosted, a click on the link will result in a new instance of the browser being instantiated.

Mshtml.dll is the component that performs the HTML parsing and rendering in Internet Explorer 4.0, and also exposes the HTML document through the Dynamic HTML object model. This component hosts the scripting engines, Java VM, ActiveX Controls, Plug-Ins, and other objects that might be referenced in the HTML document that is loaded. Mshtml.dll implements the Active Document server interfaces, which allows it to be hosted using standard COM interfaces.

This architecture is recursive in that Shdocvw.dll is in turn hosted by Mshtml.dll in a frameset situation. In this case, each instance of a frame is another instance of Shdocvw.dll hosting Mshtml.dll.

As this is an OLE-based architecture, the ambient properties that are commonly used by ActiveX Controls can also be applied to the Internet Explorer 4.0 components. In this way, a host of the WebBrowser control can set an ambient property that will filter down to all the frames and controls hosted in the loaded document.

Choosing the Correct Component for Reuse

Because the WebBrowser control provides a rich set of functionality that a host will typically require, such as that for in-place linking, it is much more applicable for most applications to host this control instead of MSHTML for browsing or viewing HTML documents. Hosting MSHTML is recommended only for specialized applications, such as parsing HTML. The WalkAll sample in the Internet Client SDK demonstrates how to host MSHTML.

It should also be noted that although hosting MSHTML is slightly more lightweight than hosting the WebBrowser control, the savings rarely justify the extra work involved in implementing functionality that is already available in the WebBrowser. It is very likely that the WebBrowser will already be loaded in memory, and navigating to a frameset page will also result in the WebBrowser being loaded as part of the standard working set.

Providing Extra Control

Hosts of the WebBrowser and MSHTML components have control over certain functionality. In the case of the WebBrowser control, this includes navigation as well as receiving events when the document is loaded. Hosts of either component can obtain extra control over functionality by implementing the IDocHostUIHandler and IDocHostShowUI interfaces. A common use for these interfaces is overriding the context menus that are supplied by default for the browser (this topic is discussed separately below). Uses also include setting the 3-D border, overriding the location in the registry where options are stored, and extending the Dynamic HTML object mModel.

These interfaces are obtained from the host by the component calling QueryInterface on the IOleClientSite interface implemented by the hosting application.

Controlling the Context Menus

A common requirement of hosting the WebBrowser control is the ability to override or add to the context menus that are displayed as the result of a right-click in the browser window. This is of particular interest to applications that are using the WebBrowser control to view rich content but do not want the user to know that HTML is being viewed. This is also advantageous for applications that do not want the user to be able to view the HTML source for the content.

There are two techniques available to achieve this. The first involves the use of the IDocHostUIHandler interface and allows an application to disable or replace the context menus. The second technique involves the use of the registry and allows the existing context menus to be extended.

Overriding the context menus

The WebBrowser control's context menus can be overridden entirely by implementing the IDocHostUIHandler::ShowContextMenu method. Returning E_NOTIMPL or S_FALSE from this method will indicate to the WebBrowser that it should display its own standard context menu. However, returning S_OK will cause the WebBrowser not to display its menus, and it will assume that the host has performed the appropriate action. The host can disable all context menus or bring up its own context menus. The parameters supplied to the host that implements this method allow the host to identify which of the default menus will be displayed by the WebBrowser, as well as the coordinates where the menu will be displayed. This provides the host the full context for the menu. For example, the host can choose only to override the image context menus and not the standard context menus.

Adding to the standard context menus

Items can be added to the existing context menus of the WebBrowser by placing entries in the registry and linking these to URLs that execute script. To add additional items to the standard WebBrowser context menus, create or open the following key:

HKEY_CURRENT_USER
        Software
            Microsoft
                Internet Explorer
                    MenuExt

Under this key, you create a key whose name contains the text you want displayed in the menu. The default value for this key contains the URL that will be executed. The key name can include the ampersand (&) character, which will cause the character immediately following the & to be underlined. The URL will be loaded inside a hidden HTML dialog box, all the inline script will be executed, and the dialog box will be closed. The hidden HTML dialog's external.menuArguments property contains the window object of the window on which the context menu item was executed.

The following registry entry will add an item with the title "My Menu Item" to the WebBrowser context menu and will execute the inline script contained in the file "c:\myscript.htm".

HKEY_CURRENT_USER
        Software
            Microsoft
                Internet Explorer
                    MenuExt
                        My Menu Item = "file://c:\myscript.htm"

The following are the contents of "c:\myscript.htm".

<SCRIPT LANGUAGE="JavaScript" defer>
    var parentwin = external.menuArguments;
    var doc = parentwin.document;
    var sel = doc.selection;
    var rng = sel.createRange();
    var str = new String(rng.text);
    if(str.length == 0)
        rng.text = "MY INSERTED TEXT";
    else
        rng.text =  str.toUpperCase();
    </SCRIPT>

This script obtains the parent window object from external.menuArguments. The parent window object is the WebBrowser in which the context menu item was executed. The script then obtains the current selection and, if no selection is present, inserts the text "MY INSERTED TEXT" at the point where the context menu was executed. If there is a selection present, the selected text is changed to uppercase.

Optional keys

Under the item registry key created earlier, there are a couple of optional values. One of these specifies on which context menus this item will appear. The other specifies that the script should be run as a dialog.

The "Contexts" DWORD value specifies the context menus in which an item will appear. It is a bit mask consisting of the logical OR of the following values (defined in Mshtmhst.h). These values correspond to the constant passed in an IDocHostUIHandler::ShowContextMenu call.

(0x1 << CONTEXT_MENU_DEFAULT) (evaluates to 0x1)
(0x1 << CONTEXT_MENU_IMAGE) (evaluates to 0x2)
(0x1 << CONTEXT_MENU_CONTROL) (evaluates to 0x4)
(0x1 << CONTEXT_MENU_TABLE) (evaluates to 0x8)
(0x1 << CONTEXT_MENU_TEXTSELECT) (evaluates to 0x10)
(0x1 << CONTEXT_MENU_ANCHOR) (evaluates to 0x20)
(0x1 << CONTEXT_MENU_UNKNOWN) (evaluates to 0x40)

So if, for example, you want this simple extension to appear only in the default menu and the text selection menu, you could create a DWORD value in the registry under the "My Menu Item" key called "Contexts" and set it to 0x11. From C/C++ code, this can be expressed as:

(0x1 << CONTEXT_MENU_DEFAULT) | (0x1 << CONTEXT_MENU_TEXTSELECT)

The other optional registry DWORD value is "Flags". There is only one bit (0x1) valid for this registry value; it is defined as MENUEXT_SHOWDIALOG in Mshtmhst.h. When this bit is set, the script is run just as if it had been called through the showModalDialog method. The window that runs the script is not hidden, and the dialog box is not automatically closed after inline and onload script finishes. The external.menuArguments value still contains the window object where the user selected the menu item.

The context menu event

Whenever a context menu extension is triggered, the event object off the main window (external.menuArguments.event) contains information about where the user clicked and which context menu was shown. The mouse coordinates are valid along with event.srcElement. The event.type value contains one of the following strings, indicating which context menu was shown to the user.

MenuExtDefault
MenuExtImage
MenuExtControl
MenuExtTable
MenuExtTextSelect
MenuExtAnchor
MenuExtUnknown

Another example

This example creates a new context menu item on the default menu. This item, called "Show in New Window", will start whatever is clicked on in a new window. So if something is deeply nested in a frameset, you can easily launch a specific frame in its own window.

Here are the contents of a .reg file that can be run to insert the correct registry settings. Call this Example2.reg. Double-clicking this file in Explorer will insert the settings in your registry.

REGEDIT4

    [HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\MenuExt\Show in &New Window]
    @="file://c:\\example2.htm"
    "Contexts"=dword:00000001

Here are the contents of "C:\example2.htm":

<SCRIPT LANGUAGE="JavaScript" defer>
        open(external.menuArguments.location.href);
    </SCRIPT>

Extending the Dynamic HTML Object Model

It is possible for the hosting application to extend the Dynamic HTML object model so that scripts can refer to functionality implemented by the host. Such scripts refer to the host by specifying the "external" object that is available from the "window" object. For example, a reference to "window.external.speech" will call the host to resolve the name "speech". All standard script within the document will be executed normally.

This extension mechanism is implemented in the host by providing an IDispatch interface for the object model extension that will have GetIDsofNames and Invoke called on it to resolve any references to the external object. The IDispatch that the host provides is obtained by the WebBrowser or MSHTML component by calling the host's IDocHostUIHandler::GetExternal method.

For an example of how to extend the Dynamic HTML object model, see the Driller sample in the Internet Client SDK.

Download Control

Hosts can control certain aspects of downloading, such as frames, images, Java, and so on, by implementing an ambient property defined as DISPID_AMBIENT_DLCTL. When the host's IDispatch::Invoke method is called with dispidMember set to DISPID_AMBIENT_DLCTL, it should place zero or a combination of the following values in pvarResult:

DLCTL_DLIMAGES | The browsing component will download images from the server.
DLCTL_VIDEOS | The browsing component will play any video clips that are contained in the document.
DLCTL_BGSOUNDS | The browsing component will play background sounds associated with the document.
DLCTL_NO_SCRIPTS | The browsing component will not execute any scripts.
DLCTL_NO_JAVA | The browsing component will not execute any Java applets.
DLCTL_NO_RUNACTIVEXCTLS | The browsing component will not execute any ActiveX Controls in the document.
DLCTL_NO_DLACTIVEXCTLS | The browsing component will not download any ActiveX Controls in the document.
DLCTL_DOWNLOADONLY | The browsing component will download the page but not display it.
DLCTL_NO_FRAMEDOWNLOAD | The browsing component will not download frames but will download and parse the frameset page. The browsing component will also ignore the frameset and render no frame tags.
DLCTL_RESYNCHRONIZE | The browsing component will ignore what is in the cache and ask the server for updated information. The cached information will be used if the server indicates that the cached information is up to date. This causes the BINDF_RESYNCHRONIZE flag to be set when making requests through URLMON.
DLCTL_PRAGMA_NO_CACHE | The browsing component will force the request through to the server and ignore the proxy, even if the proxy indicates that the data is up to date. This causes the BINDF_PRAGMA_NO_CACHE flag to be set when making requests through URLMON.
DLCTL_FORCEOFFLINE | The browsing component will always operate in offline mode. This causes the BINDF_OFFLINEOPERATION flag to be set even if the computer is connected to the Internet when making requests through URLMON.
DLCTL_NO_CLIENTPULL | The browsing component will not perform any client pull operations.
DLCTL_SILENT | The browsing component will not display any user interface. This causes the BINDF_SILENTOPERATION flag to be set when making requests through URLMON.
DLCTL_OFFLINEIFNOTCONNECTED | The browsing component will operate in offline mode if not connected to the Internet. This causes the BINDF_GETFROMCACHE_IF_NET_FAIL flag to be set if the computer is connected to the Internet when making requests through URLMON.
DLCTL_OFFLINE | Same as DLCTL_OFFLINEIFNOTCONNECTED.

Security Manager

Hosts of the browsing components can implement their own security management and override the settings that exist for the WebBrowser. This is achieved by implementing the IInternetSecurityManager interface. The browsing component will obtain this interface by calling the host's IServiceProvider::QueryService method with SID_SInternetSecurityManager. For more information on security management, see About URL Security Zones.


HTML Dialog Boxes

IE4/MSHTML allows you to create a modal dialog box that displays HTML. This is accomplished using the ShowHTMLDialog function that is implemented in Mshtml.dll.

Using ShowHTMLDialog

Creating an HTML Resource

Using ShowHTMLDialog

To use ShowHTMLDialog, it is necessary to dynamically load and then call this function by using the LoadLibrary and GetProcAddress functions. The SHOWHTMLDIALOGFN type is defined in Mshtmhst.h to define the proper function type for ShowHTMLDialog. The HTMLDlg sample in the Internet Client SDK shows a complete example using ShowHTMLDialog, including how to pass data to and receive data from the dialog. The following example shows how to obtain the address of the ShowHTMLDialog function:

#include <windows.h>
#include <mshtmhst.h>

{
HINSTANCE   hinstMSHTML = LoadLibrary(TEXT("MSHTML.DLL"));

if(hinstMSHTML)
   {
   SHOWHTMLDIALOGFN  *pfnShowHTMLDialog;

   pfnShowHTMLDialog = (SHOWHTMLDIALOGFN*)GetProcAddress(hinstMSHTML, TEXT("ShowHTMLDialog"));

   if(pfnShowHTMLDialog)
      {
      /*
      Perform initialization and then call ShowHTMLDialog.
      */
      }

   FreeLibrary(hinstMSHTML);
   }
}

The HTML for the dialog box is loaded from an IMoniker interface that is passed in the pmk parameter in ShowHTMLDialog. This moniker can be any moniker that evaluates to any HTML source or to a resource that uses the res: protocol. The CreateURLMoniker function can be used to create the IMoniker interface that is passed to ShowHTMLDialog.

The input parameters for the dialog box are passed in the pvaArgIn parameter in ShowHTMLDialog. The input parameters can be any information that can be passed in a VARIANT structure. In the dialog box HTML source, the input parameters are obtained from the dialogArguments property of the window object.

The output parameters for the dialog box are returned in the pvaArgOut parameter in ShowHTMLDialog. This is a VARIANT structure that you allocate. This structure must be initialized using the VariantInit function before calling ShowHTMLDialog. In the dialog box HTML source, the output parameters are set using the returnValue property of the window object.


SHOWHTMLDIALOGFN

typedef HRESULT STDAPICALLTYPE SHOWHTMLDIALOGFN(
    HWND hwndParent,
    IMoniker *pmk,
    VARIANT *pvarArgIn,
    TCHAR* pchOptions,
    VARIANT *pvarArgOut
);

Defines the function type for ShowHTMLDialog. This function creates a modal dialog box that contains HTML. The function does not return until the dialog box has been dismissed. The address of this function must be obtained by loading Mshtml.dll with LoadLibrary and then getting the address of ShowHTMLDialog with GetProcAddress.

hwndParent
Handle to the window that will be the owner of the dialog box. This window will be disabled for the life of the dialog box. If this value is NULL, the dialog box is not owned.
pmk
Address of an IMoniker interface that identifies the source of the HTML that will be contained in the dialog box.
pvarArgIn
Address of a VARIANT that contains the input data for the dialog box. The data passed in this VARIANT is placed in the window object's dialogArguments property. This parameter can be NULL.
pchOptions
Window ornaments for the dialog box. This parameter can be NULL or the address of a string that contains a combination of values, each separated by a ';'. See the description of the features parameter of the showModalDialog method of the window object for detailed information.
pvarArgOut
Address of a VARIANT that contains the output data for the dialog box. This VARIANT receives the data that was placed in the window object's returnValue property. This parameter can be NULL.


Creating an HTML Resource

Rather than distribute separate HTML files for your application's use, you can add the raw HTML to your application as a resource. You can then retrieve the HTML from your application when it is needed. ShowHTMLDialog is one example of how HTML can be used from a resource by using the res: protocol.

To add the HTML as a resource, you include a file that contains nothing but the actual HTML in your application's resource script. This file is included as an HTML type resource. The following example shows how to include a file called MyHTML.htm as an HTML resource.

HTML_RESOURCE HTML "MyHTML.htm"

In this example, "HTML_RESOURCE" is the identifier of the resource. This can be either a string or a numerical identifier. "HTML" is the resource type. Visual C++ 5.0 will interpret this as the numeric value 23 and will substitute 23 for "HTML" when the resource file is opened for editing. "MyHTML.htm" is the file that contains the HTML source that will be added. The resource compiler adds this file as is and will not attempt to interpret the contents of the file.

You can specify the HTML resource in any function that will accept a res: protocol. ShowHTMLDialog is one example of how HTML can be used from a resource by using the res: protocol. You can also use FindResource and LoadResource to obtain the HTML resource. In FindResource, specify the RT_HTML value for lpType to find an HTML resource.


Reusing the WebBrowser Control

The WebBrowser control adds browsing, document viewing, and data downloading capabilities to your applications. Applications using this control will allow the user to browse sites on the Internet's World Wide Web, as well as folders in the local file system and on a network. The WebBrowser control supports Web browsing through both point-and-click hyperlinking and Uniform Resource Locator (URL) navigation. The control maintains a history list that allows the user to browse forward and backward through previously browsed sites, folders, and documents.

The actual parsing and rendering of the HTML documents in the WebBrowser control is handled by the Mshtml.dll component of Microsoft® Internet Explorer 4.0. The MSHTML component is an Active Document (also known as an OLE document object) that provides support for parsing and rendering with the Dynamic HTML object model, as well as for hosting ActiveX™ Controls and scripts. The WebBrowser control directly handles the navigation, hyperlinking, history lists, favorites, and security. Applications can also use the WebBrowser control as an Active Document container to host other Active Documents. This means that richly formatted documents, such as a Microsoft® Excel spreadsheet or Microsoft® Word document, can be opened and edited in-place from within the WebBrowser control. WebBrowser is also an ActiveX Control container that can host any ActiveX Control.

Updates in Internet Explorer 4.0

Using the WebBrowser Control from Visual Basic

Using the WebBrowser Control from C/C++

Reference for Visual Basic Developers

Reference for C/C++ Developers

Updates in Internet Explorer 4.0

For Internet Explorer 4.0, the following new properties, methods, and events have been added:
Visual Basic | C/C++ | Type | Description
AddressBar | get_AddressBar | property | Indicates whether the URL address bar is shown.
Offline | get_Offline | property | Determines if the browser is in offline mode.
ReadyState | get_ReadyState | property | Returns the OLE ReadyState bindable object.
RegisterAsBrowser | get_RegisterAsBrowser | property | Indicates whether the WebBrowser control is registered as a top-level browser.
RegisterAsDropTarget | get_RegisterAsDropTarget | property | Indicates whether the WebBrowser control is registered as a drop target.
Resizable | get_Resizable | property | Indicates whether the Internet Explorer object can be resized.
Silent | get_Silent | property | Indicates whether dialog boxes can be shown.
TheaterMode | get_TheaterMode | property | Indicates whether the browser is in "Theater Mode" or a normal browser window.
ExecWB | ExecWB | method | Executes an IOLECommandTarget interface command.
Navigate2 | Navigate2 | method | Navigates the WebBrowser control to a URL.
QueryStatusWB | QueryStatusWB | method | Returns the status of commands using the IOLECommandTarget interface.
ShowBrowserBar | ShowBrowserBar | method | Shows or hides a browser bar.
BeforeNavigate2 | BeforeNavigate2 | event | Occurs before the WebBrowser control navigates to a new URL. (replaces BeforeNavigate and FrameBeforeNavigate)
DocumentComplete | DocumentComplete | event | Occurs when the ReadyState property is changed to READYSTATE_COMPLETE.
NavigateComplete2 | NavigateComplete2 | event | Occurs after the WebBrowser control navigates to a new URL (replaces NavigateComplete and FrameNavigateComplete).
NewWindow2 | NewWindow2 | event | Occurs when navigation occurs with the navOpenInNewWindow flag (replaces NewWindow and FrameNewWindow).
OnFullScreen | OnFullScreen | event | Occurs when the FullScreen property changes.
OnMenuBar | OnMenuBar | event | Occurs when the MenuBarproperty changes.
OnQuit | OnQuit | event | Occurs before the Internet Explorer application quits.
OnStatusBar | OnStatusBar | event | Occurs when the StatusBar property changes.
OnTheaterMode | OnTheaterMode | event | Occurs when the TheaterMode property changes.
OnToolBar | OnToolBar | event | Occurs when the ToolBar property changes.
OnVisible | OnVisible | event | Occurs when the Visible property changes.

Internet Explorer 3.0 Compatibility

The new WebBrowser_V1 object is now included with the WebBrowser control. This object supports the set of properties, methods, and events that exist in Internet Explorer 3.0. You can use the WebBrowser_V1 object in a Visual Basic project to run on computers with either Internet Explorer 3.0 or 4.0 installed. The WebBrowser object requires Internet Explorer 4.0 to access the new properties, methods, and events listed above.

Using the WebBrowser Control from Visual Basic

The WebBrowser control supports properties, methods, and events that allow developers to create a highly customized Web browser with the WebBrowser object. Companies may want to use the WebBrowser control to create a Web browsing application that restricts navigation to a local intranet and company-approved public Web sites.

An application can also create and manipulate an instance of the Internet Explorer application through OLE Automation with the InternetExplorer object. In this context, additional properties and methods not supported by the WebBrowser object are available. These additional features are indicated in the Applies To list for the InternetExplorer object only. If these features are used with the WebBrowser object, error codes will be returned. Errors can be trapped in Visual Basic with the "On Error Resume Next" statement and by accessing the Err object's associated properties such as Err.Number and Err.Description.

To implement the InternetExplorer object in a Visual Basic application, declare the object as indicated in the Application property description. To use the WebBrowser object, simply add the "Microsoft Internet Controls" to your Visual Basic project and place the WebBrowser control on a Visual Basic form. This is accomplished by selecting the "Components..." item on the Project menu in Visual Basic 5.0, or by selecting the "Custom Controls..." item on the Tools menu in Visual Basic 4.0.

Retrieving Information About the WebBrowser Control

Many properties can be used to retrieve information about the WebBrowser control. The LocationName and LocationURL properties can be used to retrieve information about the location that is currently displayed. If the location is an HTML page on the World Wide Web, LocationName retrieves the title of that page, and LocationURL retrieves the URL of that page. If the location is a folder or file on the network or local computer, LocationName and LocationURL both retrieve the Universal Naming Convention (UNC) name or the full path of the folder or file.

The current status of the WebBrowser control can be obtained using the Busy property. This Boolean value indicates whether the control is engaged in a navigation or downloading operation. You should check the value of this property before issuing the Stop method to cancel navigation or downloading operations.

Customizing the User Interface

The WebBrowser control supports properties and associated events to manipulate various user interface elements of an Internet Explorer application or a custom browser. The size and position of the window used by the WebBrowser control can be read or set with the Height, Left, Top, and Width properties. Other user interface elements are enabled with individual properties such as MenuBar, FullScreen, StatusBar, and ToolBar. The associated OnMenuBar, OnFullScreen, OnStatusBar, and OnToolBar events are triggered when the property value changes. These events return a Boolean value to indicate the new state of the property and to provide a mechanism to respond to user actions in the InternetExplorer object.

When using OLE Automation with the InternetExplorer object, the application window can be shown or hidden by setting the value of the Visible property. When changed, the associated OnVisible event returns the current Boolean value of the property. You may also want to retrieve information about the Internet Explorer application itself. To do so, use the Name property to get the Internet Explorer application name, and use the Path and FullName properties to get the Internet Explorer application's path and file name.

Navigating with the WebBrowser Control

Use the Navigate or Navigate2 method to browse HTML pages on the World Wide Web or any file or folder on the network or local computer. In addition to the required URL argument passed to the Navigate or Navigate2 method, you can optionally include flags to specify more detailed information about the navigation, such as the HTML frame name target and the HTTP headers sent to the server. You can browse through the sites maintained in the browser's history list during each browser session by using the GoBack and GoForward methods. If you wish to go directly to the Internet Explorer home or search pages that have been specified in the Internet Explorer Options dialog box, use the GoHome or GoSearch method. To display the most current version of a page the browser is viewing, use the Refresh or Refresh2 method. When using OLE Automation, call the Quit method to close the instance of the Internet Explorer application.

The WebBrowser control triggers a number of different events to notify an application of user- and browser-generated activity. When the browser is about to navigate to a new location, it triggers a BeforeNavigate2 event that specifies the URL or path of the new location and any other data that will be transmitted to the Internet server through the HTTP transaction. The data can include the HTTP header, HTTP post data, and the URL of the referrer. The BeforeNavigate2 event also includes a flag that can be set to cancel the pending navigation request. This event can be useful for checking the requested URL against a database of unauthorized World Wide Web sites or local and network folders, and for canceling the navigation request. The WebBrowser control fires the NavigateComplete2 event after it has navigated to a new location. This event includes the same information as BeforeNavigate2, except NavigateComplete2 does not include the cancel flag.

Whenever the browser is about to begin a download operation, it triggers the DownloadBegin event. The control also generates a number of ProgressChange events as the operation progresses, and then it triggers the DownloadComplete event after completing the operation. Applications typically use these three events to indicate the progress of the download operation, often by displaying a progress bar. An application would show the progress bar in response to DownloadBegin, update the progress bar in response to ProgressChange, and hide the progress bar in response to DownloadComplete.

When an application calls the Navigate or Navigate2 method with the navOpenInNewWindow flag, the NewWindow2 event occurs before the new browser window is created. This event allows the application to create the new browser window or have a new instance of the Internet Explorer application created. Once the new window is created, an accompanying BeforeNavigate2 event occurs.

Note The events discussed in the preceding section that apply to the InternetExplorer object are supported in Visual Basic version 5.0 and later.

Creating a Custom Browser with Limited Functionality

Suppose you want to create a custom browser application to start and display an HTML page that is not the user's home or start page. You also want the custom browser to navigate only to HTML pages on the local domain or view files on the local hard disk. Here's how you could create this simple application:

  1. Use the Navigate2 method to go to the desired HTML page during form loading.
    Private Sub Form_Load()
    On Error Resume Next		'Don't stop execution, continue on next line
    WebBrowser.Navigate2 "http:\\www.xyzcorp.com"
    If Err.Number <> 0 Then MsgBox "Error :" & Err.Description	'Display error message
End Sub
  2. Check the URL in the BeforeNavigate2 event to make sure the location string contains the local domain or disk. If the location string doesn't meet the criteria, cancel the operation and display an error message to the user.
    Private Sub WebBrowser_BeforeNavigate2(ByVal URL As String, ByVal Flags As Long,
        ByVal TargetFrameName As String, PostData As Variant, ByVal Headers As String,
        Cancel As Boolean)
    If (Instr(1,URL,"xyzcorp.com") = 0) And (Instr(1,URL,"C:") = 0) Then
        Cancel = True
        MsgBox "Access denied to URL: " & URL
    End If
End Sub

Printing the Current Page with the WebBrowser Control

The WebBrowser control supports several common file operations—such as Print, Print Preview, Save, Save As, New, and Properties—with the QueryStatusWB and ExecWB methods. These methods directly access the IOleCommandTarget interface for issuing commands on the Active Document or inquiring about which commands it supports. The following example shows the implementation of a Print command button that, when clicked, checks to make sure the Print command is valid and then displays the print dialog box for the WebBrowser control.

Private Sub BtnPrint_Click()
    Dim eQuery As OLECMDF       'return value type for QueryStatusWB

    On Error Resume Next
    eQuery = WebBrowser1.QueryStatusWB(OLECMDID_PRINT)  'get print command status
    If Err.Number = 0 Then
            If eQuery And OLECMDF_ENABLED Then
                WebBrowser1.ExecWB OLECMDID_PRINT, OLECMDEXECOPT_PROMPTUSER, "", ""    'Ok to Print?
          Else
                MsgBox "The Print command is currently disabled."
            End If
    End If
    If Err.Number <> 0 Then MsgBox "Print command Error: " & Err.Description
End Sub

Capturing Events with the InternetExplorer Object

When using OLE Automation to control a separately running instance of an application, you will need to create a mechanism to respond to events triggered by that ActiveX object. To create this mechanism, commonly referred to as an event sink, use the following steps as a guideline.

  1. Create a Standard EXE project in Visual Basic version 5.0.
  2. Select References under the Project menu, and add a reference to the "Microsoft Internet Controls" by checking the appropriate box. If this library is not available, you should browse for the Shdocvw.dll file.
  3. Select Add Class Module under the Project menu.
  4. In the General Declarations section of the class module, add this line of code:
    Public WithEvents m_oWbSink As SHDocVw.InternetExplorer
  5. At this point, you can select the m_oWbSink object in the left-hand object drop-down menu of the code window. After selecting this object, the right-hand procedure drop-down window lists all of the events supported by this object. Select one of the events, and add the code to process the event. This example updates a text box on the form with the current browser status text.
    Private Sub m_oWbSink_StatusTextChange(ByVal Text As String)
    Form1.txtStatus.Text = Text
End Sub
  6. Add the necessary declarations in the "General Declarations" section of the form, as follows:
    'Global reference to an instance of the browser
Dim g_oIE As New SHDocVw.InternetExplorer
'Global reference to an instance of a class that can sink the browser's events
Dim g_oIESink As New Class1
  7. Now you can hook up the event sink to the instance of the browser by placing the following code in the form's "Form_Load" event:
    Set g_oIESink.m_oWbSink = g_oIE
  8. Finally, add any additional desired controls (buttons or text boxes, for example) and code to your project. Any events you need to use will be available in your newly created class module.

Note The preceding steps are unnecessary when using the WebBrowser object. Events are automatically trapped when you select the WebBrowser control in the Visual Basic toolbox and place it directly on a form.

Using the WebBrowser Control from C/C++

This section describes some of the common implementations of the WebBrowser control, including:

  • Adding Internet browsing functionality to your application
  • Printing Web pages with the WebBrowser control
  • Changing fonts with the WebBrowser control
  • Working with WebBrowser events

Adding Internet Browsing Functionality to Your Application

One of the most common uses for the WebBrowser control is to add Internet browsing functionality to your application. Using the IWebBrowser2 interface, you can browse to any location in the local file system, on the network, or on the World Wide Web. You can use the Navigate method to tell the control which location to browse to. The first parameter is a string that contains the name of the location. To browse to a location in the local file system or on the network, specify the full path to the file system location or the Universal Naming Convention (UNC) name of the location on the network. To browse to a site on the World Wide Web, specify the URL of the site. By including a text box in your application, you can let the user specify the location to browse to and then pass the location to the Navigate method.

In this example, the WebBrowser control was inserted into a basic Microsoft Foundation Class Library (MFC) application. A class was added to the project, and the control was dynamically created in the OnCreate handler of the application's View class.

CRect rect;
GetClientRect (&rect);

// Create the control.
m_pBrowser = new CWebBrowser;
ASSERT (m_pBrowser);
if (!m_pBrowser->Create(NULL,NULL,WS_VISIBLE,rect,this,NULL))
{
    TRACE("failed to create browser\n");
    delete m_pBrowser;
    m_pBrowser = NULL;
    return 0;
}

// Initialize the first URL.
COleVariant noArg;
m_pBrowser->Navigate("www.microsoft.com",&noArg,&noArg,&noArg,&noArg);
return 0;

In addition, the Navigate method allows you to target a specific frame on an HTML page, causing the WebBrowser control to display a Web site or file system location in that frame. First, you would call the Navigate method and specify the URL of an HTML page that contains a frame. Then, by specifying the name of the frame in subsequent calls to Navigate, you can direct the control to display subsequent locations within that frame.

You can also use the get_LocationName and get_LocationURL methods to retrieve information about the location that the WebBrowser control is currently displaying. If the location is an HTML page on the World Wide Web, get_LocationName retrieves the title of that page, and get_LocationURL retrieves the URL of that page. If the location is a folder or file on the network or local computer, get_LocationName and get_LocationURL both retrieve the UNC or full path of the folder or file.

Printing Pages with the WebBrowser Control

Although the WebBrowser control does not support a print method, you can print its contents using one of the following methods:

  • Set the focus to the WebBrowser control and send a key combination of CTRL+P.
  • Call the get_Document method, which returns an IDispatch pointer. Using this IDispatch pointer, call QueryInterface on IID_IOleCommandTarget. With the object pointer returned, call Exec (NULL, OLECMDID_PRINT, 0, NULL, NULL).
    LPDISPATCH lpDispatch = NULL;
LPOLECOMMANDTARGET lpOleCommandTarget = NULL;

lpDispatch = m_pBrowser.get_Document();
ASSERT(lpDispatch);

lpDispatch->QueryInterface(IID_IOleCommandTarget, (void**)&lpOleCommandTarget);
ASSERT(lpOleCommandTarget);

lpDispatch->Release();

// Print contents of WebBrowser control.
lpOleCommandTarget->Exec(NULL, OLECMDID_PRINT, 0, NULL,NULL);
lpOleCommandTarget->Release();

Changing Fonts with the WebBrowser Control

The WebBrowser automation model does not support a method that allows you to change the font of the text of the currently displayed page. However, the WebBrowser control exposes this functionality through the IOleCommandTarget interface. Call the get_Document method, which returns an IDispatch pointer. Using this IDispatch pointer, call QueryInterface on IID_IOleCommandTarget. With this IOleCommandTarget interface pointer, call Exec with OLECMDID_ZOOM and use the pvaIn input argument to pass a value in the range of 0 to 5 (where 0 is smallest) indicating the desired scale of the font. This, in effect, mimics the functionality available through the Internet Explorer Fonts command on the View menu.

LPDISPATCH pDisp = NULL;
LPOLECOMMANDTARGET pCmdTarg = NULL;

pDisp = m_pBrowser.get_Document();
ASSERT(pDisp);

pDisp->QueryInterface(IID_IOleCommandTarget, (LPVOID*)&pCmdTarg);
ASSERT(pCmdTarg);

VARIANT vaZoomFactor;   // input arguments
VariantInit(&vaZoomFactor);
V_VT(&vaZoomFactor) = VT_I4;
V_I4(&vaZoomFactor) = fontSize;

pCmdTarg->Exec(NULL,
        OLECMDID_ZOOM,
        OLECMDEXECOPT_DONTPROMPTUSER,
        &vaZoomFactor,
        NULL);
VariantClear(&vaZoomFactor);

if (pCmdTarg)
   pCmdTarg->Release(); // release document's command target
if (pDisp)
   pDisp->Release();    // release document's dispatch interface

Working with WebBrowser Events

The WebBrowser control fires a number of different events to notify an application of user- and browser-generated activity. The events are implemented using the DWebBrowserEvents2 interface. When the control is about to navigate to a new location, it fires a BeforeNavigate2 event that specifies the URL or path of the new location and any other data that will be transmitted to the Internet server through the HTTP transaction. The data can include the HTTP header, HTTP post data, and the URL of the referrer. BeforeNavigate2 also includes a cancel flag that you can set to FALSE to cancel the navigation. The WebBrowser control fires the NavigateComplete2 event after it has navigated to a new location. This event includes the same information as BeforeNavigate2, but NavigateComplete2 does not include the cancel flag.

When the WebBrowser control is about to begin a download operation, it fires the DownloadBegin event. The control fires a number of ProgressChange events as the operation progresses, and then it fires the DownloadComplete event after completing the operation. Applications typically use these three events to indicate the progress of the download operation, often by displaying a progress bar. An application would show the progress bar in response to DownloadBegin, update the progress bar in response to ProgressChange, and hide it in response to DownloadComplete.

When an application calls the Navigate method with the Flags parameter set to navOpenInNewWindow, the WebBrowser control fires the NewWindow2 event before navigating to the new location. The event includes information about the new location and a flag that indicates whether the application or the control is to create the new window. Set this flag to TRUE if your application will create the window or to FALSE if the WebBrowser control should create it.

You will need to implement an event sink to capture and handle the various events. The Internet Client SDK includes a generic event sink class called EVTSINK. For more information, refer to the \Samples\BaseCtl\Objvw subdirectory within your SDK.


Reference for Visual Basic Developers

The following sections are a reference guide for using the WebBrowser control with Microsoft® Visual Basic®. This reference covers all the supported properties, methods, and events associated with the WebBrowser and InternetExplorer objects.

  • Objects
  • Properties
  • Methods
  • Events


Objects

This section describes the WebBrowser and InternetExplorer objects.

WebBrowser Object

InternetExplorer Object


WebBrowser Object

Description

The WebBrowser object adds browsing capabilities to your applications. Applications hosting this ActiveX™ Control will support browsing sites on the World Wide Web, as well as directories on the local computer and on network servers.

Properties

AddressBar ,Application, Busy, Container, Document, FullScreen, Height, Left, LocationName, LocationURL, MenuBar, Offline, Parent, ReadyState, RegisterAsBrowser, RegisterAsDropTarget, Resizable, Silent, StatusBar, StatusText, TheaterMode, ToolBar, Top, TopLevelContainer, Type, Visible, Width

Methods

ExecWB, GoBack, GoForward, GoHome, GoSearch, Navigate, Navigate2, Quit, Refresh, Refresh2, ShowBrowserBar, Stop

Events

BeforeNavigate2, CommandStateChange, DocumentComplete, DownloadBegin, DownloadComplete, NavigateComplete2, NewWindow2, OnFullScreen, OnMenuBar, OnStatusBar, OnTheaterMode, OnToolBar, OnVisible, ProgressChange, StatusTextChange, TitleChange


InternetExplorer Object

Description

The InternetExplorer object controls a remote instance of the Internet Explorer application through OLE Automation.

Properties

AddressBar, Application, Busy, Container, Document, FullName, FullScreen, Height, HWND, Left, LocationName, LocationURL, MenuBar, Name, Offline, Parent, Path, ReadyState, RegisterAsBrowser, RegisterAsDropTarget, Resizable, Silent, StatusBar, StatusText, TheaterMode, ToolBar, Top, TopLevelContainer, Type, Visible, Width

Methods

ClientToWindow, ExecWB, GetProperty, GoBack, GoForward, GoHome, GoSearch, Navigate, Navigate2, PutProperty, QueryStatusWB, Quit, Refresh, Refresh2, ShowBrowserBar, Stop

Events

BeforeNavigate2, CommandStateChange, DocumentComplete, DownloadBegin, DownloadComplete, NavigateComplete2, NewWindow2, OnFullScreen, OnMenuBar, OnQuit, OnStatusBar, OnTheaterMode, OnToolBar, OnVisible, ProgressChange, PropertyChange, StatusTextChange, TitleChange


Properties

This section describes the properties associated with the WebBrowser control.

AddressBar Property

Application Property

Busy Property

Container Property

Document Property

FullName Property

FullScreen Property

Height Property

HWND Property

Left Property

LocationName Property

LocationURL Property

MenuBar Property

Name Property

Offline Property

Parent Property

Path Property

ReadyState Property

RegisterAsBrowser Property

RegisterAsDropTarget Property

Resizable Property

Silent Property

StatusBar Property

StatusText Property

TheaterMode Property

ToolBar Property

Top Property

TopLevelContainer Property

Type Property

Visible Property

Width Property


AddressBar Property

Description

Returns or sets a value that determines whether the Internet Explorer application URL address bar is visible or hidden.

Syntax

object.AddressBar

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

The WebBrowser object ignores the AddressBar property.

Applies To

InternetExplorer, WebBrowser


Application Property

Description

Returns the automation object supported by the application that contains the WebBrowser control, if the object is accessible; otherwise, this property returns the WebBrowser control's automation object.

Syntax

object.Application

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application as shown in the following early binding example.

Dim IE As SHDocVw.InternetExplorer

Set IE = CreateObject("InternetExplorer.Application")

Applies To

InternetExplorer, WebBrowser


Busy Property

Description

Returns a Boolean value indicating whether the WebBrowser control or Internet Explorer application is engaged in a navigation or downloading operation. If the control is busy, you can use the Stop method to cancel the navigation or download operation before it is completed.

Syntax

object.Busy

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

The Busy property returns TRUE if a download or navigation operation is currently in progress, or FALSE otherwise.

Applies To

InternetExplorer, WebBrowser

See Also

Stop


Container Property

Description

Returns an object that evaluates to the container of the WebBrowser control, if any.

Syntax

object.Container

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Document


Document Property

Description

Returns the automation object of the active document, if any. This provides access to the contents of the HTML document through the object model. For more information, see the document object section in the Dynamic HTML reference.

Syntax

object.Document

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Container


FullName Property

Description

Returns a string that evaluates to the fully qualified path of the executable file that contains the Internet Explorer application.

Syntax

object.FullName

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer


FullScreen Property

Description

Returns or sets a value indicating whether the Internet Explorer window is maximized.

Syntax

object.FullScreen [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether Internet Explorer is maximized. If TRUE, the browser window is maximized; if FALSE, it is not. The default value is FALSE.

Remarks

The WebBrowser object ignores the FullScreen property.

Applies To

InternetExplorer, WebBrowser


Height Property

Description

Returns or sets the vertical dimension, in pixels, of the frame window that contains the WebBrowser control.

Syntax

object.Height [= height]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
height | Optional. A long integer value that specifies the vertical dimension of the frame window, in pixels.

Applies To

InternetExplorer, WebBrowser

See Also

ClientToWindow, Width


HWND Property

Description

Returns the window handle to the Internet Explorer main window.

Syntax

object.HWND

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer


Left Property

Description

Returns or sets the distance between the internal left edge of the WebBrowser control and the left edge of its container.

Syntax

object.Left [= distance]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
distance | Optional. A long integer expression that specifies the distance between the internal left edge of the WebBrowser control and the left edge of its container.

Remarks

The Left property is measured in units depending on the coordinate system of its container. The values for this property change as the object is moved by the user or by code.

Applies To

InternetExplorer, WebBrowser


LocationName Property

Description

Returns a string that contains the name of the resource that the WebBrowser control is currently displaying. If the resource is an HTML page on the World Wide Web, the name is the title of that page. If the resource is a folder or file on the network or local computer, the name is the full path of the folder or file in the Universal Naming Convention (UNC) format.

Syntax

object.LocationName

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

LocationURL


LocationURL Property

Description

Returns a string that contains the URL of the resource that the WebBrowser control or Internet Explorer application is currently displaying. If the resource is a folder or file on the network or local computer, the name is the full path of the folder or file in the Universal Naming Convention (UNC) format.

Syntax

object.LocationURL

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

LocationName


MenuBar Property

Description

Returns or sets a value that determines whether the Internet Explorer application menu bar is visible or hidden.

Syntax

object.MenuBar [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether the menu bar is visible. If TRUE, the menu bar is visible; if FALSE, it is hidden. The default value is TRUE.

Remarks

Setting this property to FALSE prevents the user from accessing the File, Edit, View, Go, Favorites, and Help menus. This can be used for limiting the functionality of an Internet Explorer application from a controlling application.

Remarks

The WebBrowser object ignores the MenuBar property.

Applies To

InternetExplorer, WebBrowser


Name Property

Description

Returns a string that evaluates to the name of the Internet Explorer application—that is, "Microsoft Internet Explorer."

Syntax

object.Name

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

This property is read-only.

Applies To

InternetExplorer


Offline Property

Description

Returns or sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

Syntax

object.Offline [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether the WebBrowser control is in offline mode. If TRUE, the WebBrowser will read data about its current URL from its local cache; if FALSE, it will attempt to read the source document. The default value is FALSE.

Applies To

InternetExplorer, WebBrowser


Parent Property

Description

Returns an object that evaluates to the form on which the WebBrowser control is located, or to the automation object supported by Internet Explorer.

Syntax

object.Parent

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser


Path Property

Description

Returns a string that evaluates to the full path of the Internet Explorer application.

Syntax

object.Path

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer


ReadyState Property

Description

Retrieves the ready state of the object. This will be one of the READYSTATE values.

Syntax

object.ReadyState

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser, READYSTATE


RegisterAsBrowser Property

Description

Returns or sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

object.RegisterAsBrowser [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether Internet Explorer is registered as a top-level browser. If TRUE, the WebBrowser is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.

Applies To

InternetExplorer, WebBrowser


RegisterAsDropTarget Property

Description

Returns or sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

object.RegisterAsDropTarget [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether Internet Explorer is registered as a drop target for navigation. If TRUE, the WebBrowser is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.

Applies To

InternetExplorer, WebBrowser


Resizable Property

Description

Sets or retrieves a value indicating whether the object can be resized.

Syntax

object.Resizable [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that sets the object's resizable property. If this value is TRUE, the object can be resized. If this value is FALSE, the object cannot be resized. The default value is TRUE.

Remarks

The WebBrowser object ignores the Resizable property.

Applies To

InternetExplorer, WebBrowser


Silent Property

Description

Returns or sets a value indicating whether any dialog boxes can be shown.

Syntax

object.Silent [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether the WebBrowser can show any dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE.

Applies To

InternetExplorer, WebBrowser


StatusBar Property

Description

Returns or sets a value that determines whether the status bar is visible.

Syntax

object.StatusBar [= value]

Part | Description
object | Required. An object expression that evaluates to an InternetExplorer object.
value | Optional. A Boolean expression that determines whether the status bar is visible. If TRUE, the status bar is visible; if FALSE, it is hidden. The default is TRUE.

Remarks

The WebBrowser object ignores the StatusBar property.

Applies To

InternetExplorer, WebBrowser

See Also

StatusText, StatusTextChange, ToolBar, Visible


StatusText Property

Description

Returns or sets the text for the status bar.

Syntax

object.StatusText [= value]

Part | Description
object | Required. An object expression that evaluates to an InternetExplorer object.
value | Optional. A string that evaluates to the text for the status bar.

Remarks

The WebBrowser object ignores the StatusText property.

Applies To

InternetExplorer, WebBrowser

See Also

StatusBar, StatusTextChange


TheaterMode Property

Description

Returns or sets a value indicating whether Internet Explorer is in theater or normal window mode. In theater mode, the Internet Explorer main window fills the entire screen and displays a toolbar with a minimal set of navigational buttons. A status bar is also provided in the upper right-hand corner of the screen. Channels, Search, History, and Favorites browser bars appear (if enabled) as an autohide pane on the left edge of the screen in theater mode.

Syntax

object.TheaterMode [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression that determines whether Internet Explorer is in theater or normal window mode. If TRUE, the object is in theater mode; if FALSE, it is in normal mode. The default value is FALSE.

Remarks

The WebBrowser object ignores the TheaterMode property.

Applies To

InternetExplorer, WebBrowser


ToolBar Property

Description

Returns or sets a value that determines whether the toolbar is visible.

Syntax

object.ToolBar [= value]

Part | Description
object | Required. An object expression that evaluates to an InternetExplorer object.
value | Optional. A Boolean expression that determines whether the toolbar is visible. If TRUE, the toolbar is visible; if FALSE, it is hidden. The default is TRUE.

Remarks

The WebBrowser object ignores the ToolBar property.

Applies To

InternetExplorer, WebBrowser

See Also

StatusBar, Visible


Top Property

Description

Returns or sets the distance between the internal top edge of the WebBrowser control and the top edge of its container.

Syntax

object.Top [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A long integer expression that specifies the distance.

Remarks

The Top property is measured in units depending on the coordinate system of its container. The values for this property change as the object is moved by the user or by code.

Applies To

InternetExplorer, WebBrowser


TopLevelContainer Property

Description

Returns a Boolean value indicating whether the given object is a top-level container.

Syntax

object.TopLevelContainer

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser


Type Property

Description

Returns a string expression that specifies the type name of the contained document object—that is, "Windows HTML Viewer."

Syntax

object.Type

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser


Visible Property

Description

Returns or sets a value indicating whether the object is visible or hidden.

Syntax

object.Visible [= value]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
value | Optional. A Boolean expression specifying the visible state of Internet Explorer. If TRUE, the window is visible; if FALSE, it is hidden. The default value is FALSE.

Remarks

Although the Internet Explorer application is hidden when it is first created, it becomes visible after using the Navigate or GoSearch method.

Applies To

InternetExplorer, WebBrowser


Width Property

Description

Returns or sets the horizontal dimension, in pixels, of the frame window that contains the WebBrowser control.

Syntax

object.Width [= width]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
width | Optional. A long integer value that specifies the horizontal dimension of the frame window, in pixels.

Applies To

InternetExplorer, WebBrowser

See Also

ClientToWindow, Height


Methods

This section describes the methods associated with the WebBrowser control.

ClientToWindow Method

ExecWB Method

GetProperty Method

GoBack Method

GoForward Method

GoHome Method

GoSearch Method

Navigate Method

Navigate2 Method

PutProperty Method

QueryStatusWB Method

Quit Method

Refresh Method

Refresh2 Method

ShowBrowserBar Method

Stop Method


ClientToWindow Method

Description

Converts the client coordinates of a point to window coordinates. Client coordinates are relative to the upper-left corner of the client area; window coordinates are relative to the upper-left corner of a window.

Syntax

object.ClientToWindow pcx, pcy

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
pcx | Required. A long integer value that specifies the x-coordinate of the point in client coordinates. When ClientToWindow returns, this variable contains the x-coordinate of the point in window coordinates.
pcy | Required. A long integer value that specifies the y-coordinate of the point in client coordinates. When ClientToWindow returns, this variable contains the y-coordinate of the point in window coordinates.

Applies To

InternetExplorer

See Also

Height, Width


ExecWB Method

Description

Executes a command on an OLE object and returns the status of the command execution using the IOLECommandTarget interface.

Syntax

object.ExecWB nCmdID, nCmdExecOpt, [pvaIn], [pvaOut]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
nCmdID | Required. A long integer that represents the identifier of the command to execute.
nCmdExecOpt | Required. A long integer that represents the options set for executing the command.
pvaIn | Optional. A variant used for specifying command input arguments.
pvaOut | Optional. A variant used for specifying command output arguments.

Applies To

InternetExplorer, WebBrowser


GetProperty Method

Description

Retrieves the current value of a property associated with the given object.

Syntax

object.GetProperty szProperty, vtValue

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
szProperty | Required. A string expression that contains the name of the property to retrieve.
vtValue | Required. A variable that receives the current value of the property.

Applies To

InternetExplorer

See Also

PropertyChange, PutProperty


GoBack Method

Description

Navigates backward one item in the history list.

Syntax

object.GoBack

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

During a browsing session, the WebBrowser control and Internet Explorer application maintain a history list of all Web sites visited during a session (unless you specify the navNoHistory flag when using the Navigate method). Use the CommandStateChange event to check the enabled state of backward navigation. If the event's CSC_NAVIGATEBACK command is disabled, the beginning of the history list has been reached and the GoBack method should not be used.

Applies To

InternetExplorer, WebBrowser

See Also

GoForward, GoHome, GoSearch, Navigate, CommandStateChange


GoForward Method

Description

Navigates forward one item in the history list.

Syntax

object.GoForward

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

During a browsing session, the WebBrowser control and Internet Explorer application maintain a history list of all Web sites visited during a session (unless you specify the navNoHistory flag when using the Navigate method). Use the CommandStateChange event to check the enabled state of forward navigation. If the event's CSC_NAVIGATEFORWARD command is disabled, the end of the history list has been reached and the GoForward method should not be used.

Applies To

InternetExplorer, WebBrowser

See Also

GoBack, GoHome, GoSearch


GoHome Method

Description

Navigates to the current home or start page, as specified in the Internet Explorer Options dialog box and Internet Control Panel.

Syntax

object.GoHome

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

GoBack, GoForward, GoSearch


GoSearch Method

Description

Navigates to the current search page, as specified in the Internet Explorer Options dialog box and Internet Control Panel.

Syntax

object.GoSearch

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

GoBack, GoForward, GoHome


Navigate Method

Description

Navigates to the resource identified by a Universal Resource Locator (URL) or to the file identified by a full path.

Syntax

object.Navigate URL [Flags,] [TargetFrameName,] [PostData,] [Headers]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
URL | Required. A string expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) location and name of the resource to display.
Flags Optional. A constant or value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following constants or values.
Constant | Value | Meaning
navOpenInNewWindow | 1 | Open the resource or file in a new window.
navNoHistory | 2 | Do not add the resource or file to the history list. The new page replaces the current page in the list.
navNoReadFromCache | 4 | Do not read from the disk cache for this navigation.
navNoWriteToCache | 8 | Do not write the results of this navigation to the disk cache.
TargetFrameName Optional. String expression that evaluates to the name of an HTML frame in URL to display in the browser window. 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.
<window_name> | 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 | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If this parameter does not specify any post data, the Navigate method issues an HTTP GET transaction. This parameter is ignored if URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if URL is not an HTTP URL.

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. Use the Navigate method to tell the browser which location to browse to. By including a text box in your application, you can let the user specify the location to browse to and then pass the location to the Navigate method.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate2


Navigate2 Method

Description

Navigates to the resource identified by a Universal Resource Locator (URL) or to the file identified by a full path. The Navigate2 method extends the Navigate method to support browsing on special folders—such as Desktop and My Computer—that are represented by a pointer to an item identifier list (PIDL). However, this is not applicable to the Visual Basic programming language. For information on this functionality, see the Using the WebBrowser Control from C/C++ section.

Syntax

object.Navigate2 URL [Flags,] [TargetFrameName,] [PostData,] [Headers]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
URL | Required. A string expression that evaluates to the URL of the resource to display or the full path to the file location.
Flags Optional. A constant or value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following constants or values.
Constant | Value | Meaning
navOpenInNewWindow | 1 | Open the resource or file in a new window.
navNoHistory | 2 | Do not add the resource or file to the history list. The new page replaces the current page in the list.
navNoReadFromCache | 4 | Do not read from the disk cache for this navigation.
navNoWriteToCache | 8 | Do not write the results of this navigation to the disk cache.
TargetFrameName Optional. String expression that evaluates to the name of an HTML frame in URL to display in the browser window. 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.
<window_name> | 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 | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If this parameter does not specify any post data, the Navigate2 method issues an HTTP GET transaction. This parameter is ignored if URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if URL is not an HTTP URL.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate


PutProperty Method

Description

Sets the value of a property associated with the given object.

Syntax

object.PutProperty szProperty, vtValue

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
szProperty | Required. A string expression that contains the name of the property to set.
vtValue | Required. A variable that specifies the new value of the property.

Applies To

InternetExplorer

See Also

GetProperty, PropertyChange


QueryStatusWB Method

Description

Queries an OLE object and returns the status of commands using the IOLECommandTarget interface.

Syntax

object.QueryStatusWB nCmdID

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
nCmdID | Required. A long integer that represents the identifier of the command on which the caller needs status information. This will be one of the OLECMDID values.

Return Value

Returns an unsigned long that is one of the OLECMDF values.

Applies To

InternetExplorer, WebBrowser


Quit Method

Description

Closes the Internet Explorer application.

Syntax

object.Quit

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer

See Also

OnQuit, Stop


Refresh Method

Description

Reloads the page currently displayed in the WebBrowser control.

Syntax

object.Refresh

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

The WebBrowser control and Internet Explorer application store Web pages from recently visited sites in cached memory on the user's hard disk. This saves time when revisiting a site by reloading the page from the local disk rather than downloading it again across the network from the remote HTTP server. You can force the WebBrowser control or Internet Explorer application to redownload a page by using the Refresh or Refresh2 method to ensure that you are viewing the most current version of the page. Also, you can disable the cache from being used by specifying the navNoReadFromCache and navNoWriteToCache flags when calling the Navigate or Navigate2 method.

Applies To

InternetExplorer, WebBrowser

See Also

Refresh2, Stop


Refresh2 Method

Description

Reloads the page currently displayed in the WebBrowser control. Unlike the Refresh method, this method contains a parameter that specifies the refresh level.

Syntax

object.Refresh2 [Level]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
Level Optional. A constant or value that specifies the refresh level. It can be one of the following constants or values.
Constant | Value | Meaning
REFRESH_NORMAL | 0 | Perform a lightweight refresh that does not include sending the HTTP "pragma:nocache" header to the server.
REFRESH_IFEXPIRED | 1 | Perform a lightweight refresh if the page has expired.
REFRESH_COMPLETELY | 3 | Perform a full refresh that includes sending a "pragma:nocache" header to the server (HTTP URLs only).

Remarks

The "pragma:nocache" header tells the server not to return a cached copy. This ensures that the information is as fresh as possible. Browsers typically send this header when the user selects refresh, but the header can cause problems for some servers.

Applies To

InternetExplorer, WebBrowser

See Also

Quit, Refresh, Stop


ShowBrowserBar Method

Description

Shows or hides a specified browser bar.

Syntax

object.ShowBrowserBar pvaClsid, [pvarShow,] [pvarSize]

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
pvaClsid Required. A string containing the class identifier of the browser bar to show or hide. This object must be registered as an Explorer Bar object with the CATID_InfoBand component category. For more information, see Band Objects. The standard browser bars use the following class identifiers:

Browser Bar Name | Class ID
Search | {30D02401-6A81-11D0-8274-00C04FD5AE38}
Favorites | {EFA24E61-B078-11D0-89E4-00C04FC9E26E}
History | {EFA24E62-B078-11D0-89E4-00C04FC9E26E}
Channels | {EFA24E63-B078-11D0-89E4-00C04FC9E26E}

pvarShow | Optional. A Boolean value that specifies whether the browser bar should be shown or hidden. If this is TRUE, the browser bar is shown. If this is FALSE, the browser bar is hidden. The default value is TRUE.
pvarSize | Optional. Not currently used.

Remarks

Browser bars, also known as Explorer Bars, can be shown or hidden by the user from Internet Explorer's View menu. The ShowBrowserBar method is ignored by the WebBrowser object.

Applies To

InternetExplorer, WebBrowser


Stop Method

Description

Cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.

Syntax

object.Stop

Part | Description
object | Required. An object expression that evaluates to an object in the Applies To list.

Remarks

Before calling the Stop method, you can use the object's Busy property to determine if the browser is currently in the process of navigating to a new location or downloading a file.

Applies To

InternetExplorer, WebBrowser

See Also

BeforeNavigate2, Busy, DownloadBegin, ProgressChange, Refresh, Refresh2


Events

This section describes the events associated with the WebBrowser control.

BeforeNavigate2 Event

CommandStateChange Event

DocumentComplete Event

DownloadBegin Event

DownloadComplete Event

NavigateComplete2 Event

NewWindow2 Event

OnFullScreen Event

OnMenuBar Event

OnQuit Event

OnStatusBar Event

OnTheaterMode Event

OnToolBar Event

OnVisible Event

ProgressChange Event

PropertyChange Event

StatusTextChange Event

TitleChange Event


BeforeNavigate2 Event

Description

Occurs when the WebBrowser control is about to navigate to a different URL, which may happen as a result of external automation, internal automation from a script, or the user clicking a link or typing in the address bar. The container has an opportunity to cancel the pending navigation.

Syntax

Private Sub object_BeforeNavigate2(ByVal pDisp As Object, ByVal URL As String,
ByVal Flags As Long, ByVal TargetFrameName As String, PostData As Variant,
ByVal Headers As String, Cancel As Boolean)

Value | Description
object | Required. An object expression that evaluates to an object in the Applies To list.
pDisp | An object that evaluates to the top-level or frame WebBrowser object corresponding to the navigation.
URL | A string expression that evaluates to the URL to which the browser is navigating.
Flags | Reserved for future use.
TargetFrameName | A string expression that evaluates to the name of the frame in which the resource will be displayed, or NULL if no named frame is targeted for the resource.
PostData | Data to send to the server if the HTTP POST transaction is being used.
Headers | A value that specifies the additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code.
Cancel | A Boolean value that the container can set to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, Navigate2, NavigateComplete2


CommandStateChange Event

Description

Occurs when the enabled state of a command changes.

Syntax

Private Sub object_CommandStateChange (ByVal Command As Long,
 ByVal Enable As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
Command A long integer specifying the identifier of the command that changed. It can be one of the following constants or values.
Constant | Value | Meaning
CSC_UPDATECOMMANDS | -1 | The enabled state of a toolbar button may have changed; the Enable parameter should be ignored.
CSC_NAVIGATEFORWARD | 1 | The enabled state of the Forward button has changed.
CSC_NAVIGATEBACK | 3 | The enabled state of the Back button has changed.
Enable | A Boolean value that is TRUE if the command is enabled, or FALSE if not.

Applies To

InternetExplorer, WebBrowser


DocumentComplete Event

Description

Occurs when the document that is being navigated to reaches the READYSTATE_COMPLETE state.

Syntax

Private Sub object_DocumentComplete(ByVal pDisp As Object, URL As Variant)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
pDisp | An object that evaluates to the top-level or frame WebBrowser object corresponding to the event.
URL | A string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by DocumentComplete will be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

Remarks

For a document without frames, this event will fire once when the document is finished loading. On a document containing multiple frames, this event is fired once for each frame. When the multiple-frame document has finished loading, the top-level frame fires the event one final time. To detect the last DocumentComplete event of a multiple-frame document, compare the pDisp object returned from the event to the WebBrowser object itself. The following example indicates how to trap the final DocumentComplete event.

Private Sub WebBrowser1_DocumentComplete(ByVal pDisp As Object, URL As Variant)
    If (pDisp Is WebBrowser1.Object) Then
        Debug.Print "Document is finished loading."
    End If
End Sub

Applies To

InternetExplorer, WebBrowser

See Also

BeforeNavigate2, Navigate, Navigate2, READYSTATE


DownloadBegin Event

Description

Occurs when a navigation operation is beginning. This event is fired shortly after the BeforeNavigate2 event, unless the navigation is canceled. Any animation or "busy" indication that the container needs to display should be connected to this event. Note that any DownloadBegin event will have a corresponding DownloadComplete event.

Syntax

Private Sub object_DownloadBegin

Value | Description
object | An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, ProgressChange


DownloadComplete Event

Description

Occurs when a navigation operation finishes, is halted, or fails. Unlike NavigateComplete2, which is fired only when a URL is successfully navigated to, this event is always fired after a navigation starts. Any animation or "busy" indication that the container needs to display should be connected to this event. Note that any DownloadBegin event will have a corresponding DownloadComplete event.

Syntax

Private Sub object_DownloadComplete

Value | Description
object | An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, Navigate2, ProgressChange


NavigateComplete2 Event

Description

Occurs after the browser has successfully navigated to a new location. The document might still be downloading (and in the case of HTML, images may still be downloading), but at least part of the document has been received from the server, and the viewer for the document has been created.

Syntax

Private Sub object_NavigateComplete2(ByVal pDisp As Object, URL As Variant)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
pDisp | An object that evaluates to the top-level or frame WebBrowser object corresponding to the event.
URL | A string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by NavigateComplete2 will be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

Applies To

InternetExplorer, WebBrowser

See Also

BeforeNavigate2


NewWindow2 Event

Description

Occurs when a new window is to be created for displaying a resource. Some actions that can cause this include the user shift-clicking on a link, the user right-clicking on a link and choosing "open in new window", or a targeted navigation to a frame name that does not yet exist. Your browser application can also trigger this event by calling the Navigate or Navigate2 method with the navOpenInNewWindow flag. The WebBrowser control has an opportunity to handle the new window creation itself. If it does not, a top-level Internet Explorer window is created as a separate (nonhosted) process.

Syntax

Private object_NewWindow2 (ByVal ppDisp As Object, ByVal Cancel As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
ppDisp | An object expression that, optionally, receives a new, hidden WebBrowser or InternetExplorer object with no URL loaded.
Cancel | A Boolean value that, when set to TRUE, is used to cancel the new window creation and attempt the navigation in the current window.

Remarks

The application processing this notification can respond in one of three ways:

  1. Create a new, hidden, non-navigated WebBrowser or InternetExplorer object that is returned in ppDisp. Upon return from this event, the object that fired this event will then configure and navigate (including a BeforeNavigate2 event) the new object to the target location.
  2. Cancel the new window creation by setting Cancel to true. No object is created and the navigation is attempted on the current window (with an accompanying BeforeNavigate2 event).
  3. Do nothing and do not set ppDisp to any value. This will cause the object that fired the event to create a new InternetExplorer object to handle the navigation.

Applies To

InternetExplorer, WebBrowser

See Also

NavigateComplete2


OnFullScreen Event

Description

Occurs when the FullScreen property is changed.

Syntax

Private Sub object_OnFullScreen(ByVal FullScreen As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
FullScreen | If TRUE, the browser window is maximized; if FALSE, it is not.

Remarks

An application hosting the WebBrowser control should respond to this event by enlarging or reducing the window size. When using scripting in an HTML page, this event corresponds to the size properties passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnMenuBar Event

Description

Occurs when the MenuBar property is changed.

Syntax

Private Sub object_OnMenuBar(ByVal MenuBar As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
MenuBar | If TRUE, the menu bar is shown; if FALSE, the menu bar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the menu bar, if applicable. When using scripting in an HTML page, this event corresponds to the menu bar property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnQuit Event

Description

Occurs before the Internet Explorer application quits.

Syntax

Private Sub object_OnQuit()

Value | Description
object | An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer

See Also

Quit


OnStatusBar Event

Description

Occurs when the StatusBar property is changed.

Syntax

Private Sub object_OnStatusBar(ByVal StatusBar As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
StatusBar | If TRUE, the status bar is shown; if FALSE, the status bar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the status bar, if applicable.

Applies To

InternetExplorer, WebBrowser


OnTheaterMode Event

Description

Occurs when the TheaterMode property is changed.

Syntax

Private Sub object_OnTheaterMode(ByVal TheaterMode As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
TheaterMode | If TRUE, the browser is in theater mode; if FALSE, the browser is in normal viewing mode. The default value is FALSE.

Remarks

Theater mode uses the entire screen to display the content.

Applies To

InternetExplorer, WebBrowser


OnToolBar Event

Description

Occurs when the ToolBar property is changed.

Syntax

Private Sub object_OnToolBar(ByVal ToolBar As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
ToolBar | If TRUE, the toolbar is shown; if FALSE, the toolbar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the toolbar, if applicable. When using scripting in an HTML page, this event corresponds to the toolbar property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnVisible Event

Description

Occurs when the Visible property is changed.

Syntax

Private Sub object_OnVisible(ByVal Visible As Boolean)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
Visible | If TRUE, the WebBrowser window should be shown; if FALSE, the window should be hidden.

Applies To

InternetExplorer, WebBrowser


ProgressChange Event

Description

Occurs when the progress of a download operation is updated.

Syntax

Private Sub object_ProgressChange(ByVal Progress As Long, ByVal ProgressMax As Long)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
Progress | A long integer that specifies the amount of total progress to show, or -1 when progress is complete.
ProgressMax | A long integer that specifies the maximum progress value.

Remarks

The container can use the information provided by this event to display the number of bytes downloaded so far or to update a progress indicator.

To calculate the percentage of progress to show in a progress indicator, multiply the value of Progress by 100 and divide by the value of ProgressMax (unless Progress is -1, in which case the container can indicate that the operation is finished or hide the progress indicator).

Applies To

InternetExplorer, WebBrowser

See Also

DownloadBegin, DownloadComplete, Navigate


PropertyChange Event

Description

Occurs when the PutProperty method changes the value of a property.

Syntax

Private Sub object_PropertyChange(ByVal szProperty As String)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
szProperty | A string expression that contains the name of the property whose value has changed.

Applies To

InternetExplorer

See Also

GetProperty


StatusTextChange Event

Description

Occurs when the status bar text has changed.

Syntax

Private Sub object_StatusTextChange(ByVal Text As String)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
Text | A string containing the new status bar text.

Remarks

The container can use the information provided by this event to update the text of a status bar. When using scripting in an HTML page, this event corresponds to the status property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser

See Also

StatusBar, StatusText


TitleChange Event

Description

Occurs when the title of a document in the WebBrowser control becomes available or changes. Because the title might change while an HTML page is downloading, the URL of the document is set as the title. After the title specified in the HTML page, if there is one, is parsed, the title is changed to reflect the actual title.

Syntax

Private Sub object_TitleChange(ByVal Text As String)

Value | Description
object | An object expression that evaluates to an object in the Applies To list.
Text | A string containing the new document title.

Applies To

InternetExplorer, WebBrowser


Reference for C/C++ Developers Reference for C/C++ Developers *
  * Previous Topic: TitleChange Event
  * Next Topic: Interface

Reference for C/C++ Developers

This reference contains the following sections:

  • Interface
  • Events
  • Enumerations


Interface

This section describes the new IWebBrowser2 interface that replaces the IWebBrowser and IWebBrowserApp interfaces from previous releases.


IWebBrowser2

IWebBrowser2 designates an interface that allows applications to implement an instance of the WebBrowser control in an application (ActiveX Control) or control an instance of the Internet Explorer application (OLE Automation). For methods applicable to the Internet Explorer object only, the description section in the following table uses the "Internet Explorer only" notation, and throughout the reference sections the "Applies To" heading also indicates which object (WebBrowser or Internet Explorer) that method applies to. The Exdisp.h file defines all the WebBrowser interfaces as well as the GUIDs (globally unique identifiers).

Methods in Vtable Order

IWebBrowser2 methods | Description
GoBack | Navigates to the previous item in the history list.
GoForward | Navigates to the next item in the history list.
GoHome | Navigates to the current home or start page.
GoSearch | Navigates to the current search page.
Navigate | Navigates to a resource identified by a Universal Resource Locator (URL).
Refresh | Reloads the current file.
Refresh2 | Reloads the current file and optionally prevents the "pragma:nocache" header from being sent.
Stop | Stops opening a file.
get_Application | Returns an application object representing the application that contains the current instance of the Internet Explorer application.
get_Parent | Returns the automation object.
get_Container | Returns the container of the WebBrowser control.
get_Document | Returns the active document.
get_TopLevelContainer | Returns a value indicating whether the current object is the top-level container of the WebBrowser control.
get_Type | Returns the type name of the document object.
get_Left | Returns the screen coordinate of the left edge of the Internet Explorer main window.
put_Left | Sets the horizontal position of the Internet Explorer main window.
get_Top | Returns the screen coordinate of the top edge of the Internet Explorer main window.
put_Top | Sets the vertical position of the Internet Explorer main window.
get_Width | Returns the width of the Internet Explorer main window.
put_Width | Sets the width of the Internet Explorer main window.
get_Height | Returns the height of the Internet Explorer main window.
put_Height | Sets the height of the Internet Explorer main window.
get_LocationName | Returns the name of the resource that WebBrowser is currently displaying.
get_LocationURL | Returns the URL of the resource that WebBrowser is currently displaying.
get_Busy | Returns a value indicating whether a download or other activity is still in progress.
Quit | Closes the Internet Explorer application. (Internet Explorer only)
ClientToWindow | Converts the client coordinates of a point to window coordinates. (Internet Explorer only)
PutProperty | Sets the value of a property associated with the given object. (Internet Explorer only)
GetProperty | Retrieves the current value of a property associated with the given object. (Internet Explorer only)
get_Name | Returns the name of the object that contains the WebBrowser control used by Internet Explorer. (Internet Explorer only)
get_HWND | Returns the window handle to the Internet Explorer main window. (Internet Explorer only)
get_FullName | Returns the full path of the file that Internet Explorer is currently displaying. (Internet Explorer only)
get_Path | Returns a string that evaluates to the full path of the resource that Internet Explorer is currently displaying. (Internet Explorer only)
get_Visible | Returns a value indicating whether the object is visible or hidden.
put_Visible | Sets a value indicating whether the object is visible or hidden.
get_StatusBar | Returns a value that indicates whether the status bar is visible.
put_StatusBar | Sets a value that determines whether the status bar is visible.
get_StatusText | Returns the text of the status bar.
put_StatusText | Sets the text for the status bar.
get_ToolBar | Returns a value that indicates whether the toolbar is visible.
put_ToolBar | Sets a value that determines whether the toolbar is visible.
get_MenuBar | Returns a value that indicates whether the menu bar is visible.
put_MenuBar | Sets a value that determines whether the menu bar is visible.
get_FullScreen | Returns a value indicating whether Internet Explorer is in full-screen or normal window mode.
put_FullScreen | Sets a value that determines whether Internet Explorer is in full-screen or normal window mode.
Navigate2 | Navigates to a resource identified by a pointer to an item identifier list (PIDL).
QueryStatusWB | Queries the object for status of commands.
ExecWB | Executes a command.
ShowBrowserBar | Shows or hides a specified browser bar.
get_ReadyState | Returns a standard OLE ReadyState bindable property for the WebBrowser control.
get_Offline | Returns a value that determines whether the control is offline.
put_Offline | Sets a value that determines whether the control is offline.
get_Silent | Returns a value indicating whether any dialog boxes can be shown.
put_Silent | Sets a value indicating whether any dialog boxes can be shown.
get_RegisterAsBrowser | Returns a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.
put_RegisterAsBrowser | Sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.
get_RegisterAsDropTarget | Returns a value indicating whether the WebBrowser control is registered as a drop target for navigation.
put_RegisterAsDropTarget | Sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.
get_TheaterMode | Retrieves a value indicating whether the WebBrowser control is in theater mode.
put_TheaterMode | Sets a value indicating whether the WebBrowser control is in theater mode.
get_AddressBar | Determines if the Internet Explorer object's address bar is visible.
put_AddressBar | Shows or hides the Internet Explorer object's address bar.
get_Resizable | Retrieves the Internet Explorer object's resizable property.
put_Resizable | Sets the Internet Explorer object's resizable property.


IWebBrowser2::ClientToWindow

HRESULT ClientToWindow(
    int FAR* pcx,
    int FAR* pcy
);

Converts the client coordinates of a point to window coordinates. Client coordinates are relative to the upper-left corner of the client area; window coordinates are relative to the upper-left corner of a window.

  • Returns S_OK to indicate that the operation was successful.
pcx
The x-coordinate of the point to convert, in client coordinates. When ClientToWindow returns, this variable contains the x-coordinate of the point in window coordinates.
pcy
The y-coordinate of the point to convert, in client coordinates. When ClientToWindow returns, this variable contains the y-coordinate of the point in window coordinates.

Applies To

Internet Explorer


IWebBrowser2::ExecWB

HRESULT ExecWB(
    [in] OLECMDID cmdID,
    [in] OLECMDEXECOPT cmdexecopt,
    [in] VARIANT * pvaIn,
    [out, in] VARIANT * pvaOut)

Implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

cmdID
OLECMDID value that specifies the command to execute.
cmdexecopt
OLECMDEXECOPT value that specifies the command options.
pvaIn
Address of a VARIANT structure that specifies command input arguments. This argument may be NULL.
pvaOut
Address of a VARIANT structure that receives command output. This argument may be NULL.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::QueryStatusWB


IWebBrowser2::GetProperty

HRESULT GetProperty(
    BSTR szProperty,
    VARIANT FAR* pvtValue
);

Retrieves the value of a property associated with the given object.

  • Returns S_OK if the operation is successful, or E_INVALIDARG if one or more parameters are invalid.
szProperty
Caller-allocated buffer that contains the name of the property to retrieve.
pvtValue
Address of a variable that receives the value associated with the given property.

Applies To

Internet Explorer

See also IWebBrowser2::PutProperty


IWebBrowser2::GoBack

HRESULT GoBack(void);

Navigates backward one item in the history list.

  • Returns S_OK to indicate that the operation was successful.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::GoForward, IWebBrowser2::GoHome, IWebBrowser2::GoSearch


IWebBrowser2::GoForward

HRESULT GoForward(void);

Navigates forward one item in the history list.

  • Returns S_OK to indicate that the operation was successful.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::GoBack, IWebBrowser2::GoHome, IWebBrowser2::GoSearch


IWebBrowser2::GoHome

HRESULT GoHome(void);

Navigates to the current home or start page, as specified in the Internet Explorer Options dialog box and Internet Control Panel.

  • Returns S_OK to indicate that the operation was successful.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::GoBack, IWebBrowser2::GoForward, IWebBrowser2::GoSearch


IWebBrowser2::GoSearch

HRESULT GoSearch(void);

Navigates to the current search page, as specified in the Internet Explorer Options dialog box and Internet Control Panel.

  • Returns S_OK to indicate that the operation was successful.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::GoBack, IWebBrowser2::GoForward, IWebBrowser2::GoHome


IWebBrowser2::Navigate

HRESULT IWebBrowser2::Navigate(
    BSTR URL,
    VARIANT FAR* Flags,
    VARIANT FAR* TargetFrameName,
    VARIANT FAR* PostData,
    VARIANT FAR* Headers,
);

Navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_INVALIDARG | One or more parameters are invalid.
    E_OUTOFMEMORY | Out of memory.
URL
A caller-allocated string that contains the URL to navigate to or the full path of the file to display.
Flags
Address of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the BrowserNavConstants enumeration.
TargetFrameName
Address of a string that contains the name of the frame in which to display the resource.
PostData
Address of data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, Navigate issues an HTTP GET transaction. This parameter is ignored if URL is not an HTTP URL.
Headers
Address of a value that specifies the HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if URL is not an HTTP URL.

The post data specified by PostData is passed as a SAFEARRAY structure. The variant should be of type VT_ARRAY and point 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.

Applies To

WebBrowser, Internet Explorer

See also DWebBrowserEvents2::BeforeNavigate2, DWebBrowserEvents2::NavigateComplete2


IWebBrowser2::Navigate2

HRESULT Navigate2(
    [in] VARIANT * URL,
    [in, optional] VARIANT * Flags,
    [in, optional] VARIANT * TargetFrameName,
    [in, optional] VARIANT * PostData,
    [in, optional] VARIANT * Headers,
);

Navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Windows shell namespace.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_INVALIDARG | One or more parameters are invalid.
    E_OUTOFMEMORY | Out of memory.
URL
A caller-allocated string that contains the URL to navigate to or the full path of the file to display.
Flags
Address of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window. The variable can be a combination of the values defined by the BrowserNavConstants enumeration.
TargetFrameName
Address of a string that contains the name of the frame in which to display the resource.
PostData
Address of data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, the Navigate2 method issues an HTTP GET transaction. This parameter is ignored if URL is not an HTTP URL.
Headers
Address of a value that specifies the HTTP headers to send to the server. These headers are added to the default Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if URL is not an HTTP URL.

This method extends the Navigate method to allow for shell integration; however, the original Navigate method can still be used for URL navigations (Navigate2 does not make Navigate obsolete).

The post data specified by PostData is passed as a SAFEARRAY structure. The variant should be of type VT_ARRAY and point 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.

Applies To

WebBrowser, Internet Explorer

See also DWebBrowserEvents2::BeforeNavigate2, DWebBrowserEvents2::NavigateComplete2


IWebBrowser2::PutProperty

HRESULT PutProperty(
    BSTR szProperty,
    VARIANT vtValue
);

Sets the value of a property associated with the given object.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_INVALIDARG | One or more parameters are invalid.
    E_OUTOFMEMORY | Out of memory.
szProperty
Caller-allocated buffer that contains the name of the property to set.
vtValue
New value for the given property.

Applies To

Internet Explorer

See also IWebBrowser2::GetProperty


IWebBrowser2::QueryStatusWB

HRESULT QueryStatusWB(
    [in] OLECMDID nCmdID,
    [out, retval] OLECMDF *pcmdf
);

Implements a wrapper that allows you to query an OLE object for status of commands using the IOleCommandTarget::QueryStatus method.

nCmdID
OLECMDID value of the command for which the caller needs status information.
pcmdf
Address of an OLECMDF value that receives the status of the command.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::ExecWB


IWebBrowser2::Quit

HRESULT Quit(void);

Closes the Internet Explorer application.

  • Returns S_OK to indicate that the operation was successful.

Applies To

Internet Explorer


IWebBrowser2::Refresh

HRESULT Refresh(void);

Reloads the file that Internet Explorer is currently displaying.

  • Returns S_OK if successful, or E_FAIL otherwise.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::Refresh2

HRESULT Refresh2(
    VARIANT FAR* Level
);

Reloads the file that Internet Explorer is currently displaying. Unlike IWebBrowser2::Refresh, this method contains a parameter that specifies the refresh level.

  • Returns S_OK if successful, or E_FAIL otherwise.
Level
Address of a variable that specifies the level of refresh operation to perform. The variable can contain a type defined by the RefreshConstants enumeration.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::ShowBrowserBar

HRESULT ShowBrowserBar(
    VARIANT FAR* pvaClsid,
    VARIANT FAR* pvarShow,
    VARIANT FAR* pvarSize
);

Shows or hides a specified browser bar.

  • Returns S_OK if successful, or E_FAIL otherwise.
pvaClsid
Address of a string VARIANT that contains the class identifier of the browser bar to show or hide. This object must be registered as an Explorer Bar object with the CATID_InfoBand component category. For more information, see Band Objects.
pvarShow
Address of a BOOL VARIANT that specifies if the browser bar should be shown or hidden. If this is nonzero, the browser bar is shown. If this is zero, the browser bar is hidden.
pvarSize
Not currently used.

Applies To

Internet Explorer


IWebBrowser2::Stop

HRESULT Stop(void);

Cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.

  • Returns S_OK to indicate that the operation was successful.

Applies To

WebBrowser, Internet Explorer

See also DWebBrowserEvents2::BeforeNavigate2, DWebBrowserEvents2::DownloadBegin, DWebBrowserEvents2::ProgressChange, IWebBrowser2::Quit, IWebBrowser2::Refresh


IWebBrowser2::get_AddressBar

HRESULT get_AddressBar(
    VARIANT_BOOL FAR* pValue
);

Determines if the Internet Explorer object's address bar is visible.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pValue
Address of a variable that receives a nonzero value if the address bar is visible, or zero if it is not visible.

Applies To

Internet Explorer

See also IWebBrowser2::put_AddressBar


IWebBrowser2::get_Application

HRESULT get_Application(
    IDispatch * FAR* ppDisp
);

Retrieves the automation interface supported by the Internet Explorer application.

  • Returns S_OK if successful, or E_NOINTERFACE if the interface is not supported.
ppDisp
Address of a variable that receives the pointer to the application's IDispatch interface.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Container, IWebBrowser2::get_Document, IWebBrowser2::get_Parent


IWebBrowser2::get_Busy

HRESULT get_Busy(
    VARIANT_BOOL FAR* pBool
);

Discovers whether Internet Explorer is engaged in a downloading operation or other activity.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pBool
Address of a variable that receives TRUE if Internet Explorer is busy, or FALSE if not.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_Container

HRESULT get_Container(
    IDispatch * FAR* ppDisp
);

Retrieves a pointer to the IDispatch interface of the container.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_NOINTERFACE | The interface is not supported.
ppDisp
Address of a variable that receives the pointer to the container's IDispatch interface.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Application, IWebBrowser2::get_Document, IWebBrowser2::get_Parent


IWebBrowser2::get_Document

HRESULT get_Document(
    IDispatch * FAR* ppDisp
);

Retrieves a pointer to the IDispatch interface of the Active Document object.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_INVALIDARG | One or more parameters are invalid.
    E_NOINTERFACE | The interface is not supported.
ppDisp
Address of a variable that receives the pointer to the object's IDispatch interface.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Application, IWebBrowser2::get_Container, IWebBrowser2::get_Parent


IWebBrowser2::get_FullName

HRESULT get_FullName(
    BSTR FAR* pbstrFullName
);

Retrieves the fully qualified path of the Internet Explorer executable file.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_OUTOFMEMORY | Out of memory.
pbstrFullName
Address of a callee-allocated buffer that receives the path of the executable file. The caller frees this buffer with the SysFreeString API.

Applies To

Internet Explorer, WebBrowser


IWebBrowser2::get_FullScreen

HRESULT get_FullScreen(
    VARIANT_BOOL FAR* pbFullScreen
);

Determines if Internet Explorer is in full-screen or normal window mode.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbFullScreen
Address of a variable that receives TRUE if Internet Explorer is in full-screen mode, or FALSE if it is in normal window mode.

In full-screen mode, the Internet Explorer main window is maximized and the status bar, toolbar, menu bar, and title bar are hidden.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::put_FullScreen


IWebBrowser2::get_Height

HRESULT get_Height(
    long FAR* pl
);

Retrieves the height of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
pl
Address of a variable that receives the height, in pixels, of the main window.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Width, IWebBrowser2::put_Height


IWebBrowser2::get_HWND

HRESULT get_HWND(
    long FAR* pHWND
);

Retrieves the handle to the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
pHWND
Address of a variable that receives the window handle.

Applies To

Internet Explorer


IWebBrowser2::get_Left

HRESULT get_Left(
    long FAR* pl
);

Retrieves the screen coordinate of the left edge of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
pl
Address of a variable that receives the screen coordinate of the main window's left edge.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Top, IWebBrowser2::put_Left


IWebBrowser2::get_LocationName

HRESULT get_LocationName(
    BSTR FAR* pbstrLocationName
);

Retrieves the name of the resource that Internet Explorer is currently displaying.

  • Returns S_OK if the operation was successful.
pbstrLocationName
Address of a callee-allocated buffer that receives the name of the location. The caller frees this buffer with the SysFreeString API.

If the resource is an HTML page on the World Wide Web, the name is the title of that page. If the resource is a folder or file on the network or local computer, the name is the UNC or full path of the folder or file.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::get_LocationURL


IWebBrowser2::get_LocationURL

HRESULT get_LocationURL(
    BSTR FAR* pbstrLocationURL
);

Retrieves the URL of the resource that Internet Explorer is currently displaying.

  • Returns S_OK if the operation was successful.
pbstrLocationURL
Address of a callee-allocated buffer that receives the URL. The caller frees this buffer with the SysFreeString API.

If the resource is a folder or file on the network or local computer, the name is the UNC or full path of the folder or file.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::get_LocationName


IWebBrowser2::get_MenuBar

HRESULT get_MenuBar(
    VARIANT_BOOL FAR* Value
);

Returns a value that indicates whether the Internet Explorer menu bar is visible.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
Value
Address of a variable that receives TRUE if the menu bar is visible, or FALSE if it is not.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::put_MenuBar


IWebBrowser2::get_Name

HRESULT get_Name(
    BSTR FAR* pbstrName
);

Retrieves the name of the object that contains the WebBrowser control used by Internet Explorer.

  • Returns S_OK if the operation was successful.
pbstrName
Address of a callee-allocated buffer that receives the name of the object that contains the WebBrowser control. The caller frees this buffer with the SysFreeString API.

Applies To

Internet Explorer


IWebBrowser2::get_Offline

HRESULT get_Offline(
    VARIANT_BOOL FAR* pbOffline
);

Returns a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbOffline
Address of a variable that receives TRUE if WebBrowser is offline, or FALSE if not.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_Parent

HRESULT get_Parent(
    IDispatch * FAR* ppDisp
);

Retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_NOINTERFACE | The interface is not supported.
ppDisp
Address of a variable that receives the pointer to the container's IDispatch interface.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Application, IWebBrowser2::get_Container, IWebBrowser2::get_Document


IWebBrowser2::get_Path

HRESULT get_Path(
    BSTR FAR* pbstrPath
);

Retrieves the full path of the Internet Explorer application.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_OUTOFMEMORY | Out of memory.
pbstrPath
Address of a callee-allocated buffer that receives the full path. The caller frees this buffer with the SysFreeString API.

Applies To

Internet Explorer


IWebBrowser2::get_ReadyState

HRESULT get_ReadyState(
    [retval, out] long *plReadyState
);

Retrieves the ready state of the object.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
plReadyState
Address of a long variable that receives the ReadyState property. This will be one of the READYSTATE values.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_RegisterAsBrowser

HRESULT get_RegisterAsBrowser(
    VARIANT_BOOL FAR* pbRegister
);

Returns a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbRegister
Boolean expression that determines whether the object is registered as a top-level browser. If TRUE, the WebBrowser is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_RegisterAsDropTarget

HRESULT get_RegisterAsDropTarget(
    VARIANT_BOOL FAR* pbRegister
);

Returns a value indicating whether the WebBrowser control is registered as a drop target for navigation.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbRegister
Optional. A Boolean expression that determines whether the object is registered as a drop target for navigation. If TRUE, the object is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_Resizable

HRESULT get_Resizable(
    VARIANT_BOOL FAR* pValue
);

Retrieves the Internet Explorer object's resizable property.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pValue
Address of a variable that receives a nonzero value if the object is resizable or zero if it is not resizable.

Applies To

Internet Explorer

See also IWebBrowser2::put_Resizable


IWebBrowser2::get_Silent

HRESULT get_Silent(
    VARIANT_BOOL FAR* pbSilent
);

Returns a value indicating whether any dialog boxes can be shown.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbSilent
Optional. A Boolean expression that determines whether the WebBrowser can show any dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_StatusBar

HRESULT get_StatusBar(
    VARIANT_BOOL FAR* pBool
);

Returns a value that indicates whether the Internet Explorer status bar is visible.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pBool
Address of a variable that receives TRUE if the status bar is visible, or FALSE if it is not.

Applies To

Internet Explorer

See also IWebBrowser2::put_StatusBar


IWebBrowser2::get_StatusText

HRESULT get_StatusText(
    BSTR FAR* pbstr
);

Retrieves the text of the Internet Explorer status bar.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbstr
Address of a callee-allocated buffer that receives the text of the status bar. The caller frees this buffer with the SysFreeString API.

Applies To

Internet Explorer

See also IWebBrowser2::put_StatusText


IWebBrowser2::get_TheaterMode

HRESULT get_TheaterMode(
    VARIANT_BOOL FAR* pbTheaterMode
);

Retrieves a value indicating whether the WebBrowser control is in theater mode.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbTheaterMode
Optional. A Boolean value that receives the TheaterMode property. If this value is nonzero, the WebBrowser is in theater mode. If this value is zero, the WebBrowser is not in theater mode. The default value is zero.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_ToolBar

HRESULT get_ToolBar(
    int FAR* pValue
);

Retrieves a value that indicates whether the Internet Explorer toolbar is visible.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pValue
Address of a variable that receives TRUE if the toolbar is visible, or FALSE if it is not.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::put_ToolBar


IWebBrowser2::get_Top

HRESULT get_Top(
    long FAR* pl
);

Retrieves the screen coordinate of the top edge of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
pl
Address of a variable that receives the screen coordinate of the main window's top edge.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Left, IWebBrowser2::put_Top


IWebBrowser2::get_TopLevelContainer

HRESULT get_TopLevelContainer(
    VARIANT_BOOL FAR* pBool
);

Determines if Internet Explorer is the top-level container of the WebBrowser control.

  • Returns S_OK to indicate that the operation was successful.
pBool
Address of a variable that receives TRUE if the container is a top-level container, or FALSE otherwise.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::get_Type

HRESULT get_Type(
    BSTR FAR* pbstrType
);

Retrieves the type name of the contained document object.

  • Returns one of these values:
    S_OK | The operation was successful.
    E_FAIL | The operation failed.
    E_OUTOFMEMORY | Out of memory.
pbstrType
Address of a callee-allocated buffer that receives the type name. The caller frees this buffer with the SysFreeString API.

Applies To

Internet Explorer, WebBrowser


IWebBrowser2::get_Visible

HRESULT get_Visible(
    VARIANT_BOOL FAR* pBool
);

Determines whether the object is visible or hidden.

  • Returns S_OK to indicate that the operation was successful.
pBool
Address of a variable that receives TRUE if the object is visible, or FALSE if it is hidden.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::put_Visible


IWebBrowser2::get_Width

HRESULT get_Width(
    long FAR* pl
);

Retrieves the width of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
pl
Address of a variable that receives the width, in pixels, of the main window.

Applies To

Internet Explorer

See also IWebBrowser2::get_Height, IWebBrowser2::put_Width


IWebBrowser2::put_AddressBar

HRESULT put_AddressBar(
    VARIANT_BOOL FAR* pValue
);

Shows or hides the Internet Explorer object's address bar.

  • Returns S_OK if the operation was successful, or an OLE-defined error code otherwise.
pValue
Address of a variable that contains a nonzero value if the address bar is to be shown, or zero if it is to be hidden.

Applies To

Internet Explorer

See also IWebBrowser2::get_AddressBar


IWebBrowser2::put_FullScreen

HRESULT put_FullScreen(
    VARIANT_BOOL bFullScreen
);

Sets Internet Explorer to either full-screen or normal window mode.

  • Returns S_OK to indicate that the operation was successful.
bFullScreen
Full-screen flag. If this parameter is TRUE, Internet Explorer is set to full-screen mode; if FALSE, it is set to normal window mode.

In full-screen mode, the Internet Explorer main window is maximized and the status bar, toolbar, menu bar, and title bar are hidden.

The WebBrowser object ignores this property.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_FullScreen


IWebBrowser2::put_Height

HRESULT put_Height(
    long Height
);

Sets the height of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
Height
Height, in pixels, of the main window.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Height, IWebBrowser2::put_Width


IWebBrowser2::put_Left

HRESULT put_Left(
    long Left
);

Sets the horizontal position of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
Left
Screen coordinate of the left edge of the main window.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Left, IWebBrowser2::put_Top


IWebBrowser2::put_MenuBar

HRESULT put_MenuBar(
    VARIANT_BOOL Value
);

Shows or hides the Internet Explorer menu bar.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
Value
Show flag. A value of TRUE shows the menu bar; a value of FALSE hides it.

The WebBrowser object ignores this property.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_MenuBar


IWebBrowser2::put_Offline

HRESULT put_Offline(
    VARIANT_BOOL pbOffline
);

Sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbOffline
Address of a variable that receives the Offline flag. If this parameter is TRUE, the WebBrowser control is reading from the local cache. If this parameter is FALSE, the control will attempt to read from the source document.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::put_RegisterAsBrowser

HRESULT put_RegisterAsBrowser(
    VARIANT_BOOL bRegister
);

Sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
bRegister
Boolean expression that determines whether Internet Explorer is registered as a top-level browser. If TRUE, the WebBrowser is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::put_RegisterAsDropTarget

HRESULT put_RegisterAsDropTarget(
    VARIANT_BOOL bRegister
);

Sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
bRegister
Optional. A Boolean expression that determines if the object is registered as a drop target for navigation. If TRUE, the object is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::put_Resizable

HRESULT put_Resizable(
    VARIANT_BOOL FAR* pValue
);

Sets the Internet Explorer object's resizable property.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pValue
Address of a variable that contains a nonzero value if the object is resizable, or zero if it is not resizable.

Applies To

Internet Explorer

See also IWebBrowser2::get_Resizable


IWebBrowser2::put_Silent

HRESULT put_Silent(
    VARIANT_BOOL FAR* pbSilent
);

Sets a value indicating whether any dialog boxes can be shown.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pbSilent
Optional. A Boolean expression that determines whether the object can show any dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::put_StatusBar

HRESULT put_StatusBar(
    VARIANT_BOOL Value
);

Shows or hides the Internet Explorer status bar.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
Value
Show flag. A value of TRUE shows the status bar; a value of FALSE hides it.

The WebBrowser object ignores this property.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::get_StatusBar


IWebBrowser2::put_StatusText

HRESULT put_StatusText(
    BSTR bstr
);

Sets the text of the Internet Explorer status bar.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
bstr
Status bar text.

The WebBrowser object ignores this property.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::get_StatusText


IWebBrowser2::put_TheaterMode

HRESULT put_TheaterMode(
    VARIANT_BOOL bTheaterMode
);

Sets the TheaterMode property for the WebBrowser control.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
bTheaterMode
Optional. A Boolean value that contains the TheaterMode property. If this value is nonzero, the WebBrowser changes to theater mode. If this value is zero, the WebBrowser is taken out of theater mode. The default value is zero.

The WebBrowser object ignores this property.

Applies To

WebBrowser, Internet Explorer


IWebBrowser2::put_ToolBar

HRESULT put_ToolBar(
    int Value
);

Shows or hides the Internet Explorer toolbar.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
Value
Show flag. A value of TRUE shows the toolbar; a value of FALSE hides it.

The WebBrowser object ignores this property.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_ToolBar


IWebBrowser2::put_Top

HRESULT put_Top(
    long Top
);

Sets the vertical position of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
Top
Screen coordinate of the top edge of the main window.

Applies To

WebBrowser, Internet Explorer

See also IWebBrowser2::get_Top, IWebBrowser2::put_Left


IWebBrowser2::put_Visible

HRESULT put_Visible(
    VARIANT_BOOL Value
);

Sets the visibility state of the object.

  • Returns S_OK to indicate that the operation was successful.
Value
Visibility flag. If this parameter is TRUE, the object is visible; if FALSE, it is hidden.

Applies To

Internet Explorer, WebBrowser

See also IWebBrowser2::get_Visible


IWebBrowser2::put_Width

HRESULT put_Width(
    long Width
);

Sets the width of the Internet Explorer main window.

  • Returns S_OK to indicate that the operation was successful.
Width
Width, in pixels, of the main window.

Applies To

Internet Explorer

See also IWebBrowser2::get_Width, IWebBrowser2::put_Height


Events Events *
  * Previous Topic: IWebBrowser2::put_Width
  * Next Topic: DWebBrowserEvents2

Events

This section describes the event methods exposed by the DWebBrowserEvents2 interface.


DWebBrowserEvents2

DWebBrowserEvents2 designates an event sink interface that an application must implement in order to receive event notifications from a WebBrowser control or from the Internet Explorer application.

Methods in Vtable Order

DWebBrowserEvents2 methods | Description
StatusTextChange | Occurs when the status bar text has changed.
ProgressChange | Occurs when the progress of a download operation is updated.
CommandStateChange | Occurs when the enabled state of a command changes.
DownloadBegin | Occurs when a navigation operation is beginning, shortly after the BeforeNavigate2 event, unless the navigation is canceled.
DownloadComplete | Occurs when a navigation operation finishes, is halted, or fails.
TitleChange | Occurs when the title of a document in the WebBrowser control becomes available or changes.
PropertyChange | Occurs when the IWebBrowser2::PutProperty method changes the value of a property.
BeforeNavigate2 | Occurs when the WebBrowser control is about to navigate to a new URL.
NewWindow2 | Occurs when a new window is to be created for displaying a resource.
NavigateComplete2 | Occurs after the browser has successfully navigated to a new location.
DocumentComplete | Occurs when the document being navigated to is ready.
OnQuit | Occurs when the Internet Explorer application is ready to quit.
OnVisible | Occurs when the window for the WebBrowser should be shown/hidden.
OnToolBar | Occurs when the ToolBar property has changed.
OnMenuBar | Occurs when the MenuBar property has changed.
OnStatusBar | Occurs when the StatusBar property has changed.
OnFullScreen | Occurs when the FullScreen property has changed.
OnTheaterMode | Occurs when the TheaterMode property has changed.


DWebBrowserEvents2::BeforeNavigate2

void BeforeNavigate2(
    [in] IDispatch* pDisp,
    [in] VARIANT* URL,
    [in] VARIANT* Flags,
    [in] VARIANT* TargetFrameName,
    [in] VARIANT* PostData,
    [in] VARIANT* Headers,
    [out] VARIANT_BOOL* Cancel
);

Fires before a navigation occurs in the given WebBrowser (on either a window or frameset element).

  • No return value.
pDisp
Address of the frame's IDispatch interface.
URL
URL to be navigated to.
Flags
Reserved for future use.
TargetFrameName
String that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData
Address of data to send to the server if the HTTP POST transaction is being used.
Headers
Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code.
Cancel
Address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.

The pDisp parameter is that of the top-level or frame WebBrowser object corresponding to the navigation. The processing of this navigation can be modified by setting the Cancel parameter to TRUE and either ignoring or reissuing a modified navigation method to the WebBrowser object. The URL parameter can be a PIDL in the case of a shell namespace entity for which there is no URL representation.

The post data specified by PostData is passed as a SAFEARRAY structure. The variant should be of type VT_ARRAY and point 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.

This event replaces the BeforeNavigate and FrameBeforeNavigate events, which should no longer be used. Internet Explorer 4.0 will continue to fire the BeforeNavigate and FrameBeforeNavigate events for compatibility with Internet Explorer 3.0.

Providing the pDisp pointer of the corresponding WebBrowser object gives the host better information and control over the Internet Explorer 3.0 specification, which used FrameBeforeNavigate and a target frame name to identify the target of navigation (target frame names are not unique).

Applies To

WebBrowser, Internet Explorer

See also DWebBrowserEvents2::NavigateComplete2, IWebBrowser2::Navigate2


DWebBrowserEvents2::CommandStateChange

void CommandStateChange(
    [in] long Command,
    [in] VARIANT_BOOL Enable
);

Notifies an application that the enabled state of a WebBrowser command has changed.

  • No return value.
Command
Identifier of the command whose enabled state has changed.
Enable
Enabled state. This parameter is TRUE if the command is enabled, or FALSE if it is disabled.


DWebBrowserEvents2::DocumentComplete

void DocumentComplete(
    [in] IDispatch* pDisp,
    [in] Variant * URL
);

Notifies an application that a document has reached the READYSTATE_COMPLETE state.

  • Returns S_OK to indicate that the operation was successful.
pDisp
Address of the frame's IDispatch interface. In the case of a document that contains multiple frames, each frame will fire this event. The top-level frame will fire this event after each subframe is completed.
URL
String expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by DocumentComplete would be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

The URL parameter can be a PIDL in the case of a shell namespace entity for which there is no URL representation.

Not every frame will fire this event, but each frame that fires a DownloadBegin event will fire a corresponding DocumentComplete event.

Applies To

WebBrowser, Internet Explorer

See also READYSTATE


DWebBrowserEvents2::DownloadBegin

void DownloadBegin(void);

Notifies an application that a navigation operation is beginning.

  • No return value.

This event is fired shortly after the BeforeNavigate2 event, unless the navigation is canceled. Any animation or "busy" indication that the container needs to display should be connected to this event.

Each DownloadBegin event will have a corresponding DownloadComplete event.


DWebBrowserEvents2::DownloadComplete

void DownloadComplete(void);

Occurs when a navigation operation finishes, is halted, or fails.

  • No return value.

Unlike NavigateComplete2, which is fired only when a URL is successfully navigated to, this event is always fired after a navigation starts. Any animation or "busy" indication that the container needs to display should be connected to this event.

Each DownloadBegin event will have a corresponding DownloadComplete event.

See also DWebBrowserEvents2::DownloadBegin


DWebBrowserEvents2::NavigateComplete2

void NavigateComplete2(
    [in] IDispatch* pDisp,
    [in] Variant * URL
);

Fires after a navigation to a hyperlink is completed (on either a window or frameset element).

  • Returns S_OK to indicate that the operation was successful.
pDisp
Address of the frame's IDispatch interface.
URL
String expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by NavigateComplete2 would be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

The URL parameter can be a PIDL in the case of a shell namespace entity for which there is no URL representation.

This event replaces the NavigateComplete and FrameNavigateComplete events, which should no longer be used. Internet Explorer 4.0 continues to fire the NavigateComplete and FrameNavigateComplete events for compatibility with Internet Explorer 3.0.

Applies To

WebBrowser, Internet Explorer


DWebBrowserEvents2::NewWindow2

void NewWindow2(
    [out] IDispatch** ppDisp,
    [out] VARIANT_BOOL * Cancel
);

Occurs when a new window is to be created for displaying a resource. This event precedes the creation of a new window from within the WebBrowser (for example, in response to a navigation targeted to a new window, or to a scripted window.open method).

ppDisp
Address of an interface pointer that, optionally, receives the IDispatch interface pointer of a new WebBrowser or InternetExplorer object.
Cancel
Address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.

The application processing this notification can respond in one of three ways:

  1. Create a new, hidden, non-navigated WebBrowser or InternetExplorer object that is returned in ppDisp. Upon return from this event, the object that fired this event will then configure and navigate (including a BeforeNavigate2 event) the new object to the target location.
  2. Cancel the new window creation by setting Cancel to TRUE. No object is created and the navigation is attempted on the current window (with an accompanying BeforeNavigate2 event).
  3. Do nothing and do not set ppDisp to any value. This will cause the object that fired the event to create a new InternetExplorer object to handle the navigation.

Applies To

WebBrowser, Internet Explorer


DWebBrowserEvents2::OnFullScreen

void OnFullScreen(
    [in] VARIANT_BOOL FullScreen
);

Occurs when the FullScreen property has changed.

FullScreen
Nonzero if Internet Explorer is in full-screen mode, or zero otherwise.

Applies To

Internet Explorer


DWebBrowserEvents2::OnMenuBar

void OnMenuBar(
    [in] VARIANT_BOOL MenuBar
);

Occurs when the MenuBar property is changed.

MenuBar
Nonzero if Internet Explorer's menu bar is visible, or zero otherwise.

Applies To

Internet Explorer


DWebBrowserEvents2::OnQuit DWebBrowserEvents2::OnQuit *
  * Previous Topic: DWebBrowserEvents2::OnMenuBar
  * Next Topic: DWebBrowserEvents2::OnStatusBar

DWebBrowserEvents2::OnQuit

void OnQuit(void);

Notifies an application that the Internet Explorer application is ready to quit.

Applies To

Internet Explorer


DWebBrowserEvents2::OnStatusBar

void OnStatusBar(
    [in] VARIANT_BOOL StatusBar
);

Occurs when the StatusBar property is changed.

StatusBar
Nonzero if Internet Explorer's status bar is visible, or zero otherwise.

Applies To

Internet Explorer


DWebBrowserEvents2::OnTheaterMode

void OnTheaterMode(
    [in] VARIANT_BOOL TheaterMode
);

Occurs when the TheaterMode property is changed.

TheaterMode
Nonzero if Internet Explorer is in theater mode, or zero otherwise.

Applies To

Internet Explorer


DWebBrowserEvents2::OnToolBar

void OnToolBar(
    [in] VARIANT_BOOL ToolBar
);

Occurs when the ToolBar property is changed.

ToolBar
Nonzero if Internet Explorer's toolbar is visible, or zero otherwise.

Applies To

Internet Explorer


DWebBrowserEvents2::OnVisible

void OnVisible(
    [in] VARIANT_BOOL Visible
);

Occurs when the window for the WebBrowser should be shown/hidden. This allows the host window to behave the same way the Internet Explorer window would.

Visible
Nonzero if the object is visible, or zero otherwise.

Applies To

WebBrowser, Internet Explorer


DWebBrowserEvents2::ProgressChange

void ProgressChange(
    [in] long Progress,
    [in] long ProgressMax
);

Notifies an application that the progress of a download operation has been updated.

  • No return value.
Progress
Amount of total progress to show, or -1 when progress is complete.
ProgressMax
Maximum progress value.

The container can use the information provided by this event to display the number of bytes downloaded so far or to update a progress indicator.

To calculate the percentage of progress to show in a progress indicator, multiply the value of Progress by 100 and divide by the value of ProgressMax (unless Progress is -1, in which case the container can indicate that the operation is finished or hide the progress indicator).

See also DWebBrowserEvents2::DownloadBegin, DWebBrowserEvents2::DownloadComplete


DWebBrowserEvents2::PropertyChange

void PropertyChange(
    BSTR szProperty,
);

Notifies an application that the PutProperty method has changed the value of a property.

  • No return value.
szProperty
Caller-allocated buffer that contains the name of the property.

See also IWebBrowser2::GetProperty, IWebBrowser2::PutProperty


DWebBrowserEvents2::StatusTextChange

void StatusTextChange(
    [in] BSTR bstrText
);

Notifies an application that the text of the status bar associated with the WebBrowser control has changed.

  • No return value.
bstrText
String that contains the new status bar text.


DWebBrowserEvents2::TitleChange

void TitleChange(
    [in] BSTR Text
);

Notifies an application if the title of a document in the WebBrowser control becomes available or changes.

  • No return value.
Text
Caller-allocated buffer that contains the new document title.

Because the title might change while an HTML page is downloading, the URL of the document is set as the title. After the title specified in the HTML page, if there is one, is parsed, the title is changed to reflect the actual title.

See also DWebBrowserEvents2::CommandStateChange, DWebBrowserEvents2::StatusTextChange


Enumerations Enumerations *
  * Previous Topic: DWebBrowserEvents2::TitleChange
  * Next Topic: BrowserNavConstants

Enumerations

This section defines enumerations used with the WebBrowser interfaces.


BrowserNavConstants

typedef enum BrowserNavConstants {
    navOpenInNewWindow = 0x1,
    navNoHistory       = 0x2,
    navNoReadFromCache = 0x4,
    navNoWriteToCache  = 0x8
    navAllowAutosearch = 0x10,
    navBrowserBar      = 0x20
} BrowserNavConstants;

Contains values used by the IWebBrowser2::Navigate and IWebBrowser2::Navigate2 methods.

Values
navOpenInNewWindow | Open the resource or file in a new window.
navNoHistory | Do not add the resource or file to the history list. The new page replaces the current page in the list.
navNoReadFromCache | Not used.
navNoWriteToCache | Not used.
navAllowAutosearch | If the navigation fails, the autosearch functionality will attempt to navigate common root domains (.com, .edu, and so on). If this still fails, the URL will be passed to a search engine.
navBrowserBar | Causes the current Explorer Bar to navigate to the given item, if possible.

See also DWebBrowserEvents2::BeforeNavigate2, DWebBrowserEvents2::NavigateComplete2, DWebBrowserEvents2::NewWindow2


CommandStateChangeConstants

typedef enum CommandStateChangeConstants {
    CSC_UPDATECOMMANDS = 0xFFFFFFFF,
    CSC_NAVIGATEFORWARD = 0x00000001,
    CSC_NAVIGATEBACK = 0x00000002
} CommandStateChangeConstants;

Contains values used by the DWebBrowserEvents2::CommandStateChange event.

Values
CSC_UPDATECOMMANDS | The enabled state of a toolbar button might have changed.
CSC_NAVIGATEFORWARD | The enabled state of the Forward button has changed.
CSC_NAVIGATEBACK | The enabled state of the Back button has changed.


READYSTATE

typedef enum tagREADYSTATE{
    READYSTATE_UNINITIALIZED = 0,
    READYSTATE_LOADING = 1,
    READYSTATE_LOADED = 2,
    READYSTATE_INTERACTIVE = 3,
    READYSTATE_COMPLETE = 4
} READYSTATE;

Contains values that indicate what state an object is in. This is used with the ReadyState property and the IWebBrowser2::get_ReadyState method.

Values
READYSTATE_UNINITIALIZED | The default initialization state.
READYSTATE_LOADING | The object is currently loading its properties.
READYSTATE_LOADED | The object has been initialized.
READYSTATE_INTERACTIVE | The object is interactive, but not all of its data is available.
READYSTATE_COMPLETE | The object has received all of its data.


RefreshConstants

typedef enum RefreshConstants {
    REFRESH_NORMAL = 0,
    REFRESH_IFEXPIRED = 1,
    REFRESH_CONTINUE = 2,
    REFRESH_COMPLETELY = 3
} RefreshConstants;

Contains values used with the Refresh2 and IWebBrowser2::Refresh2 methods.

The "pragma:nocache" header tells the server not to return a cached copy but to ensure that the information is as fresh as possible. Browsers typically send this header when the user selects Refresh, but the header can cause problems for some servers.

Values
REFRESH_NORMAL | Perform a lightweight refresh that does not include sending the HTTP "pragma:nocache" header to the server.
REFRESH_IFEXPIRED | Perform a lightweight refresh if the page has expired.
REFRESH_CONTINUE | For internal use only; do not use.
REFRESH_COMPLETELY | Perform a full refresh that includes sending a "pragma:nocache" header to the server (HTTP URLs only).

See also Refresh, IWebBrowser2::Refresh


Reusing MSHTML

IE4/MSHTML is a rendering engine and parser for HTML. It is the main HTML component of the IE4 Web browser and can be reused in other applications. It hosts ActiveX™ Controls and supports the OC96 specification for windowless controls. Controls that use the OC96 interfaces can gain in performance, and they can be transparent and have an irregular shape.

IE4/MSHTML itself is an Active Document, so it may be hosted by implementing the Active Document interfaces in an application. IE4/MSHTML can also be customized by aggregation to create a special-purpose HTML Active Document. Applications that contain IE4/MSHTML supply their own toolbars and menu UI. The container can also override the default context menus.

It is also possible to use IE4/MSHTML without UI activation to make use of IE4/MSHTML's ability to parse HTML. By loading HTML, you can use the object model to access the underlying HTML and modify any elements. COM objects hosted by IE4/MSHTML (such as ActiveX Controls) also have the ability to access the Dynamic HTML object model and, as a result, closely integrate with the IE4/MSHTML container to affect the host.

For many purposes, it is more appropriate to host the WebBrowser control to integrate browsing into an application. The WebBrowser control implements support for in-place linking and navigation in addition to IE4/MSHTML. For additional information on the WebBrowser control, see Reusing the WebBrowser and MSHTML.

Containing IE4/MSHTML

Replacing IE4/MSHTML's User Interface

Substituting User Preferences

Loading HTML and Referenced Data

Automating IE4/MSHTML

Scripts within IE4/MSHTML

Sending and Receiving Commands

Terminology

Containing IE4/MSHTML

IE4/MSHTML can be hosted to form an integral part of an application. There are two ways that this can be done.

  1. Host IE4/MSHTML as an Active Document. IE4/MSHTML is an Active Document and can be hosted in an application that implements the Active Document Hosting interfaces. In this mode of operation, IE4/MSHTML supplies its own UI for context menus to the containing application, although the container can replace the UI, if required, by implementing additional interfaces.
  2. Aggregate IE4/MSHTML to create an Active Document. If a host needs to provide extra services and functionality, but it still needs to be an Active Document for use within another application, it can do so by aggregating IE4/MSHTML. This allows the host to take advantage of IE4/MSHTML's implementation of Active Document server interfaces without having to re-implement them. This still allows the host to wrap IE4/MSHTML to provide additional functionality and its own UI.

Hosting IE4/MSHTML as an Active Document

As an Active Document, IE4/MSHTML follows the standard OLE mechanisms for negotiating with the container for menu merging and displaying its toolbars. IE4/MSHTML supports only the single view implementation of Active Documents. Commands can be sent and received using the IOleCommandTarget interface that is also part of the Active Document specification. The standard NULL command set is supported as well as a set of extended commands specific to IE4/MSHTML.

A host of IE4/MSHTML can turn off IE4/MSHTML's menus and toolbars and supply its own UI. The host may also intercept any of IE4/MSHTML's UI, such as context menus and message boxes. For more information about intercepting UI, see Replacing IE4/MSHTML's User Interface. For more information about implementing an Active Document host, see Programming an Active Document Container.

Aggregating IE4/MSHTML

If your application is using IE4/MSHTML to implement an Active Document that customizes IE4/MSHTML's behavior, a host may aggregate with IE4/MSHTML to create a new class. IE4/MSHTML is designed to support aggregation. Overriding a small number of interfaces can customize much of IE4/MSHTML's behavior.

Creating a new Active Document

The minimum interfaces that need to be supplied by an aggregator are IOleObject and the IPersist* interfaces.

These interfaces supply the object's ClassID and UserType (through IOleObject::GetUserClassID, IOleObject::GetUserType, and IPersist::GetClassID methods). The aggregator should supply its own implementations to differentiate the new object from IE4/MSHTML.

Some common functionality that can be customized by aggregation includes:

  • Commands can be added. Simply override the IOleCommandTarget interface (described later in this document).
  • Automation interfaces can be added. When doing this, be sure to override IProvideClassInfo as well as IDispatch and IConnectionPointContainer (discussed later in this document).

Other customization can be done by supplying services to IE4/MSHTML.

Supplying services and ambient properties when aggregating

IE4/MSHTML provides or uses interfaces that allow an aggregator to supply ambient properties to it without having to implement a full client site for hosting IE4/MSHTML. The site object normally supplies ambient properties, but a site object has a number of other interfaces that are not trivial to implement. Using this technique, the aggregator can let the container's client site pass through to IE4/MSHTML while the aggregator still supplies ambient properties.

Replacing IE4/MSHTML's User Interface

If IE4/MSHTML is tightly integrated into an application, it may be desirable to have the application supply its own menus, toolbars and other UI. To do this, the host can supply optional services to IE4/MSHTML that allow the host to hook into and replace IE4/MSHTML's UI. In implementing these interfaces, a host knows that IE4/MSHTML is the component being hosted and has knowledge of IE4/MSHTML's command set.

When replacing IE4/MSHTML's UI, the host turns off IE4/MSHTML's menus and toolbars and can replace them. This does not involve any negotiation. A host of IE4/MSHTML can display message boxes, Help UI, and all in-place active UI on behalf of IE4/MSHTML by implementing two interfaces, IDocHostUIHandler and IDocHostShowUI.

To replace the menus, toolbars, and other UI for IE4/MSHTML, the host should implement the IDocHostUIHandler interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostUIHandler. If the host does not implement a client site, it can QueryInterface IE4/MSHTML for the ICustomDoc interface and call the ICustomDoc::SetUIHandler method to set IE4/MSHTML's UI handler.

When IDocHostUIHandler is present, IE4/MSHTML delegates a number of IOleInPlaceObject and IOleInPlaceActiveObject methods directly to it, allowing a host to hook into methods such as IOleInPlaceActiveObject::TranslateAccelerator and IOleInPlaceActiveObject::ResizeBorder. Returning S_OK on the IDocHostUIHandler::ShowUI method called by IE4/MSHTML will cause IE4/MSHTML to hide its menus and toolbars and not call the IOleInPlaceFrame methods for menu merging and border space negotiation.

To supply message boxes and Help UI, the host should implement the IDocHostShowUI interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostShowUI. The site object implements both IOleDocumentSite and IOleClientSite.

Substituting User Preferences

As IE4/MSHTML may be used in a number of different host environments, there is a requirement that each host environment be able to set different default user preferences in the registry. IE4/MSHTML allows its host to specify a special registry key under which to store the default preferences.

IE4/MSHTML calls IDocHostUIHandler::GetOptionKeyPath on the host at initialization to allow the host to specify the registry location for the preference settings. IE4/MSHTML then uses this registry key to store and get the settings for its preference property pages. If the host returns S_FALSE for this method, or the returned registry key path is NULL or empty, then IE4/MSHTML will revert to its own default set of options.

Loading HTML and Referenced Data

There are three situations where IE4/MSHTML needs to resolve URLs or load data:

  1. When an HTML page is loaded into IE4/MSHTML. IE4/MSHTML is capable of loading pages from URLs (or any other asynchronous moniker) or from files.
  2. When data (for example, an <IMG> tag) is referred to on the HTML page. A host can optionally supply a service to IE4/MSHTML to assist in resolving these references.
  3. When a hyperlink needs to be followed. IE4/MSHTML invokes the standard hyperlinking API. A host may optionally provide the hyperlinking support so that IE4/MSHTML can link to the new object within the host frame.

Loading an HTML page

For a host to get IE4/MSHTML to load and display the page at a specific URL, the host constructs a moniker using the CreateURLMoniker API call. Then it calls IPersistMoniker::Load on IE4/MSHTML. IE4/MSHTML's implementation of IPersistMoniker is specifically designed to support the loading of data asynchronously over slow links.

More information about these interfaces can be found in the Asynchronous and URL Monikers Overview section of the Internet Client SDK.

IE4/MSHTML is also capable of simple synchronous loading and saving of HTML through IPersistStreamInit or asynchronous loading from a file through IPersistFile.

Resolving Hyperlinks

If a user clicks on a link within an HTML page viewed in IE4/MSHTML, IE4/MSHTML will call the HlinkNavigate API (after having set up an IHlink object). If the host does not implement IHlinkFrame, this API launches a separate application to follow the hyperlink.

Hosts that wish to act as browsers (and navigate within the same frame) can implement IHlinkFrame on the FRAME object. The HlinkNavigate API calls IHlinkFrame::Navigate, allowing a browser application to hide the previous instance of IE4/MSHTML and create, load, and show a new instance of IE4/MSHTML (or other Active Document) to display the new page.

For more information on hyperlinking, see Hyperlinks.

Because the WebBrowser control has built-in support for hyperlinking, hosting the WebBrowser control is the preferred solution here.

Automating IE4/MSHTML

IE4/MSHTML can be automated using IDispatch and IConnectionPointContainer-style automation interfaces. These interfaces allow a host to automate IE4/MSHTML through the object model.

Scripts within IE4/MSHTML

IE4/MSHTML is responsible for loading and running scripts that appear within HTML. Because scripting is done by using the ActiveX Scripting interfaces, any ActiveX script engine can be hosted by IE4/MSHTML.

For more information about ActiveX scripting engines and hosts, see ActiveX Scripting.

Sending and Receiving Commands

Because IE4/MSHTML is an Active Document, it communicates with its host using the IOleCommandTarget interface. With this interface, the following details are communicated to the hosting frame.

  • Menu/Toolbar Enabling – The common menus and toolbar buttons found on the host (Cut, Copy, Paste, and so on) are enabled and disabled by sending IE4/MSHTML commands and queries.
  • IE4/MSHTML Commands – Common functions like Refresh, Stop, and Hide Toolbars are sent by the host to IE4/MSHTML through commands.
  • Status Bar Updates – Progress and status bar text information is communicated to the hosting frame by IE4/MSHTML through commands.

In addition to the standard command group, IE4/MSHTML supports a group of IE4/MSHTML-specific commands that provide simple access to a number of IE4/MSHTML-specific features. For more information, see the OLECMDID enumeration.

Terminology

ActiveX™ Control – Also known as an OLE Control. An ActiveX Control is a contained mini-application. It can (optionally) maintain state, draw itself, persist itself, have its own window, respond to automation methods, throw events, take keyboard focus, respond to mouse and keyboard input, and show merged menu and toolbar UI. Most of the control interfaces are documented in MSDN. The OC96 and OLE Controls/COM Objects for the Internet specifications introduce a number of new interfaces for controls to improve their performance and make them suitable for the Internet. Further extensions supported by IE4/MSHTML are discussed later in this section.

Active Document – Also known as an OLE Document Object or Doc Object. An Active Document is a contained object; the container provides the frame and some basic UI. In such containers, the Active Document may be interchanged with other Active Documents while the containing frame and its UI remain constant. Examples of Active Document containers include the Office Binder and Internet Explorer 3.0x, where the Active Document could change to Microsoft® Word or Excel while maintaining the same outer frame application. An Active Document is similar to an OLE Embedding scenario or an ActiveX Control, but its interfaces are designed to support an object that is at the top level and takes up the entire content area of the frame. There are specific interfaces required to support Active Document functionality. For more information, see Active Documents.

ActiveX Scripting – A standard set of interfaces that allows for language-independent script integration to applications. Any script engine (VBScript, JScript, or a third party scripting language, for example) that supports the standard interfaces can be integrated with an ActiveX script host such as IE4/MSHTML.

IE4/MSHTML – An Active Document that is capable of rendering HTML and laying out contained ActiveX Controls. In this document, it refers to an instance of the IE4/MSHTML COM object that implements IOleObject, IOleDocument, IOleDocumentView, and many other interfaces.

Aggregation – A kind of run-time inheritance. By aggregating, an object can extend and enhance the functionality of another object but still take advantage of the functionality and interfaces of the aggregated object. Objects can be designed to be aggregated or not. IE4/MSHTML is designed to be aggregated.

Site – The object supplied by a container to a contained object through IOleObject::SetClientSite. Containers of an ActiveX object must supply a site before doing anything else. IE4/MSHTML gets much of its information about its geometry, activation, ambient properties, and so on, from its container site. (In this specification, there's no distinction between IE4/MSHTML's container document site and its view site.) IE4/MSHTML also supplies a site for each ActiveX Control it hosts.

Container – The ActiveX object that owns the site obtained through IOleClientSite::GetContainer (may be null). From the container, the contained objects may be enumerated through IOleContainer::EnumObjects. This concept of containment should not be confused with the concept of containment used for scripting and supplied by automation interfaces. Some contained automation objects are not contained ActiveX objects, and some contained ActiveX objects cannot be automated.

Frame – The outer application frame, with menu and toolbar space, supplied to an ActiveX object through IOleInPlaceSite::GetWindowContext. This is the object with which IE4/MSHTML negotiates for menu and toolbar space and also for hyperlinks.

Document Window – The document window, with toolbar space, supplied to an ActiveX object through IOleInPlaceSite::GetWindowContext. (In MDI it is the document window, and in SDI it is NULL.) IE4/MSHTML currently ignores the document window.

Command – A simple action sent to an ActiveX object through the IOleCommandTarget interface. Commands usually correspond to user-level commands, like the commands on menus, and can be enabled or disabled by the command target. A command can be sent to the frame, the container site, IE4/MSHTML, or a control.

Automation – A set of standards to allow an object to be programmed by scripts. Every object that can be automated can have methods and properties that can be used by a script, as well as events that can trigger scripts to be run.

Dispatch Interface – An interface inheriting from IDispatch that is used to access named automation properties and methods of an object from a script.

Event Interface – A callback interface attached to an object using IConnectionPointContainer. Used by script engines to get notification of events thrown by objects.

Type Info – A structure used to specify properties, methods, and events (automatable or otherwise). Can be obtained from a dispatch interface through IDispatch or an object that supplies IProvideClassInfo*.

X Object – An object that IE4/MSHTML wraps around each hosted control to supply common, per-control, container-owned properties and events. IE4/MSHTML aggregates the X object to the control, if possible, and merges types with the control.

Service – A service supplied by the host to an ActiveX object through the IServiceProvider interface on the container site. Each service is identified by a service identifier (SID), allowing access to interfaces and methods.

Ambient – A property owned by the container and supplied to an ActiveX object through the IDispatch interface on its hosting site.


Advanced Hosting Interfaces

This document describes the interfaces used for customizing the behavior of IE4/MSHTML objects. In addition to the interfaces described here, IE4/MSHTML can be customized through a number of interfaces that match IE4/MSHTML's Object Model. For a more general overview of IE4/MSHTML's hosting and extensibility mechanisms, see Reusing MSHTML.

ICustomDoc Interface

IDocHostUIHandler Interface

IDocHostShowUI Interface


ICustomDoc Interface

The ICustomDoc interface is implemented by IE4/MSHTML to allow a host to set IE4/MSHTML's IDocHostUIHandler interface. Normally, IE4/MSHTML will call the host client site's QueryInterface method to obtain the IDocHostUIHandler interface. IE4/MSHTML implements ICustomDoc so that a host that does not implement a client site can still use IE4/MSHTML's UI customization features.

ICustomDoc is derived from IUnknown. The following is the ICustomDoc specific method:
SetUIHandler


ICustomDoc::SetUIHandler

HRESULT SetUIHandler(
    IDocHostUIHandler *pUIHandler
);

Sets IE4/MSHTML's IDocHostUIHandler.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
pUIHandler
Address of the host's IDocHostUIHandler interface.

IE4/MSHTML will release its previous IDocHostUIHandler interface (if one is present) and call pUIHandler's AddRef method.


IDocHostUIHandler Interface

A host can replace the menus, toolbars, and context menus used by IE4/MSHTML by implementing the IDocHostUIHandler interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostUIHandler. This interface has methods that allow IE4/MSHTML to communicate with the host about its UI status.

IDocHostUIHandler is derived from IUnknown. The following are the methods specific to IDocHostUIHandler:
ShowContextMenu
GetHostInfo
ShowUI
HideUI
UpdateUI
EnableModeless
OnDocWindowActivate
OnFrameWindowActivate
ResizeBorder
TranslateAccelerator
GetOptionKeyPath
GetDropTarget
GetExternal
TranslateUrl
FilterDataObject

The following are the structures and enumerations used with the IDocHostUIHandler interface:
DOCHOSTUIINFO
DOCHOSTUIDBLCLK
DOCHOSTUIFLAG


IDocHostUIHandler::EnableModeless

HRESULT EnableModeless(
    BOOL fEnable
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::EnableModeless. Also called when IE4/MSHTML displays modal UI. The host should enable or disable its modeless UI as appropriate.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
fEnable
Indicates if the host's modeless dialog boxes are enabled or disabled. If this value is nonzero, modeless dialog boxes are enabled. If this value is zero, modeless dialog boxes are disabled.


IDocHostUIHandler::FilterDataObject

HRESULT FilterDataObject(
    IDataObject *pDO,
    IDataObject **ppDORet
);

Called on the host by IE4/MSHTML to allow the host to replace IE4/MSHTML's data object. This allows the host to block certain clipboard formats or support additional clipboard formats.

  • Returns S_OK if the data object is replaced, S_FALSE if the data object is not replaced, or an OLE-defined error code if an error occurs.
pDO
Address of the IDataObject interface supplied by IE4/MSHTML.
ppDORet
Address that receives the IDataObject interface pointer supplied by the host. The contents of this parameter should always be initialized to NULL, even if the method fails.


IDocHostUIHandler::GetDropTarget

HRESULT GetDropTarget(
    IDropTarget *pDropTarget,
    IDropTarget **ppDropTarget
);

Called by IE4/MSHTML when it is being used as a drop target to allow the host to supply an alternative IDropTarget.

  • Return Values:
    S_OK | The host wants to replace the IDropTarget with the one specified in ppDropTarget.
    S_FALSE | The host does not want to replace the IDropTarget.
    E_NOTIMPLE | The host has not implemented this method.
pDropTarget
IDropTarget IE4/MSHTML proposes to use.
ppDropTarget
Address of the IDropTarget that receives the IDropTarget interface pointer the host wants to provide.


IDocHostUIHandler::GetExternal

HRESULT GetExternal(
    IDispatch **ppDispatch
);

Called by IE4/MSHTML to obtain the host's IDispatch interface.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
ppDispatch
Address that receives the IDispatch interface pointer of the host application. If the host exposes an automation interface, it can provide a reference to IE4/MSHTML through this parameter. The contents of this parameter should always be initialized to NULL, even if the method fails.


IDocHostUIHandler::GetHostInfo

HRESULT GetHostInfo(
    DOCHOSTUIINFO FAR *pInfo
);

Retrieves the UI capabilities of the IE4/MSHTML host.

  • Returns S_OK If successful, or an OLE-defined error code otherwise.
pInfo
Address of a DOCHOSTUIINFO structure that receives the host's UI capabilities.


IDocHostUIHandler::GetOptionKeyPath

HRESULT GetOptionKeyPath(
    LPOLESTR *pchKey,
    DWORD dwReserved
);

Returns the registry key under which IE4/MSHTML stores user preferences.

  • Returns S_OK if successful, or S_FALSE otherwise. If S_FALSE, IE4/MSHTML will default to its own user options.
pchKey
Address of an LPOLESTR that receives the registry subkey string where the host stores its default options. This subkey will be under the HKEY_CURRENT_USER key. The implementation must allocate this memory using CoTaskMemAlloc. The calling application is responsible for freeing this memory using CoTaskMemFree. Even if the method fails, this parameter should be set to NULL.
dwReserved
Reserved for future use. Not currently used.

If pchKey is null on return from this function, then IE4/MSHTML uses the default location for storing options in the registry.


IDocHostUIHandler::HideUI

HRESULT HideUI(void);

Called when IE4/MSHTML removes its menus and toolbars.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.

If a host displayed menus and toolbars during the call to IDocHostUIHandler::ShowUI, the host should remove them when this method is called. This method is called regardless of the return value from the ShowUI method.


IDocHostUIHandler::OnDocWindowActivate

HRESULT OnDocWindowActivate (
    BOOL fActive
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnDocWindowActivate.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
fActive
Indicates the state of the document window. If this value is nonzero, the window is being activated. If this value is zero, the window is being deactivated.


IDocHostUIHandler::OnFrameWindowActivate

HRESULT OnFrameWindowActivate (
    BOOL fActive
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::OnFrameWindowActivate.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
fActive
Indicates the state of the container's top-level frame window. If this value is nonzero, the window is being activated. If this value is zero, the window is being deactivated.


IDocHostUIHandler::ResizeBorder

HRESULT ResizeBorder(
    LPCRECT prcBorder,
    IOleInPlaceUIWindow FAR *pUIWindow,
    BOOL fFrameWindow
);

Called from the IE4/MSHTML implementation of IOleInPlaceActiveObject::ResizeBorder.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.
prcBorder
New outer rectangle for border space.
pUIWindow
Frame or document window border change.
fFrameWindow
Indicates TRUE if the frame window is calling ResizeBorder, or FALSE otherwise.


IDocHostUIHandler::ShowContextMenu

HRESULT ShowContextMenu(
    DWORD dwID,
    POINT FAR *ppt,
    IUnknown FAR *pcmdtReserved,
    IDispatch FAR *pdispReserved
);

Called from IE4/MSHTML when it is about to show its context menu.

  • Return Values:
    S_OK | Host displayed its own UI. IE4/MSHTML will not attempt to display its UI.
    S_FALSE | Host did not display any UI. IE4/MSHTML will display its UI.
    DOCHOST_E_UNKNOWN | Menu identifier is unknown. IE4/MSHTML may attempt an alternative identifier from a previous version.
dwID
Identifier of the context menu to be displayed.
ppt
Screen coordinates for the menu.
pcmdtReserved
IOleCommandTarget interface used to query command status and execute commands on this object.
pdispReserved
IDispatch interface of the object at the screen coordinates. This allows a host to differentiate particular objects to provide more specific context.

The following menu identifiers are currently used. Note: These identifiers are likely to change and are not currently exposed in a header file as part of the IE4/MSHTML SDK.
#define CONTEXT_MENU_DEFAULT 0
#define CONTEXT_MENU_IMAGE 1
#define CONTEXT_MENU_CONTROL 2
#define CONTEXT_MENU_TABLE 3
#define CONTEXT_MENU_DEBUG 4
#define CONTEXT_MENU_1DSELECT 5
#define CONTEXT_MENU_ANCHOR 6
#define CONTEXT_MENU_IMGDYNSRC 7


IDocHostUIHandler::ShowUI

HRESULT ShowUI(
    DWORD dwID,
    IOleInPlaceActiveObject FAR *pActiveObject,
    IOleCommandTarget FAR *pCommandTarget,
    IOleInPlaceFrame FAR *pFrame,
    IOleInPlaceUIWindow FAR *pDoc
);

Allows the host to replace the IE4/MSHTML menus and toolbars.

  • Return Values:
    S_OK | Host displayed its own UI. IE4/MSHTML will not display its UI.
    S_FALSE | Host did not display its own UI. IE4/MSHTML will display its UI.
    DOCHOST_E_UNKNOWN | Host did not recognize the UI identifier. IE4/MSHTML will either try an alternative identifier for compatibility with a previous version or display its own UI.
dwID
Reserved for future use.
pActiveObject
IOleInPlaceActiveObject interface of the currently active object.
pCommandTarget
IOleCommandTarget interface of the object.
pFrame
IOleInPlaceFrame interface of the object. This is needed for menus and toolbars.
pDoc
IOleInPlaceUIWindow interface for the object. This is needed for toolbars.

This method is called just before IE4/MSHTML displays its menus and toolbars. If the host returns S_FALSE from this method, IE4/MSHTML does not display its UI and assumes that the host is handling the UI.

If the host makes use of any of the interfaces handed to it as part of this function, it should call the interface's AddRef method if it is to be saved for later use. If the host calls the interface's AddRef method, it must also call the interface's Release method when the interface is no longer required.

A host can disable modeless UI on IE4/MSHTML by calling IOleCommandTarget::Exec with IDM_DISABLEMODELESS and IDM_ENABLEMODELESS.


IDocHostUIHandler::TranslateAccelerator

HRESULT TranslateAccelerator(
    LPMSG lpMsg,
    const GUID FAR *pguidCmdGroup,
    DWORD nCmdID
);

Called by IE4/MSHTML when IOleInPlaceActiveObject::TranslateAccelerator or IOleControlSite::TranslateAccelerator is called.

  • Returns S_OK if successful, or S_FALSE otherwise.
lpMsg
Points to the message that might need to be translated.
pguidCmdGroup
Command group identifier.
nCmdID
Command identifier.


IDocHostUIHandler::TranslateUrl

HRESULT TranslateUrl(
    DWORD dwTranslate,
    OLECHAR *pchURLIn,
    OLECHAR **ppchURLOut
);

Called by IE4/MSHTML to allow the host an opportunity to modify the URL to be loaded.

  • Returns S_OK if the URL was translated, S_FALSE if the URL was not translated, or an OLE-defined error code if an error occurred.
dwTranslate
Reserved for future use.
pchURLIn
Address of a string supplied by IE4/MSHTML that represents the URL to be translated.
ppchURLOut
Address of a string pointer that receives the address of the translated URL. The host allocates the buffer using the task memory allocator. The contents of this parameter should always be initialized to NULL, even if the URL is not translated or the method fails.


IDocHostUIHandler::UpdateUI

HRESULT UpdateUI(void);

Notifies the host that the command state has changed.

  • Returns S_OK if successful, or an OLE-defined error code otherwise.

The host should update the state of toolbar buttons. This method is called regardless of the return value from the ShowUI method.


IDocHostUIHandler Structures and Enumerations IDocHostUIHandler Structures and Enumerations *
  * Previous Topic: IDocHostUIHandler::UpdateUI
  * Next Topic: DOCHOSTUIINFO

IDocHostUIHandler Structures and Enumerations

The following are the structures and enumerations used with the IDocHostUIHandler interface.


DOCHOSTUIINFO

typedef struct _DOCHOSTUIINFO{
    ULONG cbSize;
    DWORD dwFlags;
    DWORD dwDoubleClick;
}DOCHOSTUIINFO;

Used by the IDocHostUIHandler::GetHostInfo method to allow IE4/MSHTML to retrieve information about the host's UI requirements.

cbSize
Size of this structure, in bytes.
dwFlags
One or more of the DOCHOSTUIFLAG values that specify the UI capabilities of the host.
dwDoubleClick
One of the DOCHOSTUIDBLCLK values that specify the operation that should take place in response to a double-click.


DOCHOSTUIFLAG

typedef enum tagDOCHOSTUIFLAG{
    DOCHOSTUIFLAG_DIALOG = 1,
    DOCHOSTUIFLAG_DISABLE_HELP_MENU = 2,
    DOCHOSTUIFLAG_NO3DBORDER = 4,
    DOCHOSTUIFLAG_SCROLL_NO = 8,
    DOCHOSTUIFLAG_DISABLE_SCRIPT_INACTIVE = 16,
    DOCHOSTUIFLAG_OPENNEWWIN = 32,
    DOCHOSTUIFLAG_DISABLE_OFFSCREEN = 64,
    DOCHOSTUIFLAG_FLAT_SCROLLBAR = 128
    DOCHOSTUIFLAG_DIV_BLOCKDEFAULT = 256,
    DOCHOSTUIFLAG_ACTIVATE_CLIENTHIT_ONLY = 512
 }DOCHOSTUIFLAG;

Defines a set of flags that indicate the capabilities of a IDocHostUIHandler implementation.

DOCHOSTUIFLAG_DIALOG
IE4/MSHTML will not allow selection of the text in the form.
DOCHOSTUIFLAG_DISABLE_HELP_MENU
IE4/MSHTML will not display context menus.
DOCHOSTUIFLAG_NO3DBORDER
IE4/MSHTML does not use 3-D borders.
DOCHOSTUIFLAG_SCROLL_NO
IE4/MSHTML does not have scroll bars.
DOCHOSTUIFLAG_DISABLE_SCRIPT_INACTIVE
IE4/MSHTML will not execute any script when loading pages.
DOCHOSTUIFLAG_OPENNEWWIN
IE4/MSHTML will open a site in a new window when a link is clicked rather than browse to the new site using the same browser window.
DOCHOSTUIFLAG_DISABLE_OFFSCREEN
Not implemented or used.
DOCHOSTUIFLAG_FLAT_SCROLLBAR
IE4/MSHTML will use flat scroll bars for any UI it displays. Not currently supported.
DOCHOSTUIFLAG_DIV_BLOCKDEFAULT
IE4/MSHTML will insert the <DIV> tag if a return is entered in edit mode. Without this flag, IE4/MSHTML will use the <P> tag.
DOCHOSTUIFLAG_ACTIVATE_CLIENTHIT_ONLY
IE4/MSHTML will only become UI-active if the mouse is clicked in the client area of the window. It will not become UI-active if the mouse is clicked on a nonclient area, such as a scroll bar.


DOCHOSTUIDBLCLK

typedef enum tagDOCHOSTUIDBLCLK{
    DOCHOSTUIDBLCLK_DEFAULT = 0,
    DOCHOSTUIDBLCLK_SHOWPROPERTIES = 1,
    DOCHOSTUIDBLCLK_SHOWCODE = 2
}DOCHOSTUIDBLCLK;

Defines values used to indicate the proper action on a double-click event.

DOCHOSTUIDBLCLK_DEFAULT
Perform the default action.
DOCHOSTUIDBLCLK_SHOWPROPERTIES
Show the item's properties.
DOCHOSTUIDBLCLK_SHOWCODE
Show the page's source.


IDocHostShowUI Interface

A host can supply mechanisms for message boxes and Help to be shown by implementing the IDocHostShowUI interface. IE4/MSHTML will obtain this interface by calling the host's client site QueryInterface, requesting IID_IDocHostShowUI. The site is the object that implements the IOleDocumentSite and IOleClientSite interfaces.

IDocHostShowUI is derived from IUnknown. The following are the methods specific to IDocHostShowUI.
ShowHelp
ShowMessage


IDocHostShowUI::ShowHelp

HRESULT STDMETHODCALLTYPE ShowHelp(
    HWND hwnd,
    LPOLESTR pszHelpFile,
    UINT uCommand,
    DWORD dwData,
    POINT ptMouse,
    IDispatch *pDispatchObjectHit
);

Called by IE4/MSHTML when it needs to show Help.

  • Return Values:
    S_OK | Host displayed Help. IE4/MSHTML will not display its Help.
    S_FALSE | Host did not display Help. IE4/MSHTML will display its Help.
hwnd
Handle to the owner window.
pszHelpFile
Help file name.
uCommand
Type of Help. See the WinHelp function.
dwData
Additional data. See the WinHelp function.
ptMouse
Mouse position in screen coordinates.
pDispatchObjectHit
IDispatch of the object at the screen coordinates.

The first four parameters are the same as those passed to the WinHelp function. The ptMouse parameter gives the screen coordinates, and the pDispatchObjectHit parameter allows the host to differentiate the object at the screen coordinates to a greater degree than IE4/MSHTML.


IDocHostShowUI::ShowMessage

HRESULT ShowMessage(
    HWND hwnd,
    LPOLESTR lpstrText,
    LPOLESTR lpstrCaption,
    DWORD dwType,
    LPOLESTR lpstrHelpFile,
    DWORD dwHelpContext,
    LRESULT *plResult
);

Called by IE4/MSHTML when it needs to display a message box.

  • Return Values:
    S_OK | Host displayed its UI. IE4/MSHTML will not display its message box.
    S_FALSE | Host did not display its UI. IE4/MSHTML will display its message box.
hwnd
Handle to the owner window.
lpstrText
Text for the message box.
lpstrCaption
Caption for the message box.
dwType
Type flags (taken from the MessageBox MB_xxxx constants).
lpstrHelpFile
Help file name.
dwHelpContext
Help context identifier.
plResult
Button clicked by user (taken from the MessageBox IDxxx constants).


Dependencies

The WebBrowser control is implemented in the dynamic-link library file Shdocvw.dll under the custom control name "Microsoft Internet Controls." To use the WebBrowser control object in your application, you need to have Microsoft® Internet Explorer loaded on your computer.


Licensing and Distribution

Application developers who want to redistribute Microsoft® Internet Explorer technologies, such as the WebBrowser control, Wininet.dll, Urlmon.dll, or Comctl32.dll, must obtain a redistribution license for Microsoft® Internet Explorer 4.0. The Internet Explorer self-extracting executable installs a number of system files and registry entries in addition to the actual WebBrowser control. You can license Microsoft Internet Explorer for Windows® 95, Windows® 3.1, Windows NT® Workstation, and Apple Macintosh® royalty-free to redistribute within your organization or to your customers. Plus, you can use the Microsoft Internet Explorer Administration Kit (IEAK) to easily create Internet Explorer distribution media, which you can customize to specify start and search pages and a favorites list. This lets your organization create and distribute a Web browser that reflects your specific needs and the needs of your users. For more information on redistributing Internet Explorer, see the Microsoft Web page at http://www.microsoft.com/ie/ieak/.

Determining the Installed Version of Internet Explorer 4.0

Using the Internet Explorer 4.0 Minimal Installation Package

Adding an Application to the Warning List for Internet Explorer 4.0 Uninstall

Determining the Installed Version of Internet Explorer 4.0

If your application requires Internet Explorer 4.0 services, you must determine the version of Internet Explorer that is installed, if any, before installing your application. There are two methods that can be used to determine the installed version of Internet Explorer. The first obtains the version information from the registry, and the second obtains the version information from one of the Internet Explorer components.

Determining the Internet Explorer Version from the Registry

To obtain the installed Internet Explorer version from the registry, open the following registry key:

HKEY_LOCAL_MACHINE\
   Software\
      Microsoft\
         Internet Explorer

In this key, obtain the "Version" value. This is a string value that contains the Internet Explorer 4.0 version in the following format:

"<major version>.<minor version>.<build number>.<sub-build number>"

Internet Explorer 3.0x does not install this value, so if this value is retrieved and the major version is "4" and the minor version is "71", then Internet Explorer 4.0 is installed.

Internet Explorer 3.0x does install the "Build" value under this same key. For backward compatibility, Internet Explorer 4.0 modifies or adds the "Build" value also. Internet Explorer 3.0x's "Build" value is a string that contains a four-character build number. Internet Explorer 4.0's "Build" value is a string that contains a five-character value that takes the following format:

"4<build number>"

Therefore, if the "Build" value is the character '4' followed by a four-character build number, Internet Explorer 4.0 is installed.

Determining the Internet Explorer Version from Shdocvw.dll

The Internet Explorer browser is implemented in Shdocvw.dll. The version of this DLL is used to determine which version of Internet Explorer is installed. If this file is not present, Internet Explorer is either not installed or is not properly installed.

The following are the different versions of Shdocvw.dll and the browser version that each represents.

  • Version 4.70 – Internet Explorer 3.0
  • Version 4.71 – Internet Explorer 4.0

The following function retrieves the major and minor version numbers of the Shdocvw.dll that is installed on the local system.

#include <windows.h>
#include <shlwapi.h>

HRESULT GetBrowserVersion(LPDWORD pdwMajor, LPDWORD pdwMinor)
{
HINSTANCE   hBrowser;

if(   IsBadWritePtr(pdwMajor, sizeof(DWORD)) ||
      IsBadWritePtr(pdwMinor, sizeof(DWORD)))
   return E_INVALIDARG;

*pdwMajor = 0;
*pdwMinor = 0;

//Load the DLL.
hBrowser = LoadLibrary(TEXT("shdocvw.dll"));

if(hBrowser)
   {
   HRESULT           hr = S_OK;
   DLLGETVERSIONPROC pDllGetVersion;

   /*
   You must get this function explicitly.
   */
   pDllGetVersion = (DLLGETVERSIONPROC)GetProcAddress(hBrowser, TEXT("DllGetVersion"));

   if(pDllGetVersion)
      {
      DLLVERSIONINFO    dvi;

      ZeroMemory(&dvi, sizeof(dvi));
      dvi.cbSize = sizeof(dvi);

      hr = (*pDllGetVersion)(&dvi);

      if(SUCCEEDED(hr))
         {
         *pdwMajor = dvi.dwMajorVersion;

         *pdwMinor = dvi.dwMinorVersion;
         }
      }
   else
      {
      /*
      If GetProcAddress failed, there is a problem with the DLL.
      */
      hr = E_FAIL;
      }

   FreeLibrary(hBrowser);

   return hr;
   }

return E_FAIL;
}

Using the Internet Explorer 4.0 Minimal Installation Package

The Internet Explorer 4.0 minimal installation package includes the Internet Explorer 4.0 base browser, DirectShow, and the Microsoft Win32 VM for Java. The package can be run in normal mode with user interface and prompts or in automated mode without user interface and prompts. The following installation packages are available:

Installation Package | Target Platform
ie4stw95.exe | Windows® 95
ie4stnt.exe | Windows NT® 4.0 for the Intel X86 processor

The following command line:

ie4stw95.exe /Q:A

will install the Internet Explorer 4.0 minimal installation package with the following options:

  • No setup user interface.
  • No integrated desktop.
  • No reboot prompt.
  • Internet Explorer 4.0 will be made the default browser.
  • The Internet icon will be added to the desktop.

The following command line:

ie4stw95.exe /Q:A /C:"ie4wzd.exe /Q:A /X /I:N /R:N /S:""#e"""

will install the Internet Explorer 4.0 minimal installation package with the following options:

  • No setup user interface.
  • No integrated desktop.
  • No reboot prompt.
  • Internet Explorer 4.0 will not be made the default browser.
  • The Internet icon will not be added to the desktop.

For other installation options, please refer to the Internet Explorer Administration Kit.

Note These examples use the Windows 95 installation package, but the command line options are the same for all packages.

Before installing Internet Explorer 4.0, you must make sure that the setup application has the proper administration rights (if applicable) and that there is enough hard disk space available for the installation. The minimal installation package requires approximately 60 MB of free disk space to accommodate the temporary and installed files.

Once the installation is complete, your setup application must reboot the computer in order for the Internet Explorer 4.0 installation to complete. Your setup application should ask users if they want to reboot the computer and give them an option not to. Internet Explorer 4.0 will not be useable until the computer has been rebooted.

Adding an Application to the Warning List for Internet Explorer 4.0 Uninstall

If your application requires Internet Explorer 4.0 services, you can add your application to the list of applications that require Internet Explorer 4.0 to be installed. When users attempt to uninstall Internet Explorer 4.0, this list will be displayed and they will be told that these applications may not function correctly if Internet Explorer 4.0 is uninstalled. Users will be asked if they still want to uninstall Internet Explorer 4.0.

To add your application to this list, add a string value under the following key:

HKEY_LOCAL_MACHINE\
   Software\
      Microsoft\
         IE4\
            DependentComponents

Under this key, create a string value that takes the following format:

MyApp = "My Application."

The value name in this example is "MyApp". Make sure the value name you create is unique among all other values in the same key. The value's data ("My Application.") is what is actually displayed to the user.

When your application is uninstalled, remember to remove any values you add under this key.


Microsoft Script Debugger for Internet Explorer

Microsoft Script Debugger for Internet Explorer is a debugging environment that extends Microsoft Internet Explorer and Microsoft Internet Information Server (IIS) by allowing Web developers to browse, edit, and debug .htm and .asp pages that contain Visual Basic Scripting Edition (VBScript) or JScript (Microsoft's implementation of JavaScript). The Microsoft Script Debugger gives developers a seamless way to combine HTML and script development. Developers can also use the debugger to test programs written in Sun Microsystems Java and run using the Microsoft Java Virtual Machine (VM), and to debug scripts for any scripting language engine that supports ActiveX debugging interfaces.

The Script Debugger provides the same functionality as traditional debuggers, including the ability to:

  • Set and clear breakpoints.
  • Step through and over procedures.
  • Display and change the values of variables and properties.
  • Evaluate expressions.
  • View the call stack, and navigate to any currently-loaded procedure.

The Script Debugger also includes the ability for developers to open and edit HTML pages. The Script Debugger supports script colorization for maximum readability.

The Script Debugger and accompanying documentation is available for download at http://www.microsoft.com/scripting/.


URL Security Zones

Monikers, URLs, security zones, and pluggable protocols provide capabilities that allow you to asynchronously bind objects, bind Uniform Resource Locators (URLs), manage URL security zones, and create custom URL protocols. This section covers the functionality exported by the Urlmon.dll dynamic-link library (DLL).

URL Security Zones Overview

URL Security Zones Reference


URL Security Zones Overview

Monikers, URLs, security zones, and pluggable protocols provide capabilities that allow you to asynchronously bind objects, bind Uniform Resource Locators (URLs), manage URL security zones, and create custom URL protocols. This section covers the functionality exported by the Urlmon.dll dynamic-link library (DLL).

Introduction

About URLs and Name Spaces

About URL Security Zones

Handling URL Security Zones

Creating a Customized URL Security Manager

Accessing the Default Managers

Appendix A: Header File Additions Required for ActiveX Controls

Introduction

If you want to compile programs that use the functionality provided in Urlmon.dll, you must make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory, of the C/C++ compiler you use.

This documentation assumes that you have an understanding of Microsoft® Win32® programming. Also, for asynchronous monikers, asynchronous pluggable protocols, and URL monikers you should have an understanding of OLE and COM programming. For the Internet-related interfaces, methods, and functions, an understanding of the format and syntax of URLs is also required. For more information, see RFC 1738, Uniform Resource Locators (URL). You can find this document at http://ds.internic.net/rfc/rfc1738.txt. External Link

About URLs and Name Spaces

A Uniform Resource Locator (URL) follows the syntax described in RFC 1738, which specifies a protocol scheme followed by a scheme-specific portion (<scheme>:<scheme-specific portion>). For example, in the URL http://www.microsoft.com/, "http" is the scheme and "//www.microsoft.com/" is the scheme-specific portion.

The beginning portion of the scheme-specific portion of the URL contains the server name. This portion of the URL is often referred to as the URL name space.

About URL Security Zones

To fully understand URL security zones, you need to understand a few terms:

  • URL action is an action that a browser can take that might pose a security risk to the local computer. These include actions such as running a Java applet (URLACTION_JAVA_PERMISSIONS in this case) or an ActiveX™ control (URLACTION_ACTIVEX_RUN in this case).
  • URL policy is a policy that determines what permission or trust level is set for a particular URL action. These include setting the safety level for Java to high (URLPOLICY_JAVA_HIGH in this case).
  • URL security zone is a group of URL name spaces that are assigned an equal level of permission (or trust). Each URL action for the zone has an appropriate URL policy assigned to it that reflects the level of trust given to the URL name spaces in that zone.

Previously, Microsoft Internet Explorer utilized the same security policy for all URL name spaces. Each URL action in a particular security level was handled by a predetermined URL policy, which could not be changed. In Internet Explorer 4.0, URL name spaces are divided into URL security zones, which have different levels of trust assigned to them. Users can easily customize the default URL security zones by changing the URL policy settings for each URL action with the user interface provided by Internet Explorer.

Default URL Security Zones

The default URL security zones used by Internet Explorer 4.0 are:

  • The Intranet
  • Trusted Web sites
  • Internet
  • Untrusted sites

The Intranet zone is used for content located on a company's intranet. Since the servers and information would be within a company's firewall, a user or company could assign a higher trust level to the content on their intranet.

The following table contains the default settings for the intranet zone.
URL action | URL policy | Aggregates
URLACTION_ACTIVEX_RUN | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_SIGNED_ACTIVEX | URLPOLICY_QUERY | none
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX | URLPOLICY_DISALLOW | none
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY | URLPOLICY_QUERY | URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
URLACTION_SCRIPT_RUN | URLPOLICY_ALLOW | none
URLACTION_SCRIPT_JAVA_USE | URLPOLICY_ALLOW | none
URLACTION_JAVA_PERMISSIONS | URLPOLICY_JAVA_HIGH | none
URLACTION_HTML_FONT_DOWNLOAD | URLPOLICY_ALLOW | none
URLACTION_SHELL_FILE_DOWNLOAD | URLPOLICY_QUERY | none
URLACTION_HTML_SUBMIT_FORMS | URLPOLICY_QUERY | URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO
URLACTION_SHELL_INSTALL_DTITEMS | URLPOLICY_QUERY | none
URLACTION_SHELL_MOVE_OR_COPY | URLPOLICY_QUERY | none
URLACTION_SHELL_VERB | URLPOLICY_ALLOW | none
URLACTION_CREDENTIALS_USE | URLPOLICY_CREDENTIALS_MUST_PROMPT_USER | none
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS | URLPOLICY_CHANNEL_SOFTDIST_PRECACHE | none
URLACTION_SHELL_WEBVIEW_VERB | URLPOLICY_ALLOW | none

The Trusted Web sites zone is used for content located on Web sites that are considered more reputable and/or trustworthy than other sites on the Internet. Users can use this zone to assign a higher trust level to these sites to minimize the number of authentication requests. The URLs of these trusted Web sites would need to be mapped into this zone.

The following table contains the default settings for the Trusted Web sites zone.
URL action | URL policy | Aggregates
URLACTION_ACTIVEX_RUN | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_SIGNED_ACTIVEX | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX | URLPOLICY_QUERY | none
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY | URLPOLICY_QUERY | URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
URLACTION_SCRIPT_RUN | URLPOLICY_ALLOW | none
URLACTION_SCRIPT_JAVA_USE | URLPOLICY_ALLOW | none
URLACTION_JAVA_PERMISSIONS | URLPOLICY_JAVA_LOW | none
URLACTION_HTML_FONT_DOWNLOAD | URLPOLICY_ALLOW | none
URLACTION_SHELL_FILE_DOWNLOAD | URLPOLICY_QUERY | none
URLACTION_HTML_SUBMIT_FORMS | URLPOLICY_ALLOW | URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO
URLACTION_SHELL_INSTALL_DTITEMS | URLPOLICY_ALLOW | none
URLACTION_SHELL_MOVE_OR_COPY | URLPOLICY_ALLOW | none
URLACTION_SHELL_VERB | URLPOLICY_QUERY | none
URLACTION_CREDENTIALS_USE | URLPOLICY_CREDENTIALS_SILENT_LOGON_OK | none
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS | URLPOLICY_CHANNEL_SOFTDIST_AUTOINSTALL | none
URLACTION_SHELL_WEBVIEW_VERB | URLPOLICY_ALLOW | none

The Internet zone is used for the Web sites on the Internet that do not belong to another zone. The default settings would cause the user to be prompted whenever potentially unsafe content was about to be downloaded. Web sites that are not mapped into other zones automatically fall into this zone.

The following table contains the default settings for the Internet zone.
URL action | URL policy | Aggregates
URLACTION_ACTIVEX_RUN | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_SIGNED_ACTIVEX | URLPOLICY_QUERY | none
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX | URLPOLICY_DISALLOW | none
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY | URLPOLICY_QUERY | URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
URLACTION_SCRIPT_RUN | URLPOLICY_ALLOW | none
URLACTION_SCRIPT_JAVA_USE | URLPOLICY_ALLOW | none
URLACTION_JAVA_PERMISSIONS | URLPOLICY_JAVA_HIGH | none
URLACTION_HTML_FONT_DOWNLOAD | URLPOLICY_ALLOW | none
URLACTION_SHELL_FILE_DOWNLOAD | URLPOLICY_QUERY | none
URLACTION_HTML_SUBMIT_FORMS | URLPOLICY_QUERY | URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO
URLACTION_SHELL_INSTALL_DTITEMS | URLPOLICY_QUERY | none
URLACTION_SHELL_MOVE_OR_COPY | URLPOLICY_QUERY | none
URLACTION_SHELL_VERB | URLPOLICY_QUERY | none
URLACTION_CREDENTIALS_USE | URLPOLICY_CREDENTIALS_MUST_PROMPT_USER | none
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS | URLPOLICY_CHANNEL_SOFTDIST_PRECACHE | none
URLACTION_SHELL_WEBVIEW_VERB | URLPOLICY_QUERY | none

The Untrusted sites zone is used for Web sites that contain content that could cause, or have caused, problems when downloaded. This zone could be used to cause the user to be prompted every time potentially unsafe content was about to be downloaded or prevent that content from being downloaded. The URLs of these untrusted Web sites would need to be mapped into this zone.

The following table contains the default settings for the Untrusted sites zone.
URL action | URL policy | Aggregates
URLACTION_ACTIVEX_RUN | URLPOLICY_DISALLOW | none
URLACTION_DOWNLOAD_SIGNED_ACTIVEX | URLPOLICY_DISALLOW | none
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX | URLPOLICY_DISALLOW | none
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY | URLPOLICY_DISALLOW | URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
URLACTION_SCRIPT_RUN | URLPOLICY_ALLOW | none
URLACTION_SCRIPT_JAVA_USE | URLPOLICY_DISALLOW | none
URLACTION_JAVA_PERMISSIONS | URLPOLICY_JAVA_HIGH | none
URLACTION_HTML_FONT_DOWNLOAD | URLPOLICY_QUERY | none
URLACTION_SHELL_FILE_DOWNLOAD | URLPOLICY_DISALLOW | none
URLACTION_HTML_SUBMIT_FORMS | URLPOLICY_DISALLOW | URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO
URLACTION_SHELL_INSTALL_DTITEMS | URLPOLICY_DISALLOW | none
URLACTION_SHELL_MOVE_OR_COPY | URLPOLICY_DISALLOW | none
URLACTION_SHELL_VERB | URLPOLICY_DISALLOW | none
URLACTION_CREDENTIALS_USE | URLPOLICY_CREDENTIALS_MUST_PROMPT_USER | none
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS | URLPOLICY_CHANNEL_SOFTDIST_PROHIBIT | none
URLACTION_SHELL_WEBVIEW_VERB | URLPOLICY_QUERY | none

There is also an implicit zone used for content that exists on the local computer. The content found on the local computer, except for content cached by Microsoft Internet Explorer on the local system, is treated with a high level of trust. Content that has been cached by Internet Explorer is accessed through the URL of origin and is assigned to the appropriate zone.

The following table contains the default settings for the local computer zone.
URL action | URL policy | Aggregates
URLACTION_ACTIVEX_RUN | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_SIGNED_ACTIVEX | URLPOLICY_ALLOW | none
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX | URLPOLICY_ALLOW | none
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY | URLPOLICY_QUERY | URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
URLACTION_SCRIPT_RUN | URLPOLICY_ALLOW | none
URLACTION_SCRIPT_JAVA_USE | URLPOLICY_ALLOW | none
URLACTION_JAVA_PERMISSIONS | URLPOLICY_JAVA_MEDIUM | none
URLACTION_HTML_FONT_DOWNLOAD | URLPOLICY_ALLOW | none
URLACTION_SHELL_FILE_DOWNLOAD | URLPOLICY_ALLOW | none
URLACTION_HTML_SUBMIT_FORMS | URLPOLICY_ALLOW | URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO
URLACTION_SHELL_INSTALL_DTITEMS | URLPOLICY_ALLOW | none
URLACTION_SHELL_MOVE_OR_COPY | URLPOLICY_ALLOW | none
URLACTION_SHELL_VERB | URLPOLICY_ALLOW | none
URLACTION_CREDENTIALS_USE | URLPOLICY_CREDENTIALS_SILENT_LOGON_OK | none
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS | URLPOLICY_CHANNEL_SOFTDIST_PRECACHE | none
URLACTION_SHELL_WEBVIEW_VERB | URLPOLICY_ALLOW | none

Asynchronous pluggable protocols can specify how their URLs should be assigned to a security zone. The IInternetProtocolInfo::ParseUrl method using the PARSE_SECURITY_URL value should return a URL that the security manager can use to make decisions.

URL Actions and Policies

Each URL security zone has a set of URL actions with a URL policy assigned to it. The URL actions cover all operations that have security implications. A URL policy is assigned to each URL action to determine how that URL action will be handled. For example, URLACTION_JAVA_PERMISSIONS would be checked for operations related to Java applets. To force all Java applets to run out of a sandbox (that is, prevent it from doing anything that would be a security risk to the local computer), the URL policy would be set to URLPOLICY_JAVA_HIGH.

Some URL actions are an aggregate of two or more URL actions. The user interface for the default URL security zone manager would allow the user to set the aggregate value only (such as URLACTION_HTML_SUBMIT_FORMS). The browser would call the specific value (such as URLACTION_HTML_SUBMIT_FORMS_FROM) because it is reacting to that particular action. If the aggregate URL action has a URL policy set, that policy is used for the aggregate URL action and the specific URL actions it aggregated. All security zone managers must be designed to handle calls to the specific URL actions and know where to find the appropriate URL policy.

Handling URL Security Zones

There are two scenarios where you would use the URL security zone interfaces:

  • Applications that are hosting either the WebBrowser control or IE4/MSHTML and want to implement their own security manager to handle security zones.
  • Controls that are hosted by IE4/MSHTML and want to get information about a security setting.

In a few cases, an application might want to manage the default URL security zone settings by using the IInternetZoneManager interface. The changes would not be static, because the user could override any changes by setting the URL security zone options in Internet Explorer 4.0. In most cases, applications that need to control the URL security zone settings should create an application that hosts the WebBrowser control or IE4/MSHTML and implement their own security manager.

Interfaces related to URL security zones

  • IInternetHostSecurityManager
  • IInternetSecurityManager
  • IInternetSecurityMgrSite
  • IInternetZoneManager

Applications Hosting the WebBrowser Control or IE4/MSHTML

The WebBrowser control or IE4/MSHTML hosts could create a security manager (by implementing the IInternetSecurityManager interface) that handles the URL actions and policies that are important to the host. Other URL actions and policies would be passed to the default security manager so it can handle them appropriately. The IInternetSecurityMgrSite interface would be used to handle Windows®-related information from the component so that the customized security manager can handle any user interface it needed.

To create a customized security manager, the component must implement the IInternetSecurityManager interface. Any methods or URL actions that the customized security manager wants the default security manager to act on should return INET_E_DEFAULT_ACTION.

The component must also implement a ClientSite object when embedding either the WebBrowser control or IE4/MSHTML.

The following steps occur for a URL action:

  1. IE4/MSHTML uses CoCreateInstance to create an instance of the Internet Security Manager.

    Creating an instance of the security manager

  2. The Internet Security Manager calls the QueryInterface method on IE4/MSHTML to get its IServiceProvider interface. IE4/MSHTML then calls the QueryInterface method on the IOleClientSite interface to get the IServiceProvider interface.

    Finding the IServiceProvider interface

  3. IServiceProvider::QueryService is called to get an IInternetSecurityManager interface. The component then passes a pointer to its implementation of IInternetSecurityManager to the Internet Security Manager.

    Getting a reference to the custom security manager

  4. Calls from IE4/MSHTML to the IInternetSecurityManager methods are passed to the custom security manager from the default Internet Security Manager.

    Passing a call to the custom security manager

  5. If the method called returns INET_E_DEFAULT_ACTION, the default implementation of IInternetSecurityManager is used to resolve the call. Otherwise the result from the custom security manager is returned.

    Returning back to the default security manager

  6. The Internet Security Manager returns the result back to IE4/MSHTML.

    Returning back to IE4/MSHTML

Note The URL security zone API offers support only for a single, customized security manager to delegate URL actions back to the default security manager. If more than one customized security manager is implemented, the additional security managers must explicitly find and invoke the security manager above it to allow multiple delegations to operate correctly.

Components Hosted by IE4/MSHTML

Components hosted by the WebBrowser control or IE4/MSHTML might need to query the security manager for the URL policies being implemented in the URL security zone they are in. These components include script engines (JScript and VBScript), controls, Java applets, code download, and so on. For example, the code download component of Internet Explorer 4.0 needs to ask the security manager if it can download unsigned ActiveX Controls. The component calls the IInternetHostSecurityManager::ProcessUrlAction method to check what the policy is on Java applets to help make its decision.

To query for URL policies, these components use the IInternetHostSecurityManager interface. The component must also have the address of a site interface implemented by the WebBrowser control or IE4/MSHTML. The exact site interface would depend on the type of component being hosted. For example, a script engine should have the IActiveScriptSite interface implemented, while controls would implement an IOleClientSite interface. To get the address of this interface:

  1. The component calls the QueryInterface method on the site interface to get the IServiceProvider interface. The component then calls IServiceProvider::QueryService to get the IInternetHostSecurityManager interface.

    Accessing the host security manager

  2. The component calls the IInternetHostSecurityManager methods. The host security manager creates an instance of the Internet Security Manager. The host security manager then adds the URL and calls the associated method on the IInternetSecurityManager interface.

    Getting security zone information

    If a custom security manager was implemented by a host application, the default Internet Security Manager would pass the call up to the custom security manager's IInternetSecurityManager interface.

  3. The IInternetSecurityManager method would return its results to IInternetHostSecurityManager, which would then pass the results to the component.

    Returning results back from the security manager

Creating a Customized URL Security Manager

A customized URL security manager can be created for applications that host either the WebBrowser control or IE4/MSHTML by implementing the IInternetSecurityManager interface. Most of the IInternetSecurityManager methods, except IInternetSecurityManager::ProcessUrlAction, would only need to return INET_E_DEFAULT_ACTION to defer the call to the default security manager.

The following example shows an implementation of the IInternetSecurityManager::ProcessUrlAction method for a customized security manager that wants to require that data be encrypted.

HRESULT MySecurityManager::ProcessUrlAction(
    LPWSTR pwszUrl,
    DWORD dwAction,
    BYTE *pPolicy,
    DWORD cbPolicy,
    DWORD dwReserved
)
{
    DWORD dwPolicy = URLPOLICY_ENCRYPT_REQUIRED;

    if (dwAction == URLACTION_ENCRYPT_DATA)
    {
        if (cbPolicy >= sizeof (DWORD))
         {
                *(DWORD *)pPolicy = dwPolicy;
                return S_OK;
        }
        else
            return S_FALSE;
    }
    else
        return INET_E_DEFAULT_ACTION;
}

Note The Internet Explorer 4.0 default security manager cannot be replaced by a customized security manager.

Accessing the Default Managers

To access the default Internet Security Manager and Internet Zone Manager objects, the client application should use the CoCreateInstance function to create an instance of these objects.

The following sample creates an instance of both the Internet Security Manager and the Internet Zone Manager.

HRESULT hr;
IInternetSecurityManager *pSecurityMgr;
IInternetZoneManager *pZoneMgr;

hr = CoCreateInstance(CLSID_InternetSecurityManager, NULL, CLSCTX_INPROC_SERVER,
            IID_IInternetSecurityManager, (void**)&pSecurityMgr);

hr = CoCreateInstance(CLSID_InternetZoneManager, NULL, CLSCTX_INPROC_SERVER,
            IID_IInternetZoneManager, (void**)&pZoneMgr);


Appendix A: Header File Additions Required for ActiveX Controls

The following definitions didn't make it into the Urlmon.idl and Urlmon.h files in time for the Microsoft® Internet Explorer 4.0 release, so they need to be added to those files for any ActiveX™ Controls that access the new URL security zone manager implemented in Internet Explorer 4.0.

#define CONFIRMSAFETYACTION_LOADOBJECT    0x00000001

struct CONFIRMSAFETY
{
    CLSID clsid;
    IUnknown *punk;
    DWORD dwFlags;
};

static const GUID GUID_CUSTOM_CONFIRMOBJECTSAFETY =
    { 0x10200490, 0xfa38, 0x11d0, { 0xac, 0xe, 0x0, 0xa0, 0xc9, 0xf, 0xff, 0xc0 } };


URL Security Zones Reference

This reference covers the APIs that are exported from the Urlmon.dll dynamic-link library. These APIs allow a developer to:

  • Create monikers that can instantiate a named object and return a pointer to one of the object's interfaces asynchronously.
  • Create an asynchronous moniker whose data is referenced by a URL (Uniform Resource Locator).
  • Implement customized URL protocols, name space handlers, and MIME filters.
  • Use functions that combine the functionality of asynchronous monikers and URL monikers.
  • Manage URL security zones.

The reference contains the interfaces, methods, functions, structures, enumerated types, security zone flags, and error codes used by these APIs.

Objects

Interfaces

Methods

Functions

Structures

Enumerated Types

URL Security Zone Flags


Objects

This section contains the objects exposed by monikers, URLs, security zones, and pluggable protocols.
Internet Security Manager
Internet Zone Manager


Internet Security Manager

CLSID_InternetSecurityManager

The Internet Security Manager is an object that manages security.

Interfaces
IInternetSecurityManager


Internet Zone Manager

CLSID_InternetZoneManager

The Internet Zone Manager is an object that manages zones.

Interfaces
IInternetZoneManager


Interfaces

This section contains the interfaces exposed by monikers, URLs, security zones, and pluggable protocols.
IInternetHostSecurityManager
IInternetSecurityManager
IInternetSecurityMgrSite
IInternetZoneManager


IInternetHostSecurityManager

This interface is provided by the HTML host for components to use to manage security.
IInternetHostSecurityManager methods | Description
GetSecurityId | Retrieves the security identification of the host.
ProcessUrlAction | Retrieves the policy associated with the URL action in the given context.
QueryCustomPolicy | Retrieves the custom policy associated with the specified key in the given context.

Use SID_SInternetHostSecurityManager to request this interface when using IServiceProvider::QueryService.


IInternetSecurityManager

This interface allows client applications to influence the security of the browser components.
IInternetSecurityManager methods | Description
GetSecurityId | Retrieves the domain of the given URL.
GetSecuritySite | Retrieves the security site manager.
GetZoneMappings | Retrieves the zone mappings.
MapUrlToZone | Retrieves the zone index for the given URL.
ProcessUrlAction | Determines the policy for the specified action and displays a user interface if the policy indicates that the user should be queried.
QueryCustomPolicy | Retrieves the custom policy associated with the URL and specified key in the given context.
SetSecuritySite | Sets the security site manager.
SetZoneMapping | Maps a pattern into the specified zone.

Use SID_SInternetSecurityManager to request this interface when using IServiceProvider::QueryService.


IInternetSecurityMgrSite

This interface is provided by an HTML host to be used by components to manage the user interface of the security manager.
IInternetSecurityMgrSite methods | Description
EnableModeless | Enables or disables the use of modeless pop-up windows.
GetWindow | Retrieves the handle to the parent window.


IInternetZoneManager

This interface is used by a host to control the security zone infrastructure.
IInternetZoneManager methods | Description
CreateZoneEnumerator | Creates a zone enumerator.
DestroyZoneEnumerator | Destroys the zone enumerator.
GetZoneActionPolicy | Retrieves the policy associated with the given URL action.
GetZoneAt | Retrieves the zone associated with the specified index and enumerator.
GetZoneAttributes | Retrieves the attributes of the specified zone.
GetZoneCustomPolicy | Retrieves the custom policies associated with the zone.
LogAction | Not currently implemented.
PromptAction | Not currently implemented.
SetZoneActionPolicy | Sets the policy associated with the given action on the specified zone.
SetZoneAttributes | Sets the attributes of the specified zone.
SetZoneCustomPolicy | Sets the custom policy on the specified zone.


Methods

This section contains the methods exposed by monikers, URLs, security zones, and pluggable protocols.
IInternetHostSecurityManager::GetSecurityId
IInternetHostSecurityManager::ProcessUrlAction
IInternetHostSecurityManager::QueryCustomPolicy
IInternetSecurityManager::GetSecurityId
IInternetSecurityManager::GetSecuritySite
IInternetSecurityManager::GetZoneMappings
IInternetSecurityManager::MapUrlToZone
IInternetSecurityManager::ProcessUrlAction
IInternetSecurityManager::QueryCustomPolicy
IInternetSecurityManager::SetSecuritySite
IInternetSecurityManager::SetZoneMapping
IInternetSecurityMgrSite::EnableModeless
IInternetSecurityMgrSite::GetWindow
IInternetZoneManager::CreateZoneEnumerator
IInternetZoneManager::DestroyZoneEnumerator
IInternetZoneManager::GetZoneActionPolicy
IInternetZoneManager::GetZoneAt
IInternetZoneManager::GetZoneAttributes
IInternetZoneManager::GetZoneCustomPolicy
IInternetZoneManager::LogAction
IInternetZoneManager::PromptAction
IInternetZoneManager::SetZoneActionPolicy
IInternetZoneManager::SetZoneAttributes
IInternetZoneManager::SetZoneCustomPolicy


IInternetHostSecurityManager::GetSecurityId

HRESULT GetSecurityId(
    [out] BYTE *pbSecurityId,
    [in, out] DWORD *pcbSecurityId,
    [in] DWORD dwReserved
);

Retrieves the security identification of the host.

  • Returns S_OK if successful, or E_INVALIDARG if the buffer is set to NULL or the string passed in to pwszUrl is not a valid URL.
pbSecurityId
Address of a buffer containing the scheme, domain name, and zone of the host.
pcbSecurityId
Address of a double word value containing the size of the buffer being passed in.
dwReserved
Reserved. Must be set to zero.

If successful, pbSecurityId contains the scheme, domain, and zone information in the following format:

<scheme>:<domain>+<zone>

The pcbSecurityID parameter will contain the actual size of the data stored in the buffer.


IInternetHostSecurityManager::ProcessUrlAction

HRESULT ProcessUrlAction(
    [in] DWORD dwAction,
    [out] BYTE *pPolicy,
    [in] DWORD cbPolicy,
    [in] BYTE *pContext,
    [in] DWORD cbContext,
    [in] DWORD dwFlags,
    [in] DWORD dwReserved
);

Retrieves the policy associated with the URL action in the given context.

  • Returns one of the following values:
    S_OK | Successful, and the URL policy is URLPOLICY_ALLOW.
    S_FALSE | Found a valid URL policy that is not URLPOLICY_ALLOW.
    E_OUTOFMEMORY | Not enough memory to complete the operation.

    The method can also return an HRESULT derived from the Win32 error code ERROR_NOT_FOUND if the URL action could not be read from the registry.

dwAction
Double-word value that contains the action to process. Can be one of the URL Action Flags values.
pPolicy
Address of the output buffer to store the policy. Since all the URLPOLICY_* values are double-word values, the buffer should be greater than or equal to the size of a DWORD. Can contain one of the URL Policy Flags values.
cbPolicy
Double-word value that contains the size of the output buffer.
pContext
Address of a buffer that contains the context information used by the delegation routines.
cbContext
Double-word value that contains the size of the context information buffer.
dwFlags
Double-word value that contains the flags controlling this method. Can be one of the PUAF values.
dwReserved
Reserved. Must be set to zero.


IInternetHostSecurityManager::QueryCustomPolicy

HRESULT QueryCustomPolicy(
    [in] REFGUID guidKey,
    [out] BYTE **ppPolicy,
    [out] DWORD *pcbPolicy,
    [in] BYTE *pContext,
    [in] DWORD cbContext,
    [in] DWORD dwReserved
);

Retrieves the custom policy associated with the specified key in the given context.

  • Returns S_OK if successful, or E_OUTOFMEMORY if not enough memory to complete the operation.

    This method can also return the HRESULT derived from the Win32 error code ERROR_NOT_FOUND if the action could not be read from the registry.

guidKey
Globally unique identifier associated with the custom policy.
ppPolicy
Address of a pointer to the buffer to store the policy information.
pcbPolicy
Address of a double-word value that contains the policy buffer size.
pContext
Address of a buffer that contains the context information.
cbContext
Unsigned long integer value that contains the size of the context buffer.
dwReserved
Reserved. Must be set to zero.


IInternetSecurityManager::GetSecurityId

HRESULT GetSecurityId(
    [in] LPCWSTR pwszUrl,
    [out] BYTE *pbSecurityId,
    [in, out] DWORD *pcbSecurityId,
    [in] DWORD dwReserved
);

Retrieves the security identification of the given URL.

  • Returns S_OK if successful, or E_INVALIDARG if the buffer is set to NULL or the string passed in to pwszUrl is not a valid URL.
pwszUrl
String value that contains the URL.
pbSecurityId
Address of a buffer that contains the scheme, domain name, and zone associated with the URL.
pcbSecurityId
Address of a double-word value containing the size of the buffer being passed in.
dwReserved
Unsigned long integer that indicates the domain to use. If set to zero, the full domain name is used. Otherwise, a string value containing a suffix to the domain name can be specified. This larger domain name, the full domain name combined with the suffix, will be used as the security ID.

If successful, pbSecurityId contains the scheme, domain, and zone information in the following format:

<scheme>:<domain>+<zone>

And pcbSecurityID will contain the actual size of the data stored in the buffer.


IInternetSecurityManager::GetSecuritySite

HRESULT GetSecuritySite(
    [out] IInternetSecurityMgrSite **ppSite

Retrieves the security site manager.

  • Returns S_OK if successful.
ppSite
Address of a pointer to the current IInternetSecurityMgrSite interface.


IInternetSecurityManager::GetZoneMappings

HRESULT GetZoneMappings(
    [in] DWORD dwZone,
    [out] IEnumString **ppenumString,
    [in] DWORD dwFlags
);

Retrieves the complete set of patterns mapped to a zone.

  • Returns S_OK if successful or E_OUTOFMEMORY if there is not enough memory to complete the operation.
dwZone
DWORD value that contains the zone index.
ppenumString
Address of a pointer to the IEnumString interface that will enumerate the strings for the security zone mappings.
dwFlags
Reserved. Must be set to zero.


IInternetSecurityManager::MapUrlToZone

HRESULT MapUrlToZone(
    [in] LPCWSTR pwszUrl,
    [out] DWORD *pdwZone,
    [in] DWORD dwFlags
);

Retrieves the zone index for the given URL.

  • Returns E_INVALIDARG if pdwZone is set to NULL, or S_OK otherwise.
pwszUrl
String value that contains the URL.
pdwZone
Address of a double-word variable that contains the zone index.
dwFlags
Double-word value that contains flags that control this method. If the value is set to ISECMGR_PREPEND_FILE, IInternetSecurityManager::MapUrlToZone adds the "file:" to the beginning of the URL stored in pwszUrl.


IInternetSecurityManager::ProcessUrlAction

HRESULT ProcessUrlAction(
    [in] LPCWSTR pwszUrl,
    [in] DWORD dwAction,
    [out] BYTE *pPolicy
    [in] DWORD cbPolicy,
    [in] DWORD dwReserved
);

Determines the policy for the specified action, and displays a user interface if the policy indicates that the user should be queried.

  • Returns one of the following values:
    S_OK | Successful, and the URL policy is URLPOLICY_ALLOW.
    S_FALSE | Found a valid URL policy that is not URLPOLICY_ALLOW.
    E_OUTOFMEMORY | Not enough memory to complete the operation.

    The method might also return an HRESULT derived from the Win32 error code ERROR_NOT_FOUND if the URL action could not be read from the registry.

pwszUrl
String value that contains the URL.
dwAction
Double-word value that contains the action to be performed. Can be one of the URL Action Flags values.
pPolicy
Address of the buffer where the policy for the given URL and action will be stored. Can contain one of the URL Policy Flags values.
cbPolicy
Double-word value that contains the size of the buffer.
dwReserved
Reserved. Must be set to zero.


IInternetSecurityManager::QueryCustomPolicy

HRESULT QueryCustomPolicy(
    [in] LPCWSTR pwszUrl,
    [in] REFGUID guidKey,
    [out] BYTE **ppPolicy,
    [out] DWORD *pcbPolicy,
    [in] BYTE *pContext
    [in] DWORD cbContext,
    [in] DWORD dwReserved
);

Retrieves the custom policy associated with the URL and specified key in the given context.

  • Returns S_OK if successful, or E_OUTOFMEMORY if there is not enough memory to complete the operation.

    This method can also return the HRESULT derived from the Win32 error code ERROR_NOT_FOUND if the action could not be read from the registry.

pwszUrl
String value containing the URL.
guidKey
Globally unique identifier associated with the custom policy.
ppPolicy
Address of a pointer to the buffer to store the policy information.
pcbPolicy
Address of a double-word value that contains the policy buffer size.
pContext
Address of a buffer that contains the context information.
cbContext
Unsigned long integer value that contains the size of the context buffer.
dwReserved
Reserved. Must be set to zero.


IInternetSecurityManager::SetSecuritySite

HRESULT SetSecuritySite (
    [in, unique] IInternetSecurityMgrSite *pSite

Sets the security site manager.

  • Returns S_OK if successful.
pSite
Address of the IInternetSecurityMgrSite interface to set.


IInternetSecurityManager::SetZoneMapping

HRESULT SetZoneMapping(
    [in] DWORD dwZone,
    [in] LPCWSTR lpszPattern,
    [in] DWORD dwFlags
);

Maps a pattern into the specified zone.

  • Returns one of the following values:
    S_OK | Success.
    E_ACCESSDENIED | Attempting to enter a non-SSL site into a zone that requires server verification.
    URL_E_INVALID_SCHEME | Either an improper scheme or no scheme is specified in the URL.
    E_FAIL | Mapping already exists.

    The method can also return the HRESULT derived from the Win32 error code ERROR_FILE_EXISTS if the URL already exists in another zone.

dwZone
Double-word value that contains the zone index.
lpszPattern
String value that contains the URL pattern with a limited number of wildcards.
dwFlags
Double-word value that indicates whether the mappings should be added or deleted. Can be one of the SZM_FLAGS values.


IInternetSecurityMgrSite::EnableModeless

HRESULT EnableModeless(
    [in] BOOL fEnable
);

Enables the use of modeless pop-up windows.

  • Returns S_OK if successful, or E_FAIL otherwise.
fEnable
Boolean value that sets whether modeless pop-up windows are used. TRUE enables modeless pop-up windows; FALSE disables them.


IInternetSecurityMgrSite::GetWindow

HRESULT GetWindow(
    [out] HWND *phwnd
);

Retrieves the parent window handle.

  • Returns S_OK if successful, or E_FAIL otherwise.
phwnd
Address of the parent window handle.


IInternetZoneManager::CreateZoneEnumerator

HRESULT CreateZoneEnumerator(
    [out] DWORD *pdwEnum,
    [out] DWORD *pdwCount,
    [in] DWORD dwFlags
);

Creates a zone enumerator.

pdwEnum
Address of the double-word value that serves as the zone enumerator.
pdwCount
Address of a double-word value that contains the number of zones enumerated.
dwFlags
Reserved. Must be set to zero.


IInternetZoneManager::DestroyZoneEnumerator

HRESULT DestroyZoneEnumerator(
    [in] DWORD dwEnum
);

Destroys a zone enumerator.

dwEnum
Double-word enumerator that was created by IInternetZoneManager::CreateZoneEnumerator.


IInternetZoneManager::GetZoneActionPolicy

HRESULT GetZoneActionPolicy(
    [in] DWORD dwZone,
    [in] DWORD dwAction,
    [out] BYTE *pPolicy,
    [in] DWORD cbPolicy,
    [in] URLZONEREG urlZoneReg
);

Retrieves the policy associated with the given URL action.

dwZone
Double-word value of the zone.
dwAction
Double-word value of the action.
pPolicy
Address of the buffer to store the policy information.
cbPolicy
Double-word value containing the size of the buffer.
urlZoneReg
URLZONEREG value that indicates the section in the registry to search.


IInternetZoneManager::GetZoneAt

HRESULT GetZoneAt(
    [in] DWORD dwEnum,
    [in] DWORD dwIndex,
    [out] DWORD *pdwZone
);

Retrieves the zone associated with the specified index on the given enumerator.

dwEnum
Double-word value that contains the enumerator created by IInternetZoneManager::CreateZoneEnumerator.
dwIndex
Double-word value that contains the index of the zone in the enumerator.
pdwZone
Address of a double-word value that contains the zone.

The index set in dwIndex must be greater than or equal to zero and less than or equal to the value pointed to by pdwCount in the call to IInternetZoneManager::CreateZoneEnumerator.


IInternetZoneManager::GetZoneAttributes

HRESULT GetZoneAttributes(
    [in] DWORD dwZone,
    [in, out, unique] ZONEATTRIBUTES *pZoneAttributes
);

Retrieves the zone attributes.

dwZone
Double-word value that contains the zone index.
pZoneAttributes
Address of a ZONEATTRIBUTES variable to store the zone's attributes.


IInternetZoneManager::GetZoneCustomPolicy

HRESULT GetZoneCustomPolicy(
    [in] DWORD dwZone,
    [in] REFGUID guidKey,
    [out] BYTE **ppPolicy,
    [out] DWORD *pcbPolicy,
    [in] URLZONEREG urlZoneReg
);

Retrieves the named custom policy associated with the zone.

  • Returns S_OK if the key is found and the buffer is allocated.
dwZone
Double-word value that contains the zone.
guidKey
Globally unique identifier that indicates the key to look up.
ppPolicy
Address of a buffer to contain the policy information.
pcbPolicy
Address of a double-word value that contains the size of the buffer.
urlZoneReg
URLZONEREG value that determines how the registry is accessed.


IInternetZoneManager::LogAction IInternetZoneManager::LogAction *
  * Previous Topic: IInternetZoneManager::GetZoneCustomPolicy
  * Next Topic: IInternetZoneManager::PromptAction

IInternetZoneManager::LogAction

Not currently implemented.


IInternetZoneManager::PromptAction

HRESULT PromptAction(
    [in] DWORD dwAction,
    [in] HWND hwndParent,
    [in] LPCWSTR pwszUrl,
    [in] LPCWSTR pwszText,
    [in] DWORD dwPromptFlags
);
);

Not currently implemented.


IInternetZoneManager::SetZoneActionPolicy

HRESULT SetZoneActionPolicy(
    [in] DWORD dwZone,
    [in] DWORD dwAction,
    [in] BYTE *pPolicy,
    [in] DWORD cbPolicy,
    [in] URLZONEREG urlZoneReg
);

Sets the action policy associated with a zone.

  • Returns S_OK if the action is valid.
dwZone
Double-word value that contains the zone index.
dwAction
Double-word value that contains the index number of the action.
pPolicy
Address of the buffer that contains the policy information.
cbPolicy
Double-word value that contains the size of the buffer.
urlZoneReg
URLZONEREG value that indicates how the registry is accessed.


IInternetZoneManager::SetZoneAttributes

HRESULT SetZoneAttributes(
    [in] DWORD dwZone,
    [in] ZONEATTRIBUTES *pZoneAttributes
);

Sets the zone attributes.

  • Returns S_OK if successful.
dwZone
Double-word value that contains the zone index.
pZoneAttributes
Address of a ZONEATTRIBUTES value that contains the zone attributes to be set.


IInternetZoneManager::SetZoneCustomPolicy

HRESULT SetZoneCustomPolicy(
    [in] DWORD dwZone,
    [in] REFGUID guidKey,
    [out] BYTE *pPolicy,
    [in] DWORD cbPolicy,
    [in] URLZONEREG urlZoneReg
);

Sets a named custom policy associated with a zone.

  • Returns S_OK if successful.
dwZone
Double-word value that contains the zone index.
guidKey
Globally unique identifier that contains the key.
pPolicy
Address of the buffer that contains the policy to be set.
cbPolicy
Double-word value that contains the size of the buffer.
urlZoneReg
URLZONEREG value that indicates where the information will be set in the registry.


Functions

This section describes the functions included in monikers, URLs, security zones, and pluggable protocols.
CoInternetCreateSecurityManager
CoInternetCreateZoneManager
CoInternetGetSecurityURL


CoInternetCreateSecurityManager CoInternetCreateSecurityManager *
  * Previous Topic: Functions
  * Next Topic: CoInternetCreateZoneManager

CoInternetCreateSecurityManager

Obsolete. Do not use.


CoInternetCreateZoneManager CoInternetCreateZoneManager *
  * Previous Topic: CoInternetCreateSecurityManager
  * Next Topic: CoInternetGetSecurityURL

CoInternetCreateZoneManager

Obsolete. Do not use.


CoInternetGetSecurityURL

HRESULT CoInternetGetSecurityURL(
    LPCWSTR pwzUrl,
    LPWSTR *ppwzSecUrl,
    PSUACTION psuAction,
    DWORD dwReserved
);

Retrieves the security URL for the specified URL.

pwzUrl
String value that contains the URL.
ppwzSecUrl
Address of the string value that contains the security URL.
psuAction
PSUACTION value that determines what information is returned.
dwReserved
Reserved. Must be set to zero.


Structures Structures *
  * Previous Topic: CoInternetGetSecurityURL
  * Next Topic: ZONEATTRIBUTES

Structures

This section contains the structures that are exposed by Urlmon.dll.
ZONEATTRIBUTES


ZONEATTRIBUTES

typedef struct _ZONEATTRIBUTES {
    ULONG cbSize;
    WCHAR szDisplayName[MAX_PATH];
    WCHAR szDescription[MAX_ZONE_DESCRIPTION];
    WCHAR szIconPath[MAX_PATH];
    DWORD dwTemplateMinLevel;
    DWORD dwTemplateRecommended;
    DWORD dwTemplateCurrentLevel;
    DWORD dwFlags;
} ZONEATTRIBUTES, *LPZONEATTRIBUTES;

Contains the attributes of a particular zone.

cbSize
Unsigned long integer value that contains the size of the structure.
szDisplayName
Array of wide characters that contains the display name of the zone.
szDescription
Array of wide characters that contains the description of the zone.
szIconPath
Array of wide characters that contains the path to the icon associated with this zone.
dwTemplateMinLevel
Double-word value that contains the minimum template level.
dwTemplateRecommended
Double-word value that contains the recommended template level.
dwTemplateCurrentLevel
Double-word value that contains the current template level.
dwFlags
Double-word value that contains the flags associated with the specified zone. Can be one of the ZAFLAGS values.


Enumerated Types

This section contains the enumerated types that are exposed by Urlmon.dll.
PSUACTION
PUAF
SZM_FLAGS
URLTEMPLATE
URLZONE
URLZONEREG
ZAFLAGS


PSUACTION

typedef enum _tagPSUACTION{
    PSU_DEFAULT = 1,
    PSU_SECURITY_URL_ONLY
} PSUACTION;

This enumerated type contains the flags passed into the CoInternetGetSecurityURL function.

PSU_DEFAULT
Retrieve the security URL and return its domain.
PSU_SECURITY_URL_ONLY
Retrieve just the security URL.


PUAF

typdef enum {
    PUAF_DEFAULT = 0x0000000,
    PUAF_NOUI = 0x00000001,
    PUAF_ISFILE = 0x00000002,
    PUAF_WARN_IF_DENIED = 0x00000004,
    PUAF_FORCEUI_FOREGROUND = 0x00000008,
    PUAF_CHECK_TIFS = 0x00000010,
} PUAF;

This enumerated type contains the flags passed into IInternetSecurityManager::ProcessUrlAction.

PUAF_DEFAULT
Use the defaults associated with the action.
PUAF_NOUI
Do not display any user interfaces.
PUAF_ISFILE
Assume the URL is a file. The protocol scheme, "file://", is not required.
PUAF_WARN_IF_DENIED
Warn user that a URL action was denied.
PUAF_FORCEUI_FOREGROUND
Force the user interface to be displayed in the foreground.
PUAF_CHECK_TIFS
Obsolete. Do not use.


SZM_FLAGS

typedef enum {
    SZM_CREATE = 0x00000000,
    SZM_DELETE = 0x00000001,
} SZM_FLAGS;

This enumerated type contains the flag values used for creating and enumerating security zone mappings.

SZM_CREATE
Create a new mapping.
SZM_DELETE
Delete the mapping.


URLTEMPLATE

typdef enum tagURLTEMPLATE{
    URLTEMPLATE_CUSTOM = 0x00000,
    URLTEMPLATE_PREDEFINED_MIN = 0x10000,
    URLTEMPLATE_LOW = 0x10000,
    URLTEMPLATE_MEDIUM = 0x11000,
    URLTEMPLATE_HIGH = 0x12000,
    URLTEMPLATE_PREDEFINED_MAX = 0x20000
} URLTEMPLATE;

This enumerated type contains the security level templates.

URLTEMPLATE_CUSTOM
Current set of policies are not based on any template.
URLTEMPLATE_PREDEFINED_MIN
Minimum value of the predefined values for this enumerated type.
URLTEMPLATE_LOW
Use low security settings (all downloads okay).
URLTEMPLATE_MEDIUM
Use medium security settings (user queried before downloading potentially dangerous content).
URLTEMPLATE_HIGH
Use high security settings (no potentially dangerous content is downloaded).
URLTEMPLATE_PREDEFINED_MAX
Maximum value of the predefined values for this enumerated type.


URLZONE

typedef enum tagURLZONE {
    URLZONE_PREDEFINED_MIN = 0,
    URLZONE_LOCAL_MACHINE = 0,
    URLZONE_INTRANET,
    URLZONE_TRUSTED,
    URLZONE_INTERNET,
    URLZONE_UNTRUSTED,
    URLZONE_PREDEFINED_MAX = 999,
    URLZONE_USER_MIN = 1000,
    URLZONE_USER_MAX = 10000
} URLZONE;

This enumerated type contains all the predefined zones used by Internet Explorer.

URLZONE_PREDEFINED_MIN
Minimum value allowed for a zone value.
URLZONE_LOCAL_MACHINE
Zone used for content already on the user's local computer. This zone is not exposed by the user interface.
URLZONE_INTRANET
Zone used for content found on an intranet.
URLZONE_TRUSTED
Zone used for trusted Web sites on the Internet.
URLZONE_INTERNET
Zone used for most of the content on the Internet.
URLZONE_UNTRUSTED
Zone used for Web sites that are not trusted.
URLZONE_PREDEFINED_MAX
Maximum value allowed for a zone value.
URLZONE_USER_MIN
Minimum value allowed for a user-defined zone.
URLZONE_USER_MAX
Maximum value allowed for a user-defined zone.


URLZONEREG

typedef enum _URLZONEREG {
    URLZONEREG_DEFAULT = 0,
    URLZONEREG_HKLM,
    URLZONEREG_HKCU
} URLZONEREG;

This enumerated type contains the registry location values.

URLZONEREG_DEFAULT
Use the default registry location.
URLZONEREG_HKLM
Use HKEY_LOCAL_MACHINE.
URLZONEREG_HKCU
Use HKEY_CURRENT_USER.


ZAFLAGS

typdef enum {
    ZAFLAGS_CUSTOM_EDIT = 0x00000001,
    ZAFLAGS_ADD_SITES = 0x00000002,
    ZAFLAGS_REQUIRE_VERIFICATION = 0x00000004,
    ZAFLAGS_INCLUDE_PROXY_OVERRIDE = 0x00000008,
    ZAFLAGS_INCLUDE_INTRANET_SITES = 0x00000010,
    ZAFLAGS_NO_UI = 0x00000020,
    ZAFLAGS_SUPPORTS_VERIFICATION = 0x00000040,
    ZAFLAGS_UNC_AS_INTRANET = 0x00000080,
} ZAFLAGS;

This enumerated type contains the zone attribute flags.

ZAFLAGS_CUSTOM_EDIT
Edit a custom URL security zone.
ZAFLAGS_ADD_SITES
Add sites to a URL security zone.
ZAFLAGS_REQUIRE_VERIFICATION
Require user verification.
ZAFLAGS_INCLUDE_PROXY_OVERRIDE
Override the proxy settings.
ZAFLAGS_INCLUDE_INTRANET_SITES
URL security zone includes intranet sites.
ZAFLAGS_NO_UI
Do not display any user interfaces.
ZAFLAGS_SUPPORTS_VERIFICATION
Supports server verification.
ZAFLAGS_UNC_AS_INTRANET


URL Security Zone Flags

The URL security zones use two sets of values: URL actions and URL policies. The URL actions determine what actions can be taken in a given security zone. URL policies define how a URL action will be handled.

URL Action Flags

URL Policy Flags


URL Action Flags

The following list contains the values associated with the actions that can be taken in a URL security zone.

URLACTION_ACTIVEX_CONFIRM_NOOBJECTSAFETY
User can decide whether to load and script an ActiveX control that is not safe.
URLACTION_ACTIVEX_CURR_MAX
Current maximum value of the URL action ActiveX flags.
URLACTION_ACTIVEX_MAX
Maximum value of the URL action ActiveX flags.
URLACTION_ACTIVEX_MIN
Minimum value of the URL action ActiveX flags.
URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY
Determines if ActiveX safety for untrusted data can be overridden.
URLACTION_ACTIVEX_OVERRIDE_OBJECT_SAFETY
Determines if the ActiveX control object safety is overridden or enforced for pages in the URL security zone. Object safety should be overridden only if all ActiveX Controls and scripts that might interact with them on pages in the zone can be reliably trusted not to breach security. Aggregate of URLACTION_ACTIVEX_OVERRIDE_DATA_SAFETY and URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY.
URLACTION_ACTIVEX_OVERRIDE_SCRIPT_SAFETY
Determines whether ActiveX safety for scripting is overridden.
URLACTION_ACTIVEX_RUN
Manages the execution of ActiveX Controls and plug-ins from HTML pages in the zone.
URLACTION_ACTIVEX_TREATSUNTRUSTED
Not currently implemented.
URLACTION_AUTHENTICATE_CLIENT
Determines the strength of client authentication when the user's credentials are used over the network. This URL action does not have any effect if the URL action URLACTION_CREDENTIALS_USE is assigned the URL policy URLPOLICY_CREDENTIALS_ANONYMOUS_ONLY.
URLACTION_CHANNEL_SOFTDIST_MAX
Maximum value for a URL action Software Update Channel flag.
URLACTION_CHANNEL_SOFTDIST_MIN
Minimum value for a URL action Software Update Channel flag.
URLACTION_CHANNEL_SOFTDIST_PERMISSIONS
Determines the level of trust placed on Software Update Channels.
URLACTION_CREDENTIALS_USE
Determines how the user's credentials are used over the network.
URLACTION_DOWNLOAD_CURR_MAX
Maximum value for the URL action download flags.
URLACTION_DOWNLOAD_MAX
Maximum value of a URL action download flag.
URLACTION_DOWNLOAD_MIN
Mimimum value of a URL action download flag.
URLACTION_DOWNLOAD_SIGNED_ACTIVEX
Manages the download of signed ActiveX Controls from the URL zone of the HTML page that contains the control.
URLACTION_DOWNLOAD_UNSIGNED_ACTIVEX
Manages the download of unsigned ActiveX Controls from the URL zone of the HTML page that contains the control.
URLACTION_HTML_CURR_MAX
Current maximum value of the URL action HTML flags.
URLACTION_HTML_FONT_DOWNLOAD
Determines if HTML font downloads are allowed.
URLACTION_HTML_JAVA_RUN
Determines if Java applets are allowed to run.
URLACTION_HTML_MAX
Maximum value of the URL action HTML flags.
URLACTION_HTML_MIN
Minimum value of the URL action HTML flags.
URLACTION_HTML_SUBMIT_FORMS
Determines if HTML forms on pages in the URL security zone, or submitted to servers in the zone, are allowed. Aggregate of the URLACTION_HTML_SUBMIT_FORMS_FROM and URLACTION_HTML_SUBMIT_FORMS_TO flags.
URLACTION_HTML_SUBMIT_FORMS_FROM
Determines if form submissions from pages in the security zone are allowed. This flag is part of the URLACTION_HTML_SUBMIT_FORMS aggregate flag.
URLACTION_HTML_SUBMIT_FORMS_TO
Determines if form submissions to a server in the security zone are allowed. This flag is part of the URLACTION_HTML_SUBMIT_FORMS aggregate flag.
URLACTION_INFODELIVERY_CURR_MAX
Reserved for future use.
URLACTION_INFODELIVERY_MAX
Reserved for future use.
URLACTION_INFODELIVERY_MIN
Reserved for future use.
URLACTION_INFODELIVERY_NO_ADDING_CHANNELS
Reserved for future use.
URLACTION_INFODELIVERY_NO_ADDING_SUBSCRIPTIONS
Reserved for future use.
URLACTION_INFODELIVERY_NO_CHANNEL_LOGGING
Reserved for future use.
URLACTION_INFODELIVERY_NO_EDITING_CHANNELS
Reserved for future use.
URLACTION_INFODELIVERY_NO_EDITING_SUBSCRIPTIONS
Reserved for future use.
URLACTION_INFODELIVERY_NO_REMOVING_CHANNELS
Reserved for future use.
URLACTION_INFODELIVERY_NO_REMOVING_SUBSCRIPTIONS
Reserved for future use.
URLACTION_JAVA_CURR_MAX
Current maximum value of the URL action Java flags.
URLACTION_JAVA_MAX
Maximum value for URL action Java flags.
URLACTION_JAVA_MIN
Minimum value for URL action Java flags.
URLACTION_JAVA_PERMISSIONS
Determines the Java permissions for the zone.
URLACTION_NETWORK_CURR_MAX
Current maximum value for URL action network flags.
URLACTION_NETWORK_MAX
Maximum value for URL action network flags.
URLACTION_NETWORK_MIN
Minimum value for URL action network flags.
URLACTION_SCRIPT_SAFE_ACTIVEX
Determines if scripting of safe ActiveX controls is allowed or not.
URLACTION_SCRIPT_CURR_MAX
Current maximum value for a URL action script flag.
URLACTION_SCRIPT_JAVA_USE
Determines if script code on HTML pages in the URL security zone can use Java applets if the properties, methods, and events of the applet are exposed to scripts or not.
URLACTION_SCRIPT_MAX
Maximum value for a URL action script flag.
URLACTION_SCRIPT_MIN
Minimum value for a URL action script flag.
URLACTION_SCRIPT_OVERRIDE_SAFETY
Do not use ActiveX safety for objects created by scripts.
URLACTION_SCRIPT_RUN
Determines if script code on the pages in the URL security zone are run or not.
URLACTION_SHELL_CURR_MAX
Current maximum value for a URL action shell flag.
URLACTION_SHELL_FILE_DOWNLOAD
Determines if file downloads are permitted from the URL security zone of the HTML page with the link that is causing the download.
URLACTION_SHELL_INSTALL_DTITEMS
Determines if desktop items can be installed.
URLACTION_SHELL_MAX
Maximum value for a URL action shell flag.
URLACTION_SHELL_MIN
Minimum value for a URL action shell flag.
URLACTION_SHELL_MOVE_OR_COPY
Determines if move or copy operations are allowed.
URLACTION_SHELL_VERB
Determines if launching of applications and files is permitted from the URL security zone.
URLACTION_SHELL_WEBVIEW_VERB
Determines if executable files and HTML pages can be launched from WebView. There is no user interface that affects this URL action.


URL Policy Flags

The following list contains the values associated with the policies used with the URL action flags.

URLPOLICY_ALLOW
Allow the action to take place silently.
URLPOLICY_AUTHENTICATE_CHALLENGE_RESPONSE
Use challenge-response authentication schemes (such as NTLM).
URLPOLICY_AUTHENTICATE_CLEARTEXT_OK
Use basic HTTP authentication.
URLPOLICY_AUTHENTICATE_MUTUAL_ONLY
Require mutual authentication with the server.
URLPOLICY_CHANNEL_SOFTDIST_AUTOINSTALL
Allow automatic installation of software updates.
URLPOLICY_CHANNEL_SOFTDIST_PRECACHE
Cache content downloaded from Software Update Channels.
URLPOLICY_CHANNEL_SOFTDIST_PROHIBIT
Prohibit downloads from Software Update Channels.
URLPOLICY_CREDENTIALS_ANONYMOUS_ONLY
Only allow anonymous logons, so the user's credentials are not exposed.
URLPOLICY_CREDENTIALS_MUST_PROMPT_USER
Prompt user to enter a username and password.
URLPOLICY_CREDENTIALS_SILENT_LOGON_OK
Automatically log on with the user's credentials.
URLPOLICY_DISALLOW
Do not allow the action.
URLPOLICY_JAVA_CUSTOM
Not currently implemented.
URLPOLICY_JAVA_HIGH
Set high Java security. Java applets will run in a sandbox.
URLPOLICY_JAVA_LOW
Set low Java security. Java applets will be allowed to do high-capability operations, such as file I/O.
URLPOLICY_JAVA_MEDIUM
Set medium Java security. Java applets run in a sandbox with additional capabilities, such as scratch space.
URLPOLICY_JAVA_PROHIBIT
Prevent Java applets from running.
URLPOLICY_MASK_PERMISSIONS
Mask that can be used for comparisons to get the bits that have to do with permissions.
URLPOLICY_QUERY
Prompt the user to determine if an action is allowed.


Microsoft Web Publishing SDK

This section provides all the information necessary to make use of the Microsoft® Web Publishing Software Development Kit (SDK). It details the specification of the Web Publishing API, the Web Publishing Service Provider interface, and the Web Publishing File Upload Control interface.

Web Publishing Overview

Web Publishing Programmer's Reference


Web Publishing Overview

This section describes the Microsoft® Web Publishing Software Development Kit (SDK), including a description of the command-line options for the Web Publishing Wizard, Wpwiz.exe. Use this SDK to access Web Publishing functionality through your application.

For detailed descriptions of the interface methods and for code examples, see the Web Publishing Programmer's Reference. Note that the examples in the Web Publishing Programmer's Reference are not complete samples and often omit most error processing.

What's in the SDK

Web Publishing Sites

The Posting Information File

The Web Publishing API

The Web Publishing SPI

The File Upload Control

Web Publishing Wizard

What's in the SDK

The Web Publishing SDK includes the following:
The application programming interface (API). The API is designed for use by applications that want to include Web Publishing functionality. The API manages multiple publishing destinations (called sites) and calls the service provider interface (SPI) to do the work of transferring the files over the network. The API can support multiple service providers (implementations of the SPI), and provides mechanisms for selecting from among installed providers when setting up a new site.
The service provider interface (SPI). The SPI consists of a COM interface and several helper functions; the latter must be callable entry points in the DLL that services the COM interface.
The File Upload Control. This control packages the Web Publishing API's functionality in an ActiveX(tm) control, which can easily be included on HTML pages.

Web Publishing Sites

A site is a destination to which files can be published. Typically this is a computer connected to the Internet and running an HTTP server. The concept of a site in the Web Publishing API encompasses all information required in order to get files from the user's local computer onto the destination computer. The API handles management of the core set of information common to all varieties of sites, namely:

  • A friendly name.
  • The URL from which the files will be retrievable once they have been published (called the destination URL).
  • The service provider installed on the user's local computer that is used to transfer files to the destination computer.
  • A local base directory that corresponds to the destination URL. This is an optional feature of a site; if it is set it indicates how much of the path of a local file should be preserved when publishing to the destination computer. For example, if a site "MySite" has its local base directory set to C:\MYSITE and its destination URL set to http://www.mysite.com, then these example files would be posted as follows.
    Local file | Posted to
    c:\mysite\file.html | http://www.mysite.com/file.html
    c:\mysite\images\gifs\me.gif | http://www.mysite.com/images/gifs/me.gif

    If a file is posted to a site with a local base directory specified, and the file is not under the local base directory tree, it is posted directly to the destination URL.
    Local file | Posted to
    c:\site2\images\icons\redball.gif | http://www.mysite.com/redball.gif

When the preceding information is gathered and stored for a given destination computer, a site is said to be "created." WpCreateSite collects these four pieces of information, either from the parameters passed to it or possibly, in the case of the service provider, by querying the service providers installed on the system to see whether they can publish to the specified destination URL. The information is then stored in a registry key under HKCU\Software\Microsoft\WebPost\Sites named with the friendly name of the site.

It is likely that most service providers will require more than this minimal set of information in order to get files onto the destination computer. For instance, the Microsoft® FTP service provider requires the name of the FTP server, the subfolder on the server, and possibly a user name and password in order to upload files. Service providers are encouraged to store this extra information on the same site key used by the API. Aside from simple centralization, the advantage of keeping information there is that any parameter values specified in the posting information file on the destination computer (see The Posting Information File) are automatically saved under this key when the site is first configured, making those parameters easily available to the service provider and possibly eliminating the need to obtain technical information from the user.

The Posting Information File

Because of variations among Internet servers, Microsoft requests that Internet service providers (ISPs) include a posting information file on their Internet servers. This file contains details about the posting protocol and policy. The Web Publishing API uses the information in the file to help with the detection of the Web Publishing protocol.

The version 1.5 release supports a new mechanism that meets with the approval of the W3C, in addition to the old postinfo.htm from version 1.1. The new mechanism allows the ISP to place a <META NAME="POSTINFO" CONTENT="URL"> tag in the default page on their server. This tag specifies a URL to the posting information file. The URL can be any path (even another machine) with any name but must be enclosed in quotation marks.

The file is simply a text file with sections and keys. The version statement must be the first statement in the file, followed by section(s) defining the transfer types. Multiple protocols can be supported on the server. Each new protocol section must start with the transfer type in brackets and include keys required by that provider. The transfer types must appear in priority order. When the Web Publishing client binds to a site it will attempt to use the first protocol listed; if that is not available, then it will try the next, and so on The transfer type can be specified as either a program ID or a GUID, enclosed in brackets. The convention for a program ID is Webpost.ProviderDll, where ProviderDll is the actual file name of the provider. A GUID must include the standard braces within the brackets. The GUIDs for the installed providers can be found in the registry under HKLM\System\CurrentControlSet\Services\Webpost\Providers.

All blank lines will be ignored and the fields are not case sensitive. Case will be preserved on all quoted string values. The keys can appear in any order within a section. There is one supported parameter and that is the $USERNAME variable. The Web Publishing client will substitute the local user name for that value when read from the server. The following is a sample posting information file that could appear on a server:

Version=1.5

[WebPost.FTPWPP]
ServerName="Server"
Subfolder="ftpupl/$USERNAME"
DefaultPage="default.html"

[WebPost.CRSWPP]
ServerName="Server"

For a complete list of parameters for different service providers, including CRS, FTP, and HTTP, see Appendix C, Parameters, in the Web Publishing Programmer's Reference.

The Web Publishing API

The Web Publishing application programming interface (API) makes it possible for authoring tools to post Web pages to an Internet site with just one call to the WpPost function. In a typical scenario, an authoring tool's File menu would include a "Post to Web" command that, when clicked, causes the tool to call the WpPost function. This function starts a wizard that asks the user for a friendly name for the Internet site and the Uniform Resource Locator (URL) for the site. Next, the function connects to the Internet server at the given URL, determines the protocol to use for posting the Web pages, and then posts the requested files. For subsequent posting to the same site, this function remembers the details of how to connect to the site, and posts the files with little user intervention. Thus, the Web Publishing API maintains a friendly site name, remembers all the details involved in posting to that site, and allows the applications to easily post Web pages to a site or to the URL associated with that site.

As an alternative to the wizard, an authoring tool can let the user choose the Web site before calling WpPost by displaying a list of sites (plus a "New Site" item) obtained by a call to the WpListSites function. The list of sites could be in a nested menu that appears when the user clicks the "Post to Web" command.

Interface Definition

The Web Publishing API consists of the following methods.
Method | Description
WpBindToSite | Obtains a pointer to a service provider object supporting either the IWPSite interface or the IWPProvider interface.
WpCreateSite | Creates a new site entry in the registry.
WpCreateSiteEx | Creates a new site entry in the registry, using a user name and password.
WpDeleteSite | Deletes the information for a site from the registry.
WpDoesSiteExist | Determines whether or not the specified site exists.
WpEnumProviders | Enumerates the currently installed service providers.
WpGetErrorString | Translates an error code.
WpListSites | Lists the sites for which there is currently information in the registry.
WpPost | Posts one or more files or directories to the specified site.
WpPostEx | Posts one or more files or directories to the specified site, using a user name and password.
WpPostFile | Posts one file or directory to the specified site.

The Web Publishing SPI

The Web Publishing service provider interface (SPI) describes the interface each service provider must support to allow the core web publishing services to post content. The SPI DLLs are OLE COM servers provide the following methods and helper functions. The Web Publishing API functions and the Web Publishing Wizard route requests to a provider based on a site name or URL, and use the SPI functions to post the files.

Interface Definition

The Web Publishing SPI consists of the following methods.
Helper function | Description
WppBindToSite | Retrieves the address of an interface if the provider DLL owns the site name or the URL.
WppDeleteSite | Deletes a site name that has been configured.
Interface method | Description
AddWizardPages | Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.
DeleteFile | Deletes the given file from the destination site.
FindClose | Closes the specified search handle.
FindFirstFile | Searches a directory for a file whose name matches the specified file name on the destination site.
FindNextFile | Continues a file search from a previous call to the FindFirstFile function.
GetError | Retrieves additional information about an error.
GetParam | Retrieves a parameter value for this site.
GetSiteInfo | Retrieves the site information for the current object.
NetworkConnect | Connects to the Internet.
NetworkDisconnect | Disconnects from the Internet.
PostFiles | Posts files to the specified URL.
ServerLogin | Logs the user on to the Internet server.
ServerLogout | Logs the user out of the Internet server.
SetParam | Sets the value of a parameter for a given site.
SetProgressUpdateProc | Specifies the callback function.

Helper Functions

Each service provider DLL must export one helper function not available through the COM interface: WppBindToSite. This entry point will be called from WpBindToSite and WpPost in order to obtain a pointer to the service provider object. It will also be called from WpCreateSite.

If a service provider exports a WppDeleteSite entry point, it will be called from WpDeleteSite.

Note that one of the primary design changes in Web Publishing 1.5 is the shift of responsibility for maintaining site information from the individual service providers to the Web Publishing API. Providers should not maintain site-related state information independently of the Web Publishing API except when necessary. However, if separate record-keeping is necessary, a service provider is guaranteed under this model to be notified whenever sites are added, removed, or utilized for posting.

Self-Registration Responsibilities

Service provider DLLs are required to export a DllRegisterServer method that performs the following functions:

  1. Registers its object's CLSID according to standard COM procedure.
  2. Inserts a subkey for itself under HKLM\System\CurrentControlSet\Services\WebPost\Providers named with its CLSID and containing the following values.
    Value | Meaning
    Provider | A string that contains the name of the provider. This name is used in the wizard; it appears in the list box that contains the names of the providers.
    Path | A string that contains the path of the service provider DLL.
    Priority | A DWORD value that indicates the provider's priority. Zero is highest priority. Microsoft Web Publishing 1.5 service providers' priorities start at 0x00010000 and are 0x00000100 apart.
    PostInfoRequired(new) | If this DWORD value is non-zero, then this service provider requires a posting information file in order to obtain all the information necessary to post. If the posting information file cannot be retrieved, the attempt to create a site using this provider will fail.
  3. (Optional.) Calls WpCreateSite to add the sites it supports to the registry.

The File Upload Control

The File Upload Control is an ActiveX control that uses the Web Publishing API. It can be included on an HTML page to allow posting to a server. Typical applications would be for a file upload area, or for an ISP to allow easy uploading to a personal Web pages site. The control also provides all configuration information normally provided by the wizard.

When the user sees the control on a page, he or she can simply drag files onto it to have them instantly sent, or double-click to display a dialog allowing selection of the local files to be transmitted. Right-clicking the icon will bring up a property sheet for the site, which will allow the user to edit the parameters.

Note If you intend to use this control from Visual Basic® applications on machines where Internet Explorer is not installed, you will need the following binary files: OLEPRO32.DLL, MSVCRT40.DLL, MSVCIRT.DLL.

Interface Definition

The File Upload Control interface has the following methods.
Method | Description
AboutBox | Displays information about the File Upload Control.
CreatePermBinding | Creates a permanent site and binds to it.
CreateTempBinding | Creates a temporary site and binds to it.
FoundPostInfo | Checks whether a postinfo file was found on the target server.
SetBindingParam | Sets binding parameters.

If the site should be retained on the client machine after the post is complete, the CreatePermBinding method should be used. The CreatePermBinding method will allow the author to specify a site name, URL, and, optionally, a provider. The call will return a value indicating whether the site was created, the site already existed, or the call failed. The author also has the ability to determine whether the path information from the client will be preserved when passing the file to the server. There are three flags supported for this method: strip, preserve, and prompt. The strip option can be used in a raw file upload situation where only the files are desired. The preserve option will assume the path of the first file/directory sent will become the base directory for this site. The prompt option will display a dialog allowing the user to set the local base directory. This dialog will be preloaded with the path of the first file/directory but the user will be allowed to change it as needed.

If the site definition will only be used for a single session, the CreateTempBinding method should be called. The only UI required of the ActiveX control is the file selection dialog, which is only displayed if the user double-clicks the icon, a transferring files dialog similar to the one used in the wizard, and a dialog indicating the completion status (success or error). There is also a dialog that can be brought up on a right-click that allows the user to set the local base directory.

Web Publishing Wizard

This section describes the command-line options for the Web Publishing Wizard, Wpwiz.exe.

Syntax

Wpwiz [–w "FriendlyName"] [–u "URL"] [–n "UserName"] [–p "password"] [–s "Service"] [–f [flags]] path [...]
Parameters
-w "FriendlyName" | The friendly name to use for the site.
-u "URL" | The destination URL to use for the site.
-n "UserName" | The username to use for the site.
-p "Password" | The password to use for the site.
-s "Service" | The service provider to use for the site.
-f[flags] Force flags. By default the Wizard will skip any pages for which the required information has already been provided on the command line. These flags allow you to override this default behavior and force the Wizard to show whatever pages you specify.

There should not be a space between the "-f" and the list of page letter-identifiers. The letter-identifiers may appear in any order, and again should not be separated by spaces. The letter-identifiers are:
a | All pages (shorthand for "iswnup")
i | Introductory (welcome) page
s | Source paths page (where user specifies file/folder to be published)
w | Web server page (where user selects from list of existing friendly-named sites)
n | Name the web server pages (where user provides friendly name for new site)
u | URL page (where user provides URL for new site)
p | Provider-specific pages (i.e., FTP prompts for Server name and Subfolder)

-b | Disable auto-binding. This only applies when a new site is being created.
-i | Don't recurse into folder being published; only publish its immediate children.
path [path [path [...]]] | List of files to be published. Paths must be complete and absolute. Paths may be interspersed with flags.

Example

The following example invokes the Web Publishing wizard with the friendly name New Site, the URL http://myserver.com/myfolder, the user name anonymous, the password e-mail, with all flags and no auto-binding on the files Index.htm and Hello.htm. Note that the final path must be enclosed in double-quote marks since it contains a space.

C:\> wpwiz -w "New Site" -u "http://myserver.com/myfolder"
-n "anonymous" -p "e-mail" -s "FTP" -fa -b -i C:\Index.htm
"C:\HTML Files\Hello.htm"


Web Publishing Programmer's Reference

This section contains detailed descriptions of the interface methods and code examples for the Microsoft® Web Publishing Software Development Kit (SDK.) The examples in the Programmer's Reference are not complete samples and often omit most error processing.

Please read the Web Publishing Overview first for overview and general information about the Web Publishing SDK.

Note The Web Publishing interfaces (including the File Upload Control interface) cannot be used from a UI-less environment. For instance, if a pop-up dialog is created during a server-side run, the client never sees the dialog on its end and the process cannot complete.

Conventions

The Web Publishing API

The Web Publishing SPI

The File Upload Control Interface

Appendix A, Structures

Appendix B, Error Codes

Appendix C, Parameters


Conventions

The following text formats are used throughout this document.
Bold text | Denotes a term or character to be typed literally, such as a predefined data type or function name (HWND or GetExtendedError.) You must type these terms exactly as shown.
Italic text | Denotes a placeholder or variable. You must provide the actual value. For example, the statement SetCursorPos(X, Y) requires you to substitute values for the X and Y parameters.
SMALL CAPITALS | Indicates the names of keys, key sequences, and key combinations—for example, ALT+SPACEBAR.
FULL CAPITALS | Indicates most type and structure names, which are also bold, and constants.
monospace | Sets off code examples and shows syntax spacing.
[] Encloses optional parameters.
| Separates an either/or choice.


The Web Publishing API

The Web Publishing API consists of the following methods.
Method | Description
WpBindToSite | Obtains a pointer to a service provider object supporting either the IWPSite interface or the IWPProvider interface.
WpCreateSite | Creates a new site entry in the registry.
WpCreateSiteEx | Creates a new site entry in the registry, using a user name and password.
WpDeleteSite | Deletes the information for a site from the registry.
WpDoesSiteExist | Determines whether or not the specified site exists.
WpEnumProviders | Enumerates the currently installed service providers.
WpGetErrorString | Translates an error code.
WpListSites | Lists the sites for which there is currently information in the registry.
WpPost | Posts one or more files or directories to the specified site.
WpPostEx | Posts one or more files or directories to the specified site, using a user name and password.
WpPostFile | Posts one file or directory to the specified site.


WpBindToSite

DWORD WpBindToSite(
    [in]		HWND	hWnd
    [in, string]	LPTSTR	szSiteName
    [in, string]	LPTSTR	szSiteURL
    [in]	DWORD		dwFlags
    [in]	DWORD		dwReserved
    [out]	LPVOID *	ppUnk
    );

Attempts to determine the provider responsible for servicing the specified site based upon szSiteName and/or szSiteURL.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    E_OUTOFMEMORY
    WEBPOST_ERROR_LIST_SITES
    WEBPOST_ERROR_SITE_CORRUPT
    WEBPOST_ERROR_PROVCLSID_UNKNOWN
    WEBPOST_ERROR_PROV_CORRUPT
    WEBPOST_ERROR_PROV_DLL
    WEBPOST_ERROR_PROV_EP
    WEBPOST_ERROR_BAD_PROV_PTR
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO

    More information about these error codes can be found in Appendix B, Error Codes.

hWnd
Optional. Window handle to receive focus upon completion of this API call. May be NULL.
szSiteName
Posting site name. May be NULL if valid szSiteURL is given.
szSiteURL
Posting site URL. May be NULL if valid szSiteName is given.
dwFlags
Action flags. Possible values are shown in the following table.
Value | Meaning
WPF_NO_DIRECT_LOOKUP | Do not attempt to look up the site based on the posting site name. This has the same effect as a NULL or empty szSiteName.
WPF_NO_URL_LOOKUP | Do not attempt to look up the site based on the posting site URL. This has the same effect as a NULL or empty szSiteURL.
dwReserved
Reserved. Must be set to zero.
ppUnk
Address of an IUnknown pointer, which can be queried upon return to determine whether the service provider supports the old IWPSite or the new IWPProvider interface. May not be NULL.

The site lookup procedure works as follows:

  1. If szSiteName and szSiteURL are both either NULL or empty, return E_INVALIDARG.
  2. Registry lookup. If szSiteName is non-NULL/empty and WPF_NO_DIRECT_LOOKUP is not set:
    1. Get a site subkey.
    2. Check szSiteName for a match with the subkey name. If there is a match, get the site URL and call WppBindToSite into the indicated provider with the WPF_FORCE_BIND flag and return the interface pointer so obtained.
    3. If all subkeys have been enumerated, proceed to URL Lookup. Otherwise return to step 2-1.
  3. URL lookup. If szSiteURL is non-NULL/empty and WPF_NO_URL_LOOKUP is not set:
    1. Get a site subkey.
    2. Check whether the szSiteURL value of the subkey is a prefix of szSiteURL. If so, get the site name and call WppBindToSite into the indicated provider with the WPF_FORCE_BIND flag and return the interface pointer so obtained.
    3. If all subkeys have been enumerated, quit with error result. Otherwise return to step 3-1.

Examples
C/C++

{
    HRESULT hResult = NOERROR;
    void *pUnknown;

    hResult = WpBindToSite(NULL, "site1", NULL, 0, 0, &pUnknown);
}


WpCreateSite

DWORD WpCreateSite(
    [in, string]	LPTSTR	szSiteName
    [in, string]	LPTSTR	szSiteLocalBaseDir
    [in, string]	LPTSTR	szSiteURL
    [in, string]	LPTSTR	szProviderCLSID
    [in]		DWORD	dwFlags
    );

Creates a new site in the registry.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    E_OUTOFMEMORY
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_CREATE_SITE
    WEBPOST_ERROR_INVALID_POSTINFO
    WEBPOST_ERROR_NO_POSTINFO
    WEBPOST_ERROR_PROV_DLL
    WEBPOST_ERROR_PROV_EP
    WEBPOST_ERROR_SITE_EXISTS
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO
    WEBPOST_ERROR_POSTINFO_REQUIRED
    WEBPOST_ERROR_AUTOBIND_FAILED

    More information about these error codes can be found in Appendix B, Error Codes.

szSiteName
Posting site name.
szSiteLocalBaseDir
Optional. Local base directory for the site. If NULL, then the local base directory feature is not used for the site.
szSiteURL
Posting site URL.
szProviderCLSID
Optional. CLSID as string, of the provider that will handle this site. If NULL, then this method will search for a posting information (postinfo) file or attempt to auto-bind to an appropriate provider.
dwFlags
Optional.
WPF_USE_PROVIDER_PASSED If WpCreateSite has been called and returned WEBPOST_ERROR_PROV_NOT_IN_POSTINFO, use this flag to have WpCreateSiteExuse the provider specified in szProviderCLSID even if there is a postinfo file and it does not list this provider.

Examples
C/C++

{
    HRESULT hResult = NOERROR;

    hResult = WpCreateSite("site1", NULL, "http://site1", NULL, 0);
}


WpCreateSiteEx

DWORD WpCreateSiteEx(
    [in, string]	LPTSTR	szSiteName
    [in, string]	LPTSTR	szSiteLocalBaseDir
    [in, string]	LPTSTR	szSiteURL
    [in, string]	LPTSTR	szProviderCLSID
    [in, string]	LPTSTR	szUsername,
    [in, string]	LPSTR		szPassword,
    [in]		DWORD		dwFlags,
    [out]		Iunknown	**ppSPI,
    [out]		DWORD		*pdwCharSet
    );

Creates a new site in the registry, using a user name and password, and returns a pointer to the service provider interface.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    E_OUTOFMEMORY
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_CREATE_SITE
    WEBPOST_ERROR_INVALID_POSTINFO
    WEBPOST_ERROR_NO_POSTINFO
    WEBPOST_ERROR_PROV_DLL
    WEBPOST_ERROR_PROV_EP
    WEBPOST_ERROR_SITE_EXISTS
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO
    WEBPOST_ERROR_POSTINFO_REQUIRED
    WEBPOST_ERROR_AUTOBIND_FAILED

    More information about these error codes can be found in Appendix B, Error Codes.

szSiteName
Posting site name.
szSiteLocalBaseDir
Optional. Local base directory for the site. If NULL, then the local base directory feature is not used for the site.
szSiteURL
Posting site URL.
szProviderCLSID
Optional. CLSID as string, of the provider that will handle this site. If NULL, then this method will search for a posting information (postinfo) file or attempt to auto-bind to an appropriate provider.
szUsername
Optional. The user name to use when logging on to the remote servers. If NULL or incorrect, the user is prompted to supply a user name and password.
szPassword
Optional. The password to use when logging on to the remote servers. If NULL or incorrect, the user is prompted to supply a user name and password.
dwFlags
Optional.
WPF_USE_PROVIDER_PASSED If WpCreateSite has been called and returned WEBPOST_ERROR_PROV_NOT_IN_POSTINFO, use this flag to have WpCreateSiteExuse the provider specified in szProviderCLSID even if there is a postinfo file and it does not list this provider.
**ppSPI
Optional. If WpCreateSiteExreturns successfully, *pSPI should point to a IWPSiteA, IWPSiteW, or IWPProvider interface.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    IUnknown *pUnkSPI = NULL;
    DWORD dwCharSet;

    hResult = WpCreateSiteEx(
        "site1",
        NULL,
        "http://site1",
        NULL,
        "CRSadmin",
        "ptmyhygmn",
        NULL,
        0,
        &pUnkSPI,
        &dwCharSet);
}


WpDeleteSite

DWORD WpDeleteSite(
    [in, string]	LPTSTR	szSiteName
    );

Deletes a site from the registry.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_SITE_DOESNOTEXIST
    WEBPOST_ERROR_PROV_EP
    WEBPOST_ERROR_DELETE_SITE
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO

    More information about these error codes can be found in Appendix B, Error Codes.

szSiteName
Posting site name.

WpDeleteSite calls WppDeleteSite on the provider that owns the specified site.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;

    hResult = WpDeleteSite("site1");
}


WpDoesSiteExist

DWORD WpDoesSiteExist(
    [in, string]	LPTSTR	szSiteName
    [out]		BOOL	*	pbSiteExists
    );

Checks to see whether a site with the specified name exists.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    WEBPOST_ERROR_INIT_FAILED

    More information about these error codes can be found in Appendix B, Error Codes.

szSiteName
Posting site name.
pbSiteExists
Returned as TRUE if site exists, FALSE otherwise.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    BOOL b;

    hResult = WpDoesSiteExist("site1",&b);
}


WpEnumProviders

DWORD WpEnumProviders(
    [in, out]		LPDWORD		pdwProvidersBufLen
    [out]		LPWPPROVINFO	pProvidersBuffer
    [out]		LPDWORD		pdwNumProviders
    );

Retrieves the list of all currently registered providers.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    E_OUTOFMEMORY
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_PROV_CORRUPT
    WEBPOST_ERROR_ENUM_PROVS

    More information about these error codes can be found in Appendix B, Error Codes.

pdwProvidersBufLen
Size, in bytes, of pProvidersBuffer. On return, contains the actual number of bytes used in pProvidersBuffer. If pProvidersBuffer is NULL or too small to hold all the providers, this parameter shows the necessary size of the buffer to allocate.
pProvidersBuffer
Receives an array of WPPROVINFO structures.
pdwNumProviders
Number of providers. This value is set whether or not pProvidersBuffer is NULL or points to a large enough buffer.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;
    DWORD Num;

    hResult = WpEnumProviders(&BufLen, NULL, &Num);
}


WpGetErrorString

DWORD WpGetErrorString(
    [in]		UINT		uErrCode
    [in, out]		LPTSTR	szOutputBuf
    [in, out]		DWORD *	pdwBuflen
    );

Provides a textual explanation of the specified error code.

  • Returns NO_ERROR if successful. If the error code could not be translated, returns an E_FAIL error code.
uErrCode
The error code to translate.
szOutputBuf
The error message as NULL-terminated string. If NULL or not large enough, then use the value returned in pdwBufLen to allocate the necessary buffer.
pdwBufLen
On entry, the size of buffer provided. On return, the required buffer size in bytes.

The error code is first looked up in Web Publishing's error message table, then in the Win32® system table. If the error code cannot be translated, the function returns E_FAIL and the buffer is filled with an "Unknown Error" message.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;

    hResult = WpGetErrorString(0, NULL, &BufLen);
}


WpListSites

DWORD WpListSites(
    [in, out]		LPDWORD		pdwSitesBufLen
    [out]		LPWPSITEINFO	pSitesBuffer
    [out]		LPDWORD		pdwNumSites
    );

Retrieves the list of all sites about which Web Publishing currently has information.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    E_INVALIDARG
    E_OUTOFMEMORY
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_SITE_CORRUPT
    WEBPOST_ERROR_LIST_SITES

    More information about these error codes can be found in Appendix B, Error Codes.

pdwSitesBufLen
Size, in bytes, of pSitesBuffer. On return, contains the actual number of bytes used in pSitesBuffer. If pSitesBuffer is NULL or too small to hold all the sites, this parameter shows the necessary size of the buffer to allocate.
pSitesBuffer
Receives an array of WPSITEINFO structures.
pdwNumSites
Number of sites. This value is set whether or not pdwSitesBuffer is NULL or points to a large enough buffer.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    DWORD BufLen;
    DWORD Num;

    hResult = WpListSites(&BufLen, NULL, &Num);
}


WpPost

DWORD WpPost(
    [in]		HWND 	hWnd
    [in]		DWORD	dwNumLocalPaths
    [in]		LPTSTR *	pszLocalPaths
    [in, out]		LPDWORD	pdwSiteNameBufLen
    [in, out]		LPTSTR	szSiteName
    [in, out]		LPDWORD	pdwDestURLBufLen
    [in, out]		LPTSTR	szDestURL
    [in]		DWORD	dwFlags
    );

Posts files and directories to a desired site.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_PROV_QI
    WEBPOST_ERROR_POST_FILES
    WEBPOST_ERROR_INIT_FILES
    WEBPOST_ERROR_COCREATE_WIZARD
    WEBPOST_ERROR_HTTP_GET_FAILED
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO

    For further information on error codes, see Appendix B, Error Codes.

hWnd
Optional. Window handle to receive focus upon completion of this API call. May be NULL.
dwNumLocalPaths
Number of elements in the array pointed to by pszLocalPaths.
pszLocalPaths
String names of files or directories to be posted. If the string specifies a directory (and the WPF_NO_RECURSIVE_POST flag is not set in the dwFlags parameter), all the files in that directory are posted.
pdwSiteNameBufLen
Size, in bytes, of buffer szSiteName. On return, contains the actual number of bytes used in szSiteName. If szSiteName is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szSiteName
The posting site name. This parameter and the szDestURL parameter may not both be NULL or empty if the WPF_NO_WIZARD flag is set.
pdwDestURLBufLen
Size, in bytes, of buffer szDestURL. On return, contains the actual number of bytes used in szDestURL. If szDestURL is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szDestURL
The destination URL. If this parameter is non-NULL and of sufficient size, and the WPF_NO_WIZARD flag is not set, then on return it will contain the destination URL for the site.
dwFlags
Action flags. Possible values are shown in the following table.
Value | Meaning
WPF_FIRST_FILE_AS_DEFAULT | Take the first file specified in pszLocalPaths as the file that will be shown as the default page.
WPF_NO_RECURSIVE_POST | If any element in pszLocalPaths points to a directory, do not post files recursively.
WPF_NO_WIZARD | Do not prompt the user for any input.
WPF_NO_DIRECT_LOOKUP | Do not attempt to look up the site based on the site name. This has the same effect as a NULL or empty szSiteName.
WPF_NO_URL_LOOKUP | Do not attempt to look up the site based on the site URL. This has the same effect as a NULL or empty szSiteURL.
WPF_NO_PROGRESS_DLGS | Do not show the "Publishing files" progress bar during the transfer of files to the destination computer.
WPF_NO_UI | Predefined combination of WPF_NO_WIZARD and WPF_NO_PROGRESS_DLGS.
WPF_SHOWPAGE_WELCOME | Forces the wizard to display the initial "Publish Your Files on the Web" page. Normally this page is skipped if the only other page being displayed is the Finish page. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_SRCFILE | Forces the wizard to display the "Select a File or Folder" page. Normally this page is skipped if the path or paths to publish are specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_DESTSITE | Forces the wizard to display the "Select a Web Server" page. Normally this page is skipped if the site name is specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_PROVIDER | Forces the wizard to display any and all pages associated with the service provider. Note that it is the responsibility of service provider implementations to be compliant with this flag (see the specification of the AddWizardPages SPI function.) Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_ALL | Predefined combination of WPF_SHOWPAGE_*. Note that the WPF_NO_WIZARD flag overrides this one.

The following tables explain how whether dwFlags has the WPF_NO_WIZARD flag set and the various values of the szSiteName and the szDestURL parameters affect what WpPost does.

dwFlags has the WPF_NO_WIZARD flag set
szDestURL == NULL | szDestURL == existing site Y | szDestURL is prefixed by an existing site Y | szDestURL is new
szSiteName == NULL | Returns E_INVALIDARG | Posts to site Y | Posts to site Y; publishes to URL szDestURL | Creates a new site
szSiteName == existing site X | Posts to site X | If X == Y, posts to that site; otherwise, returns E_INVALIDARG | If X == Y, posts to that site and publishes to to URL szDestURL; otherwise, returns E_INVALIDARG | Returns E_INVALIDARG
szSiteName is new | Returns E_INVALIDARG | Creates a new site | Creates a new site | Creates a new site

dwFlags does not have the WPF_NO_WIZARD flag set
szDestURL == NULL | szDestURL == existing site Y | szDestURL is prefixed by an existing site Y | szDestURL is new
szSiteName == NULL | Creates a new site; displays all Wizard pages | Posts to site Y; displays Welcome and Finish Wizard pages | Posts to site Y; publishes to URL szDestURL; displays Welcome and Finish Wizard pages | Creates a new site; displays all Wizard pages except URL
szSiteName == existing site X | Posts to site X; displays Welcome and Finish Wizard pages | Posts to site X; displays Welcome and Finish Wizard pages | Posts to site X; displays Welcome and Finish Wizard pages | Posts to site X; displays Welcome and Finish Wizard pages
szSiteName is new | Creates a new site; displays all Wizard pages except Name the Web Server | Creates a new site; displays all Wizard pages except Name the Web Server and URL | Creates a new site; displays all Wizard pages except Name the Web Server and URL | Creates a new site; displays all Wizard pages except Name the Web Server and URL

If the wizard is invoked (the WPF_NO_WIZARD flag is not set), the wizard will examine the information specified in the call to WpPost and display the minimum set of pages necessary to complete the publishing process (this minimum-UI behavior may be overridden with the WPF_SHOWPAGE flags.) If the user is prompted to enter the friendly name and/or URL for the site, this information is returned to the caller of WpPost in the buffers provided.

If the wizard is not invoked, WpPost calls WpBindToSite to get an interface pointer to the provider that owns the specified site. If the WpBindToSite call fails, WpPost tries to create the site by calling WpCreateSite. Note that WpPost passes the destination URL to WpBindToSiteand WpCreateSite. When calling WpCreateSite, it also passes NULL for the local base directory, indicating that this site does not use the local base directory feature and that all posts to this site should go to the root destination URL; and it passes NULL for the service provider, specifying that the service provider should be determined by auto-binding. If the site's provider cannot be determined from the site name passed to WpPost or an auto-bind, WpPost will fail.

Since WpPost relies on WpBindToSite to do site lookup, all site lookup functionality resides within WpBindToSite. The procedure followed when performing this lookup is detailed under WpBindToSite.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    LPTSTR szLocalPaths = {"c:\\MyDir"};

    hResult = WpPost(NULL, 1, &szLocalPaths, 0, NULL, 0, NULL, 0);
}


WpPostEx

DWORD WpPostEx(
    [in]		HWND 	hWnd
    [in]		DWORD	dwNumLocalPaths
    [in]		LPTSTR *	pszLocalPaths
    [in, out]		LPDWORD	pdwSiteNameBufLen
    [in, out]		LPTSTR	szSiteName
    [in, out]		LPDWORD	pdwDestURLBufLen
    [in, out]		LPTSTR	szDestURL
    [in]		LPSTR		szUsername
    [in]		LPSTR		szPassword
    [in]		DWORD	dwFlags
    );

Posts files and directories to a desired site, using a user name and password.

  • Returns NO_ERROR if successful. Otherwise, returns an error code, which may be one of the following:
    WEBPOST_ERROR_INIT_FAILED
    WEBPOST_ERROR_PROV_QI
    WEBPOST_ERROR_POST_FILES
    WEBPOST_ERROR_INIT_FILES
    WEBPOST_ERROR_COCREATE_WIZARD
    WEBPOST_ERROR_HTTP_GET_FAILED
    WEBPOST_ERROR_EXTENDED_ERROR
    WEBPOST_ERROR_NO_EXT_ERROR_INFO

    For further information on error codes, see Appendix B, Error Codes.

hWnd
Optional. Window handle to receive focus upon completion of this API call. May be NULL.
dwNumLocalPaths
Number of elements in the array pointed to by pszLocalPaths.
pszLocalPaths
String names of files or directories to be posted. If the string specifies a directory (and the WPF_NO_RECURSIVE_POST flag is not set in the dwFlags parameter), all the files in that directory are posted.
pdwSiteNameBufLen
Size, in bytes, of buffer szSiteName. On return, contains the actual number of bytes used in szSiteName. If szSiteName is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szSiteName
The posting site name. This parameter and the szDestURL parameter may not both be NULL or empty if the WPF_NO_WIZARD flag is set. If this parameter is non-NULL and of sufficient size, and the WPF_NO_WIZARD flag is not set, then on return it will contain the site to which the files were posted.
pdwDestURLBufLen
Size, in bytes, of buffer szDestURL. On return, contains the actual number of bytes used in szDestURL. If szDestURL is NULL or too small, this parameter shows the necessary size of the buffer to allocate.
szDestURL
The destination URL. If this parameter is non-NULL and of sufficient size, and the WPF_NO_WIZARD flag is not set, then on return it will contain the destination URL for the site.
szUsername
Optional. The user name to use when logging on to the remote servers. If NULL or incorrect, the user is prompted to supply a user name and password.

QUESTION: Does WP prompt for both a user name and password if either the user name is NULL or incorrect or the password is NULL or incorrect (versus just prompting for only the missing information)? For example, if the user name is correct but the password is not correct, does WP prompt for only a password?

szPassword
Optional. The password to use when logging on to the remote servers. If NULL or incorrect, the user is prompted to supply a user name and password.
dwFlags
Action flags. Possible values are shown in the following table.
Value | Meaning
WPF_FIRST_FILE_AS_DEFAULT | Take the first file specified in pszLocalPaths as the file that will be shown as the default page.
WPF_NO_RECURSIVE_POST | If any element in pszLocalPaths points to a directory, do not post files recursively.
WPF_NO_WIZARD | Do not prompt the user for any input.
WPF_NO_DIRECT_LOOKUP | Do not attempt to look up the site based on the site name. This has the same effect as a NULL or empty szSiteName.
WPF_NO_URL_LOOKUP | Do not attempt to look up the site based on the site URL. This has the same effect as a NULL or empty szSiteURL.
WPF_NO_PROGRESS_DLGS | Do not show the "Publishing files" progress bar during the transfer of files to the destination computer.
WPF_NO_UI | Predefined combination of WPF_NO_WIZARD and WPF_NO_PROGRESS_DLGS.
WPF_SHOWPAGE_WELCOME | Forces the wizard to display the initial "Publish Your Files on the Web" page. Normally this page is skipped if the only other page being displayed is the Finish page. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_SRCFILE | Forces the wizard to display the "Select a File or Folder" page. Normally this page is skipped if the path or paths to publish are specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_DESTSITE | Forces the wizard to display the "Select a Web Server" page. Normally this page is skipped if the site name is specified in the call to WpPost. Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_PROVIDER | Forces the wizard to display any and all pages associated with the service provider. Note that it is the responsibility of service provider implementations to be compliant with this flag (see the specification of the AddWizardPages SPI function.) Note that the WPF_NO_WIZARD flag overrides this one.
WPF_SHOWPAGE_ALL | Predefined combination of WPF_SHOWPAGE_*. Note that the WPF_NO_WIZARD flag overrides this one.

If the wizard is invoked (the WPF_NO_WIZARD flag is not set), the wizard will examine the information specified in the call to WpPost and display the minimum set of pages necessary to complete the publishing process (this minimum-UI behavior may be overridden with the WPF_SHOWPAGE flags.) If the user is prompted to enter the friendly name and/or URL for the site, this information is returned to the caller of WpPost in the buffers provided.

If the wizard is not invoked, WpPost calls WpBindToSite to get an interface pointer to the provider that owns the specified site. If the WpBindToSite call fails, WpPost tries to create the site by calling WpCreateSite. Note that WpPost passes the destination URL to WpBindToSiteand WpCreateSite. When calling WpCreateSite, it also passes NULL for the local base directory, indicating that this site does not use the local base directory feature and that all posts to this site should go to the root destination URL; and it passes NULL for the service provider, specifying that the service provider should be determined by auto-binding. If the site's provider cannot be determined from the site name passed to WpPost or an auto-bind, WpPost will fail.

Since WpPost relies on WpBindToSite to do site lookup, all site lookup functionality resides within WpBindToSite. The procedure followed when performing this lookup is detailed under WpBindToSite.

Examples
C/C=++

{
    HRESULT hResult = NOERROR;
    LPTSTR szLocalPaths = {"c:\\MyDir"};

    hResult = WpPost(
        NULL,
        1,
        &szLocalPaths,
        0,
        NULL,
        0,
        NULL,
        "anonynous",
        "e-mail",
        0);
}


WpPostFile

HRESULT WpPostFile(
    [in]		LONG	 	hWnd
    [in]		BSTR		bstrLocalPath
    [in, out]		LONG *	plSiteNameBufLen
    [in, out]		BSTR		bstrSiteName
    [in, out]		LONG *	plDestURLBufLen
    [in, out]		BSTR		bstrDestURL
    [in]		LONG		lFlags
    [out, retval]	LONG *	plRetCode
    );

Simply a version of WpPost accessible through WpObj's COM Interface. The functionality is identical to that described in WpPost except as follows:
WpPostFile can only accept a single file for posting (although that file may be a directory, in which case all files within it will be posted.)
The WPF_NO_WIZARD flag is disabled, and the WPF_SHOWPAGE_SRCFILE flag is automatically set. This is to ensure that users who may download a Web page that uses this method are always prompted before any files can be uploaded from their machine.

  • Return values are the same as WpPost.
hWnd
Same as WpPost.
bstrLocalPath
String name of a single file or directory to be posted. If the string specifies a directory (and the WPF_NO_RECURSIVE_POST flag is not set in the lFlags parameter), all the files in that directory are posted.
plSiteNameBufLen
Same as WpPost.
bstrSiteName
Same as WpPost.
plDestURLBufLen
Same as WpPost.
bstrDestURL
Same as WpPost.
lFlags
Same as WpPost.
plRetCode
Pointer to a long integer that receives the return code of the operation.


The Web Publishing SPI

The Web Publishing SPI consists of the following methods.
Helper function | Description
WppBindToSite | Retrieves the address of an interface if the provider DLL owns the site name or the URL.
WppDeleteSite | Deletes a configured site.
Interface method | Description
AddWizardPages | Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.
DeleteFile | Deletes the specified file from the destination site.
FindClose | Closes the specified search handle.
FindFirstFile | Searches a directory for a file whose name matches the specified file name on the destination site.
FindNextFile | Continues a file search from a previous call to the FindFirstFile method.
GetError | Retrieves additional information about an error.
GetParam | Retrieves a parameter value for this site.
GetSiteInfo | Retrieves the site information for the current object.
NetworkConnect | Connects to the Internet.
NetworkDisconnect | Disconnects from the Internet.
PostFiles | Posts files to the specified URL.
ServerLogin | Logs the user on to the Internet server.
ServerLogout | Logs the user out of the Internet server.
SetParam | Sets the value of a parameter for a given site.
SetProgressUpdateProc | Specifies the callback function.


WppBindToSite

LONG WppBindToSite(
    [in]		HWND 	hwnd
    [in, string]	LPCTSTR 	wsSiteName
    [in, string]	LPCTSTR 	wsURL
    [in]		REFIID 	riid
    [in]		DWORD 	fdwFlags
    [in]		DWORD 	dwReserved
    [out]		PVOID *	ppvObj
    );

Retrieves the address of an interface if the provider DLL owns the site name or the URL.

  • Returns ERROR_SUCCESS if successful or an error value otherwise.
hwnd
Handle of the window to which the focus returns when the wizard, if invoked, completes. This parameter can be NULL if the wizard is not invoked or if this function is called from a console application.
wsSiteName
Optional. Address of a null-terminated string that contains an Internet site name.
wsURL
Optional. Address of a null-terminated string that contains a URL.
riid
Interface identifier. All providers should support the IID_IWPSiteinterface identifier. Provider implementations that implement IWPProvider should also support the IID_IWPProvider ID.
fdwFlags
Action flags. Possible values are shown in the following table.
Value | Meaning
WPF_FORCE_BIND | The provider should not query the site to see whether it can post to it (that is, do not test whether the protocol used by the provider is supported by the server.)
dwReserved
Reserved, and must be set to zero (0).
ppvObj
Address of a variable to receive the interface address.

See a C++ sample provider template included with Web Publishing in the Internet Client SDK.


WppDeleteSite

LONG WppDeleteSite(
    [in, string] 	LPCTSTR 	szSiteName
    );

Deletes a configured site.

  • Returns ERROR_SUCCESS if successful or an error value otherwise.
szSiteName
Address of a null-terminated string that contains the site name.

See a C++ sample provider template included with Web Publishing in the Internet Client SDK.


AddWizardPages

HRESULT AddWizardPages(
    [in]	LPVOID			pvFlags
    [in]	LPFNADDPROPSHEETPAGE	pfnAdd
    [in, out]	LPARAM			pParam
    );

Allows the provider DLLs to plug pages into the wizard invoked by the WpPost function.

pvFlags
The address of a LONG containing action flags. This parameter must be cast to an LPVOID in the call to AddWizardPages for backward compatibility. The only flag value supported is WPF_SHOWPAGE_PROVIDER, which indicates that the service provider should add its pages to the wizard whether or not it thinks that they are required.
pfnAdd
Address of a function that this Web Publishing service provider should use to add wizard pages. The declaration of this function-pointer type (LPFNADDPROPSHEETPAGE), is included in the header files of the Win32 SDK.
pParam
Address of a page identifier, an unsigned integer.

As input to this function, the low-order word is the dialog identifier of the page after the last page of the provider, and the high-order word is the dialog identifier of the page before the first page of the provider.

As output from this function, the low-order word is the dialog identifier of the provider's last page, and the high-order word is the dialog identifier of the provider's first page. If the provider has no pages, it should return zero as the page identifier.

As an example, in setting up a new site the wizard would provide the friendly site name and the site's URL and the provider DLLs would handle the rest of the site set up. The dialog identifier of the provider wizard page should be a value between the values of IDD_FIRST_PROV_PAGE and IDD_LAST_PROV_PAGE, as defined in the file WPPDEFS.H included with the stubbed service provider among the SDK samples.


Commit

HRESULT Commit(void);

Ensures that all the files posted to this server with the PostFiles function are actually written to the Internet server.

If a callback function has been specified to the service provider with a previous call into SetProgressUpdateProc, the service provider should call the callback function while committing. See the description of SetProgressUpdateProc for more information.


DeleteFile

HRESULT DeleteFile(
    [in, string]	LPCWSTR	wsFile
    );

Deletes the given file from the destination site.

wsFile
Address of a null-terminated string that contains the name of the file to delete.


FindClose

HRESULT FindClose(
    [in] 	HANDLE 	hSearchHandle
    );

Closes the specified search handle.

hSearchHandle
Search handle returned by a previous call to the FindFirstFile function.

The FindFirstFile and FindNextFile functions use the search handle to locate files with names that match a given name.


FindFirstFile

HRESULT FindFirstFile(
    [in, string] 	LPCWSTR			wsSearchFile
    [out] 		LPWIN32_FIND_DATAW 	pFindFileData
    [out] 		LPHANDLE		pSearchHandle
    );

Searches a directory for a file whose name matches the specified file name on the destination site identified by this object. It examines subdirectory names as well as file names.

wsSearchFile
Address of a null-terminated string that contains the file name to find.
pFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the file or subdirectory that has been found.
pSearchHandle
Address of a variable that receives a handle that can be used for subsequent calls to the FindNextFile and FindClose functions.


FindNextFile

HRESULT FindNextFile(
    [in] 	HANDLE			hSearchHandle
    [out] 	LPWIN32_FIND_DATAW	pFindFileData
    );

Continues a file search from a previous call to the FindFirstFile function.

hSearchHandle
Search handle returned by a previous call to the FindFirstFile function.
pFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the file or subdirectory that has been found.


GetError

HRESULT GetError(
    [out] 		LPDWORD	pdwErrorType
    [in, out] 	LPDWORD	pdwErrorCode
    [in, out] 	LPDWORD	pdwErrorBufLen
    [out, string] 	LPWSTR	wsError
    );

Retrieves additional information about an error.

pdwErrorType
Indicates the error type. Currently set to zero.
pdwErrorCode
Indicates the error code.
pdwErrorBufLen
Indicates the size, in bytes, of the wsError buffer. Set to the number of bytes written to wsError if the buffer was large enough, or to the required buffer size if the buffer was not large enough.
wsError
Address of a buffer that receives the error information.


GetParam

HRESULT GetParam(
    [in, string]	LPCWSTR	wsParameter
    [in, out] 		LPDWORD	pdwValueBufLen
    [out, string] 	LPWSTR	wsValue
    );

Retrieves a parameter value for this site.

wsParameter
Address of a null-terminated string that contains the name of a site parameter.
pdwValueBufLen
Address of a variable that receives the size of the wsValue buffer. If wsValue is NULL, or if the buffer length is short, this variable receives the size, in bytes, of the parameter name.
wsValue
Address of a buffer that receives the value of the parameter queried.


GetSiteInfo

HRESULT GetSiteInfo(
    [out]	LPWPSITEINFO 	pbSite
    [in, out] 	LPDWORD		pdwSiteBufLen
    );

Retrieves the site information for the current object.

Note With version 1.5, implementation of this function has become optional, since site management should be done with the Web Publishing API.

pbSite
Address of a buffer that receives a WPSITEINFO structure containing the site information.
pdwSiteBufLen
Address of a variable that contains the size, in bytes, of the pbSite buffer.


NetworkConnect

HRESULT NetworkConnect(
    [in, string]	LPCWSTR	wsUserName
    [in, string]	LPCWSTR	wsPassword
    );

Connects to the Internet.

wsUserName
Address of a null-terminated string that contains the user name for the Internet connection.
wsPassword
Address of a null-terminated string that contains the password for the Internet connection.


NetworkDisconnect

HRESULT NetworkDisconnect(void);

Disconnects from the Internet (hangs up if a dial-up connection was used.)


PostFiles

HRESULT PostFiles(
    [in] 		DWORD 	cLocalPaths
    [in, string] 	LPWSTR *	pwsLocalPaths
    [in, out] 		LPDWORD 	pdwURLBufLen
    [in, out, string]	LPWSTR 	wsURL
    [in] 		DWORD 	fdwFlags
    );

Posts files to the specified URL on the destination site identified by this object.

cLocalPaths
Number of elements in the pwsLocalPaths array.
pwsLocalPaths
Address of an array of null-terminated strings that contain the file names or directories to be posted on the Internet. If any of these strings point to a directory and the WPF_NO_RECURSIVE_POST flag is not set in fdwFlags, all the files in that directory are posted.
pdwURLBufLen
Address of a variable that indicates the length of the wsURL buffer. When the function returns, the variable contains the length, in bytes, of the that buffer.
wsURL
Optional. Address of a null-terminated string that contains the destination URL. If this parameter is NULL, the files are posted in the root URL for the site.

If this parameter is not NULL, the URL of the copied file, or the URL of the directory that the files were copied to, is returned in the buffer pointed to by this parameter.

fdwFlags
Action flags.
Value | Meaning
WPF_NO_RECURSIVE_POST | If any element in the pwsLocalPaths array points to a directory, do not post files recursively.

Changes for version 1.5:
Service providers are no longer required to support the posting of multiple files. It is not a violation of the interface contract for a service provider to return failure if cLocalPaths is greater than 1.
If a callback function has been specified to the service provider with a previous call into SetProgressUpdateProc, the service provider should call the callback function while posting. See the description of SetProgressUpdateProc for more information.

See also WpPost


ServerLogin

HRESULT ServerLogin(
    [in, string]	LPCWSTR	wsUserName
    [in, string]	LPCWSTR	wsPassword
    );

Logs the user on to the Internet server.

wsUserName
Address of a null-terminated string that contains the user name for the Internet server.
wsPassword
Address of a null-terminated string that contains the password for the Internet server.

The given user name and password are for the Internet server. They may or may not be the same as those used for the NetworkConnect function.


ServerLogout ServerLogout *
  * Previous Topic: ServerLogin
  * Next Topic: SetParam

ServerLogout

HRESULT ServerLogout(void);

Logs the user out of the Internet server.


SetParam

HRESULT SetParam(
    [in, string]	LPCWSTR	wsParameter
    [in, string]	LPCWSTR	wsValue
    );

Sets the value of a parameter for a given site.

wsParameter
Address of a null-terminated string that contains a parameter name.
wsValue
Address of a null-terminated string that contains the configuration parameter value.


SetProgressUpdateProc

HRESULT SetProgressUpdateProc(
    [in] 	LONG *	pfnProgressUpdateProc
    );

Specifies the callback function the provider should use to update the "Publishing Files" progress dialog displayed by the API.

pfnProgressUpdateProc
Function with the following declaration:
HRESULT CALLBACK *pfnProgressUpdateProc(
[in, string] 	LPCWSTR 	wsFileName
[in]			DWORD		dwNumBytes
    );

The type PFNPROGRESSUPDATEPROC declared in WPSPI.IDL encapsulates this declaration.

The service provider should cache the function pointer specified here so that it can call into the update procedure from PostFiles and Commit. (The progress bar is reset after all the PostFiles calls have been made, and fills a second time during the call to Commit.)

The Service Provider should call this function from both PostFiles and Commit to update the progress dialog as it posts and commits the files passed to it. WpPost will do a series of PostFiles calls, followed by a single call to Commit. The API keeps track of the total number of bytes being transferred, so on each call the service provider should just specify the file name to display and the number of bytes that have been posted or committed since the last call.

If the update procedure returns an error, the Service Provider must quit its current operation and return the error (as the result code from PostFiles or Commit.) This ensures that if the "Cancel" button is clicked by the user during publishing, it will be processed correctly.

A typical call to the callback procedure is as follows:

hResult = (*m_pfnProgressUpdateProc)(wsFileName, dwFileSize);

If the service provider wishes to change the file name displayed in the progress dialog without advancing the progress bar, it should make a call such as the following:

hResult = (*m_pfnProgressUpdateProc)(wsFileName, 0);


The File Upload Control Interface

The File Upload control is an ActiveX control onto which users can drag and drop files or directories for posting to the server hosting the page with the control. The File Upload Control interface has the following methods.
Method | Description
AboutBox | Displays information about the File Upload Control.
CreatePermBinding | Creates a permanent site and binds to it.
CreateTempBinding | Creates a temporary site and binds to it.
FoundPostInfo | Checks whether a postinfo file was found on the target server.
SetBindingParam | Sets binding parameters.


AboutBox AboutBox *
  * Previous Topic: The File Upload Control Interface
  * Next Topic: CreatePermBinding

AboutBox

HRESULT AboutBox(void);

Displays a friendly message about the File Upload Control.


CreatePermBinding

CreatePermBinding(
    [in]	BSTR	bstrBindingName
    [in]	BSTR	bstrDestUrl
    [in]	BSTR	bstrProvCLSID
    );

Creates a permanent site and binds to it.

bstrBindingName
Address of a null-terminated string that contains the site name. This may not be NULL or empty.
bstrDestUrl
Address of a null-terminated string that contains the destination URL for the site. This is where the files dropped on the File Upload Control will be posted. This may not be a NULL or empty.
bstrProvCLSID
Address of a null-terminated string that contains the CLSID of the provider that will handle this site. This may be NULL or empty, in which case the File Upload Control will attempt to find a posting information file or auto-bind to an appropriate provider.

The site information is persistent, that is, it will remain on the user's machine even after the browser is shut down.


CreateTempBinding

HRESULT CreateTempBinding(
    [in]	BSTR	bsDestUrl
    [in]	BSTR	bsProvCLSID
    );

Creates a temporary site and binds to it.

bsDestUrl
Address of a null-terminated string that contains the destination URL for the site. This is where the files dropped on the File Upload Control will be posted. This may not be NULL or empty.
bsProvCLSID
Address of a null-terminated string that contains the CLSID of the provider that will handle this site. This may be NULL or empty, in which case the File Upload Control will attempt to find a posting information file or auto-bind to an appropriate provider.

Garbage collection should take care of this site information when the user shuts down the browser.

Sample HTML Usage

<HTML>
<HEAD>
<TITLE>File Upload Control</TITLE>
</HEAD>

<BODY LEFTMARGIN=20 TOPMARGIN=20 BGCOLOR=#FFFFFF TEXT=#000000 LINK=#FF0066 VLINK=#330099 ALINK=#000000 language="VBS" onload="InitializeControl">

<FONT FACE="ARIAL" SIZE=2>

<CENTER>
<P><FONT SIZE=5><B>Welcome</B></FONT>
</CENTER>

<H3>File Upload</H3>
<P>
You can upload your html content using this control.
<OBJECT
    classid="clsid:886E7BF0-C867-11CF-B1AE-00AA00A3F2C3"
    id=FlUpl1
    width=100
    height=100
    align=textmiddle
    color=blue
    codebase=http://my_server/flupl/FlUpl.cab#Version=6,0,86,0

</OBJECT>
You may drag and drop files onto it. Or double click on it to get a FileOpen dialog.

<SCRIPT LANGUAGE="VBS">

Sub InitializeControl
    FlUpl1.CreateTempBinding "http://my_server", "{8B14B770-748C-11D0-A309-00C04FD7CFC5}"
End Sub
</SCRIPT>

<P ALIGN=CENTER><FONT SIZE=2><B>For more information on VB Script, visit the <A TARGET="_top" HREF="http://www.microsoft.com/vbscript/default.htm">VB Script site.</A></B></FONT>

</FONT>

</BODY>
</HTML>


FoundPostInfo

HRESULT FoundPostInfo(void);

Determines whether a postinfo file was found on the target server.

This property is set to true if during a CreateTempBinding or CreatePermBinding call a postinfo file was found on the server.

Example

REM This example demonstrates binding parameters required by the CRS
REM provider
Flupl.CreateTempBinding "<http://www.icp.com/hello>", "{FFCF1E40-7978-11D0-B1C9-00AA006DCDF4}"

If not Flupl.FoundPostInfo then
    Flupl.SetBindingParam "Servername", "www.crsserver.com <http://>"
    Flupl.SetBindingParam "Authentication", "MSN, NTLM"
Endif


SetBindingParam

SetBindingParam(
    [in]	BSTR	bstrParamName
    [in]	BSTR	bstrParamValue
    );

Sets the parameters of an incomplete binding in case a previous CreateTempBinding or CreatePermBinding call failed to find a postinfo file on the server.

bstrParamName
Address of a null-terminated string that contains the name of the provider-specific binding parameter to be set.
bstrParamValue
Address of a null-terminated string that contains the value to which the parameter should be set.

This method takes the name of the provider specific binding parameter and the value and sets it. This should be used only as a fallback mechanism in case the postinfo file is not found on the server.


Appendix A, Structures

WPPROVINFO
WPSITEINFO

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.


WPPROVINFO

typedef struct tagWPPROVINFO
{
    DWORD	dwSize;
    DWORD	dwFlags;
    DWORD	dwPriority;
    LPTSTR	lpszProviderName;
    LPTSTR	lpszProviderCLSID;
    LPTSTR	lpszDllPath;
}
WPPROVINFO, *LPWPPROVINFO;
dwSize
Size of the provider information structure in bytes, including the string buffers for the name, CLSID, and DLL path.
dwFlags
Provider flags. Not currently used.
dwPriority
Integer that indicates the provider's priority. 0 is highest priority.
lpszProviderName
Friendly name of the provider.
lpszProviderCLSID
CLSID of the provider implementation object.
lpszDllPath
Fully qualified path of the DLL that contains the COM server for the provider.


WPSITEINFO

typedef struct tagWPSITEINFO
{
DWORD	dwSize;
    DWORD	dwFlags;
    LPTSTR	lpszSiteName;
    LPTSTR	lpszSiteURL;
}
WPSITEINFO, *LPWPSITEINFO;
dwSize
Size of the site information structure in bytes, including the string buffers for the site name and URL.
dwFlags
Site flags. Not currently used.
lpszSiteName
Friendly name of the site.
lpszSiteURL
Destination URL for the site (location where posted files can be accessed.)


Appendix B, Error Codes

The following error codes are used in this SDK.

Web Publishing API

Error code | Meaning
WEBPOST_ERROR_AUTOBIND_FAILED | The Web Publishing API was unable to automatically determine which service provider to use for this site.
WEBPOST_ERROR_BAD_PROV_PTR | The Web Publishing API was not able to obtain a valid pointer to the requested service provider.
WEBPOST_ERROR_COCREATE_WIZARD | The Web Publishing API could not invoke the Web Publishing Wizard.
WEBPOST_ERROR_CREATE_SITE | An error occurred while the Web Publishing API was creating the requested site.
WEBPOST_ERROR_DELETE_SITE | An error occurred while the Web Publishing API was deleting the requested site.
WEBPOST_ERROR_ENUM_PROVS | An error occurred while the Web Publishing API was enumerating the providers on this system.
WEBPOST_ERROR_EXTENDED_ERROR | A Web Publishing extended error occurred. This means that the API received an error code that the API client may not be able to translate, so the API performed the translation and cached the error message for retrieval on a call to the WpGetErrorString method.
WEBPOST_ERROR_HTTP_GET_FAILED | Informational (non-failure) result indicating failure in the attempt to retrieve one of the published files with an HTTP GET. This error is only returned in cases where the files were all successfully uploaded.
WEBPOST_ERROR_INIT_FAILED | An error occurred while attempting to initialize the Web Publishing API DLL.
WEBPOST_ERROR_INVALID_POSTINFO | Informational (non-failure) result indicating that the postinfo file found on the server during site creation could not be parsed correctly. This error is only returned if the site creation is otherwise successful.
WEBPOST_ERROR_LIST_SITES | An error occurred while the Web Publishing API was enumerating the sites on this system.
WEBPOST_ERROR_NO_EXT_ERR_INFO | An extended error occurred in the Web Publishing API, but the error message could not be retrieved.
WEBPOST_ERROR_NO_POSTINFO | Informational (non-failure) result indicating that the postinfo file could not be retrieved during a site creation. This error is only returned if the site creation is otherwise successful.
WEBPOST_ERROR_POST_FILES | An error occurred while the Web Publishing API was attempting to post the requested files.
WEBPOST_ERROR_POSTINFO_REQUIRED | This service provider requires a postinfo file on the server, and none could be found.
WEBPOST_ERROR_PROV_CORRUPT | The Web Publishing API could not retrieve all of the required service provider information.
WEBPOST_ERROR_PROV_DLL | The Web Publishing API could not load the DLL for one of its service providers.
WEBPOST_ERROR_PROV_EP | The Web Publishing API could not locate a required entry point in one of its service providers.
WEBPOST_ERROR_PROV_NOT_IN_POSTINFO | The server to which you are trying to post does not indicate support for the service provider you have requested.
WEBPOST_ERROR_PROV_QI | The Web Publishing API was unable to determine what interface is exported by the specified service provider.
WEBPOST_ERROR_PROVCLSID_UNKNOWN | The Web Publishing API could not locate the service provider used to transfer files to this site.
WEBPOST_ERROR_SITE_CORRUPT | The Web Publishing API could not retrieve all of the required site information.
WEBPOST_ERROR_SITE_DOESNOTEXIST | The Web Publishing API could not delete the requested site because no site with the specified name exists.
WEBPOST_ERROR_SITE_EXISTS | The Web Publishing API could not create the requested site because a site with the same name already exists.
WEBPOST_ERROR_UNKNOWN | An unknown error occurred during Web Publishing.
WPWIZ_ERROR_COCREATE_WEBPOST | The Web Publishing Wizard could not create the Web Publishing implementation object.
WPWIZ_ERROR_FILE_NOT_FOUND | The local file(s) selected to be published could not be found.
WPWIZ_ERROR_INIT_FAILED | An error occurred during the initialization of the Web Publishing Wizard.
WPWIZ_ERROR_NO_PROVIDERS | The Web Publishing Wizard could not run because there are no service providers installed.
WPWIZ_ERROR_OUTOFMEMORY | The Wizard ran out of memory.
WPWIZ_ERROR_PROPSHEET_ERROR | The wizard received an error result back from the PropertySheet() call into the system.
WPWIZ_ERROR_PROV_QI | The Web Publishing Wizard could not determine which interface is exported by the requested service provider.
WPWIZ_ERROR_STATE_PTR | The Web Publishing Wizard could not retrieve a pointer to its state object.
WPWIZ_ERROR_UNKNOWN | An unknown error occurred.
WPWIZ_ERROR_WEBPOST_PTR | The Web Publishing Wizard cannot complete the operation because it does not have a pointer to the Web Publishing API implementation object.

Web Publishing SPI

Error code | Meaning
CRSWPP_BIND_FAILED | Could not bind to the site with the information specified.
CRSWPP_FAILED_AUTH | You do not have the necessary access privileges to post content to this CRS server.
CRSWPP_INVALID_POSTINFO_FILE | The postinfo file is invalid on the server you selected.
CRSWPP_NO_MATCHING_MAPURL | The CRS project you selected has no MAPURL.
CRSWPP_POSTINFO_NEEDED | Server does not have a postinfo file. Additional information is needed, please invoke my Wizard Pages to complete bind operation.
CRSWPP_PROJECT_BINDING_INCOMPLETE | An internal error (0x2205) has occurred in the CRS service provider.
CRSWPP_SECURITY_PACKAGE | The initialization of the security package failed.
CRSWPP_SECURITY_PACKAGE_NOT_FOUND | The security package(s) required by the server could not be found on your computer.
CRSWPP_SERVER_BINDING_INCOMPLETE | The site is not yet bound to a CRS server.
CRSWPP_SERVER_NOT_RESPONDING | The CRS server is not responding.
FTPWPP_ERROR_AUTHENTICATION_FAILED | The FTP service provider was unable to log on to the FTP server.
FTPWPP_ERROR_INETOPEN_FAILED | The FTP service provider was not able to connect to the Internet.
WPP_POST_POSTING_NO_RESPONSE_ERROR | Posting Server response is either missing or invalid. No status is available about the uploaded files.
WPP_POST_POSTING_SERVER_ERROR | Server returned a posting error.
WPP_POST_POSTING_URL_ERROR | The supplied posting URL is invalid.


Appendix C, Parameters

The following tables list the parameters supported by each Microsoft service provider. When writing a posting information file for a server, as many parameters as possible should be specified for each service provider the server will support, in order to minimize the amount of information that must be entered by a user.

The DefaultPage parameter is handled by the Web Publishing API (as such it is not listed under the individual service providers.) It specifies the name to use when saving a file as the default page for a site (when indicated by the WPF_FIRST_FILE_AS_DEFAULT flag to WpPost.)

The service provider section of the posting information file must include the registration identifier. To get this string value, use the WpEnumProvidersmethod.

Content Replication System Service Provider

Parameter | Example value | Meaning
Authentication | NTLM | The name of the security package to use when authenticating against the server.
ServerName | myserver | The name of the CRS server.

FTP Service Provider

Note that if present, the special string "$USERNAME" will be replaced with the name of the account used to log on to the server during publishing. This string can be used in the ServerName and Subfolder values.

The ConnectTimeout, ConnectRetries, SendTimeout, and ReceiveTimeout, were made site parameters to allow dynamic adjustment of the waiting behavior on network calls. However, a typical postinfo file will probably not need to include these parameters. The values listed under "Example Value" for these four parameters are the defaults.
Parameter | Example value | Meaning
ServerName | myserver | The name of the FTP server.
Subfolder | home/users/$USERNAME | The path on the FTP server where files should be saved. Note that $USERNAME will be replaced with the "UserName" value.
ConnectTimeout | 60000 (msec) | The length of the timeout to use when connecting to the server.
ConnectRetries | 5 | The number of retries to make when connecting to the server.
SendTimeout | 60000 (msec) | The length of the timeout for all network packets sent.
ReceiveTimeout | 60000 (msec) | The length of the timeout for all network packets received.
BasePath - This value is obsolete. If present on a site key that was used with version 1.1 of the Web Publishing Wizard, it will be upgraded to "Subfolder" the first time the FTP provider binds to the site.
FtpServerName - This value is obsolete. If present on a site key that was used with version 1.1 of the Web Publishing Wizard, it will be upgraded to "ServerName" the first time the FTP provider binds to the site.

HTTP POST Service Provider

Parameter | Example value | Meaning
PostingURL | http://myserver/scripts/cpshost.dll?PUBLISH | The URL of the HTTP POST acceptor.
TargetURL | http://myserver/users | The URL where the uploaded files should be placed.


Windows Scripting Host Programmer's Reference

The following information is presented in this programmer's reference:

  • About Windows Scripting Host
    • ActiveX Scripting Hosts
    • Overview of the Windows Scripting Host Object Model
  • Using Windows Scripting Host
    • Writing a Scripting Engine for Windows Scripting Host
    • How Windows Scripting Host Uses the Registry
    • Registering a Scripting Engine for Windows Scripting Host
    • Running Scripts Using Wscript.Exe
    • Running Scripts Using Cscript.Exe
    • Document Conventions
  • Windows Scripting Host Object Reference
  • Wscript Object
    • Wscript.Application
    • Wscript.Arguments
    • Wscript.FullName
    • Wscript.Name
    • Wscript.Path
    • Wscript.ScriptFullName
    • Wscript.ScriptName
    • Wscript.Version
    • Wscript.CreateObject
    • Wscript.DisconnectObject
    • Wscript.Echo
    • Wscript.GetObject
    • Wscript.Quit
  • WshArguments Object
    • WshArguments.Item
    • WshArguments.Count
    • WshArguments.length
  • WshShell Object
    • WshShell.Environment
    • WshShell.SpecialFolders
    • WshShell.CreateShortcut
    • WshShell.ExpandEnvironmentStrings
    • WshShell.Popup
    • WshShell.RegDelete
    • WshShell.RegRead
    • WshShell.RegWrite
    • WshShell.Run
  • WshNetwork Object
    • WshNetwork.ComputerName
    • WshNetwork.UserDomain
    • WshNetwork.UserName
    • WshNetwork.AddPrinterConnection
    • WshNetwork.EnumNetworkDrives
    • WshNetwork.EnumPrinterConnections
    • WshNetwork.MapNetworkDrive
    • WshNetwork.RemoveNetworkDrive
    • WshNetwork.RemovePrinterConnection
    • WshNetwork.SetDefaultPrinter
  • WshCollection Object
    • WshCollection.Item
    • WshCollection.Count
    • WshCollection.length
  • WshEnvironment Object
    • WshEnvironment.Item
    • WshEnvironment.Count
    • WshEnvironment.length
    • WshEnvironment.Remove
  • WshShortcut Object
    • WshShortcut.Arguments
    • WshShortcut.Description
    • WshShortcut.FullName
    • WshShortcut.Hotkey
    • WshShortcut.IconLocation
    • WshShortcut.TargetPath
    • WshShortcut.WindowStyle
    • WshShortcut.WorkingDirectory
    • WshShortcut.Save
  • WshSpecialFolders Object
    • WshSpecialFolders.Item
    • WshSpecialFolders.Count
    • WshSpecialFolders.length
  • WshUrlShortcut Object
    • WshUrlShortcut.FullName
    • WshUrlShortcut.TargetPath
    • WshUrlShortcut.Save


WinInet API

This section covers the Win32® Internet functions, which provide a high-level interface that abstracts the underlying protocols. This section also includes automatic dialing functions to handle dial-up connections.

Microsoft Win32 Internet Functions Overview

Microsoft Win32 Internet Functions Reference


Microsoft Win32 Internet Functions Overview

The Microsoft® Win32® Internet (WinInet) API provides stand-alone applications with easy access to standard Internet protocols such as Gopher, FTP, and HTTP, abstracting the protocols into a high-level interface that is familiar to Win32 developers. This section covers how to use the Win32 Internet API in an application. See the Microsoft Win32 Internet Functions Reference for descriptions of the individual functions.

Introduction

Establishing a Dial-Up Connection to the Internet

Enabling Internet Functionality

Common Functions

Handling Uniform Resource Locators

Handling Authentication

FTP Sessions

Gopher Sessions

HTTP Sessions

Cookie Functions

Caching

Appendix A: HINTERNET Handles

Appendix B: Using Buffers

Appendix C: Handling Errors

Introduction

The following sections contain an overview of the Microsoft® Win32® Internet (WinInet) functions, which provide developers with a set of functions to interact with Gopher, FTP, and HTTP protocols. As the standards evolve, the Win32 Internet functions will handle the changes in underlying protocols, allowing the functions to maintain a consistent behavior. This overview describes how to use these functions to access the vast resources on the Internet.

The Win32 Internet functions do require an understanding of C/C++, a familiarity with Win32 programming, and a basic understanding of the FTP, Gopher, and HTTP protocols.

Internet Protocols

The three major protocols used on the Internet are the FTP, Gopher, and HTTP protocols.

For the more information on these protocols, see the Request For Comments (RFC) documents that cover FTP, Gopher, and HTTP specifications. The following documents on these protocols can be found on the Internet:

  • RFC 959, File Transfer Protocol (FTP), can be found at http://ds.internic.net/rfc/rfc959.txt. External link
  • RFC 1436, The Internet Gopher Protocol, can be found at http://ds.internic.net/rfc/rfc1436.txt. External link
  • RFC 1945, Hypertext Transfer Protocol - HTTP/1.0, can be found at http://ds.internic.net/rfc/rfc1945.txt. External link
  • RFC 2068, Hypertext Transfer Protocol - HTTP/1.1, can be found at http://ds.internic.net/rfc/rfc2068.txt. External link


Establishing a Dial-Up Connection to the Internet

The Win32 Internet functions include seven functions that handle modem connections.
Function | Description
InternetAutodial | Initiates an unattended dial-up connection.
InternetAutodialHangup | Disconnects a modem connection initiated by InternetAutodial.
InternetDial | Initiates a dial-up connection.
InternetGetConnectedState | Retrieves the current state of the Internet connection.
InternetHangUp | Disconnects a modem connect initiated by InternetDial.
InternetGoOnline | Prompts the user for permission to initiate a dial-up connection to the given URL.
InternetSetDialState | Sets the current state of the Internet connection.

Detailed information on how to use these functions will be included in a future version of this documentation.


Enabling Internet Functionality

To compile programs that utilize the Win32 Internet functions, the header file, Wininet.h, must be in the include directory, and the library file, Wininet.lib, must be in the library directory of the C/C++ compiler being used.

Before using the Win32 Internet functions, the application should attempt to make a connection to the Internet by using the InternetAttemptConnect function. This function calls the dial-up dialog box to initiate a connection to the Internet or check if a connection already exists. If this function fails, the application can enter offline mode, which allows it to access information that was cached during previous connections to the Internet.

The InternetCheckConnection function can be used to check the connection to the Internet. It attempts to ping the server designated by the Uniform Resource Locator (URL) that is passed to the function. If the FLAG_ICC_FORCE_CONNECTION flag is set and NULL was given as the URL, the function checks to see if there is an entry in the WinInet server database for the nearest server. If one exists, the function pings that server.

To begin using the Win32 Internet functions, use the InternetOpen function to establish the characteristics of the Internet connection being used. InternetOpen creates the root HINTERNET handle that is used to establish HTTP, FTP, and Gopher sessions. InternetOpen does not test the connection to the Internet to verify that the characteristics passed to the function are correct.

Use the InternetConnect function to create a specific session. InternetConnect initializes an FTP, Gopher, or HTTP session for the specified site using the arguments passed to it and creates an HINTERNET handle that is a branch off the root handle. InternetConnect does not attempt to access or establish a connection to the specified site, except in the case of an FTP session. FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, GopherOpenFile, and HttpOpenRequest functions use the handle created by InternetConnect to establish a connection to the specified site.

The following diagram illustrates the hierarchy of the HINTERNET handles.

HINTERNET handles hierarchy

The InternetOpen function, which creates the root HINTERNET handle, is at the top level. The next level contains the InternetOpenUrl function and the InternetConnect function. The functions that use the HINTERNET handle returned by InternetConnect make up the last level. For more information about HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

Using InternetOpen

To enable a connection to the Internet, a root HINTERNET handle must be created by using InternetOpen. Information about the user agent (the application calling the Internet functions), the type of access to the Internet, the proxy names, the hosts and addresses that bypass the proxy, and the behavior are passed to InternetOpen.

Setting the user agent

The lpszAgent parameter of InternetOpen should be given a string that contains the name of the application or entity accessing the Internet. This string is used as the user agent in the HTTP protocol. For example, Internet Explorer uses "Microsoft Internet Explorer".

Setting access types

InternetOpen supports three access types:

  • Use INTERNET_OPEN_TYPE_DIRECT if the system on which the application is running uses a direct connection to the Internet. The lpszProxyName and lpszProxyBypass parameters of InternetOpen are not used and should be set to NULL.
  • Use INTERNET_OPEN_TYPE_PROXY if the system on which the application is running uses one or more proxy servers to access the Internet. InternetOpen uses the proxy servers indicated by lpszProxyName and bypasses the proxy for any host names or IP addresses specified by lpszProxyBypass.
  • Use INTERNET_OPEN_TYPE_PRECONFIG to instruct your application to retrieve the configuration from the registry.

INTERNET_OPEN_TYPE_PRECONFIG looks at the registry values ProxyEnable, ProxyServer, and ProxyOverride. These values are located under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings.

If ProxyEnable is zero, the application uses INTERNET_OPEN_TYPE_DIRECT. Otherwise, the application uses INTERNET_OPEN_TYPE_PROXY and uses the ProxyServer and ProxyOverride information.

The Win32 Internet functions provide support for SOCKS type proxies only if Microsoft Internet Explorer is installed. The installation of Internet Explorer installs the Wsock32n.dll, which the Win32 Internet functions need to support SOCKS proxies. The Wsock32n.dll is not redistributable.

Listing proxy servers

The Win32 Internet functions recognize two types of proxies: CERN type proxies (HTTP only) and TIS FTP proxies (FTP only). If Internet Explorer is installed, the Win32 Internet functions also support SOCKS type proxies. InternetConnect assumes, by default, that the specified proxy is a CERN proxy. If the access type is set to INTERNET_OPEN_TYPE_DIRECT or INTERNET_OPEN_TYPE_PRECONFIG, the lpszProxyName parameter of InternetOpen should be set to NULL. Otherwise, the value passed to lpszProxyName must contain the proxies in a space-delimited string. The proxy listings can contain the port number that is used to access the proxy.

To list a proxy for a specific protocol, the string must follow the format "<protocol>=<protocol>://<proxy_name>". The valid protocols are http, https, ftp, and gopher. For example, to list an FTP proxy, a valid string would be "ftp=ftp://ftp_proxy_name:21", where "ftp_proxy_name" is the name of the FTP proxy and "21" is the port number that must be used to access the proxy. If the proxy uses the default port number for that protocol, the port number can be omitted. If a proxy name is listed by itself, it is used as the default proxy for any protocols that do not have a specific proxy specified. For example, "http=http://http_proxy other" would use "http_proxy" for any HTTP operations, while all other protocols (such as FTP and Gopher) would use "other".

Listing the proxy bypass

Host names or IP addresses that are known locally can be listed in the proxy bypass. This list can contain wildcards, "*", which cause the application to bypass the proxy server for addresses that fit the specified pattern. To list multiple addresses and host names, separate them with blank spaces in the proxy bypass string. If the "<local>" macro is specified, the function bypasses any host name that does not contain a period.

The following example shows sample calls to InternetOpen using different proxy bypass strings. The comments above each call describe what effect the bypass string has on the host names that are accessed from the HINTERNET handle it creates.

/* bypass the proxy for any host name that does not
    contain a period */
hInternetRoot = InternetOpen("WinInet Example",
    INTERNET_OPEN_TYPE_PROXY,"proxy","<local>", 0);

/* bypass the proxy for any host name that starts with the
    letters "ms" */
hInternetRoot = InternetOpen("WinInet Example",
    INTERNET_OPEN_TYPE_PROXY,"proxy","ms*", 0);

/* bypass the proxy for any host name that contains "int",
    such as "internet" and "painter" */
hInternetRoot = InternetOpen("WinInet Example",
    INTERNET_OPEN_TYPE_PROXY,"proxy","*int*", 0);

/* bypass the proxy for the host name "example" and any
    host name that contains "test" */
hInternetRoot = InternetOpen("WinInet Example",
    INTERNET_OPEN_TYPE_PROXY,"proxy","example *test*", 0);

Using InternetConnect

To begin a Gopher, FTP, or HTTP session, the InternetConnect function must create a handle off the root handle returned by the InternetOpen function. InternetConnect sets the server address, port number, user name, password, and type of service.

InternetConnect uses the root HINTERNET handle created by InternetOpen to establish a session handle. If the INTERNET_FLAG_ASYNC flag was set in the call to InternetOpen, the call to InternetConnect should include a nonzero context value.

The server name can be a constant string or a variable containing a string value of type LPSTR. This string can contain either the host name (for example, www.servername.com) or IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).

The server port is the TCP/IP port number to connect to on the server. InternetConnect uses the default port for the selected service type if the INTERNET_INVALID_PORT_NUMBER value is used. There are four server port defaults included with the Win32 Internet functions.
Value | Meaning
INTERNET_DEFAULT_FTP_PORT | Use the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT | Use the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT | Use the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT | Use the default port for HTTPS servers (port 443).
INTERNET_DEFAULT_SOCKS_PORT | Uses the default port for SOCKS firewall servers (port 1080).

Defining the user name and password

The user name is the address of a NULL-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP; a NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is anonymous.

The password is the address of a NULL-terminated string that contains the password to use to log on. If both lpszUsername and lpszPassword are NULL, the function uses the default anonymous password. In the case of FTP, the default anonymous password is the user's e-mail name. If lpszUsername is not NULL and lpszPassword is NULL, the function uses a blank password. There are four possible settings of lpszUsername and lpszPassword, which produce the behaviors shown in the following table.
lpszUsername | lpszPassword | User name sent to FTP server | Password sent to FTP server
NULL | NULL | "anonymous" | User's e-mail name
Non-NULL string NULL lpszUsername ""
NULL | Non-NULL string | ERROR | ERROR
Non-NULL string | Non-NULL string | lpszUsername | lpszPassword

This information can be changed by using the InternetSetOption and InternetErrorDlg functions. InternetSetOption changes the user name and password values, while InternetErrorDlg displays a dialog box requesting the proper user name and password.

Defining the session

To define the session that is being established, InternetConnect must have the service type, flags, and context value set.

There are three service types available to InternetConnect: INTERNET_SERVICE_FTP, INTERNET_SERVICE_GOPHER, and INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP is used for both HTTP and HTTPS sessions.

INTERNET_FLAG_PASSIVE is the only service-specific flag used by the Win32 Internet functions. This flag can be set when the service type is INTERNET_SERVICE_FTP in order to use passive FTP semantics.

For all synchronous operations, the value of dwContext should be set to zero. If asynchronous operations were established by setting the INTERNET_FLAG_ASYNC flag in the call to InternetOpen, a nonzero value should be supplied for dwContext. For more information on asynchronous operations, see Setting up asynchronous operations.

For FTP sessions, InternetConnect tries to establish a connection to the server on the Internet. HTTP and Gopher sessions do not establish a connection until a function attempts to get information from the server.


Common Functions

The different Internet protocols (such as FTP, HTTP, and Gopher) use several of the same Win32 Internet functions to handle information on the Internet. These common functions handle their tasks in a consistent manner, regardless of the particular protocol to which they are being applied. Applications can use these functions to create general-purpose functions that handle tasks across the different protocols (such as reading files for FTP, HTTP, and Gopher protocols).

The common functions handle the following tasks:

  • Downloading resources from the Internet can be handled by the InternetReadFile, InternetSetFilePointer, InternetFindNextFile, and InternetQueryDataAvailable functions.
  • Setting up asynchronous operations is handled by the InternetSetStatusCallback.
  • Viewing and changing options is handled by the InternetSetOption and InternetQueryOption functions.
  • Closing all types of HINTERNET handles is handled by the InternetCloseHandle function.
  • Placing and removing locks on resources being used with InternetLockRequestFile and InternetUnlockRequestFile.

Using Common Functions

The following table lists the common functions included in the Win32 Internet functions. The common functions can be used on different types of HINTERNET handles or can be used during different types of sessions.
Function | Description
InternetFindNextFile | Continues file enumeration or search. Requires a handle created by the FtpFindFirstFile, GopherFindFirstFile, or InternetOpenUrl function.
InternetLockRequestFile | Allows the user to place a lock on the file that is being used. This function requires a handle returned by the FtpOpenFile, GopherOpenFile, HttpOpenRequest, or InternetOpenUrl function.
InternetQueryDataAvailable | Queries the amount of data available. Requires a handle created by the FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.
InternetQueryOption | Queries the setting of an Internet option.
InternetReadFile | Reads URL data. Requires a handle created by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.
InternetSetFilePointer | Sets the position for the next read in a file. Requires a handle created by InternetOpenUrl (on an HTTP URL only) or a handle created by HttpOpenRequest using the GET method.
InternetSetOption | Sets an Internet option.
InternetSetStatusCallback | Sets a callback function that is called with status information. Assigns a callback function to the designated HINTERNET handle and all handles derived from it.
InternetUnlockRequestFile | Unlocks a file that was locked using the InternetLockRequestFile function.

Reading files, finding the next file, manipulating options, and setting up asynchronous operations are common to various protocols and HINTERNET handle types.

Reading files

The InternetReadFile function is used to download resources from an HINTERNET handle returned by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.

InternetReadFile accepts a void pointer variable that contains the address of a buffer and a pointer to a double-word (DWORD) variable that contains the length of the buffer. It returns the data in the buffer and the amount of data downloaded into the buffer.

The Win32 Internet functions provide two techniques to download an entire resource:

  • Using the InternetQueryDataAvailable function.
  • Using the return values of InternetReadFile.

InternetQueryDataAvailable takes the HINTERNET handle created by InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest (after HttpSendRequest has been called on the handle) and returns the number of bytes available. The application should allocate a buffer equal to the number of bytes available +1 for the NULL terminator, and use that buffer with InternetReadFile. This method does not always work because InternetQueryDataAvailable is checking the file size listed in the header and not the actual file. The information in the header file could be outdated or the header file could be missing, since it is not currently required under all standards.

The following example reads the contents of the resource accessed by the hResource handle and displayed in the edit box indicated by intCtrlID.

int WINAPI Dumper(HWND hX, int intCtrlID, HINTERNET hResource)
{
     LPSTR     lpszData;          // buffer for the data
     DWORD     dwSize;               // size of the data available
     DWORD     dwDownloaded;     // size of the downloaded data
     DWORD     dwSizeSum=0;     // size of the data in the textbox
     LPSTR     lpszHolding;     // buffer to merge the textbox data and buffer

     // Set the cursor to an hourglass.
     SetCursor(LoadCursor(NULL,IDC_WAIT));

     // This loop handles reading the data.
     do
     {
          // The call to InternetQueryDataAvailable determines the amount of
          // data available to download.
          if (!InternetQueryDataAvailable(hResource,&dwSize,0,0))
          {
               ErrorOut(hX,GetLastError(),"InternetReadFile");
               SetCursor(LoadCursor(NULL,IDC_ARROW));
               return FALSE;
          }
          else
          {
               // Allocates a buffer of the size returned by InternetQueryDataAvailable
               lpszData = new char[dwSize+1];

               // Reads the data from the HINTERNET handle.
               if(!InternetReadFile(hResource,(LPVOID)lpszData,dwSize,&dwDownloaded))
               {
                    ErrorOut(hX,GetLastError(),"InternetReadFile");
                    delete[] lpszData;
                    break;
               }
               else
               {
                    // Adds a null terminator to the end of the data buffer
                    lpszData[dwDownloaded]='\0';

                    // Allocates the holding buffer
                    lpszHolding = new char[dwSizeSum + dwDownloaded + 1];

                    // Checks if there has been any data written to the textbox
                    if (dwSizeSum != 0)
                    {
                         // Retrieves the data stored in the textbox if any
                         GetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding,dwSizeSum);

                         // Adds a null terminator at the end of the textbox data
                         lpszHolding[dwSizeSum]='\0';
                    }
                    else
                    {
                         // Make the holding buffer an empty string.
                         lpszHolding[0]='\0';
                    }

                    // Adds the new data to the holding buffer
                    strcat(lpszHolding,lpszData);

                    // Writes the holding buffer to the textbox
                    SetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding);

                    // Delete the two buffers
                    delete[] lpszHolding;
                    delete[] lpszData;

                    // Add the size of the downloaded data to the textbox data size
                    dwSizeSum = dwSizeSum + dwDownloaded + 1;

                    // Check the size of the remaining data.  If it is zero, break.
                    if (dwDownloaded == 0)
                         break;
               }
          }
     }
     while(TRUE);

     // Close the HINTERNET handle
     InternetCloseHandle(hResource);

     // Set the cursor back to an arrow
     SetCursor(LoadCursor(NULL,IDC_ARROW));

     // Return
     return TRUE;
}

InternetReadFile returns zero bytes read and completes successfully when all available data has been read. This allows an application to use InternetReadFile in a loop to download the data and exit when it returns zero bytes read and completes successfully.

The following example reads the resource from the Internet and displays the resource in the edit box indicated by intCtrlID. The HINTERNET handle, hResource, has been returned by InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest (after being sent by HttpSendRequest).

int WINAPI Dump(HWND hX, int intCtrlID, HINTERNET hResource)
{

     DWORD dwSize = 0;
     LPSTR lpszData;
     LPSTR lpszOutPut;
     LPSTR lpszHolding;
     int nCounter = 1;
     int nBufferSize = 0;
     DWORD BigSize = 8000;

     // Set the cursor to an hourglass
     SetCursor(LoadCursor(NULL,IDC_WAIT));

     // Begin the loop that reads the data
     do
     {
          // Allocate the buffer
          lpszData =new char[BigSize+1];

          // Read the data
          if(!InternetReadFile(hResource,(LPVOID)lpszData,BigSize,&dwSize))
          {
               ErrorOut(hX,GetLastError(),"InternetReadFile");
               delete []lpszData;
               break;
          }
          else
          {
               // Add a null terminator to the end of the buffer
               lpszData[dwSize]='\0';

               // Check if all of the data has been read.  This should never
               // get called on the first time through the loop.
               if (dwSize == 0)
               {
                    // Write the final data to the textbox
                    SetDlgItemText(hX,intCtrlID,lpszHolding);

                    // Delete the existing buffers.
                    delete [] lpszData;
                    delete [] lpszHolding;
                    break;
               }

               // Determine the buffer size to hold the new data and the data
               // already written to the textbox (if any).
               nBufferSize = (nCounter*BigSize)+1;

               // Increment the number of buffers read
               nCounter++;

               // Allocate the output buffer
               lpszOutPut = new char[nBufferSize];

               // Make sure the buffer is not the initial buffer
               if(nBufferSize != int(BigSize+1))
               {
                    // Copy the data in the holding buffer
                    strcpy(lpszOutPut,lpszHolding);

                    // Concatenate the new buffer with the output buffer
                    strcat(lpszOutPut,lpszData);

                    // Delete the holding buffer
                    delete [] lpszHolding;
               }
               else
               {
                    // Copy the data buffer
                    strcpy(lpszOutPut, lpszData);
               }

               // Allocate a holding buffer
               lpszHolding = new char[nBufferSize];

               // Copy the output buffer into the holding buffer
               memcpy(lpszHolding,lpszOutPut,nBufferSize);

               // Delete the other buffers
               delete [] lpszData;
               delete [] lpszOutPut;

          }

     }
     while (TRUE);

     // Close the HINTERNET handle
     InternetCloseHandle(hResource);

     // Set the cursor back to an arrow
     SetCursor(LoadCursor(NULL,IDC_ARROW));

     // Return
     return TRUE;
}

Finding the next file

The InternetFindNextFile function is used to find the next file in a file search, using the search parameters and HINTERNET handle from either FtpFindFirstFile, GopherFindFirstFile, or InternetOpenUrl.

To complete a file search, continue to call InternetFindNextFile using the HINTERNET handle returned by FtpFindFirstFile, GopherFindFirstFile, or InternetOpenUrl until the function fails with the extended error message ERROR_NO_MORE_FILES. To get the extended error information, call the GetLastError function.

The following example displays the contents of an FTP directory in the list box, IDC_FTPList. The HINTERNET handle, hSecondary, is a handle returned by the InternetConnect function after it establishes an FTP session.

bool WINAPI DisplayDir(HWND hX, int lstDirectory, HINTERNET hConnect,
                            DWORD dwFlag)
{
     WIN32_FIND_DATA pDirInfo;
     HINTERNET hDir;
     char DirList[MAX_PATH];

     // Set the cursor to an hourglass
     SetCursor(LoadCursor(NULL,IDC_WAIT));

     // Reset the list box
     SendDlgItemMessage(hX, lstDirectory,LB_RESETCONTENT,0,0);

     // Find the first file
     if ( !(hDir = FtpFindFirstFile (hConnect, TEXT ("*.*"), &pDirInfo,
                                             dwFlag, 0) ))
     {
          // Check if the error was because there were no files
          if (GetLastError()  == ERROR_NO_MORE_FILES)
          {
               // Alert user
               MessageBox(hX,"There are no files here!!!","Display Dir",MB_OK);

               // Close the HINTERNET handle
               InternetCloseHandle(hDir);

               // Set the cursor back to an arrow
               SetCursor(LoadCursor(NULL,IDC_ARROW));

               // Return
               return TRUE;
          }
          else
          {
               // Call error handler
               ErrorOut (hX, GetLastError (), "FindFirst error: ");

               // Close the HINTERNET handle
               InternetCloseHandle(hDir);

               // Set the cursor back to an arrow
               SetCursor(LoadCursor(NULL,IDC_ARROW));

               // Return
               return FALSE;
          }
     }
     else
     {

          // Write the filename to a string
          sprintf(DirList, pDirInfo.cFileName);

          // Check the type of file
          if (pDirInfo.dwFileAttributes == FILE_ATTRIBUTE_DIRECTORY)
          {
               // Add <DIR> to indicate that this is a directory to the user
               strcat(DirList," <DIR> ");
          }

          // Add the filename (or directory) to the listbox
          SendDlgItemMessage(hX,lstDirectory,LB_ADDSTRING,0,(LPARAM)DirList);

     }

     do
     {
          // Find the next file
          if (!InternetFindNextFile (hDir, &pDirInfo))
          {
               // Check if there are no more files left
               if ( GetLastError() == ERROR_NO_MORE_FILES )
               {
                    // Close the HINTERNET handle
                    InternetCloseHandle(hDir);

                    // Set the cursor back to an arrow
                    SetCursor(LoadCursor(NULL,IDC_ARROW));

                    // Return
                    return TRUE;
               }
               else
               {
                    // Handle the error
                    ErrorOut (hX,GetLastError(), "InternetFindNextFile");

                    // Close the HINTERNET handle
                    InternetCloseHandle(hDir);

                    // Set the cursor back to an arrow
                    SetCursor(LoadCursor(NULL,IDC_ARROW));

                    // Return
                    return FALSE;
               }
           }
           else
           {
               // Write the filename to a string
               sprintf(DirList, pDirInfo.cFileName);

               // Check the type of file
               if (pDirInfo.dwFileAttributes == FILE_ATTRIBUTE_DIRECTORY)
               {
                    // Add <DIR> to indicate that this is a directory to the user
                    strcat(DirList," <DIR> ");
               }

               // Add the filename (or directory) to the listbox
               SendDlgItemMessage(hX,lstDirectory,LB_ADDSTRING,0,(LPARAM)DirList);
           }
     }
     while ( TRUE);

}

Manipulating options

InternetSetOption and InternetQueryOption are used to manipulate the Win32 Internet API options.

InternetSetOption accepts a double-word value that indicates the option to set, a buffer to hold the option setting, and a pointer that contains the address of the variable containing the length of the buffer.

InternetQueryOption accepts a double-word value that indicates the option to query, a buffer to hold the option setting, and a pointer that contains the address of the variable containing the length of the buffer.

Setting up asynchronous operations

By default, the Win32 Internet functions operate synchronously. An application can request asynchronous operation by setting the INTERNET_FLAG_ASYNC flag in the call to the InternetOpen function. All future calls made against handles derived from the handle returned from InternetOpen will be made asynchronously.

The rationale for asynchronous versus synchronous operation is to allow a single-threaded application to maximize its utilization of the CPU without having to wait for network I/O to complete. Therefore, depending on the request, the operation might complete synchronously or asynchronously. The application should check the return code. If a function returns FALSE or NULL, and GetLastError returns ERROR_IO_PENDING, the request has been made asynchronously, and the application will be called back with INTERNET_STATUS_REQUEST_COMPLETE when the function has completed.

For an application to be able to make requests asynchronously, it must set the INTERNET_FLAG_ASYNC flag in the call to InternetOpen, it must register a valid callback function, and it must supply a nonzero context value.

To begin asynchronous operation, the application must set the INTERNET_FLAG_ASYNC flag in its call to InternetOpen. It must then register a valid callback function, using InternetSetStatusCallback.

After a callback function is registered for a handle, all operations on that handle can generate status indications, provided that the context value that was supplied when the handle was created was not zero. Providing a zero context value forces an operation to complete synchronously, even though INTERNET_FLAG_ASYNC was specified in InternetOpen.

Status indications are mainly intended to give the application feedback about the operation's progress and are mainly concerned with network operations, such as resolving a host name, connecting to a server, and receiving data. Three special-purpose status indications can be made for a handle:

  • INTERNET_STATUS_HANDLE_CLOSING is the last status indication that is made for a handle.
  • INTERNET_STATUS_HANDLE_CREATED indicates when the handle is initially created.
  • INTERNET_STATUS_REQUEST_COMPLETE indicates when an asynchronous operation completes.

The application must check the INTERNET_ASYNC_RESULT structure to determine whether the operation succeeded or failed after receiving an INTERNET_STATUS_REQUEST_COMPLETE indication.

The following sample shows an example of a callback function and a call to InternetSetStatusCallback to register the function as the callback function.

void
CALLBACK
CInternet::InternetCallback(
    HINTERNET hInternet,
    DWORD dwcontext,
    DWORD dwInternetStatus,
    LPVOID lpvStatusInformation,
    DWORD dwStatusInformationLength
)
{

// Insert code here.

};

INTERNET_STATUS_CALLBACK dwISC;

dwISC = InternetSetStatusCallback(   hInternet,
        (INTERNET_STATUS_CALLBACK) InternetCallback);

Closing HINTERNET handles

All HINTERNET handles can be closed by using the InternetCloseHandle function. Client applications must close all HINTERNET handles derrived from the HINTERNET handle to be closed before calling InternetCloseHandle. For more information about HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

The following example illustrates the handle hierarchy for the Win32 Internet functions.

HINTERNET hRootHandle, hOpenUrlHandle;

hRootHandle = InternetOpen("Example", INTERNET_OPEN_TYPE_DIRECT, NULL,
    NULL, 0);

hOpenUrlHandle = InternetOpenUrl(hRootHandle,
    "http://www.server.com/default.htm", NULL, 0,
    INTERNET_FLAG_RAW_DATA,0);

// Close the handle created by InternetOpenUrl, so that the InternetOpen handle can be closed.
InternetCloseHandle(hOpenUrlHandle);

// Close the handle created by InternetOpen
InternetCloseHandle(hRootHandle);

Locking and unlocking resources

The InternetLockRequestFile function allows an application to ensure that the cached resource associated with the HINTERNET handle passed to it will not disappear from the cache. If another download tries to commit a resource that has the same URL as the locked file, the cache avoids removing the file by doing a safe delete. After the application calls the InternetUnlockRequestFile function, the cache is given permission to delete the file.

If the INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE flag has been set, InternetLockRequestFile creates a temporary file with the extension TMP, unless the handle is connected to an HTTPS resource. If the function is accessing an HTTPS resource and INTERNET_FLAG_NO_CACHE_WRITE (or INTERNET_FLAG_DONT_CACHE) has been set, InternetLockRequestFile fails.


Handling Uniform Resource Locators

A Uniform Resource Locator (URL) is a compact representation of the location and access method for a resource located on the Internet. Each URL consists of a scheme (HTTP, HTTPS, FTP, or Gopher) and a scheme-specific string. This string can also include a combination of a directory path, search string, or name of the resource. The Win32 Internet functions provide the ability to create, combine, break down, and canonicalize URLs. For more information on URLs, see RFC 1738, Uniform Resource Locators (URL). This document can be found at http://ds.internic.net/rfc/rfc1738.txt. External link

The URL functions operate in a task-oriented manner. The content and format of the URL that is given to the function is not verified. The calling application should track the use of these functions to ensure that the data is in the intended format. For example, the InternetCanonicalizeUrl function would convert the character "%" into the escape sequence "%25" when using no flags. If InternetCanonicalizeUrl is used on the canonicalized URL, the escape sequence "%25" would be converted into the escape sequence "%2525", which would not work properly.

The following table summarizes the URL functions in the Win32 Internet API.
Function | Description
InternetCanonicalizeUrl | Canonicalizes the URL that is passed to the function. By default, InternetCanonicalizeUrl always encodes.
InternetCombineUrl | Combines base and relative URLs into one complete URL.
InternetCrackUrl | Breaks the URL into its component parts. This information is returned in a URL_COMPONENTS structure.
InternetCreateUrl | Allows an application to create a complete URL from its component parts.
InternetOpenUrl | Locates the resource designated by a canonicalized URL and creates a handle, which can be used by InternetReadFile to retrieve that resource. InternetOpenUrl combines the tasks normally performed by InternetConnect with the operations handled by FtpOpenFile, GopherOpenFile, and HttpOpenRequest.

What Is a Canonicalized URL?

The format of all URLs must follow the accepted syntax and semantics in order to access resources via the Internet. Canonicalization is the process of formatting a URL to follow this accepted syntax and semantics.

Characters that must be encoded include any characters that have no corresponding graphic character in the US-ASCII coded character set (hexadecimal 80-FF, which are not used in the US-ASCII coded character set, and hexadecimal 00-1F and 7F, which are control characters), blank spaces, "%" (which is used to encode other characters), and unsafe characters (<, >, ", #, {, }, |, \, ^, ~, [, ], and ').

Using the Win32 Internet Functions to Handle URLs

The following table summarizes the URL functions included with the Win32 Internet functions.
Function | Description
InternetCanonicalizeUrl | Canonicalizes the URL.
InternetCombineUrl | Combines base and relative URLs.
InternetCrackUrl | Parses a URL string into components.
InternetCreateUrl | Creates a URL string from components.
InternetOpenUrl | Begins retrieving an FTP, Gopher, HTTP, or HTTPS resource.

Canonicalizing URLs

Canonicalizing a URL is the process that converts a URL (that might contain unsafe characters such as blank spaces, reserved characters, and so on) into an accepted format.

The InternetCanonicalizeUrl function can be used to canonicalize URLs. This function is very task-oriented, so the application should track its use carefully. InternetCanonicalizeUrl does not verify that the URL passed to it is already canonicalized and that the URL that it returns is valid.

The following five flags control how InternetCanonicalizeUrl handles a particular URL. The flags can be used in combination. If no flags are used, the function encodes the URL by default.
Value | Meaning
ICU_BROWSER_MODE | Do not encode or decode characters after "#" or "?", and do not remove trailing white space after "?". If this value is not specified, the entire URL is encoded, and trailing white space is removed.
ICU_DECODE | Convert all %XX sequences to characters, including escape sequences, before the URL is parsed.
ICU_ENCODE_SPACES_ONLY | Encode spaces only.
ICU_NO_ENCODE | Do not convert unsafe characters to escape sequences.
ICU_NO_META | Do not remove meta sequences (such as "." and "..") from the URL.

The ICU_DECODE flag should be used only on canonicalized URLs, because it assumes that all %XX sequences are escape codes and converts them into the characters indicated by the code. If the URL has a "%" symbol in it that is not part of an escape code, ICU_DECODE still treats it as one. This characteristic might cause InternetCanonicalizeUrl to create an invalid URL.

To use InternetCanonicalizeUrl to return a completely decoded URL, the ICU_DECODE and ICU_NO_ENCODE flags must be specified. This setup assumes that the URL being passed to InternetCanonicalizeUrl has been previously canonicalized.

Combining base and relative URLs

A relative URL is a compact representation of the location of a resource relative to an absolute base URL. The base URL must be known to the parser and usually includes the scheme, network location, and parts of the URL path. An application can call InternetCombineUrl to combine the relative URL with its base URL. InternetCombineUrl will also canonicalize the resultant URL.

Cracking URLs

The InternetCrackUrl function separates a URL into its component parts and returns the components indicated by the URL_COMPONENTS structure that is passed to the function.

The components that make up the URL_COMPONENTS structure are the scheme number, host name, port number, user name, password, URL path, and additional information (such as search parameters). Each component, except the scheme and port numbers, has a string member that holds the information and a member that holds the length of the string member. The scheme and port numbers have only a member that stores the corresponding value; they are both returned on all successful calls to InternetCrackUrl.

To get the value of a particular component in the URL_COMPONENTS structure, the member that stores the string length of that component must be set to a nonzero value. The string member can be either the address of a buffer or NULL.

If the pointer member contains the address of a buffer, the string length member must contain the size of that buffer. InternetCrackUrl returns the component information as a string in the buffer and stores the string length in the string length member.

If the pointer member is set to NULL, the string length member can be set to any nonzero value. InternetCrackUrl stores the address of the first character of the URL string that contains the component information and sets the string length to the number of characters in the remaining part of the URL string that pertains to the component.

All pointer members set to NULL with a nonzero length member point to the appropriate starting point in the URL string. The length stored in the length member must be used to determine the end of the individual component's information.

To finish initializing the URL_COMPONENTS structure properly, the dwStructSize member must be set to the size of the URL_COMPONENTS structure.

The following example returns the components of the URL in the edit box, IDC_PreOpen1, and returns the components to the list box, IDC_PreOpenList. To display only the information for an individual component, this function copies the character immediately after the component's information in the string and temporarily replaces it with a NULL.

int WINAPI Cracker(HWND hX)
{
    URL_COMPONENTS urlcmpTheUrl;
    int intTestSize = 80;
    LPSTR lpszUrlIn;
    LPURL_COMPONENTS lpUrlComp = &urlcmpTheUrl;
    char TempOut[256];
    char tempChar;

    lpszUrlIn = new char[intTestSize];
    GetDlgItemText(hX,IDC_PreOpen1,lpszUrlIn,intTestSize);
    SendDlgItemMessage(hX,IDC_PreOpenList,LB_RESETCONTENT,0,0);
    urlcmpTheUrl.dwStructSize = sizeof(urlcmpTheUrl);

    urlcmpTheUrl.lpszScheme = NULL;
    urlcmpTheUrl.lpszHostName = NULL;
    urlcmpTheUrl.lpszUserName = NULL;
    urlcmpTheUrl.lpszPassword = NULL;
    urlcmpTheUrl.lpszUrlPath = NULL;
    urlcmpTheUrl.lpszExtraInfo = NULL;

    /* the following lines set which components will be displayed */
    urlcmpTheUrl.dwSchemeLength = 1;
    urlcmpTheUrl.dwHostNameLength = 1;
    urlcmpTheUrl.dwUserNameLength = 1;
    urlcmpTheUrl.dwPasswordLength = 1;
    urlcmpTheUrl.dwUrlPathLength = 1;
    urlcmpTheUrl.dwExtraInfoLength = 1;

    if (!InternetCrackUrl(lpszUrlIn,strlen(lpszUrlIn),0, lpUrlComp))
    {
        ErrorOut(hX,GetLastError(),"Cracker");
        return FALSE;
    }
    else
    {
        if (urlcmpTheUrl.dwSchemeLength != 0)
        {
            tempChar = urlcmpTheUrl.lpszScheme[urlcmpTheUrl.dwSchemeLength];
            urlcmpTheUrl.lpszScheme[urlcmpTheUrl.dwSchemeLength]='\0';
            sprintf(TempOut, "Scheme: %s", urlcmpTheUrl.lpszScheme);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszScheme[urlcmpTheUrl.dwSchemeLength]= tempChar;
        }

        sprintf(TempOut, "Scheme number: %d", urlcmpTheUrl.nScheme);
        SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
            (LPARAM)TempOut);

        if (urlcmpTheUrl.dwHostNameLength != 0)
        {
            tempChar = urlcmpTheUrl.lpszHostName[urlcmpTheUrl.dwHostNameLength];
            urlcmpTheUrl.lpszHostName[urlcmpTheUrl.dwHostNameLength] = '\0';
            sprintf(TempOut, "Host Name: %s", urlcmpTheUrl.lpszHostName);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszHostName[urlcmpTheUrl.dwHostNameLength] = tempChar;
        }

        sprintf(TempOut, "Port Number: %d", urlcmpTheUrl.nPort);
        SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
            (LPARAM)TempOut);

        if (urlcmpTheUrl.dwUserNameLength != 0)
        {
            tempChar = urlcmpTheUrl.lpszUserName[urlcmpTheUrl.dwUserNameLength];
            urlcmpTheUrl.lpszUserName[urlcmpTheUrl.dwUserNameLength] = '\0';
            sprintf(TempOut, "User Name: %s", urlcmpTheUrl.lpszUserName);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszUserName[urlcmpTheUrl.dwUserNameLength] = tempChar;
        }

        if (urlcmpTheUrl.dwPasswordLength != 0)
        {
            tempChar= urlcmpTheUrl.lpszPassword[urlcmpTheUrl.dwPasswordLength];
            urlcmpTheUrl.lpszPassword[urlcmpTheUrl.dwPasswordLength] = '\0';
            sprintf(TempOut, "Password: %s", urlcmpTheUrl.lpszPassword);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszPassword[urlcmpTheUrl.dwPasswordLength] = tempChar;
        }

        if (urlcmpTheUrl.dwUrlPathLength != 0)
        {
            tempChar=urlcmpTheUrl.lpszUrlPath[urlcmpTheUrl.dwUrlPathLength];
            urlcmpTheUrl.lpszUrlPath[urlcmpTheUrl.dwUrlPathLength] = '\0';
            sprintf(TempOut, "Path: %s", urlcmpTheUrl.lpszUrlPath);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszUrlPath[urlcmpTheUrl.dwUrlPathLength] = tempChar;
        }

        if(urlcmpTheUrl.dwExtraInfoLength != 0)
        {
            tempChar = urlcmpTheUrl.lpszExtraInfo[urlcmpTheUrl.dwExtraInfoLength];
            urlcmpTheUrl.lpszExtraInfo[urlcmpTheUrl.dwExtraInfoLength] = '\0';
            sprintf(TempOut, "Extra: %s", urlcmpTheUrl.lpszExtraInfo);
            SendDlgItemMessage(hX,IDC_PreOpenList,LB_ADDSTRING,0,
                (LPARAM)TempOut);
            urlcmpTheUrl.lpszExtraInfo[urlcmpTheUrl.dwExtraInfoLength] = tempChar;
        }

        return TRUE;
    }
}

Creating URLs

The InternetCreateUrl function uses the information in the URL_COMPONENTS structure to create a Uniform Resource Locator.

The components that make up the URL_COMPONENTS structure are the scheme, host name, port number, user name, password, URL path, and additional information (such as search parameters). Each component, except the port number, has a string member that holds the information and a member that holds the length of the string member.

For each required component, the pointer member should contain the address of the buffer holding the information. The length member should be set to zero if the pointer member contains the address of a zero-terminated string; the length member should be set to the string length if the pointer member contains the address of a string that is not zero-terminated. The pointer member of any components that are not required must be set to NULL.

Accessing URLs directly

Gopher, FTP, and HTTP resources on the Internet can be accessed directly by using the InternetOpenUrl, InternetReadFile, and InternetFindNextFile functions. InternetOpenUrl opens a connection to the resource at the URL passed to the function. When this connection is made, there are two possible steps. First, if the resource is a file, InternetReadFile can download it; second, if the resource is a directory, InternetFindNextFile can enumerate the files within the directory (except when using CERN proxies). For more information on InternetReadFile, see Reading files. For more information on InternetFindNextFile, see Finding the next file.

For applications that need to operate through a CERN proxy, InternetOpenUrl can be used to access FTP directories and files. The FTP requests are packaged to appear like an HTTP request, which the CERN proxy would accept.

InternetOpenUrl uses the HINTERNET handle created by the InternetOpen function and the URL of the resource. The URL must include the scheme ("http:", "ftp:", "gopher:", "file:" [for a local file], or "https:" [for hypertext protocol secure]) and network location (such as "www.microsoft.com"). The URL can also include a path (for example, "/windows/feature/") and resource name (for example, "default.htm"). For HTTP or HTTPS requests, additional headers can be included.

InternetQueryDataAvailable, InternetFindNextFile, InternetReadFile, and InternetSetFilePointer (HTTP or HTTPS URLs only) can use the handle that is created by InternetOpenUrl to download the resource.

The following diagram illustrates what handles to use with each function.

Handles to use with functions

The root HINTERNET handle created by InternetOpen is used by InternetOpenUrl. The HINTERNET handle created by InternetOpenUrl can be used by InternetQueryDataAvailable, InternetReadFile, InternetFindNextFile (not shown here), and InternetSetFilePointer (HTTP or HTTPS URLs only).

For more information about HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

The following example connects to the resource by using the InternetOpenUrl function. The sample function then uses the InternetReadFile function to download the resource. The function displays the downloaded resource in the edit box indicated by intCtrlID.

int WINAPI UrlDump(HWND hX, int intCtrlID)
{

     HINTERNET hUrlDump;
     DWORD dwSize=TRUE;
     LPSTR lpszData;
     LPSTR lpszOutPut;
     LPSTR lpszHolding;
     int nCounter=1;
     int nBufferSize;
     DWORD BigSize=8000;

     hUrlDump = InternetOpenUrl(hRootHandle, "server.name", NULL, NULL,
        INTERNET_FLAG_RAW_DATA, 0);

     do
     {
          // Allocate the buffer
          lpszData =new char[BigSize+1];

          // Read the data
          if(!InternetReadFile(hUrlDump,(LPVOID)lpszData,BigSize,&dwSize))
          {
               ErrorOut(hX,GetLastError(),"InternetReadFile");
               delete []lpszData;
               break;
          }
          else
          {
               // Add a null terminator to the end of the buffer
               lpszData[dwSize]='\0';

               // Check if all of the data has been read.  This should never
               // get called on the first time through the loop.
               if (dwSize == 0)
               {
                    // Write the final data to the textbox
                    SetDlgItemText(hX,intCtrlID,lpszHolding);

                    // Delete the existing buffers.
                    delete [] lpszData;
                    delete [] lpszHolding;
                    break;
               }

               // Determine the buffer size to hold the new data and the data
               // already written to the textbox (if any).
               nBufferSize = (nCounter*BigSize)+1;

               // Increment the number of buffers read
               nCounter++;

               // Allocate the output buffer
               lpszOutPut = new char[nBufferSize];

               // Make sure the buffer is not the initial buffer
               if(nBufferSize != int(BigSize+1))
               {
                    // Copy the data in the holding buffer
                    strcpy(lpszOutPut,lpszHolding);

                    // Concatenate the new buffer with the output buffer
                    strcat(lpszOutPut,lpszData);

                    // Delete the holding buffer
                    delete [] lpszHolding;
               }
               else
               {
                    // Copy the data buffer
                    strcpy(lpszOutPut, lpszData);
               }

               // Allocate a holding buffer
               lpszHolding = new char[nBufferSize];

               // Copy the output buffer into the holding buffer
               memcpy(lpszHolding,lpszOutPut,nBufferSize);

               // Delete the other buffers
               delete [] lpszData;
               delete [] lpszOutPut;

          }

     }
     while (TRUE);

     // Close the HINTERNET handle
     InternetCloseHandle(hUrlDump);

     // Set the cursor back to an arrow
     SetCursor(LoadCursor(NULL,IDC_ARROW));

     // Return
     return TRUE;
}


Handling Authentication

Some proxies and servers require authentication before allowing access to resources on the Internet. The Win32 Internet functions support server and proxy authentication for HTTP sessions. Authentication of Gopher and FTP servers must be handled by InternetConnect. Currently, there is no support available for FTP gateway authentication.

About HTTP Authentication

If authentication is required, the client program receives a status code of 401 (if the server requires authentication) or 407 (if the proxy requires authentication). Along with the status code, the proxy or server sends one or more authenticate response headers—Proxy-Authenticate (for proxy authentication) or WWW-Authenticate (for server authentication).

Each authenticate response header contains an available authentication scheme and a realm. If multiple authentication schemes are supported, the server returns multiple authenticate response headers. The realm value is case sensitive and defines a protection space on the proxy or server. For example, the header "WWW-Authenticate: Basic Realm="example"" would be an example of a header returned when server authentication is needed.

The client program that sent the request can authenticate itself by including an Authorization header field with the request. The Authorization header would contain the authentication scheme and the appropriate response required by that scheme. For example, the header "Authorization: Basic <username:password>" would be added to the request and resent to the server if the client received the authenticate response header "WWW-Authenticate: Basic Realm="example"".

There are two general kinds of authentication schemes:

  • Basic authentication scheme, where the user name and password are sent over in cleartext to the server.
  • Challenge-response schemes, which allows for a challenge-response format.

The Basic authentication scheme is based on the model that a client must authenticate itself with a user name and password for each realm. The server services the request if it is resent with an Authorization header that includes a valid user name and password.

Challenge-response schemes allow for more secure authentication. If a request requires authentication using a challenge-response scheme, the appropriate status code and Authenticate headers are returned to the client. The client then needs to resend the request with a negotiate. The server would return an appropriate status code with a challenge, and the client would then need to resend the request with the proper response to get the requested service.

The following table contains the authentication schemes that are used with the Win32 Internet functions, the authentication type, the DLLs that support them, and a description of the scheme.
Scheme | Type | DLL | Description
Basic (cleartext) | basic | Wininet.dll | Uses a base64 encoded string that contains the user name and password.
NT LAN Manager (NTLM) | challenge-response | Winsspi.dll | A challenge-response scheme that bases the challenge on the user name.
Microsoft Network (MSN) | challenge-response | Msnsspc.dll | The Microsoft Network's authentication scheme.
Distributed Password Authentication (DPA) | challenge-response | Msapsspc.dll | Similar to MSN authentication and will also be used by the Microsoft Network.
Remote Passphrase Authentication (RPA) | CompuServe | Rpawinet.dll, da.dll | CompuServe's authentication scheme. For more information, see http://www.compuserve.com/rpa/rpadoco.htm.

For anything other than Basic authentication, the registry keys must be set up in addition to installing the appropriate DLL(s). For more information on setting these registry keys, see Registering authentication keys.

If authentication is required, the INTERNET_FLAG_KEEP_CONNECTION flag should be used in the call to HttpOpenRequest. The INTERNET_FLAG_KEEP_CONNECTION flag is required for NTLM and other types of authentication in order to maintain the connection while completing the authentication process. If the connection is not maintained, the authentication process must be restarted with the proxy or server.

The Win32 Internet functions InternetOpenUrl and HttpSendRequest complete successfully even when authentication is required. The difference is, the information returned in the header files and InternetReadFile would receive an HTML page informing the user of the status code.

Registering authentication keys

INTERNET_OPEN_TYPE_PRECONFIG looks at the registry values ProxyEnable, ProxyServer, and ProxyOverride. These values are located under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings.

For authentication schemes other than Basic, a key needs to be added to the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Security. A string value, DLLFile, should contain the name of the DLL that supports the authentication scheme, and a DWORD value, Flags, should be set with the appropriate value. The following list shows the possible values for the Flags value.

PLUGIN_AUTH_FLAGS_UNIQUE_CONTEXT_PER_TCPIP (value=0x01)
Each TCP/IP socket will contain a different context. Otherwise, a new context will be passed for each realm or block URL template.
PLUGIN_AUTH_FLAGS_CAN_HANDLE_UI (value=0x02)
This DLL can handle its own user input.
PLUGIN_AUTH_FLAGS_CAN_HANDLE_NO_PASSWD (value=0x04)
This DLL might be capable of doing an authentication without prompting the user for a password.
PLUGIN_AUTH_FLAGS_NO_REALM (value=0x08)
This DLL does not use a standard HTTP realm string. Any data that appears to be a realm will be scheme-specific information.
PLUGIN_AUTH_FLAGS_KEEP_ALIVE_NOT_REQUIRED (value=0x10)
This DLL does not require a persistent connection for its challenge-response sequence.

For example, to add NTLM authentication, the key NTLM would need to be added to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Security. Under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Security\NTLM, the string value, DLLFile, and a DWORD value, Flags, would need to be added. DLLFile would need to be set to winsspi.dll, and Flags would need to be set to 0x08.

Server authentication

When a server receives a request that requires authentication, the server returns a 401 status code message. In that message, the server should include one or more WWW-Authenticate response headers. These headers include the authentication methods the server has available. The Win32 Internet functions pick the first method they recognize.

Basic authentication provides weak security unless the channel is first link-encrypted with SSL or PCT.

The InternetErrorDlg function can be used to obtain the user name and password information from the user, or a customized user interface can be designed to obtain the information.

A custom interface can use the InternetSetOption function to set the INTERNET_OPTION_PASSWORD and INTERNET_OPTION_USERNAME values and then resend the request to the server.

Proxy authentication

When a client attempts to use a proxy that requires authentication, the proxy returns a 407 status code message to the client. In that message, the proxy should include one or more Proxy-Authenticate response headers. These headers include the authentication methods available from the proxy. The Win32 Internet functions pick the first method they recognize.

The InternetErrorDlg function can be used to obtain the user name and password information from the user, or a customized user interface can be designed.

A custom interface can use the InternetSetOption function to set the INTERNET_OPTION_PROXY_PASSWORD and INTERNET_OPTION_PROXY_USERNAME values and then resend the request to the proxy.

If no proxy user name and password are set, the Win32 Internet functions attempt to use the user name and password for the server. This behavior allows clients to implement the same customized user interface that is used to handle server authentication.

Handling HTTP Authentication

HTTP authentication can be handled with either InternetErrorDlg or a customized function that uses InternetSetOption or adds its own authentication headers. InternetErrorDlg can examine the headers associated with an HINTERNET handle to find hidden errors, such as status codes from a proxy or server. InternetSetOption can be used to set the user name and password for the proxy and server. For MSN and DPA authentication, InternetErrorDlg must be used to set the user name and password.

For any customized function that adds its own WWW-Authenticate or Proxy-Authenticate headers, the INTERNET_FLAG_NO_AUTH flag should be set to disable WinInet's authentication.

The following example shows how InternetErrorDlg can be used to handle HTTP authentication.

HINTERNET hOpenHandle,  hConnectHandle, hResourceHandle;
DWORD dwError, dwErrorCode;

hOpenHandle = InternetOpen("Example", INTERNET_OPEN_TYPE_PRECONFIG,
                           NULL, NULL, 0);

hConnectHandle = InternetConnect(hOpenHandle, "www.server.com",
                                 INTERNET_INVALID_PORT_NUMBER, NULL,
                                 NULL, INTERNET_SERVICE_HTTP,0,0);

hResourceHandle = HttpOpenRequest(hConnectHandle, "GET", "/premium/default.htm",
                                  NULL, NULL, NULL,
                                  INTERNET_FLAG_KEEP_CONNECTION, 0);

resend:

HttpSendRequest(hResourceHandle, NULL, 0, NULL, 0);

//  dwErrorCode stores the error code associated with the call to HttpSendRequest.

dwErrorCode = hResourceHandle ? ERROR_SUCCESS : GetLastError();

dwError = InternetErrorDlg(hwnd, hResourceHandle, dwErrorCode,
                           FLAGS_ERROR_UI_FILTER_FOR_ERRORS |
                           FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS |
                           FLAGS_ERROR_UI_FLAGS_GENERATE_DATA,
                           NULL);

if (dwError == ERROR_INTERNET_FORCE_RETRY)
    goto resend;

//  Insert code to read the information from the hResourceHandle at this point.

In the example, dwErrorCode is used to store any errors associated with the call to HttpSendRequest. HttpSendRequest will complete successfully, even if the proxy or server requires authentication. When the FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag is passed to InternetErrorDlg, the function checks the headers for any hidden errors. These hidden errors would include any requests for authentication. InternetErrorDlg displays the appropriate dialog box to prompt the user for the necessary information. The FLAGS_ERROR_UI_FLAGS_GENERATE_DATA and FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS flags should also be passed to InternetErrorDlg, so that the function constructs the appropriate data structure for the error and stores the results of the dialog box in the HINTERNET handle.

The following example shows how authentication could be handled using InternetSetOption.

HINTERNET hOpenHandle,  hResourceHandle;
DWORD dwError, dwStatus;
DWORD dwStatusSize = sizeof(dwStatus);
char strUsername[64], strPassword[64];

hOpenHandle = InternetOpen("Example", INTERNET_OPEN_TYPE_PRECONFIG,
                           NULL, NULL, 0);
hConnectHandle = InternetConnect(hOpenHandle, "www.server.com",
                                 INTERNET_INVALID_PORT_NUMBER, NULL,
                                 NULL, INTERNET_SERVICE_HTTP,0,0);

hResourceHandle = HttpOpenRequest(hConnectHandle, "GET", "/premium/default.htm",
                                  NULL, NULL, NULL,
                                  INTERNET_FLAG_KEEP_CONNECTION, 0);

resend:

HttpSendRequest(hResourceHandle, NULL, 0, NULL, 0);

HttpQueryInfo(hResourceHandle, HTTP_QUERY_FLAG_NUMBER |
              HTTP_QUERY_STATUS_CODE, &dwStatus, &dwStatusSize, NULL);

switch (dwStatus)
{
    case HTTP_STATUS_PROXY_AUTH_REQ:    //Proxy Authentication Required
        // Insert code to set strUsername and strPassword
        InternetSetOption(hResourceHandle, INTERNET_OPTION_PROXY_USERNAME,
                          strUsername, strlen(strUsername)+1);
        InternetSetOption(hResourceHandle, INTERNET_OPTION_PROXY_PASSWORD,
                          strPassword, strlen(strPassword)+1);
        break;
    case HTTP_STATUS_DENIED:     //Server Authentication Required
        // Insert code to set strUsername and strPassword
        InternetSetOption(hResourceHandle, INTERNET_OPTION_USERNAME,
                          strUsername, strlen(strUsername)+1);
        InternetSetOption(hResourceHandle, INTERNET_OPTION_PASSWORD,
                          strPassword, strlen(strPassword)+1);
        break;
}

//  Insert code to read the information from the hResourceHandle at this point.


FTP Sessions

The Win32 Internet functions can be used to provide applications with the ability to navigate and manipulate directories and files on an FTP server. Applications that use a CERN proxy exclusively must use the InternetOpenUrl function because CERN proxies do not support FTP. For more information on how to use InternetOpenUrl, see Accessing URLs directly.

To begin an FTP session, use InternetConnect to create the valid FTP session handle to be used by the FTP functions provided with the Win32 Internet functions.

The Win32 Internet functions provide the capability to navigate between directories; enumerate, create, remove, and rename directories; and rename, upload, download, and delete files on an FTP server.

Navigation is provided by the FtpGetCurrentDirectory and FtpSetCurrentDirectory functions. These functions utilize the FTP session handle created by a previous call to InternetConnect to determine which directory the application is currently in or to change to a different subdirectory.

Directory enumeration is performed by using the FtpFindFirstFile and InternetFindNextFile functions. FtpFindFirstFile uses the FTP session handle created by InternetConnect to find the first file that matches the given search criteria and returns a handle to continue the directory enumeration. InternetFindNextFile uses the handle returned by FtpFindFirstFile to return the next file that matches the original search criteria. The application should continue to call InternetFindNextFile until there are no more files left in the directory.

New directories are created by using the FtpCreateDirectory function. This function uses the FTP session handle created by InternetConnect and creates the directory specified by the string passed to the function. The string can contain a directory name relative to the current directory, or a fully qualified directory path.

To rename either files or directories, the application can call FtpRenameFile. This function replaces the original name with the new name passed to the function. The name of the file or directory can be relative to the current directory, or a fully qualified name.

To upload or place files on an FTP server, the application can use either FtpPutFile or FtpOpenFile (along with InternetWriteFile). FtpPutFile can be used if the file already exists locally, while FtpOpenFile and InternetWriteFile can be used if data needs to be written to a file on the FTP server.

To download or get files, the application can use either FtpGetFile or FtpOpenFile (with InternetReadFile). FtpGetFile is used to retrieve a file from an FTP server and store it locally, while FtpOpenFile and InternetReadFile can be used to control where the downloaded information is going (for example, it could be used to display the information in an edit box).

Deleting files on an FTP server is done by using the FtpDeleteFile function. This function removes a file name that is either relative to the current directory or a fully qualified file name from the FTP server. FtpDeleteFile requires an FTP session handle returned by InternetConnect.

FTP Function Handles

The FTP functions require certain types of HINTERNET handles to work properly. These handles must be created in a set order, starting with the root handle created by InternetOpen. InternetConnect can then create an FTP session handle.

The following diagram shows the FTP functions that are dependent on the FTP session handle returned by InternetConnect. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

FTP functions dependent on FTP session handle returned by InternetConnect

The following diagram shows the two FTP functions that return HINTERNET handles and the functions that are dependent on the HINTERNET handles created by them. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

FTP functions that return HINTERNET handles

For more information about HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

Using the Win32 Internet Functions for FTP Sessions

The following Win32 Internet functions are used during FTP sessions. These functions are not recognized by CERN proxies. Applications that must function through CERN proxies should use InternetOpenUrl and access the resources directly. For more information on direct resource access, see Accessing URLs directly.
Function | Description
FtpCreateDirectory | Creates a new directory on the server. This function requires a handle created by InternetConnect.
FtpDeleteFile | Deletes a file from the server. This function requires a handle created by InternetConnect.
FtpFindFirstFile | Starts file enumeration or file search in the current directory. This function requires a handle created by InternetConnect.
FtpGetCurrentDirectory | Returns the client's current directory on the server. This function requires a handle created by InternetConnect.
FtpGetFile | Retrieves a file from the server. This function requires a handle created by InternetConnect.
FtpOpenFile | Initiates access to a file on the server for either reading or writing. This function requires a handle created by InternetConnect.
FtpPutFile | Writes a file to the server. This function requires a handle created by InternetConnect.
FtpRemoveDirectory | Deletes a directory on the server. This function requires a handle created by InternetConnect.
FtpRenameFile | Renames a file on the server. This function requires a handle created by InternetConnect.
FtpSetCurrentDirectory | Changes the client's current directory on the server. This function requires a handle created by InternetConnect.
InternetWriteFile | Writes data to an open file on the server. This function requires a handle created by FtpOpenFile.

Starting an FTP session

The application establishes an FTP session by calling InternetConnect on a handle created by InternetOpen. InternetConnect needs the server name, FTP port number, user name, password, and service type (which must be set to INTERNET_SERVICE_FTP). For passive FTP semantics, the application must also set the INTERNET_FLAG_PASSIVE flag.

The INTERNET_DEFAULT_FTP_PORT and INTERNET_INVALID_PORT_NUMBER values can be used for the FTP port number. INTERNET_DEFAULT_FTP_PORT uses the default FTP port, but the service type still must be set. INTERNET_INVALID_PORT_NUMBER uses the default value for the indicated service type.

The values for the user name and password can be set to NULL. If both values are set to NULL, InternetConnect uses "anonymous" for the user name, and the user's e-mail address for the password. If only the password is set to NULL, the user name passed to InternetConnect is used for the user name, and an empty string is used for the password. If both values are not NULL, the user name and password given to InternetConnect are used.

Enumerating directories

Enumeration of a directory on an FTP server requires the creation of a handle by FtpFindFirstFile. This handle is a branch of the FTP session handle created by InternetConnect. FtpFindFirstFile locates the first file or directory on the server and returns it in a WIN32_FIND_DATA structure. Use InternetFindNextFile until it returns ERROR_NO_MORE_FILES. This method finds all subsequent files and directories on the server. For more information on InternetFindNextFile, see Finding the next file.

To determine if the file retrieved by FtpFindFirstFile or InternetFindNextFile is a directory, check the dwFileAttributes member of the WIN32_FIND_DATA structure to see if it is equal to FILE_ATTRIBUTE_DIRECTORY.

If the application makes changes on the FTP server or if the FTP server undergoes changes frequently, the INTERNET_FLAG_NO_CACHE_WRITE and INTERNET_FLAG_RELOAD flags should be set in FtpFindFirstFile. These flags ensure that the directory information being retrieved from the FTP server is current.

After the application completes the directory enumeration, a call to InternetCloseHandle must be made on the handle created by FtpFindFirstFile. Until that handle is closed, the application cannot call FtpFindFirstFile again on the session handle created by InternetConnect. If a call to FtpFindFirstFile is made on the same session handle before the previous call to the same function is closed, the function fails, returning ERROR_FTP_TRANSFER_IN_PROGRESS.

The following example displays the contents of an FTP directory in the list box, IDC_FTPList. The HINTERNET handle, hSecondary, is a handle returned by the InternetConnect function after it establishes an FTP session.

int WINAPI DisplayDir(HWND hX, DWORD dwFlags)
{
    WIN32_FIND_DATA pDirInfo;
    HINTERNET hDir;
    DWORD dError;
    char DirList[MAX_PATH];
    DWORD dwTemp=MAX_PATH;
    LPDWORD temp =&dwTemp;
    LPVOID lpOption;
    DWORD dwSize;
    LPDWORD lpdwSize = &dwSize;

SendDlgItemMessage(hX,IDC_FTPList,LB_RESETCONTENT,0,0);
    if ( !(hDir = FtpFindFirstFile (hSecondary, TEXT ("*.*"), &pDirInfo,
        dwFlags, 0) ))
        if (GetLastError()  == ERROR_NO_MORE_FILES)
        {
            MessageBox(hX,"There are no files here!!!","Display Dir",MB_OK);
            InternetCloseHandle(hDir);
            return 1;
        }
        else
        {
            ErrorOut (hX, GetLastError (), "FindFirst error: ");
            InternetCloseHandle(hDir);
            return 0;
        }

        sprintf(DirList, pDirInfo.cFileName);
        if (pDirInfo.dwFileAttributes == FILE_ATTRIBUTE_DIRECTORY)
            strcat(DirList," <DIR> ");

        SendDlgItemMessage(hX,IDC_FTPList,LB_ADDSTRING,0,(LPARAM)DirList);

    dError = NO_ERROR;
    do
    {
         if (!InternetFindNextFile (hDir, &pDirInfo))
         {
             dError = GetLastError();
             if ( dError == ERROR_NO_MORE_FILES )
             {
                 InternetCloseHandle(hDir);
                 return 1;
             }
             else
             {
                 ErrorOut (hX,GetLastError(), "InternetFindNextFile");
                 InternetCloseHandle(hDir);
                 return 0;
             }
         }
         else
         {
            sprintf(DirList, pDirInfo.cFileName);
            if (pDirInfo.dwFileAttributes == FILE_ATTRIBUTE_DIRECTORY)
                strcat(DirList," <DIR> ");
            SendDlgItemMessage(hX,IDC_FTPList,LB_ADDSTRING,0,
                (LPARAM)DirList);
         }
    }
    while ( TRUE);

    if (!InternetCloseHandle(hDir) )
    {
        InternetCloseHandle(hDir);
        ErrorOut (hX,GetLastError(), "InternetCloseHandle error");
        return 0;
    }
    else
        return 1;

}

Navigating directories

The Win32 Internet functions FtpGetCurrentDirectory and FtpSetCurrentDirectory handle directory navigation.

FtpGetCurrentDirectory returns the application's current directory on the FTP server. The directory path from the root directory on the FTP server is included.

FtpSetCurrentDirectory changes the working directory on the server. The directory information passed to FtpSetCurrentDirectory can be either a partially or fully qualified path name relative to the current directory. For example, if the application is currently in the directory "public/info" and the path is "ftp/example", FtpSetCurrentDirectory changes the current directory to "public/info/ftp/example".

The following example uses an FTP session handle, hSecondary, returned by InternetConnect. The new directory name is stored in the edit box, IDC_FTPEdit2. Before the actual change is made, the function gets the current directory and stores it in the same edit box. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI ChangeDir(HWND hX)
{
    DWORD testsz = 320;
    LPSTR lpszUrlBuffer;            // buffer to hold the URL
    LPSTR lpszDirList;

    lpszUrlBuffer = new char[testsz];
    GetDlgItemText(hX,IDC_FTPEdit2,(LPSTR)lpszUrlBuffer,testsz);
    lpszDirList = new char[testsz];
    if (!FtpGetCurrentDirectory(hSecondary,(LPSTR)lpszDirList,&testsz))
    {
        ErrorOut(hX,GetLastError(),"Change Dir");
    }
    else
        SetDlgItemText(hX,IDC_FTPEdit2,(LPSTR)lpszDirList);

    delete(lpszDirList);

    if (!(FtpSetCurrentDirectory(hSecondary,lpszUrlBuffer)))
    {
        ErrorOut(hX,GetLastError(),"InternetConnect");
        delete(lpszUrlBuffer);
        SetDlgItemText(hX,IDC_FTPEdit2,(LPSTR)lpszUrlBuffer);
        DisplayDir(hX,INTERNET_FLAG_RELOAD);
        return 0;
    }
    else
    {
        delete(lpszUrlBuffer);
        return DisplayDir(hX,0);
    }
}

Manipulating directories on an FTP server

The Win32 Internet functions provide the capability to create and remove directories on an FTP server to which the application has the necessary privileges. If the application must log on to a server with a specific user name and password, the values can be used in InternetConnect when creating the FTP session handle.

The FtpCreateDirectory function takes a valid FTP session handle and a NULL-terminated string that contains either a fully qualified path or a name relative to the current directory and creates a directory on the FTP server.

The following example shows two separate calls to FtpCreateDirectory. In both examples, hFtpSession is the session handle created by the InternetConnect function, and the root directory is the current directory.

FtpCreateDirectory(hFtpSession, "test");
/* this will create the directory "test" in the current directory
    (which is the root directory) */

FtpCreateDirectory(hFtpSession, "\test\example");
/* this will create the directory "example" in the test directory */

The FtpRemoveDirectory function takes a valid FTP session handle and a NULL-terminated string that contains either a fully qualified path or a name relative to the current directory and removes that directory from the FTP server.

The following example shows two sample calls to FtpRemoveDirectory. In both calls, hFtpSession is the session handle created by the InternetConnect function, and the root directory is the current directory. There is a directory called "test" in the root directory and a directory called "example" in the "test" directory.

FtpRemoveDirectory(hFtpSession,"\test\example");
/* removes the "example" directory and any files or directories contained in it
    from the "test" directory */

FtpRemoveDirectory(hFtpSession, "test");
/* removes the "test" directory and any files or directories contained in it
    from the root directory */

The following example creates the directory indicated by the string stored in the edit box, IDC_FTPEdit2. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI CreateDir(HWND hX)
{
    char strInFile[80];

    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if (strlen(strInFile)==0)
    {
        MessageBox(hX,"Directory Name Must Be Specified","Create Dir",MB_OK);
        return 0;
    }
    else
    {
        if(!FtpCreateDirectory(hSecondary,strInFile))
        {
            ErrorOut(hX,GetLastError(),"Create Dir");
            return 0;
        }
        else
        {
            return DisplayDir(hX,INTERNET_FLAG_RELOAD);
        }
    }
}

The following example deletes the directory indicated by the edit box, IDC_FTPEdit2. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI RemoveDir(HWND hX)
{
    char strInFile[80];

    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if (strlen(strInFile)==0)
    {
        MessageBox(hX,"Directory Name Must Be Specified!","Remove Dir",MB_OK);
        return 0;
    }
    else
    {
        if(!FtpRemoveDirectory(hSecondary,strInFile))
        {
            ErrorOut(hX,GetLastError(),"Remove Dir");
            return 0;
        }
        else
        {
            MessageBox(hX,"Directory Deleted", "Remove Dir", MB_OK);
            return DisplayDir(hX,INTERNET_FLAG_RELOAD);
        }
    }
}

Getting files on an FTP server

The Win32 Internet functions offer three methods for retrieving files from an FTP server:

  • Using InternetOpenUrl and InternetReadFile.
  • Using FtpOpenFile and InternetReadFile.
  • Using FtpGetFile.

For more information about using the InternetReadFile function, see Reading files.

If the URL of the file is available, the application can call InternetOpenUrl to connect to that URL and then use InternetReadFile to control the download of the file. This setup allows the application to control the download more tightly and is ideal for situations where no other operations need to be made on the FTP server. For more information on how to directly access resources, see Accessing URLs directly.

If the application has established an FTP session handle to the server with InternetConnect, the application can call FtpOpenFile with the existing file name and with a new name for the locally stored file. The application can then use InternetReadFile to download the file. This allows the application to control the download more tightly and keep the connection to the FTP server, so more commands can be executed.

If the application does not need to tightly control the download, the application can use FtpGetFile with the FTP session handle, remote file name, and local file name to retrieve the file. FtpGetFile performs all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally.

The following example retrieves the file indicated by the IDC_FTPEdit2 edit box and stores it locally using the file name specified by the IDC_FTPEdit3 edit box. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI GetFile(HWND hX)
{
    char strInFile[80];
    char strOutFile[80];
    int intTransType;

    GetDlgItemText(hX,IDC_FTPEdit3,strOutFile,80);
    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if ((strlen(strOutFile)==0) | (strlen(strInFile)==0))
    {
        MessageBox(hX,"Target File or Destination File Missing","Get File",
            MB_OK);
        return 0;
    }
    else
    {
        intTransType = MessageBox(hX,
            "Do you want to download in ASCII (Default:Binary)?",
            "Get File",MB_YESNO);
        if (intTransType==IDYES)
        {
            if(!FtpGetFile(hSecondary,strInFile,strOutFile,FALSE,
                FILE_ATTRIBUTE_NORMAL,FTP_TRANSFER_TYPE_ASCII |
                INTERNET_FLAG_NO_CACHE_WRITE,0))
            {
                ErrorOut(hX,GetLastError(),"Get File");
                DisplayDir(hX,INTERNET_FLAG_RELOAD);
                return 0;
            }
            else
            {
                MessageBox(hX,"ASCII Transfer Complete","Get File",MB_OK);
                return 1;
            }
        }
        else
        {
            if(!FtpGetFile(hSecondary,strInFile,strOutFile,FALSE,
                FILE_ATTRIBUTE_NORMAL, FTP_TRANSFER_TYPE_BINARY |
                INTERNET_FLAG_RELOAD,0))
            {
                ErrorOut(hX,GetLastError(),"Get File");
                return 0;
            }
            else
            {
                MessageBox(hX,"Binary Transfer Complete","Get File",MB_OK);
                return 1;
            }
        }
    }
}

Placing files on an FTP server

An application can use two methods to place a file on an FTP server using the Win32 Internet functions:

  • Use the FtpOpenFile function with the InternetWriteFile function.
  • Use FtpPutFile.

An application that must send data to an FTP server, but does not have a local file containing all the data, should use FtpOpenFile to create and open a file on the FTP server. The application then can use InternetWriteFile to upload the information to the file.

If the file already exists locally, the application can use FtpPutFile to upload the file to the FTP server. FtpPutFile performs all the overhead that goes with uploading a local file to a remote FTP server.

The following example places the file indicated by the IDC_FTPEdit2 edit box on the FTP server, using the file name specified by the IDC_FTPEdit3 edit box. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session.

int WINAPI PutFile(HWND hX)
{
    char strInFile[80];
    char strOutFile[80];
    int intTransType;

    GetDlgItemText(hX,IDC_FTPEdit3,strOutFile,80);
    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if ((strlen(strOutFile)==0) | (strlen(strInFile)==0))
    {
        MessageBox(hX,"Target File or Destination File Missing","Put File", MB_OK);
        return 0;
    }
    else
    {
        intTransType = MessageBox(hX,
            "Do you want to upload in ASCII (Default:Binary)?",
            "Put File",MB_YESNO);

        if (intTransType==IDYES)
        {
            if(!FtpPutFile(hSecondary,strInFile,strOutFile,
                FTP_TRANSFER_TYPE_ASCII,0))
            {
                ErrorOut(hX,GetLastError(),"Get File");
                return 0;
            }
            else
            {
                MessageBox(hX,"ASCII Transfer Complete","Put File",MB_OK);
                return 1;
            }
        }
        else
        {
            if(!FtpPutFile(hSecondary,strInFile,strOutFile,
                FTP_TRANSFER_TYPE_BINARY,0))
            {
                ErrorOut(hX,GetLastError(),"Get File");
                return 0;
            }
            else
            {
                MessageBox(hX,"Binary Transfer Complete","Get File",MB_OK);
                DisplayDir(hX,INTERNET_FLAG_RELOAD);
                return 1;
            }
        }
    }
}

Deleting files from an FTP server

To delete a file from an FTP server, an application can use the FtpDeleteFile function. The calling application must have the necessary privileges specified to delete a file from the FTP server when InternetConnect creates the FTP session handle.

The following example deletes the file indicated by the IDC_FTPEdit2 edit box. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI DeleteFile(HWND hX)
{
    char strInFile[80];

    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if (strlen(strInFile)==0)
    {
        MessageBox(hX,"File Name Must Be Specified!","Remove Dir",MB_OK);
        return 0;
    }
    else
    {
        if(!FtpDeleteFile(hSecondary,strInFile))
        {
            ErrorOut(hX,GetLastError(),"Remove Dir");
            return 0;
        }
        else
        {
            MessageBox(hX,"File Deleted", "Remove Dir", MB_OK);
            return DisplayDir(hX,INTERNET_FLAG_RELOAD);
        }
    }
}

Renaming files and directories on an FTP server

Renaming files and directories on an FTP server can be performed by using the FtpRenameFile function. FtpRenameFile accepts two NULL-terminated strings that contain either partially or fully qualified names relative to the current directory and then renames the file designated by the first string to the name in the second string.

The following example renames the file or directory indicated by the IDC_FTPEdit2 edit box. The HINTERNET handle, hSecondary, was created by InternetConnect after establishing an FTP session. DisplayDir is another function that is designed to enumerate the directory.

int WINAPI RenameFile(HWND hX)
{
    char strInFile[80];
    char strOutFile[80];

    GetDlgItemText(hX,IDC_FTPEdit3,strOutFile,80);
    GetDlgItemText(hX,IDC_FTPEdit2,strInFile,80);

    if ((strlen(strOutFile)==0) | (strlen(strInFile)==0))
    {
        MessageBox(hX,"Target File or Destination File Missing","Put File",MB_OK);
        return 0;
    }
    else
    {
        if(!FtpRenameFile(hSecondary,strInFile,strOutFile))
        {
            ErrorOut(hX,GetLastError(),"Get File");
            DisplayDir(hX,INTERNET_FLAG_RELOAD);
            return 0;
        }
        else
        {
            return DisplayDir(hX,INTERNET_FLAG_RELOAD);
        }
    }
}


Gopher Sessions

The Win32 Internet Gopher functions create and use Internet Gopher utilities to access information on Gopher servers worldwide.

Gopher functions, like the FTP functions, cannot be used through a CERN type proxy because CERN proxies recognize only HTTP. Applications that need to access a Gopher server through a CERN proxy should use InternetOpenUrl to access the resource directly. For more information on direct resource access, see Accessing URLs directly.

The following diagram shows the relationship of Win32 Internet functions used for the Gopher protocol. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Win32 Internet functions used for Gopher protocol

For more information on HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

Using the Win32 Internet Functions for Gopher Sessions

The following Win32 Internet functions are used during Gopher sessions. These functions are not recognized by CERN proxies. Applications that must function through CERN type proxies should use InternetOpenUrl and access the resources directly. For more information on direct resource access, see Accessing URLs directly.
Function | Description
GopherAttributeEnumerator | Defines a callback function that processes attribute information from a Gopher server.
GopherCreateLocator | Forms a Gopher locator for use in other Gopher function calls.
GopherFindFirstFile | Starts enumerating a Gopher directory listing. This function requires a handle created by InternetConnect.
GopherGetAttribute | Retrieves attribute information on the Gopher object. This function requires a handle created by InternetConnect.
GopherGetLocatorType | Parses a Gopher locator and determines its attributes.
GopherOpenFile | Starts retrieving a Gopher object. This function requires a handle created by InternetConnect.

Creating locators

The Win32 Internet function GopherCreateLocator allows applications to create Gopher locators.

This function accepts the host address, server port used by the host, display string, selector string, Gopher type, address of the buffer that stores the locator, and the buffer length. If the buffer address is set to NULL, the buffer length needed to store the locator is stored in the buffer length variable. If the buffer size is insufficient, the function fails. The GetLastError function returns ERROR_INSUFFICIENT_BUFFER and stores the necessary length in the buffer length variable.

The display string contains the Gopher document or directory to be displayed. If this parameter is NULL, the function returns the default directory for the Gopher server.

The selector string contains the information that the application is searching for in the Gopher server. This parameter can be set to NULL.

Gopher types define the resource type the selector string is looking for; they can also define whether this is a Gopher or Gopher+ request. The following values are valid Gopher types:
GOPHER_TYPE_ASK | Ask+ item.
GOPHER_TYPE_BINARY | Binary file.
GOPHER_TYPE_BITMAP | Bitmap file.
GOPHER_TYPE_CALENDAR | Calendar file.
GOPHER_TYPE_CSO | CSO telephone book server.
GOPHER_TYPE_DIRECTORY | Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE | MS-DOS® archive file.
GOPHER_TYPE_ERROR | Error condition indicator.
GOPHER_TYPE_GIF | GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS | Gopher+ item.
GOPHER_TYPE_HTML | HTML document.
GOPHER_TYPE_IMAGE | Image file.
GOPHER_TYPE_INDEX_SERVER | Index server.
GOPHER_TYPE_INLINE | Inline file.
GOPHER_TYPE_MAC_BINHEX | Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE | Movie file.
GOPHER_TYPE_PDF | PDF file.
GOPHER_TYPE_REDUNDANT | Duplicated server indicator. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND | Sound file.
GOPHER_TYPE_TELNET | Telnet server.
GOPHER_TYPE_TEXT_FILE | ASCII text file.
GOPHER_TYPE_TN3270 | TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED | UUENCODED file.
GOPHER_TYPE_UNKNOWN | Unknown item type.

Enumerating directories

Enumeration of a directory on a Gopher server requires the creation of an HINTERNET handle by GopherFindFirstFile. This handle is a branch of the Gopher session handle created by InternetConnect. GopherFindFirstFile locates the first file or directory on the server and returns it in a GOPHER_FIND_DATA structure. Use InternetFindNextFile until it fails, returning ERROR_NO_MORE_FILES. This method finds all subsequent files and directories on the server. For more information on InternetFindNextFile, see Finding the Next File.

To determine the resource type retrieved by GopherFindFirstFile or InternetFindNextFile, check the GopherType member of the GOPHER_FIND_DATA structure. The following values are valid Gopher types:
GOPHER_TYPE_ASK | Ask+ item.
GOPHER_TYPE_BINARY | Binary file.
GOPHER_TYPE_BITMAP | Bitmap file.
GOPHER_TYPE_CALENDAR | Calendar file.
GOPHER_TYPE_CSO | CSO telephone book server.
GOPHER_TYPE_DIRECTORY | Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE | MS-DOS® archive file.
GOPHER_TYPE_ERROR | Error condition indicator.
GOPHER_TYPE_GIF | GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS | Gopher+ item.
GOPHER_TYPE_HTML | HTML document.
GOPHER_TYPE_IMAGE | Image file.
GOPHER_TYPE_INDEX_SERVER | Index server.
GOPHER_TYPE_INLINE | Inline file.
GOPHER_TYPE_MAC_BINHEX | Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE | Movie file.
GOPHER_TYPE_PDF | PDF file.
GOPHER_TYPE_REDUNDANT | Duplicated server indicator. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND | Sound file.
GOPHER_TYPE_TELNET | Telnet server.
GOPHER_TYPE_TEXT_FILE | ASCII text file.
GOPHER_TYPE_TN3270 | TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED | UUENCODED file.
GOPHER_TYPE_UNKNOWN | Unknown item type.

Downloading Gopher resources

The Win32 Internet functions GopherOpenFile and InternetReadFile allow applications to download a Gopher resource.

To begin downloading a resource, GopherOpenFile must create an HINTERNET handle off the Gopher session handle returned by InternetConnect. After the handle is created, InternetReadFile can be used to download the resource. For more information on using InternetReadFile, see Reading files.


HTTP Sessions

The Win32 Internet functions allow you to access resources on the World Wide Web (WWW). These resources can be accessed directly by using InternetOpenUrl (for more information, see Accessing URLs directly) or the HTTP functions.

Resources on the WWW are accessed by using HTTP. The Win32 Internet functions include a set of stable HTTP functions that handle the underlying protocols, while allowing your application to access information on the WWW. As the HTTP protocol evolves, the underlying protocols will be updated to maintain HTTP function behavior.

The following diagram shows the relationships of the Win32 Internet functions that are used for the HTTP protocol. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Win32 Internet functions used for HTTP

For more information on HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.

Using the Win32 Internet Functions to Access the WWW

The following functions are used during HTTP sessions to access the WWW.
Function | Description
HttpAddRequestHeaders | Adds HTTP request headers to the HTTP request handle. This function requires a handle created by HttpOpenRequest.
HttpOpenRequest | Opens an HTTP request handle. This function requires a handle created by InternetConnect.
HttpQueryInfo | Queries information about an HTTP request. This function requires a handle created by the HttpOpenRequest or InternetOpenUrl function.
HttpSendRequest | Sends the specified HTTP request to the HTTP server. This function requires a handle created by HttpOpenRequest.
InternetErrorDlg | Displays predefined dialog boxes for common Internet error conditions. This function requires the handle used in the call to HttpSendRequest.

Initiating a connection to the WWW

To start a connection to the WWW, the application must call the InternetConnect function on the root HINTERNET returned by InternetOpen. InternetConnect must establish an HTTP session by declaring the INTERNET_SERVICE_HTTP service type. For more information on using InternetConnect, see Using InternetConnect.

Opening a request

The HttpOpenRequest function opens an HTTP request and returns an HINTERNET handle that can be used by the other HTTP functions. Unlike the other open functions (such as FtpOpenFile and InternetOpenUrl), HttpOpenRequest does not send the request to the Internet when called. The HttpSendRequest function sends the request and establishes a connection over the network.

HttpOpenRequest takes an HTTP session handle created by InternetConnect and a verb, object name, version string, referrer, accept types, flags, and context value.

The verb is a string to be used in the request. Common verbs used in requests include "GET", "PUT", and "POST". If this value is set to NULL, HttpOpenRequest uses the default value "GET".

The object name is a string that contains the name of the specified verb's target object. This is generally a file name, an executable module, or a search specifier. If the object name supplied is an empty string, HttpOpenRequest looks for the default page.

The version string should contain the HTTP version. If this parameter is set to NULL, the function uses "HTTP/1.0".

The referrer specifies the address of the document from which the object name was obtained. If this parameter is NULL, no referrer is specified.

The NULL-terminated string containing the accept types indicates the content types accepted by the application. Setting this parameter to NULL indicates that no content types are accepted by the application. If an empty string is supplied, the application is indicating it accepts only documents of type "text/*". The value "text/*" indicates text-only documents—not pictures or other binary files.

The flag values control caching, cookies, and security issues. For Microsoft Network (MSN), NTLM, and other types of authentication, set the INTERNET_FLAG_KEEP_CONNECTION flag.

If the INTERNET_FLAG_ASYNC flag was set in the call to InternetOpen, a nonzero context value should be set for proper asynchronous operation.

The following example is a sample call to HttpOpenRequest.

hHttpRequest = HttpOpenRequest(hHttpSession, "GET", "", NULL, "", NULL, 0,0);

Adding request headers

The Win32 Internet function HttpAddRequestHeaders allows applications to add one or more request headers to the initial request. This function allows an application to append additional free-format headers to the HTTP request handle; it is intended for use by sophisticated applications that need precise control over the request sent to the HTTP server.

HttpAddRequestHeaders needs an HTTP request handle created by HttpOpenRequest, a string containing the headers, the length of the headers, and modifiers.

The following modifiers can be used with HttpAddRequestHeaders:
HTTP_ADDREQ_FLAG_ADD | Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW | Adds the header only if it does not already exist; otherwise, an error is returned.
HTTP_ADDREQ_FLAG_COALESCE | Coalesces headers of the same name.
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA | Coalesces headers of the same name. For example, adding "Accept: text/*" followed by "Accept: audio/*" with this flag forms the single header "Accept: text/*, audio/*", causing the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON | Coalesces headers of the same name, using a semicolon.
HTTP_ADDREQ_FLAG_REPLACE | Replaces or removes a header. If the header value is empty and the header is found, it is removed. If the header value is not empty, the header value is replaced.

Sending a request

HttpSendRequest establishes a connection to the Internet and sends the request to the specified site. This function requires an HINTERNET handle created by HttpOpenRequest. HttpSendRequest can also send additional headers or optional information. The optional information is generally used for operations that write information to the server, such as PUT and POST.

After HttpSendRequest sends the request, the application can use the InternetReadFile, InternetQueryDataAvailable, and InternetSetFilePointer functions on the HINTERNET handle created by HttpOpenRequest to download the server's resources.

Posting data to the server

To post data to a server, the verb in the call to HttpOpenRequest must be either "POST" or "PUT". The address of the buffer containing the POST data should then be passed to the lpOptional parameter in HttpSendRequest. The dwOptionalLength parameter should be set to the size of the data.

Using the Microsoft Internet Explorer 4.0 version of WinInet, you can also use the InternetWriteFile function to post data on an HINTERNET handle sent using HttpSendRequestEx.

Getting information about a request

HttpQueryInfo allows an application to retrieve information about an HTTP request. The function requires an HINTERNET handle created by HttpOpenRequest or InternetOpenUrl, an information level value, and a buffer length. HttpQueryInfo also accepts a buffer that stores the information and a zero-based header index that enumerates multiple headers with the same name.

The following information level values can be used with a modifier to control the format in which the information is stored in lpvBuffer:
HTTP_QUERY_ALLOW | Receives the methods supported by the server.
HTTP_QUERY_CONTENT_DESCRIPTION | Receives the content description.
HTTP_QUERY_CONTENT_ID | Receives the content identification.
HTTP_QUERY_CONTENT_LENGTH | Receives the size of the resource in bytes.
HTTP_QUERY_CONTENT_TRANSFER_ENCODING | Receives the additional content coding that has been applied to the resource.
HTTP_QUERY_CONTENT_TYPE | Receives the content type of the resource (such as text/html).
HTTP_QUERY_DATE | Receives the date and time at which the message was originated.
HTTP_QUERY_EXPIRES | Receives the date and time after which the resource should be considered outdated.
HTTP_QUERY_LAST_MODIFIED | Receives the date and time at which the server believes the resource was last modified.
HTTP_QUERY_MIME_VERSION | Receives the version of the MIME protocol that was used to construct the message.
HTTP_QUERY_PRAGMA | Receives the implementation-specific directives that might apply to any recipient along the request/response chain.
HTTP_QUERY_PUBLIC | Receives the methods available from this server.
HTTP_QUERY_RAW_HEADERS | Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.
HTTP_QUERY_RAW_HEADERS_CRLF | Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.
HTTP_QUERY_REQUEST_METHOD | Receives the verb that is being used in the request, typically GET or POST.
HTTP_QUERY_STATUS_CODE | Receives the status code returned by the server.
HTTP_QUERY_STATUS_TEXT | Receives any additional text returned by the server on the response line.
HTTP_QUERY_URL | Receives some or all of the URLs by which the Request-URL resource can be identified.
HTTP_QUERY_VERSION | Receives the last response code returned by the server.

The following modifiers can be used with the information values:
HTTP_QUERY_CUSTOM | Causes HttpQueryInfo to search for the ASCIIZ header name specified in lpvBuffer and store the header information in lpvBuffer.
HTTP_QUERY_FLAG_COALESCE | Combines the values from headers with the same name into the output buffer.
HTTP_QUERY_FLAG_NUMBER | Returns the data as a 32-bit number for headers whose value is a number, such as the status code.
HTTP_QUERY_FLAG_REQUEST_HEADERS | Queries request headers only.
HTTP_QUERY_FLAG_SYSTEMTIME | Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".
HTTP_QUERY_INFO_NUMBER | Sets the data type returned by HttpQueryInfo to a DWORD.

Downloading resources from the WWW

After opening a request with HttpOpenRequest and sending it to the server with HttpSendRequest, the application can use the InternetReadFile, InternetQueryDataAvailable, and InternetSetFilePointer functions to download the resource from the HTTP server.

The following example downloads a resource. The function accepts the handle to the current window, the identification number of an edit box, and an HINTERNET handle created by HttpOpenRequest and sent by HttpSendRequest. It uses InternetQueryDataAvailable to determine the size of the resource and then downloads it using InternetReadFile. The contents are then displayed in the edit box.

int WINAPI Dumper(HWND hX, int intCtrlID, HINTERNET hResource)
{
     LPSTR     lpszData;          // buffer for the data
     DWORD     dwSize;               // size of the data available
     DWORD     dwDownloaded;     // size of the downloaded data
     DWORD     dwSizeSum=0;     // size of the data in the textbox
     LPSTR     lpszHolding;     // buffer to merge the textbox data and buffer

     // Set the cursor to an hourglass.
     SetCursor(LoadCursor(NULL,IDC_WAIT));

     // This loop handles reading the data.
     do
     {
          // The call to InternetQueryDataAvailable determines the amount of
          // data available to download.
          if (!InternetQueryDataAvailable(hResource,&dwSize,0,0))
          {
               ErrorOut(hX,GetLastError(),"InternetReadFile");
               SetCursor(LoadCursor(NULL,IDC_ARROW));
               return FALSE;
          }
          else
          {
               // Allocates a buffer of the size returned by InternetQueryDataAvailable
               lpszData = new char[dwSize+1];

               // Reads the data from the HINTERNET handle.
               if(!InternetReadFile(hResource,(LPVOID)lpszData,dwSize,&dwDownloaded))
               {
                    ErrorOut(hX,GetLastError(),"InternetReadFile");
                    delete[] lpszData;
                    break;
               }
               else
               {
                    // Adds a null terminator to the end of the data buffer
                    lpszData[dwDownloaded]='\0';

                    // Allocates the holding buffer
                    lpszHolding = new char[dwSizeSum + dwDownloaded + 1];

                    // Checks if there has been any data written to the textbox
                    if (dwSizeSum != 0)
                    {
                         // Retrieves the data stored in the textbox if any
                         GetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding,dwSizeSum);

                         // Adds a null terminator at the end of the textbox data
                         lpszHolding[dwSizeSum]='\0';
                    }
                    else
                    {
                         // Make the holding buffer an empty string.
                         lpszHolding[0]='\0';
                    }

                    // Adds the new data to the holding buffer
                    strcat(lpszHolding,lpszData);

                    // Writes the holding buffer to the textbox
                    SetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding);

                    // Delete the two buffers
                    delete[] lpszHolding;
                    delete[] lpszData;

                    // Add the size of the downloaded data to the textbox data size
                    dwSizeSum = dwSizeSum + dwDownloaded + 1;

                    // Check the size of the remaining data.  If it is zero, break.
                    if (dwDownloaded == 0)
                         break;
               }
          }
     }
     while(TRUE);

     // Close the HINTERNET handle
     InternetCloseHandle(hResource);

     // Set the cursor back to an arrow
     SetCursor(LoadCursor(NULL,IDC_ARROW));

     // Return
     return TRUE;
}


Cookie Functions

Under HTTP protocol, a server or a script uses cookies to maintain state information on the client workstation. The Win32 Internet functions have implemented a persistent cookie database for this purpose. The Win32 Internet cookie functions are used to set cookies into and access cookies from the cookie database.

The Win32 Internet functions InternetSetCookie and InternetGetCookie manipulate cookies. The caller of these functions should be familiar with cookies as outlined in ftp://ds.internic.net/internet-drafts/draft-ietf-http-state-mgmt-*.txt. Please note that the implementation of these functions is evolving; be cautious when using them.

Using Cookie Functions

Two functions allow an application to create or retrieve cookies in the cookie database.
Function | Description
InternetGetCookie | Returns cookies for the specified URL and all its parent URLs.
InternetSetCookie | Sets a cookie on the specified URL.

Getting a cookie

InternetGetCookie returns the cookies for the specified URL and all its parent URLs.

No call to InternetOpen is required to use this function. InternetGetCookie looks for cookies with no expiration dates in the windows\cookies directory and searches for unexpired cookies that are not written to any files in memory.

Setting a cookie

InternetSetCookie sets a cookie on the specified URL.


Caching

The Win32 Internet functions have simple, yet flexible, built-in caching support. Any data retrieved from the network is cached on the hard disk and retrieved for subsequent requests. The application using the Win32 Internet functions can control the caching on each request. For HTTP requests from the server, most headers received are also cached. When an HTTP request is satisfied from the cache, the cached headers are also returned to the caller. This makes data download from Win32 Internet functions seamless, whether it is coming from the cache or from the network.

Unlike previous versions of the Win32 Internet functions, the current and future versions do not have an upper limit on the cache entry size. Applications must properly allocate a buffer in order to get the desired results when using the persistent URL caching functions. For more information, see Appendix B: Using Buffers.

Using Flags to Control Caching

The Win32 Internet function flags allow an application to control when and how it uses the cache. These flags can be used alone or in combination with the dwFlags parameter in functions that access information or resources on the Internet. The Win32 Internet functions store all data downloaded from the Internet by default.

The following flags can be used with the Win32 Internet functions to control caching:
INTERNET_FLAG_DONT_CACHE | Does not cache the data, either locally or in any gateways. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK | Forces the application to reload a resource if no expire time and no last-modified time was returned when the resource was stored in the cache.
INTERNET_FLAG_MAKE_PERSISTENT | No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST | Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE | Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE | Rejects any attempt by the function to store data downloaded from the Internet in the cache. This flag is necessary if the application does not want any downloaded resources to be stored locally.
INTERNET_FLAG_OFFLINE | Prevents the application from making requests to the network. All requests are resolved using the resources stored in the cache. If the resource is not in the cache, a suitable error, such as ERROR_FILE_NOT_FOUND, is returned.
INTERNET_FLAG_RELOAD | Forces the function to retrieve the requested resource directly from the Internet. The information that is downloaded is stored in the cache.
INTERNET_FLAG_RESYNCHRONIZE | Causes an application to perform a conditional download of the resource from the Internet. If the version stored in the cache is current, the information is downloaded from the cache. Otherwise, the information is reloaded from the server.

Persistent Caching Functions

Clients that need persistent caching services use the persistent caching functions to allow their applications to save data in the local file system for subsequent use, such as in situations where a low-bandwidth link limits access to the data, or the access is not available at all. The calling program that inserts data into the persistent cache assigns a source name that is used to perform operations, including retrieving, setting and getting some properties, and deleting the data.

The Win32 Internet function protocols use the cache functions to provide persistent caching and offline browsing. Unless the INTERNET_FLAG_NO_CACHE_WRITE flag explicitly specifies no caching, Win32 Internet functions cache all data downloaded from the network. The responses to POST data are not cached.

Using the Persistent URL Cache Functions

The following persistent URL cache functions allow an application to access and manipulate information stored in the cache.
Function | Description
CommitUrlCacheEntry | Caches data in the specified file in the cache storage and associates it with the given URL.
CreateUrlCacheEntry | Allocates the requested cache storage and creates a local file name for saving the cache entry corresponding to the source name.
CreateUrlCacheGroup | Generates a cache group identification.
DeleteUrlCacheEntry | Removes the file associated with the source name from the cache, if the file exists.
DeleteUrlCacheGroup | Releases a GROUPID and any associated state in the cache index file.
FindCloseUrlCache | Closes the specified enumeration handle.
FindFirstUrlCacheEntry | Begins the enumeration of the cache.
FindFirstUrlCacheEntryEx | Begins a filtered enumeration of the cache.
FindNextUrlCacheEntry | Retrieves the next entry in the cache.
FindNextUrlCacheEntryEx | Retrieves the next entry in a filtered cache enumeration.
GetUrlCacheEntryInfo | Retrieves information about a cache entry.
GetUrlCacheEntryInfoEx | Searches for the URL after translating any cached redirections that would be applied in offline mode by HttpSendRequest.
ReadUrlCacheEntryStream | Reads the cached data from a stream that has been opened using RetrieveUrlCacheEntryStream.
RetrieveUrlCacheEntryFile | Retrieves a cache entry from the cache in the form of a file.
RetrieveUrlCacheEntryStream | Provides the most efficient and implementation-independent way of accessing the cache data.
SetUrlCacheEntryGroup | Adds or removes entries from a cache group.
SetUrlCacheEntryInfo | Sets the specified members of the INTERNET_CACHE_ENTRY_INFO structure.
UnlockUrlCacheEntryFile | Unlocks the cache entry that was locked while the file was retrieved for use from the cache.
UnlockUrlCacheEntryStream | Closes the stream that has been retrieved using RetrieveUrlCacheEntryStream.

Enumerating the cache

The FindFirstUrlCacheEntry and FindNextUrlCacheEntry functions enumerate the information stored in the cache. FindFirstUrlCacheEntry starts the enumeration by taking a search pattern, a buffer, and a buffer size to create a handle and return the first cache entry. FindNextUrlCacheEntry takes the handle created by FindFirstUrlCacheEntry, a buffer, and a buffer size to return the next cache entry.

Both functions store an INTERNET_CACHE_ENTRY_INFO structure in the buffer. The size of this structure varies for each entry. If the buffer size passed to either function is insufficient, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. The buffer size variable contains the buffer size that was needed to retrieve that cache entry. A buffer of the size indicated by the buffer size variable should be allocated, and the function should be called again with the new buffer.

The INTERNET_CACHE_ENTRY_INFO structure contains the structure size; URL of the cached information; local file name; cache entry type; use count; hit rate; size; last modified, expire, last access, and last synchronized times; header information and header information size; and file extension.

FindFirstUrlCacheEntry takes a search pattern, a buffer that stores the INTERNET_CACHE_ENTRY_INFO structure, and the buffer size. Currently, only the default search pattern, which returns all cache entries, is implemented.

After the cache is enumerated, the application should call FindCloseUrlCache to close the cache enumeration handle.

The following example displays the URL of each entry in the cache into a list box, IDC_CacheList. It uses MAX_CACHE_ENTRY_INFO_SIZE to initially allocate a buffer, since the Microsoft Internet Explorer 3.0 version of WinInet did not enumerate the cache properly otherwise. Internet Explorer 4.0 does enumerate the cache properly and there is no cache size limit. All applications that run on computers with the Internet Explorer 4.0 version of WinInet must allocate a buffer of the size required. For more information, see Appendix B: Using Buffers.

int WINAPI EnumerateCacheOld(HWND hX)
{
    DWORD dwEntrySize;
    LPINTERNET_CACHE_ENTRY_INFO lpCacheEntry;
    DWORD MAX_CACHE_ENTRY_INFO_SIZE=4096;
    HANDLE hCacheDir;
    int nCount=0;

    SendDlgItemMessage(hX,IDC_CacheList,LB_RESETCONTENT,0,0);

    SetCursor(LoadCursor(NULL,IDC_WAIT));

    dwEntrySize = MAX_CACHE_ENTRY_INFO_SIZE;
    lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) new char[dwEntrySize];
    lpCacheEntry->dwStructSize = dwEntrySize;

again:

    if (!(hCacheDir = FindFirstUrlCacheEntry(NULL,lpCacheEntry,&dwEntrySize)))
    {
        delete[]lpCacheEntry;
        switch(GetLastError())
        {
            case ERROR_NO_MORE_ITEMS:
                char tempout[80];
                sprintf(tempout,"The number of cache entries = %d \n",nCount);
                MessageBox(hX,tempout,"Cache Enumeration",MB_OK);
                FindCloseUrlCache(hCacheDir);
                SetCursor(LoadCursor(NULL,IDC_ARROW));
                return TRUE;
                break;
                        case ERROR_INSUFFICIENT_BUFFER:
                                lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO)
                                                new char[dwEntrySize];
                                lpCacheEntry->dwStructSize = dwEntrySize;
                                goto again;
                                break;
                        default:
                                ErrorOut(hX,GetLastError(),"FindNextUrlCacheEntry Init");
                                FindCloseUrlCache(hCacheDir);
                                SetCursor(LoadCursor(NULL,IDC_ARROW));
                                return FALSE;
                }
        }

SendDlgItemMessage(hX,IDC_CacheList,LB_ADDSTRING,
                                0,(LPARAM)(lpCacheEntry->lpszSourceUrlName));
        nCount++;
        delete (lpCacheEntry);

        do
        {
                dwEntrySize = MAX_CACHE_ENTRY_INFO_SIZE;
                lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) new char[dwEntrySize];
                lpCacheEntry->dwStructSize = dwEntrySize;

retry:
                if (!FindNextUrlCacheEntry(hCacheDir,lpCacheEntry, &dwEntrySize))
                {
                        delete[]lpCacheEntry;
                        switch(GetLastError())
                        {
                                case ERROR_NO_MORE_ITEMS:
                                        char tempout[80];
                                        sprintf(tempout,"The number of cache entries =
                                                %d \n",nCount);
                                        MessageBox(hX,tempout,"Cache Enumeration",MB_OK);
                                        FindCloseUrlCache(hCacheDir);
                                        return TRUE;
                                        break;
                                case ERROR_INSUFFICIENT_BUFFER:
                                        lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO)
                                                        new char[dwEntrySize];
                                        lpCacheEntry->dwStructSize = dwEntrySize;
                                        goto retry;
                                        break;
                                default:
                                        ErrorOut(hX,GetLastError(),"FindNextUrlCacheEntry Init");
                                        FindCloseUrlCache(hCacheDir);
                                        return FALSE;
                        }
                }

SendDlgItemMessage(hX,IDC_CacheList,LB_ADDSTRING,
                                        0,(LPARAM)(lpCacheEntry->lpszSourceUrlName));
                nCount++;
                delete[] lpCacheEntry;

        }
        while (TRUE);

        SetCursor(LoadCursor(NULL,IDC_ARROW));
        return TRUE;

}

Retrieving cache entry information

The GetUrlCacheEntryInfo function allows you to retrieve the INTERNET_CACHE_ENTRY_INFO structure for the specified URL. This structure contains the structure size; URL of the cached information; local file name; cache entry type; use count; hit rate; size; last modified, expire, last access, and last synchronized times; header information and header information size; and file extension.

GetUrlCacheEntryInfo accepts a URL, a buffer for an INTERNET_CACHE_ENTRY_INFO structure, and the buffer size. If the URL is found, the information is copied into the buffer. Otherwise, the function fails and GetLastError returns ERROR_FILE_NOT_FOUND. If the buffer size is insufficient to store the cache entry information, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. The size required to retrieve the information is stored in the buffer size variable.

GetUrlCacheEntryInfo does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

The following example retrieves the cache entry information for the specified URL. The function then displays the header information in the IDC_CacheDump edit box.

int WINAPI GetCacheEntryInfo(HWND hX,LPSTR lpszUrl)
{
        DWORD dwEntrySize=0;
        LPINTERNET_CACHE_ENTRY_INFO lpCacheEntry;

        char strTemp[80];
        DWORD dwTemp;

        SetCursor(LoadCursor(NULL,IDC_WAIT));
        if (!GetUrlCacheEntryInfo(lpszUrl,NULL,&dwEntrySize))
        {
                if (GetLastError()!=ERROR_INSUFFICIENT_BUFFER)
                {
                        ErrorOut(hX,GetLastError(),"GetUrlCacheEntryInfo");
                        SetCursor(LoadCursor(NULL,IDC_ARROW));
                        return FALSE;
                }
                else
                        lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO)
                                        new char[dwEntrySize];
        }
        else
                return FALSE;    //should not be successful w/ NULL buffer and 0 size.

        if (!GetUrlCacheEntryInfo(lpszUrl,lpCacheEntry,&dwEntrySize))
        {
                ErrorOut(hX,GetLastError(),"GetUrlCacheEntryInfo");
                SetCursor(LoadCursor(NULL,IDC_ARROW));
                return FALSE;
        }
        else
        {
                if ((lpCacheEntry->dwHeaderInfoSize)!=0)
                {
                        LPSTR(lpCacheEntry->lpHeaderInfo)[lpCacheEntry->dwHeaderInfoSize]='\0';
                        SetDlgItemText(hX,IDC_Headers,LPSTR(lpCacheEntry->lpHeaderInfo));
                }
                else
                {
                        SetDlgItemText(hX,IDC_Headers,"None");
                }

SetCursor(LoadCursor(NULL,IDC_ARROW));
                return TRUE;
        }

}

Creating a cache entry

An application uses the CreateUrlCacheEntry and CommitUrlCacheEntry functions to create a cache entry.

CreateUrlCacheEntry accepts the URL, expected file size, and file extension. The function then creates a local file name for saving the cache entry corresponding to the URL and file extension.

Using the local file name, write the data into the local file using standard C/C++ functions or Win32 functions. After the data has been written to the local file, the application should call CommitUrlCacheEntry.

CommitUrlCacheEntry accepts the URL; local file name; expire and last modified times; cache entry type; header information and header information size; and file extension. The function then caches data in the file specified in the cache storage and associates it with the given URL.

The following example uses the local file name, created by a previous call to CreateUrlCacheEntry, stored in the text box, IDC_LocalFile, to store the text from the text box, IDC_CacheDump, in the cache entry. After the data has been written to the file using fopen, fprintf, and fclose, the entry is committed using CommitUrlCacheEntry.

int WINAPI CommitEntry(HWND hX)
{
        LPSTR lpszUrl, lpszExt, lpszFileName;
        LPSTR lpszData,lpszSize;
        DWORD dwSize;
        DWORD dwEntryType=0;
        FILE *lpfCacheEntry;
        LPFILETIME lpdtmExpire, lpdtmLastModified;
        LPSYSTEMTIME lpdtmSysTime;

        if(SendDlgItemMessage(hX,IDC_RBNormal,BM_GETCHECK,0,0))
                dwEntryType = dwEntryType + NORMAL_CACHE_ENTRY;
        else
                if(SendDlgItemMessage(hX,IDC_RBStable, BM_GETCHECK,0,0))
                        dwEntryType = dwEntryType + STABLE_CACHE_ENTRY;
                else
                        if(SendDlgItemMessage(hX,IDC_RBSticky, BM_GETCHECK,0,0))
                                dwEntryType = dwEntryType + STICKY_CACHE_ENTRY;
                        else
                                if(SendDlgItemMessage(hX,IDC_RBSparse, BM_GETCHECK,0,0))
                                        dwEntryType = dwEntryType + SPARSE_CACHE_ENTRY;

        if(SendDlgItemMessage(hX,IDC_RBOCX, BM_GETCHECK,0,0))
                dwEntryType = dwEntryType + OCX_CACHE_ENTRY;
        else
                if(SendDlgItemMessage(hX,IDC_RBCookie, BM_GETCHECK,0,0))
                        dwEntryType = dwEntryType + COOKIE_CACHE_ENTRY;
                else
                        if(SendDlgItemMessage(hX,IDC_RBUrl, BM_GETCHECK,0,0))
                                dwEntryType = dwEntryType + URLHISTORY_CACHE_ENTRY;

        if(SendDlgItemMessage(hX,IDC_RBNone, BM_GETCHECK,0,0))
        {
                dwEntryType=0;
        }

        lpdtmSysTime = new SYSTEMTIME;
        lpdtmExpire = new FILETIME;
        lpdtmLastModified = new FILETIME;

        GetLocalTime(lpdtmSysTime);
        SystemTimeToFileTime(lpdtmSysTime,lpdtmExpire);
        SystemTimeToFileTime(lpdtmSysTime,lpdtmLastModified);
        delete(lpdtmSysTime);

        lpszUrl = new char[MAX_PATH];
        lpszFileName = new char[MAX_PATH];
        lpszExt = new char[5];
        lpszSize = new char[10];

        GetDlgItemText(hX,IDC_SourceURL,lpszUrl,MAX_PATH);
        GetDlgItemText(hX,IDC_LocalFile,lpszFileName,MAX_PATH);
        GetDlgItemText(hX,IDC_FileExt,lpszExt,5);

        GetDlgItemText(hX,IDC_SizeLow,lpszSize,5);
        dwSize = (DWORD)atol(lpszSize);
        delete(lpszSize);

        if (dwSize==0)
        {
                if((MessageBox(hX,"Incorrect File Size.\nUsing 8000 characters, Okay?\n",
                        "Commit Entry",MB_YESNO))==IDYES)
                {
                        dwSize = 8000;
                }
                else
                {
                        return FALSE;
                }
        }

        lpszData = new char[dwSize];
        GetDlgItemText(hX,IDC_CacheDump,lpszData,dwSize);

        lpfCacheEntry = fopen(lpszFileName,"w");
        fprintf(lpfCacheEntry,"%s",lpszData);
        fclose(lpfCacheEntry);
        delete(lpszData);

        if (!CommitUrlCacheEntry(lpszUrl, lpszFileName, *lpdtmExpire,
                *lpdtmLastModified, dwEntryType,NULL,0,lpszExt,0))
        {
                ErrorOut(hX,GetLastError(),"Commit Cache Entry");
                delete(lpszUrl);
                delete(lpszFileName);
                delete(lpszExt);
                delete(lpdtmExpire);
                delete(lpdtmLastModified);
                return FALSE;
        }
        else
        {
                delete(lpszUrl);
                delete(lpszFileName);
                delete(lpszExt);
                delete(lpdtmExpire);
                delete(lpdtmLastModified);
                return TRUE;
        }
}

Deleting a cache entry

The DeleteUrlCacheEntry function takes a URL and removes the cache file associated with it. If the cache file does not exist, the function fails and GetLastError returns ERROR_FILE_NOT_FOUND. If the cache file is currently locked or in use, the function fails and GetLastError returns ERROR_ACCESS_DENIED, and the file will be deleted when unlocked.

Retrieving a cache entry stream

RetrieveUrlCacheEntryStream, ReadUrlCacheEntryStream, and UnlockUrlCacheEntryStream retrieve the resources stored in the cache.

RetrieveUrlCacheEntryStream accepts a URL, a buffer that stores the INTERNET_CACHE_ENTRY_INFO structure, the buffer size, and a Boolean value to determine if random reads are allowed. If the cache file is found, the function then creates a handle to the file.

RetrieveUrlCacheEntryStream does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

ReadUrlCacheEntryStream uses the handle created by RetrieveUrlCacheEntryStream, a file offset, a buffer, and a buffer size variable. If the buffer size is insufficient to hold the amount of data available, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. The buffer size variable is set to the size necessary to download the resource.

After the cache file is retrieved, the application must call UnlockUrlCacheEntryStream to close the handle that was created by RetrieveUrlCacheEntryStream.

The following example retrieves the information stored in the cache entry for the specified URL. The function displays text resources in the IDC_CacheDump edit box. Other resources are not displayed.

int WINAPI RetrieveStream(HWND hX, LPSTR lpszUrl)
{
    LPINTERNET_CACHE_ENTRY_INFO lpCacheEntry;
    DWORD dwEntrySize=0,dwStreamSize=0;
    HANDLE hStream;
    LPSTR lpszOut;

    RetrieveUrlCacheEntryStream(lpszUrl,NULL, &dwEntrySize, TRUE, 0);
    lpCacheEntry = LPINTERNET_CACHE_ENTRY_INFO(new char[dwEntrySize]);
    if (!(hStream = RetrieveUrlCacheEntryStream(lpszUrl,lpCacheEntry,
        &dwEntrySize, TRUE, 0)))
    {
        ErrorOut(hX,GetLastError(),"RetrieveUrlCacheEntryStream");
        return FALSE;
    }
    else
    {
        dwStreamSize = lpCacheEntry->dwSizeLow;
        lpszOut = new char[dwStreamSize];
        if (!ReadUrlCacheEntryStream(hStream,0,LPVOID(lpszOut),&dwStreamSize,
            0))
        {
            ErrorOut(hX,GetLastError(),"ReadUrlCacheEntryStream");
            return FALSE;
        }
        else
        {
            lpszOut[dwStreamSize]='\0';
            SetDlgItemText(hX,IDC_CacheDump,lpszOut);
            return TRUE;
        }
    }

    delete (lpCacheEntry);
    delete (lpszOut);

    if (!UnlockUrlCacheEntryStream(hStream,0))
    {
        ErrorOut(hX,GetLastError(),"UnlockUrlCacheEntryStream");
        return FALSE;
    }
    else
        return TRUE;
}

Retrieving cache entry files

For applications that require the file name of a resource in order to launch, the Win32 Internet API provides the RetrieveUrlCacheEntryFile and UnlockUrlCacheEntryFile functions. Applications that do not require the file name should use the RetrieveUrlCacheEntryStream, ReadUrlCacheEntryStream, and UnlockUrlCacheEntryStream functions to retrieve the information in the cache.

RetrieveUrlCacheEntryStream does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

RetrieveUrlCacheEntryFile accepts a URL, a buffer that stores the INTERNET_CACHE_ENTRY_INFO structure, and the buffer size. The function is retrieved and locked for the caller.

After the information in the file has been used, the application should call UnlockUrlCacheEntryFile to unlock the file.

Cache groups

Support for cache groups has been added to the Win32 Internet functions. To create a cache group, the CreateUrlCacheGroup function must be called to generate a GROUPID for the cache group. Entries can be added to the cache group by supplying the cache entry's URL and the INTERNET_CACHE_GROUP_ADD flag to the SetUrlCacheEntryGroup function. To remove a cache entry from a group, pass the cache entry's URL and the INTERNET_CACHE_GROUP_REMOVE flag to SetUrlCacheEntryGroup.

The FindFirstUrlCacheEntryEx and FindNextUrlCacheEntryEx functions can be used to enumerate the entries in a specified cache group. After the enumeration is complete, the function should call FindCloseUrlCache.

Handling Structures with Variable Size Information

The cache can contain variable size information for each URL stored. This is reflected in the INTERNET_CACHE_ENTRY_INFO structure. When the cache functions return this structure, they create a buffer that is always the size of INTERNET_CACHE_ENTRY_INFO plus any variable size information. If a pointer member is not NULL, it points to the memory area immediately after the structure. While copying the returned buffer from a function into another buffer, the pointer members should be fixed to point to the appropriate place in the new buffer, as the following example shows.

lpDstCEInfo->lpszSourceUrlName =
    (LPINTERNET_CACHE_ENTRY_INFO) ((LPBYTE) lpSrcCEInfo +
        ((DWORD) (lpOldCEInfo->lpszSourceUrlName) - (DWORD) lpOldCEInfo))

Some cache functions fail with the ERROR_INSUFFICIENT_BUFFER error message if you specify a buffer that is too small to contain the cache-entry information retrieved by the function. In this case, the function also returns the required size of the buffer. You can then allocate a buffer of the appropriate size and call the function again.


Appendix A: HINTERNET Handles

This section contains information about the handles that are used by the Win32 Internet functions and the hierarchy that they work in.

About HINTERNET Handles

The handles that are created and used by the Win32 Internet functions are called HINTERNETs. The Win32 Internet functions return HINTERNET handles that are not interchangeable with the base Win32 handles, so they cannot be used with Win32 functions such as ReadFile or CloseHandle. Similarly, base Win32 handles cannot be used with the Win32 Internet functions. For example, a handle returned by CreateFile cannot be passed to InternetReadFile.

The InternetCloseHandle function closes handles of type HINTERNET. Note that handle values are recycled quickly; therefore, if a handle is closed and a new handle is generated immediately, there is a good chance that the new handle will have the same value as the handle just closed.

Handle Hierarchy

The HINTERNET handles are maintained in a tree hierarchy. The handle returned by the InternetOpen function is the root node. Handles returned by the InternetConnect function occupy the next level. Handles returned by the FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, GopherOpenFile, and HttpOpenRequest functions are the leaf nodes.

The following diagram illustrates the hierarchy of the HINTERNET handles. Each box in the diagram represents a Win32 Internet function that returns an HINTERNET handle.

Functions That Create Handles

At the top level is the InternetOpen function, which creates the root HINTERNET handle. The next level contains the InternetOpenUrl and InternetConnect functions. The functions that use the HINTERNET handle returned by InternetConnect make up the last level.

The following diagram shows the functions that are dependent on the HINTERNET handle created by InternetOpenUrl. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the associated function.

Functions That Use The InternetOpenUrl Handle

InternetQueryDataAvailable, InternetReadFile, and InternetSetFilePointer use the HINTERNET handle created by InternetOpenUrl.

FTP hierarchy

The following diagram shows the FTP functions that are dependent on the FTP session HINTERNET handle returned by InternetConnect. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Functions That Use The FTP Session Handle

FtpCreateDirectory, FtpDeleteFile, FtpGetCurrentDirectory, FtpGetFile, FtpPutFile, FtpRemoveDirectory, FtpRenameFile, and FtpSetCurrentDirectory all use the HINTERNET handle created by InternetConnect.

The following diagram shows the two FTP functions that return HINTERNET handles and the functions that are dependent on the HINTERNET handles created by them. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Functions that use the handle from FtpOpen and FtpFindFirstFile

InternetFindNextFile is dependent on the HINTERNET handle created by FtpFindFirstFile, while InternetReadFile and InternetWriteFile use the HINTERNET handle created by FtpOpenFile.

Gopher hierarchy

The following diagram shows the Win32 Internet functions used for the Gopher protocol. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Gopher Related Functions

GopherGetAttribute is dependent on the HINTERNET handle created by InternetConnect. InternetFindNextFile uses the HINTERNET handle created by GopherFindFirstFile. The handle created by GopherOpenFile is used by InternetReadFile and InternetQueryDataAvailable.

HTTP hierarchy

The following diagram shows the relationships of the Win32 Internet functions that are used for the HTTP protocol. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Functions that use the handle from HttpOpenRequest

HttpAddRequestHeaders, HttpQueryInfo, HttpSendRequest, HttpSendRequestEx, and InternetErrorDlg are dependent on the HINTERNET handle created by HttpOpenRequest.

The following diagram shows the Win32 Internet functions that use the HINTERNET handle created by HttpOpenRequest after it is sent by HttpSendRequest. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

Functions that use the handle after HttpSendRequest

After HttpSendRequest has been used on the handle returned by HttpOpenRequest, InternetQueryDataAvailable, InternetReadFile, and InternetSetFilePointer can be used on that handle.

Functions that use the handle after HttpSendRequestEx

After HttpSendRequestEx has been used on the handle returned by HttpOpenRequest, HttpEndRequest, InternetReadFileEx, and InternetWriteFile can be used on that handle. After HttpEndRequest has been used, InternetQueryDataAvailable, InternetReadFile, and InternetSetFilePointer can be used on that handle.


Appendix B: Using Buffers

Functions that return strings contain an input lpszBuffer parameter and an lpdwBufferLength parameter. Although lpszBuffer can be NULL, lpdwBufferLength must be a valid pointer to a double-word (DWORD) variable. If the input buffer pointed to by lpszBuffer is either too small to hold the output string or NULL, the function returns a failure indication and GetLastError returns ERROR_INSUFFICIENT_BUFFER. The variable pointed to by lpdwBufferLength contains a number that represents the number of bytes the function requires to return the requested string, including the NULL terminator. The application should allocate a buffer of this size, set the variable pointed to by lpdwBufferLength to this value, and resubmit the request. If the buffer size is sufficient to receive the requested string, the string is copied to the output buffer with a NULL terminator and the function returns a success indication. The variable pointed to by lpdwBufferLength now contains the number of characters stored in the buffer, excluding the NULL terminator.


Appendix C: Handling Errors

The Win32 function GetLastError is used to get the error code for all of the Win32 Internet functions. If ERROR_INTERNET_EXTENDED_ERROR is returned, there is a string or buffer containing a verbose error message. Call the InternetGetLastResponseInfo function to retrieve the extended error text.

To get the error text for a normal Win32 Internet error, use the Win32 function FormatMessage, and pass it an HMODULE handle to the Wininet.dll using the Win32 function GetModuleHandle.

The following is an example of a function to handle Win32 Internet function errors.

BOOL WINAPI ErrorOut ( HWND hErr, DWORD dError, TCHAR * szCallFunc)
{
TCHAR szTemp[356] = "", *szBuffer=NULL, *szBufferFinal = NULL;
        DWORD  dwIntError , dwLength = 0;
        char strName[256]="";

        FormatMessage(FORMAT_MESSAGE_FROM_HMODULE,
        GetModuleHandle("wininet.dll"),dError,0,
(LPSTR)strName,256,NULL);
wsprintf (szTemp,  "%s error code: %d\nMessage: %s\n",
szCallFunc, dError, strName);
        int response;

        if (dError == ERROR_INTERNET_EXTENDED_ERROR)
        {
                InternetGetLastResponseInfo (&dwIntError, NULL, &dwLength);
                if (dwLength)
                {
                        if ( !(szBuffer = (TCHAR *) LocalAlloc ( LPTR,  dwLength) ) )
                        {
                                lstrcat (szTemp, TEXT ( "Unable to allocate memory to display
                                         Internet error code. Error code: ") );
                                lstrcat (szTemp, TEXT (_itoa (GetLastError(), szBuffer, 10)  ) );
                                lstrcat (szTemp, TEXT ("\n") );
                                response = MessageBox(hErr, (LPSTR)szTemp,"Error",MB_OK);
                                return FALSE;
                        }
                        if (!InternetGetLastResponseInfo (&dwIntError, (LPTSTR) szBuffer,
                            &dwLength))
                        {
                                lstrcat (szTemp, TEXT ( "Unable to get Internet error. Error code: ") );
                                lstrcat (szTemp, TEXT (_itoa (GetLastError(), szBuffer, 10)  ) );
                                lstrcat (szTemp, TEXT ("\n") );
                                response = MessageBox(hErr, (LPSTR)szTemp,"Error",MB_OK);
                                return FALSE;
                        }
                        if ( !(szBufferFinal = (TCHAR *) LocalAlloc ( LPTR,
                               (strlen (szBuffer) +strlen (szTemp) + 1)  ) )  )
                        {
                                lstrcat (szTemp, TEXT ( "Unable to allocate memory. Error code: ") );
                                lstrcat (szTemp, TEXT (_itoa (GetLastError(), szBuffer, 10)  ) );
                                lstrcat (szTemp, TEXT ("\n") );
                                response = MessageBox(hErr, (LPSTR)szTemp,"Error",MB_OK);
                                return FALSE;
                        }
                        lstrcpy (szBufferFinal, szTemp);
                        lstrcat (szBufferFinal, szBuffer);
                        LocalFree (szBuffer);
                        response = MessageBox(hErr, (LPSTR)szBufferFinal,"Error",MB_OK);
                        LocalFree (szBufferFinal);
                }
        }
        else
    {
                response = MessageBox(hErr, (LPSTR)szTemp,"Error",MB_OK);
        }

    return response;
}


Microsoft Win32 Internet Functions Reference

This reference describes the functions, macros, structures, flags, and error codes associated with the Microsoft® Win32® Internet (WinInet) functions.

General Win32 Internet Functions

Automatic Dialing Functions

Uniform Resource Locator (URL) Functions

FTP Functions

Gopher Functions

HTTP Functions

Cookie Functions

Persistent URL Cache Functions

Macros

Data Types

Structures

API Flags

HTTP Status Codes

Option Flags

Error Messages


General Win32 Internet Functions

The general Win32 Internet functions described in this section perform basic Internet file manipulations.
InternetAttemptConnect
InternetCheckConnection
InternetCloseHandle
InternetConfirmZoneCrossing
InternetConnect
InternetErrorDlg
InternetFindNextFile
InternetGetLastResponseInfo
InternetLockRequestFile
InternetOpen
InternetQueryDataAvailable
InternetQueryOption
InternetReadFile
InternetReadFileEx
InternetSetFilePointer
InternetSetOption
InternetSetOptionEx
InternetSetStatusCallback
InternetTimeFromSystemTime
InternetTimeToSystemTime
InternetUnlockRequestFile
InternetWriteFile


InternetAttemptConnect

DWORD InternetAttemptConnect(
    IN DWORD dwReserved
);

Attempts to make a connection to the Internet.

  • Returns ERROR_SUCCESS if successful, or a Win32 error value otherwise.
dwReserved
Reserved; must be zero.

This function allows an application to first attempt to connect before issuing any requests. A client program can use this to evoke the dialup dialog box. If the attempt fails, the application should enter offline mode.


InternetCheckConnection

BOOL InternetCheckConnection(
    IN LPCSTR lpszUrl,
    IN DWORD dwFlags,
    IN DWORD dwReserved
);

Allows an application to check if a connection to the Internet can be established.

  • Returns TRUE if a connection is made successfully, or FALSE otherwise. Use GetLastError to retrieve the error code. ERROR_NOT_CONNECTED is returned by GetLastError if a connection cannot be made or if the sockets database is unconditionally offline.
lpszUrl
Address of a string containing the Uniform Resource Locator (URL) to use to check the connection. This value can be set to NULL.
dwFlags
Unsigned long integer value containing the flag values. FLAG_ICC_FORCE_CONNECTION is the only flag that is currently available. If this flag is set, it forces a connection. A sockets connection is attempted in the following order:
  • If lpszUrl is non-NULL, the host value is extracted from it and used to ping that specific host.
  • If lpszUrl is NULL and there is an entry in WinInet's internal server database for the nearest sever, the host value is extracted from the entry and used to ping that server.
dwReserved
Reserved, must be zero.


InternetCloseHandle

BOOL InternetCloseHandle(
    IN HINTERNET hInet
);

Closes a single Internet handle.

  • Returns TRUE if the handle is successfully closed, or FALSE otherwise. To get extended error information, call GetLastError.
hInet
Valid Internet handle to be closed.

The function terminates any pending operations on the handle and discards any outstanding data. If a thread is blocking a call to Wininet.dll, another thread in the application can call InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation and unblock the first thread.

If there is a status callback registered for the handle being closed and the handle was created with a non-NULL context value, an INTERNET_STATUS_HANDLE_CLOSING callback will be made. This indication will be the last callback made from a handle and indicates that the handle is being destroyed.

If asynchronous requests are pending for the handle or any of its child handles, the handle cannot be closed immediately, but it will be invalidated. Any new requests attempted using the handle will return with an ERROR_INVALID_HANDLE notification. The asynchronous requests will complete with INTERNET_STATUS_REQUEST_COMPLETE. Applications must be prepared to receive any INTERNET_STATUS_REQUEST_COMPLETE indications on the handle before the final INTERNET_STATUS_HANDLE_CLOSING indication is made, which indicates that the handle is completely closed.

An application can call GetLastError to determine if requests are pending. If GetLastError returns ERROR_IO_PENDING, there were outstanding requests when the handle was closed.

See also FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, HttpOpenRequest, InternetConnect


InternetConfirmZoneCrossing

DWORD InternetConfirmZoneCrossing(
    IN HWND hWnd,
    IN LPSTR szUrlPrev,
    IN LPSTR szUrlNew,
    IN BOOL bPost
);

Checks for changes between secure and nonsecure URLs. When a change occurs in security between two URLs, an application should allow the user to acknowledge this change, typically by displaying a dialog box.

  • Returns one of the following values:
    ERROR_SUCCESS | The user confirmed that it was okay to continue or there was no user input needed.
    ERROR_CANCELLED | The user canceled the request.
    ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to carry out the request.
hWnd
Handle to the parent window for any needed dialog box.
szUrlPrev
URL that was viewed before the current request was made.
szUrlNew
New URL that the user has requested to view.
bPost
TRUE if a post is being made in this request. This flag is ignored in this release.


InternetConnect

HINTERNET InternetConnect(
    IN HINTERNET hInternetSession,
    IN LPCSTR lpszServerName,
    IN INTERNET_PORT nServerPort,
    IN LPCSTR lpszUsername,
    IN LPCSTR lpszPassword,
    IN DWORD dwService,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Opens an FTP, Gopher, or HTTP session for a given site.

  • Returns a valid handle to the FTP, Gopher, or HTTP session if the connection is successful, or NULL otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.
hInternetSession
Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszServerName
Address of a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).
nServerPort
Number of the TCP/IP port on the server to connect to. Can be one of the values in the following list. These flags set only the port that will be used. The service is set by the value of dwService.
INTERNET_DEFAULT_FTP_PORT | Uses the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT | Uses the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT | Uses the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT | Uses the default port for HTTPS servers (port 443).
INTERNET_DEFAULT_SOCKS_PORT | Uses the default port for SOCKS firewall servers (port 1080).
INTERNET_INVALID_PORT_NUMBER | Uses the default port for the service specified by dwService.
lpszUsername
Address of a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP; a NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is "anonymous".
lpszPassword
Address of a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUsername are NULL, the function uses the default "anonymous" password. In the case of FTP, the default password is the user's e-mail name. If lpszPassword is NULL, but lpszUsername is not NULL, the function uses a blank password. The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword.
lpszUsername | lpszPassword | User name sent to FTP server | Password sent to FTP server
NULL | NULL | "anonymous" | User's e-mail name
Non-NULL string NULL lpszUsername ""
NULL | Non-NULL string | ERROR | ERROR
Non-NULL string | Non-NULL string | lpszUsername | lpszPassword
dwService
Type of service to access. Can be one of the following values:
INTERNET_SERVICE_FTP | FTP service.
INTERNET_SERVICE_GOPHER | Gopher service.
INTERNET_SERVICE_HTTP | HTTP service.
dwFlags
Flags specific to the service used. When the value of dwService is INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the application to use passive FTP semantics.
dwContext
Application-defined value that is used to identify the application context for the returned handle in callbacks.

The InternetConnect function is required before communicating with any Internet service.

Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests by using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.

For FTP sites, InternetConnect actually establishes a connection with the server; for others, such as Gopher, the actual connection is not established until the application requests a specific transaction.

For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.

An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve the text.

For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, InternetConnect attempts to use the user's e-mail name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.


InternetErrorDlg

DWORD InternetErrorDlg(
    IN HWND hWnd,
    IN OUT HINTERNET hInternet,
    IN DWORD dwError,
    IN DWORD dwFlags,
    IN OUT LPVOID *lppvData
);

Displays a dialog box for the error that is passed to InternetErrorDlg, if an appropriate dialog box exists. If the FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag is used, the function also checks the headers for any hidden errors and displays a dialog box if needed.

  • Returns ERROR_SUCCESS, ERROR_CANCELLED, or ERROR_INTERNET_FORCE_RETRY.
hWnd
Handle to the parent window for any needed dialog box. This parameter can be NULL if no dialog box is needed.
hInternet
Handle to the Internet connection used in the call to HttpSendRequest.
dwError
Error value for which to display a dialog box. Can be one of the following values:
ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR
Notifies the user of the zone crossing to and from a secure site.
ERROR_INTERNET_INCORRECT_PASSWORD
Displays a dialog box for obtaining the user's name and password. (On Microsoft Windows® 95, the function first attempts to use any cached authentication information for the server being accessed, before displaying a dialog box.)
ERROR_INTERNET_INVALID_CA
Notifies the user that the Win32 Internet function does not recognize the certificate authority that generated the certificate for this Secure Sockets Layer (SSL) site.
ERROR_INTERNET_POST_IS_NON_SECURE
Displays a warning about posting data to the server through a nonsecure connection.
ERROR_INTERNET_SEC_CERT_CN_INVALID
Indicates that the SSL certificate Common Name (hostname field) is incorrect. Displays an Invalid SSL Common Name dialog box, and lets the user view the incorrect certificate. Also allows the user to select a certificate in response to a server request.
ERROR_INTERNET_SEC_CERT_DATE_INVALID
Tells the user that the SSL certificate has expired.
dwFlags
Action flags. Can be a combination of these values:
FLAGS_ERROR_UI_FILTER_FOR_ERRORS
Scans the returned headers for errors. Call after using HttpSendRequest. This option detects any hidden errors, such as an authentication error.
FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS
If the function succeeds, stores the results of the dialog box in the Internet handle.
FLAGS_ERROR_UI_FLAGS_GENERATE_DATA
Queries the Internet handle for needed information. The function constructs the appropriate data structure for the error. (For example, for Cert CN failures, the function grabs the certificate.)
FLAGS_ERROR_UI_SERIALIZE_DIALOGS
Serializes authentication dialog boxes for concurrent requests on a password cache entry. The lppvData parameter should contain the address of a pointer to an INTERNET_AUTHNOTIFY_DATA structure, and the client should implement a thread-safe, nonblocking callback function.
lppvData
Address of a data structure. The structure can be different for each error that needs to be handled.

Authentication errors are hidden, since the call to HttpSendRequest will complete successfully, but the status code would indicate that the proxy or server requires authentication. The FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag causes the function to search the headers for status codes that indicate that user input is needed.


InternetFindNextFile

BOOL InternetFindNextFile(
    IN HINTERNET hFind,
    OUT LPVOID lpvFindData
);

Continues a file search started as a result of a previous call to FtpFindFirstFile or GopherFindFirstFile.

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.
hFind
Valid handle returned from either FtpFindFirstFile or GopherFindFirstFile, or InternetOpenUrl (directories only).
lpvFindData
Address of the buffer that receives information about the found file or directory. The format of the information placed in the buffer depends on the protocol in use. The FTP protocol returns a WIN32_FIND_DATA structure, and the Gopher protocol returns a GOPHER_FIND_DATA structure.


InternetGetLastResponseInfo

BOOL InternetGetLastResponseInfo(
    OUT LPDWORD lpdwError,
    OUT LPSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength
);

Retrieves the last Win32 Internet function error description or server response on the thread calling this function.

  • Returns TRUE if error text was successfully written to the buffer, or FALSE otherwise. To get extended error information, call GetLastError. If the buffer is too small to hold all the error text, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the lpdwBufferLength parameter contains the minimum buffer size required to return all the error text.
lpdwError
Address of a variable that receives an error message pertaining to the operation that failed.
lpszBuffer
Address of a buffer that receives the error text.
lpdwBufferLength
Size of the lpszBuffer buffer. When the function returns, this parameter contains the size of the string written to the buffer.

The FTP and Gopher protocols can return additional text information along with most errors. This extended error information can be retrieved by using the InternetGetLastResponseInfo function whenever GetLastError returns ERROR_INTERNET_EXTENDED_ERROR (occurring after an unsuccessful function call).

The buffer pointed to by lpszBuffer must be large enough to hold both the error string and a zero terminator at the end of the string. However, note that the value returned in lpdwBufferLength does not include the terminating zero.

InternetGetLastResponseInfo can be called multiple times until another Win32 Internet function is called on this thread. When another function is called, the internal buffer that is storing the last response information is cleared.


InternetLockRequestFile

BOOL InternetLockRequestFile (
    IN HINTERNET hInternet,
    OUT HANDLE *lphLockReqHandle
);

Allows the user to place a lock on the file that is being used.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, use GetLastError.
hInternet
HINTERNET handle returned by FtpOpenFile, GopherOpenFile, HttpOpenRequest, or InternetOpenUrl.
lphLockReqHandle
Address of a handle to store the lock request handle.

If the HINTERNET handle passed to hInternet was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE, the function creates a temporary file with the extension TMP, unless it is an HTTPS resource. If the handle was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE and it is accessing an HTTPS resource, InternetLockRequestFile fails.

See also InternetUnlockRequestFile


InternetOpen

HINTERNET InternetOpen(
    IN LPCSTR lpszAgent,
    IN DWORD dwAccessType,
    IN LPCSTR lpszProxyName,
    IN LPCSTR lpszProxyBypass,
    IN DWORD dwFlags
);

Initializes an application's use of the Win32 Internet functions.

  • Returns a valid handle that the application passes on to subsequent Win32 Internet functions. If InternetOpen fails, it returns NULL. To get a specific error message, call GetLastError.
lpszAgent
Address of a string that contains the name of the application or entity calling the Internet functions (for example, Microsoft Internet Explorer). This name is used as the user agent in the HTTP protocol.
dwAccessType
Type of access required. Can be one of the following values:
INTERNET_OPEN_TYPE_DIRECT
Resolves all host names locally.
INTERNET_OPEN_TYPE_PRECONFIG
Retrieves the proxy or direct configuration from the registry.
INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY
Retrieves the proxy or direct configuration from the registry and prevents the use of a startup JScript or Internet Setup (INS) file.
INTERNET_OPEN_TYPE_PROXY
Passes requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function uses INTERNET_OPEN_TYPE_DIRECT.
lpszProxyName
Address of a string that contains the name of the proxy server (or servers) to use if proxy access was specified. If this parameter is NULL, the function reads proxy information from the registry. Do not use an empty string, because InternetOpen will use it as the proxy name. The Win32 Internet functions only recognize CERN type proxies (HTTP only) and the TIS FTP gateway (FTP only). If Microsoft Internet Explorer is installed, the Win32 Internet functions also support SOCKS proxies. FTP and Gopher requests can be made through a CERN type proxy either by changing them to an HTTP request or by using InternetOpenUrl.
lpszProxyBypass
Address of an optional list of host names or IP addresses, or both, that should not be routed through the proxy. The list can contain wildcards. Do not use an empty string, because InternetOpen will use it as the proxy bypass list. If this parameter specifies the "<local>" macro as the only entry, the function bypasses any host name that does not contain a period. If this parameter is NULL, the function reads the bypass list from the registry.
dwFlags
Flags that indicate various options affecting the behavior of the function. Can be a combination of these values:
INTERNET_FLAG_ASYNC
INTERNET_FLAG_FROM_CACHE
INTERNET_FLAG_OFFLINE

InternetOpen is the first Win32 Internet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application finishes using the Internet functions, it should call InternetCloseHandle to free the handle and any associated resources.

The application can make any number of calls to InternetOpen, although a single call is normally sufficient. The application might need to have separate behaviors defined for each InternetOpen instance, such as different proxy servers configured for each.


InternetQueryDataAvailable

BOOL InternetQueryDataAvailable(
    IN HINTERNET hFile,
    OUT LPDWORD lpdwNumberOfBytesAvailable,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Queries the amount of data available.

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.
hFile
Valid Internet file handle, as returned by InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest.
lpdwNumberOfBytesAvailable
Optional. Address of a variable that receives the number of available bytes.
dwFlags
Reserved; must be zero.
dwContext
Reserved; must be zero.

This function returns the number of bytes of data that are available to be read immediately by a subsequent call to InternetReadFile. If there is currently no data available and the end of the file has not been reached, the request waits until data becomes available. The amount of data remaining will not be recalculated until all available data indicated by the call to InternetQueryDataAvailable is read.

For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetQueryDataAvailable can be used.


InternetQueryOption

BOOL InternetQueryOption(
    IN HINTERNET hInternet,
    IN DWORD dwOption,
    OUT LPVOID lpBuffer,
    IN OUT LPDWORD lpdwBufferLength
);

Queries an Internet option on the specified handle.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hInternet
Internet handle on which to query information.
dwOption
Internet option to query. Can be one of the Option Flags values.
lpBuffer
Address of a buffer that receives the option setting.
lpdwBufferLength
Address of a variable that contains the length of lpBuffer. When the function returns, the variable receives the length of the data placed into lpBuffer. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.

See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetSetOption


InternetReadFile

BOOL InternetReadFile(
    IN HINTERNET hFile,
    IN LPVOID lpBuffer,
    IN DWORD dwNumberOfBytesToRead,
    OUT LPDWORD lpNumberOfBytesRead
);

Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo when necessary.
hFile
Valid handle returned from a previous call to InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest.
lpBuffer
Address of a buffer that receives the data read.
dwNumberOfBytesToRead
Number of bytes to read.
lpNumberOfBytesRead
Address of a variable that receives the number of bytes read. InternetReadFile sets this value to zero before doing any work or error checking.

If the return value is TRUE and the number of bytes read is zero, the transfer has been completed and there are no more bytes to read on the handle. This is analogous to reaching EOF in a local file. Call InternetCloseHandle to free the connection to the server.

The buffer pointed to by lpBuffer is not always filled by calls to InternetReadFile (sufficient data might not have arrived from the server). When reading HTML data, for the first read posted, the buffer must be large enough to hold the HTML headers. When reading HTML-encoded directory entries, the buffer must be large enough to hold at least one complete entry.

When the item being read is also being cached by a Win32 Internet function, the application must ensure that a read is made for end-of-file so the cache file is committed correctly.

This function always fulfills the user's request. If more data is requested than is available, the function waits until enough data to complete the request is available. The only time that less data is returned than requested is when the end of the file has been reached.

This function can also be used to retrieve FTP and Gopher directory listings as an HTML document on a handle opened by InternetOpenUrl. The INTERNET_FLAG_RAW_DATA value must not have been specified in the call to InternetOpenUrl.

If the HINTERNET handle stored in hFile was created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetReadFile is used.


InternetReadFileEx

InternetReadFileEx(
    IN HINTERNET hFile,
    OUT LPINTERNET_BUFFERS lpBuffersOut,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo when necessary.
hFile
HINTERNET handle returned by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.
lpBuffersOut
Address of an INTERNET_BUFFERS structure that contains the data downloaded.
dwFlags
DWORD variable that contains the flags controlling the download. Can be one of the following values:
IRF_ASYNC | Identical to WININET_API_FLAG_ASYNC.
IRF_SYNC | Identical to WININET_API_FLAG_SYNC.
IRF_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
IRF_NO_WAIT | Do not wait for data. If there is data available, the function returns either the amount of data requested or the amount of data available (whichever is smaller).
dwContext
DWORD variable that contains the context value used for asynchronous operations.


InternetSetFilePointer

DWORD InternetSetFilePointer(
    IN HINTERNET hFile,
    IN LONG lDistanceToMove,
    IN PVOID pReserved,
    IN DWORD dwMoveMethod,
    IN DWORD dwContext
);

Sets a file position for InternetReadFile. This is a synchronous call; however, subsequent calls to InternetReadFile may block or return pending if the data is not available from the cache and the server does not support random access.

  • Returns the current file position if the function succeeds, or -1 otherwise.
hFile
Valid handle returned from a previous call to InternetOpenUrl (on an HTTP or HTTPS URL) or HttpOpenRequest (using the GET or HEAD method and passed to HttpSendRequest or HttpSendRequestEx). This handle must not have been created with the INTERNET_FLAG_DONT_CACHE or INTERNET_FLAG_NO_CACHE_WRITE value set.
lDistanceToMove
Number of bytes to move the file pointer. A positive value moves the pointer forward in the file, and a negative value moves it backward.
pReserved
Reserved; must be NULL.
dwMoveMethod
Starting point for the file pointer move. Can be one of the following values:
FILE_BEGIN | The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, lDistanceToMove is interpreted as an unsigned location for the new file pointer.
FILE_CURRENT | The current value of the file pointer is the starting point.
FILE_END | The current end-of-file position is the starting point. This method fails if the content length is unknown.
dwContext
Reserved; must be zero.

This function cannot be used once the end of file has been reached by InternetReadFile.

For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetSetFilePointer is used.

InternetSetFilePointer cannot be used reliably if the content length is unknown and with chunked transfers.


InternetSetOption

BOOL InternetSetOption(
    IN HINTERNET hInternet,
    IN DWORD dwOption,
    IN LPVOID lpBuffer,
    IN DWORD dwBufferLength
);

Sets an Internet option.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hInternet
Internet handle on which to set information.
dwOption
Internet option to set. Can be one of the Option Flags values.
lpBuffer
Address of a buffer that contains the option setting.
dwBufferLength
Length of the lpBuffer buffer.

See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetQueryOption


InternetSetOptionEx InternetSetOptionEx *
  * Previous Topic: InternetSetOption
  * Next Topic: InternetSetStatusCallback

InternetSetOptionEx

Not currently implemented.


InternetSetStatusCallback

INTERNET_STATUS_CALLBACK InternetSetStatusCallback(
    IN HINTERNET hInternet,
    IN INTERNET_STATUS_CALLBACK lpfnInternetCallback
);

Sets up a callback function that Win32 Internet functions can call as progress is made during an operation.

  • Returns the previously defined status callback function if successful, NULL if there was no previously defined status callback function, or INTERNET_INVALID_STATUS_CALLBACK if the callback function is not valid.
hInternet
Handle for which the callback is to be set.
lpfnInternetCallback
Address of the callback function to call when progress is made, or to return NULL to remove the existing callback function. For more information about the callback function, see INTERNET_STATUS_CALLBACK.

Both synchronous and asynchronous functions use the callback function to indicate the progress of the request, such as resolving a name, connecting to a server, and so on. The callback function is required for an asynchronous operation. The asynchronous request will call back to the application with INTERNET_STATUS_REQUEST_COMPLETE to indicate the request has been completed.

A callback function can be set on any handle, and is inherited by derived handles. A callback function can be changed using InternetSetStatusCallback, providing there are no pending requests that need to use the previous callback value. Note, however, that changing the callback function on a handle does not change the callbacks on derived handles, such as that returned by InternetConnect. You must change the callback function at each level.

Many of the Win32 Internet functions perform several operations on the network. Each operation can take time to complete, and each can fail.

It is sometimes desirable to display status information during a long-term operation. You can display status information by setting up an Internet status callback function that cannot be removed as long as any callbacks or any asynchronous functions are pending.

After initiating InternetSetStatusCallback, the callback function can be accessed from within any Win32 Internet function for monitoring time-intensive network operations.


InternetTimeFromSystemTime

BOOL InternetTimeFromSystemTime(
    IN  CONST SYSTEMTIME *pst,
    IN  DWORD dwRFC,
    OUT LPSTR lpszTime,
    IN  DWORD cbTime
);

Formats a date and time according to the specified RFC format (as specified in the HTTP version 1.0 specification).

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError.
pst
Address of a SYSTEMTIME structure that contains the date and time to format.
dwRFC
RFC format used. Currently, the only valid format is INTERNET_RFC1123_FORMAT.
lpszTime
Address of a buffer that receives the formatted date and time. The buffer should be of size INTERNET_RFC1123_BUFSIZE.
cbTime
Size, in bytes, of the lpszTime buffer.


InternetTimeToSystemTime

BOOL InternetTimeToSystemTime(
    IN LPCSTR lpszTime,
    OUT SYSTEMTIME *pst,
    IN DWORD dwReserved
);

Takes an HTTP time/date string and converts it to a SYSTEMTIME structure.

  • Returns TRUE if the string was converted, or FALSE otherwise. To get extended error information, call GetLastError.
lpszTime
Address of a null-terminated date/time string to convert.
pst
Address of the pointer to the converted time.
dwReserved
Reserved; must be zero.


InternetUnlockRequestFile

BOOL InternetUnlockRequestFile (
    IN HANDLE hLockHandle
);

Unlocks a file that was locked using InternetLockRequestFile.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, use GetLastError.
hLockHandle
Lock request handle that was returned by InternetLockRequestFile.


InternetWriteFile

BOOL InternetWriteFile(
    IN HINTERNET hFile,
    IN LPCVOID lpBuffer,
    IN DWORD dwNumberOfBytesToWrite,
    OUT LPDWORD lpdwNumberOfBytesWritten
);

Writes data to an open Internet file.

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo when necessary.
hFile
Valid handle returned from a previous call to FtpOpenFile or an HINTERNET handle sent by HttpSendRequestEx.
lpBuffer
Address of a buffer that contains the data to be written to the file.
dwNumberOfBytesToWrite
Number of bytes to write to the file.
lpdwNumberOfBytesWritten
Address of a variable that receives the number of bytes written to the buffer. InternetWriteFile sets this value to zero before doing any work or error checking.

When the application is sending data, it must call InternetCloseHandle to end the data transfer.


Automatic Dialing Functions

The functions described in this section handle dial-up access to the Internet.
InternetAutodial
InternetAutodialHangup
InternetDial
InternetGetConnectedState
InternetGoOnline
InternetHangUp
InternetSetDialState


InternetAutodial

BOOL InternetAutodial(
    IN DWORD dwFlags,
    IN DWORD dwReserved
);

Automatically causes the modem to dial the default Internet connection.

  • Returns TRUE if successful, or FALSE otherwise.
dwFlags
Double-word value that contains the flags controlling this operation. Can be one of the following values:
INTERNET_AUTODIAL_FORCE_ONLINE | Forces an online Internet connection.
INTERNET_AUTODIAL_FORCE_UNATTENDED | Forces an unattended Internet dial-up.
dwReserved
Reserved. Must be set to zero.


InternetAutodialHangup

BOOL InternetAutodialHangup(
    IN DWORD dwReserved
);

Disconnects an automatic dial-up connection.

  • Returns TRUE if successful, or FALSE otherwise.
dwReserved
Reserved. Must be set to zero.


InternetDial

DWORD InternetDial(
    IN HWND hwndParent,
    IN LPTSTR lpszConnectoid,
    IN DWORD dwFlags,
    OUT LPDWORD lpdwConnection,
    IN DWORD dwReserved
);

Initiates a connection to the Internet using a modem connection.

hwndParent
Handle to the parent window.
lpszConnectoid
String value containing the name of the dial-up connection to use.
dwFlags
Double-word value that contains the flags to use. Can be one of the following values:
INTERNET_AUTODIAL_FORCE_ONLINE | Forces an online connection.
INTERNET_AUTODIAL_FORCE_UNATTENDED | Forces an unattended Internet dial-up.
INTERNET_DIAL_UNATTENDED | Connects to the Internet through a modem, without displaying a user interface.
lpdwConnection
Address of a double-word value containing the number associated to the connection.
dwReserved
Reserved. Must be set to zero.


InternetGetConnectedState

BOOL InternetGetConnectedState(
    OUT LPDWORD lpdwFlags,
    IN DWORD dwReserved
);

Retrieves the connected state of the local system.

  • Returns TRUE if there is an Internet connection, FALSE otherwise.
lpdwFlags
Address of a double-word variable where the connection description should be returned. Can be a combination of the following values:
INTERNET_CONNECTION_MODEM | Local system uses a modem to connect to the Internet.
INTERNET_CONNECTION_LAN | Local system uses a local area network to connect to the Internet.
INTERNET_CONNECTION_PROXY | Local system uses a proxy server to connect to the Internet.
INTERNET_CONNECTION_MODEM_BUSY | Local system's modem is busy with a non-Internet connection.
dwReserved
Reserved. Must be set to zero.


InternetGoOnline

BOOL InternetGoOnline(
    IN LPTSTR lpszURL,
    IN HWND hwndParent,
    IN DWORD dwReserved
);

Prompts the user for permission to initiate connection to a URL.

  • Returns TRUE if successful, or FALSE otherwise.
lpszURL
String value containing the URL of the Web site to connect to.
hwndParent
Handle to the parent window.
dwReserved
Reserved. Must be set to zero.


InternetHangUp

DWORD InternetHangUp(
    IN DWORD dwConnection,
    IN DWORD dwReserved
);

Instructs the modem to disconnect from the Internet.

dwConnection
Double-word value that contains the number assigned to the connection to be disconnected.
dwReserved
Reserved. Must be set to zero.


InternetSetDialState

BOOL InternetSetDialState(
    IN LPCSTR lpszConnectoid,
    IN DWORD dwState,
    IN DWORD dwReserved
);

Sets the modem dialing state.

  • Returns TRUE if successful, or FALSE otherwise.
lpszConnectoid
String value that contains the name of the dial-up connection.
dwState
Double-word value that indicates the state to set the dial-up connection to. Currently, the only defined value is INTERNET_DIALSTATE_DISCONNECTED.
dwReserved
Reserved. Must be set to zero.


Uniform Resource Locator (URL) Functions

The URL functions deal with URL manipulation and access. These functions operate in a task-oriented manner. The content and format of the URL that is being used by the function is not verified. Usage of these functions should be tracked by the calling application to ensure that the data is in the format intended. For example, InternetCanonicalizeUrl would convert the unsafe character "%" into the escape sequence "%25" when using no flags. If InternetCanonicalizeUrl is used on the canonicalized URL, the escape sequence "%25" would be converted into the escape sequence "%2525", which would not work properly.
InternetCanonicalizeUrl
InternetCombineUrl
InternetCrackUrl
InternetCreateUrl
InternetOpenUrl


InternetCanonicalizeUrl

BOOL InternetCanonicalizeUrl(
    IN LPCSTR lpszUrl,
    OUT LPSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Canonicalizes a URL, which includes converting unsafe characters and spaces into escape sequences.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible errors include:
    ERROR_BAD_PATHNAME | The URL could not be canonicalized.
    ERROR_INSUFFICIENT_BUFFER | Canonicalized URL is too large to fit in the buffer provided. The *lpdwBufferLength parameter is set to the size, in bytes, of the buffer required to hold the resultant, canonicalized URL.
    ERROR_INTERNET_INVALID_URL | The format of the URL is invalid.
    ERROR_INVALID_PARAMETER | Bad string, buffer, buffer size, or flags parameter.
lpszUrl
Address of the input URL to canonicalize.
lpszBuffer
Address of the buffer that receives the resulting canonicalized URL.
lpdwBufferLength
Length, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length of the lpszBuffer buffer—the length does not include the terminating null. If the function fails, this parameter receives the required length, in bytes, of the lpszBuffer buffer—the required length includes the terminating null.
dwFlags
Flags that control canonicalization. Can be one of the following values:
ICU_BROWSER_MODE | Does not encode or decode characters after "#" or "?", and does not remove trailing white space after "?". If this value is not specified, the entire URL is encoded, and trailing white space is removed.
ICU_DECODE | Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.
ICU_ENCODE_SPACES_ONLY | Encodes spaces only.
ICU_NO_ENCODE | Does not convert unsafe characters to escape sequences.
ICU_NO_META | Does not remove meta sequences (such as "." and "..") from the URL.

If no flags are specified (dwFlags = 0), the function converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences.

InternetCanonicalizeUrl always encodes by default, even if the ICU_DECODE flag has been specified. To decode without re-encoding, use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the URL is decoded before being parsed; unsafe characters then are re-encoded after parsing. This function will handle arbitrary protocol schemes, but to do so it must make inferences from the unsafe character set.

The application calling InternetCanonicalizeUrl should track the usage of this function on a particular URL. If unsafe characters in a URL have been converted to escape sequences, using InternetCanonicalizeUrl again on the URL (with no flags) will cause the escape sequences to be converted to another escape sequence. For example, a blank space in a URL would be converted to the escape sequence "%20". Calling InternetCanonicalizeUrl again on the URL would cause the escape sequence "%20" to be converted to the escape sequence "%2520", because the "%" sign is an unsafe character that is reserved for escape sequences and is replaced by the function with the escape sequence "%25".


InternetCombineUrl

BOOL InternetCombineUrl(
    IN LPCSTR lpszBaseUrl,
    IN LPCSTR lpszRelativeUrl,
    OUT LPSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Combines a base and relative URL into a single URL. The resultant URL will be canonicalized (see InternetCanonicalizeUrl).

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible errors include:
    ERROR_BAD_PATHNAME | The URLs could not be combined.
    ERROR_INSUFFICIENT_BUFFER | The buffer supplied to the function was insufficient or NULL. The DWORD indicated by the lpdwBufferLength parameter will contain the number of bytes required to hold the resultant, combined URL.
    ERROR_INTERNET_INVALID_URL | The format of the URL is invalid.
    ERROR_INVALID_PARAMETER | Bad string, buffer, buffer size, or flags parameter.
lpszBaseUrl
Address of the base URL to be combined.
lpszRelativeUrl
Address of the relative URL to be combined.
lpszBuffer
Address of a buffer that receives the resulting URL.
lpdwBufferLength
Size, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length, in characters, of the resultant combined URL—the length does not include the null terminator. If the function fails, this parameter receives the length, in bytes, of the required buffer—the length includes the null terminator.
dwFlags
Flags controlling the operation of the function. Can be one of the following values:
ICU_BROWSER_MODE | Does not encode or decode characters after "#" or "?", and does not remove trailing white space after "?". If this value is not specified, the entire URL is encoded and trailing white space is removed.
ICU_DECODE | Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.
ICU_ENCODE_SPACES_ONLY | Encodes spaces only.
ICU_NO_ENCODE | Does not convert unsafe characters to escape sequences.
ICU_NO_META | Does not remove meta sequences (such as "." and "..") from the URL.


InternetCrackUrl

BOOL InternetCrackUrl(
    IN LPCSTR lpszUrl,
    IN DWORD dwUrlLength,
    IN DWORD dwFlags,
    IN OUT LPURL_COMPONENTS lpUrlComponents
);

Cracks a URL into its component parts.

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError.
lpszUrl
Address of a string that contains the canonical URL to crack.
dwUrlLength
Length of the lpszUrl string, or zero if lpszUrl is an ASCIIZ string.
dwFlags
Flags controlling the operation. Can be one of the following values:
ICU_DECODE | Converts encoded characters back to their normal form. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.
ICU_ESCAPE | Converts all escape sequences (%xx) to their corresponding characters. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.
lpUrlComponents
Address of a URL_COMPONENTS structure that receives the URL components.

The required components are indicated by members of the URL_COMPONENTS structure. Each component has a pointer to the value and has a member that stores the length of the stored value. If both the value and the length for a component are equal to zero, that component is not returned. If the pointer to the value of the component is NULL and the value of its corresponding length member is nonzero, the address of the first character of the corresponding component in the lpszUrl string is stored in the pointer, and the length of the component is stored in the length member.

If the pointer contains the address of the user-supplied buffer, the length member must contain the size of the buffer. InternetCrackUrl copies the component into the buffer, and the length member is set to the length of the copied component, minus 1 for the trailing string terminator.

For InternetCrackUrl to work properly, the size of the URL_COMPONENTS structure must be stored in the dwStructSize member.

See also FtpOpenFile, InternetCloseHandle, InternetFindNextFile, InternetSetStatusCallback


InternetCreateUrl

BOOL InternetCreateUrl(
    IN LPURL_COMPONENTS lpUrlComponents,
    IN DWORD dwFlags,
    OUT LPSTR lpszUrl,
    IN OUT LPDWORD lpdwUrlLength
);

Creates a URL from its component parts.

  • Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError.
lpUrlComponents
Address of a URL_COMPONENTS structure that contains the components from which to create the URL.
dwFlags
Flags that control the operation of this function. Can be a combination of these values:
ICU_ESCAPE | Converts all escape sequences (%xx) to their corresponding characters.
ICU_USERNAME | When adding the user name, uses the name that was specified at logon time.
lpszUrl
Address of a buffer that receives the URL.
lpdwUrlLength
Length, in bytes, of the lpszUrl buffer. When the function returns, this parameter receives the length, in bytes, of the URL string, minus 1 for the terminating character. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.


InternetOpenUrl

HINTERNET InternetOpenUrl(
    IN HINTERNET hInternetSession,
    IN LPCSTR lpszUrl,
    IN LPCSTR lpszHeaders,
    IN DWORD dwHeadersLength,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Begins reading a complete FTP, Gopher, or HTTP URL. Use InternetCanonicalizeUrl first if the URL being used contains a relative URL and a base URL separated by blank spaces.

  • Returns a valid handle to the FTP, Gopher, or HTTP URL if the connection is successfully established, or NULL if the connection fails. To get a specific error message, call GetLastError. To determine why access to the service was denied, call InternetGetLastResponseInfo.
hInternetSession
Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszUrl
Address of a string that contains the URL to begin reading. Only URLs beginning with ftp:, gopher:, http:, or https: are supported.
lpszHeaders
Address of a string that contains the headers to be sent to the HTTP server. (For more information, see the description of the lpszHeaders parameter in the HttpSendRequest function.)
dwHeadersLength
Length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, lpszHeaders is assumed to be zero-terminated (ASCIIZ) and the length is calculated.
dwFlags
Action flags. Can be one of the following values:
INTERNET_FLAG_DONT_CACHE
Does not cache the data, either locally or in any gateways. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_EXISTING_CONNECT
If possible, reuses the existing connections to the server for new requests generated by InternetOpenUrl instead of creating a new session for each request. This flag is useful only for FTP connections, since FTP is the only protocol that typically performs multiple operations during the same session. The Win32 Internet API caches a single connection handle for each HINTERNET handle generated by InternetOpen.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules for HTTP requests.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates for HTTP requests.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs.
INTERNET_FLAG_KEEP_CONNECTION
Uses keep-alive semantics, if available, for the connection for HTTP requests. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_AUTH
Does not attempt authentication automatically for HTTP requests.
INTERNET_FLAG_NO_AUTO_REDIRECT
Does not automatically handle redirection for HTTP requests only.
INTERNET_FLAG_NO_CACHE_WRITE
Does not cache the data, either locally or in any gateways.
INTERNET_FLAG_NO_COOKIES
Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database for HTTP requests.
INTERNET_FLAG_NO_UI
Disables the cookie dialog box.
INTERNET_FLAG_PASSIVE
Uses passive FTP semantics for FTP files and directories.
INTERNET_FLAG_RAW_DATA
Returns the data as a GOPHER_FIND_DATA structure when retrieving Gopher directory information, or as a WIN32_FIND_DATA structure when retrieving FTP directory information. If this flag is not specified or if the call was made through a CERN proxy, InternetOpenUrl returns an HTML version of the directory.
INTERNET_FLAG_PRAGMA_NOCACHE
Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
INTERNET_FLAG_READ_PREFETCH
This flag is currently disabled.
INTERNET_FLAG_RELOAD
Gets the data from the wire even if it is locally cached.
INTERNET_FLAG_RESYNCHRONIZE
Reloads HTTP resources if the resource has been modified since the last time it was downloaded. All FTP and Gopher resources are reloaded.
INTERNET_FLAG_SECURE
Requests secure transactions on the wire with SSL or PCT. This flag applies to HTTP requests only.
dwContext
Application-defined value that is passed, along with the returned handle, to any callback functions.

This is a general function that an application can use to retrieve data over any of the protocols that the Win32 Internet functions support. This function is particularly useful when the application does not need to access the particulars of a protocol, but only requires the data corresponding to a URL. The InternetOpenUrl function parses the URL string, establishes a connection to the server, and prepares to download the data identified by the URL. The application can then use InternetReadFile (for files) or InternetFindNextFile (for directories) to retrieve the URL data. It is not necessary to call InternetConnect before InternetOpenUrl.

InternetOpenUrl disables Gopher on ports less than 1024, except for port 70 (the standard Gopher port) and port 105 (typically used for Central Services Organization [CSO] name searches).

Use InternetCloseHandle to close the handle returned from InternetOpenUrl. However, note that closing the handle before all the URL data has been read results in the connection being terminated.


FTP Functions

The FTP functions deal with FTP file and directory manipulation and navigation. Applications that use a CERN proxy exclusively must use the InternetOpenUrl function because CERN proxies do not support FTP. For more information on how to use InternetOpenUrl, see Accessing URLs directly.
FtpCreateDirectory
FtpDeleteFile
FtpFindFirstFile
FtpGetCurrentDirectory
FtpGetFile
FtpOpenFile
FtpPutFile
FtpRemoveDirectory
FtpRenameFile
FtpSetCurrentDirectory


FtpCreateDirectory

BOOL FtpCreateDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Creates a new directory on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError. If the error message indicates that the FTP server denied the request to create a directory, use InternetGetLastResponseInfo to determine why.
hFtpSession
Valid handle to an FTP session. This handle must have been returned from a previous call to InternetConnect.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to create on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpCreateDirectory translates the directory name separators to the appropriate character before they are used.


FtpDeleteFile

BOOL FtpDeleteFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszFileName
);

Deletes a file stored on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session. This handle must have been returned from a previous call to InternetConnect.
lpszFileName
Address of a null-terminated string that contains the name of the file to delete on the remote system.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpDeleteFile translates the directory name separators to the appropriate character before they are used.


FtpFindFirstFile

HINTERNET FtpFindFirstFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszSearchFile,
    OUT LPWIN32_FIND_DATA lpFindFileData,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Searches the specified directory of the given FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATA structure.

  • Returns a valid handle for the request if the directory enumeration was started successfully; otherwise, returns NULL. To get a specific error message, call GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.
hFtpSession
Valid handle to an FTP session returned from InternetConnect.
lpszSearchFile
Address of a null-terminated string that specifies a valid directory path or file name for the FTP server's file system. The string can contain wildcards, but no blank spaces are allowed. If the value of lpszSearchFile is NULL or if it is an empty string, it will find the first file in the current directory on the server.
lpFindFileData
Address of a WIN32_FIND_DATA structure that receives information about the found file or directory.
dwFlags
Application-defined value that associates this search with any application. Can be one of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Causes the FTP resource to be reloaded from the server.
dwContext
Application-defined value that associates this search with any application data. This parameter is used only if the application has already called InternetSetStatusCallback to set up a status callback function.

This function enumerates both files and directories.

FtpFindFirstFile is similar to the Win32 FindFirstFile function. Note, however, that only one FtpFindFirstFile can occur at a time within a given FTP session. The enumerations, therefore, are correlated with the FTP session handle. This is because the FTP protocol allows only a single directory enumeration per session.

After calling FtpFindFirstFile and until calling InternetCloseHandle, the application cannot call FtpFindFirstFile again on the given FTP session handle. If a call is made to FtpFindFirstFile on that handle, the function will fail with ERROR_FTP_TRANSFER_IN_PROGRESS.

After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFile function can be used to continue the enumeration.

The InternetCloseHandle function is used to close the handle returned from FtpFindFirstFile. If InternetCloseHandle closes the handle before InternetFindNextFile fails with ERROR_NO_MORE_FILES, the directory enumeration will be terminated.

Because the FTP protocol provides no standard means of enumerating, some of the common information about files, such as file creation date and time, is not always available or correct. When this happens, FtpFindFirstFile and InternetFindNextFile fill in unavailable information with a best guess based on available information. For example, creation and last access dates will often be the same as the file's modification date.

The application cannot call FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.

See also InternetSetStatusCallback


FtpGetCurrentDirectory

BOOL FtpGetCurrentDirectory(
    IN HINTERNET hFtpSession,
    OUT LPSTR lpszCurrentDirectory,
    IN OUT LPDWORD lpdwCurrentDirectory
);

Retrieves the current directory for the specified FTP session.

  • Returns TRUE if successful, or FALSE otherwise. To get the specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session.
lpszCurrentDirectory
Address of a buffer that receives the current directory string, which specifies the absolute path to the current directory. The string is null terminated.
lpdwCurrentDirectory
Address of a variable that specifies the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character. Using a length of MAX_PATH is sufficient for all paths. When the function returns, the variable receives the number of characters copied into the buffer.

If the lpszCurrentDirectory buffer is not large enough, lpdwCurrentDirectory receives the number of bytes required to retrieve the full, current directory name.


FtpGetFile

BOOL FtpGetFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszRemoteFile,
    IN LPCSTR lpszNewFile,
    IN BOOL fFailIfExists,
    IN DWORD dwLocalFlagsAndAttributes,
    IN DWORD dwInternetFlags,
    IN DWORD dwContext
);

Retrieves a file from the FTP server and stores it under the specified file name, creating a new local file in the process.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session.
lpszRemoteFile
Address of a null-terminated string that contains the name of the file to retrieve from the remote system.
lpszNewFile
Address of a null-terminated string that contains the name of the file to create on the local system.
fFailIfExists
Boolean flag that indicates whether the function should proceed if a local file of the specified name already exists. If fFailIfExists is TRUE and the local file exists, FtpGetFile fails.
dwLocalFlagsAndAttributes
File attributes for the new file. Can be any combination of the FILE_ATTRIBUTE_* flags used by the CreateFile function. For more information on FILE_ATTRIBUTE_* attributes, see CreateFile in the Platform SDK.
dwInternetFlags
Flags that control how the function will handle the file download. The first set of flag values indicates the conditions under which the transfer occurs. These transfer type flags can be used in combination with the second set of flags that control caching. The application can select one of these transfer type values:
FTP_TRANSFER_TYPE_ASCII
Transfers the file using FTP's ASCII (Type A) transfer method. Control and formatting information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY
Transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN
Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.
The following flags determine how the caching of this file will be done. Any combination of the following flags can be used with the transfer type flag. The possible values are:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Causes the FTP resource to be reloaded from the server.
dwContext
Application-defined value that associates this search with any application data. This is used only if the application has already called InternetSetStatusCallback to set up a status callback function.

FtpGetFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally. An application that needs to retrieve file data only or that requires close control over the file transfer should use the FtpOpenFile and InternetReadFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents. The default transfer is binary mode, where the file is downloaded in the same format as it is stored on the server.

Both lpszRemoteFile and lpszNewFile can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpGetFile translates the directory name separators to the appropriate character before they are used.


FtpOpenFile

HINTERNET FtpOpenFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszFileName,
    IN DWORD fdwAccess,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Initiates access to a remote file for writing or reading.

  • Returns a handle if successful, or NULL otherwise. To get a specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session.
lpszFileName
Address of a null-terminated string that contains the name of the file to access on the remote system.
fdwAccess
Value that determines how the file will be accessed. This can be GENERIC_READ or GENERIC_WRITE, but not both.
dwFlags
Conditions under which the transfers occur. The application should select one transfer type and any of the flags that control how the caching of the file will be controlled. The transfer type can be any one of the following values:
FTP_TRANSFER_TYPE_ASCII
Transfers the file using FTP's ASCII (Type A) transfer method. Control and formatting information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY
Transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN
Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.

The following values are used to control the caching of the file. The application can use one or more of the following values:

INTERNET_FLAG_DONT_CACHE
Does not cache the data, either locally or in any gateways. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not cache the data, either locally or in any gateways.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Causes the FTP resource to be reloaded from the server.
dwContext
Application-defined value that associates this search with any application data. This is only used if the application has already called InternetSetStatusCallback to set up a status callback function.

FtpOpenFile should be used in the following situations:

  • An application has data it needs to send to an FTP server to be created as a file on the FTP server, but the application does not have a local file containing the data. After the file is opened with FtpOpenFile, the application uses InternetWriteFile to send the FTP file data to the server.
  • An application needs to retrieve a file from the server into application-controlled memory, instead of writing the file to disk. The application uses InternetReadFile after using FtpOpenFile to open the file.
  • An application needs a fine level of control over a file transfer. For example, the application may need to display a progress indicator when downloading a file to indicate to the user that the file transfer is or is not proceeding correctly.

After calling FtpOpenFile and until calling InternetCloseHandle, all other calls to FTP functions on the same FTP session handle will fail and set the error message to ERROR_FTP_TRANSFER_IN_PROGRESS.

Only one file can be open in a single FTP session. Therefore, no file handle is returned and the application simply uses the FTP session handle when necessary.

The lpszFile parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpOpenFile translates the directory name separators to the appropriate character before they are used.

The InternetCloseHandle function is used to close the handle returned from FtpOpenFile. If InternetCloseHandle closes the handle before all the data has been transferred, the transfer is terminated.


FtpPutFile

BOOL FtpPutFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszLocalFile,
    IN LPCSTR lpszNewRemoteFile,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Stores a file on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session.
lpszLocalFile
Address of a null-terminated string that contains the name of the file to send from the local system.
lpszNewRemoteFile
Address of a null-terminated string that contains the name of the file to create on the remote system.
dwFlags
Conditions under which the transfer occurs. Can be any combination of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Performs a conditional download of the file.
INTERNET_FLAG_TRANSFER_ASCII
Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY
Transfers the file as binary.
dwContext
Application-defined value that associates this search with any application data. This parameter is used only if the application has already called InternetSetStatusCallback to set up a status callback.

FtpPutFile is a high-level routine that handles all the bookkeeping and overhead associated with reading a file locally and storing it on an FTP server. An application that needs to send file data only, or that requires close control over the file transfer, should use the FtpOpenFile and InternetWriteFile functions.

If the dwTransferType parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data converts control and formatting characters to local equivalents.

Both lpszNewRemoteFile and lpszLocalFile can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpPutFile translates the directory name separators to the appropriate character before they are used.


FtpRemoveDirectory

BOOL FtpRemoveDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Removes the specified directory on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get the specific error message, call GetLastError. If the error message indicates that the FTP server denied the request to remove a directory, use InternetGetLastResponseInfo to determine why.
hFtpSession
Valid handle to an FTP session.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to remove on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpRemoveDirectory translates the directory name separators to the appropriate character before they are used.


FtpRenameFile

BOOL FtpRenameFile(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszExisting,
    IN LPCSTR lpszNew
);

Renames a file stored on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError.
hFtpSession
Valid handle to an FTP session.
lpszExisting
Address of a null-terminated string that contains the name of the file that will have its name changed on the remote FTP server.
lpszNew
Address of a null-terminated string that contains the new name for the remote file.

The lpszExisting and lpszNew parameters can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpRenameFile translates the directory name separators to the appropriate character before they are used.


FtpSetCurrentDirectory

BOOL FtpSetCurrentDirectory(
    IN HINTERNET hFtpSession,
    IN LPCSTR lpszDirectory
);

Changes to a different working directory on the FTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get the specific error message, call GetLastError. If the error message indicates that the FTP server denied the request to change a directory, use InternetGetLastResponseInfo to determine why.
hFtpSession
Valid handle to an FTP session.
lpszDirectory
Address of a null-terminated string that contains the name of the directory to change to on the remote system. This can be either a fully qualified path or a name relative to the current directory.

An application should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. FtpSetCurrentDirectory translates the directory name separators to the appropriate character before they are used.


Gopher Functions

The Gopher functions described in this section control the creation and use of the Internet Gopher utilities.
GopherAttributeEnumerator
GopherCreateLocator
GopherFindFirstFile
GopherGetAttribute
GopherGetLocatorType
GopherOpenFile


GopherAttributeEnumerator

BOOL GopherAttributeEnumerator(
    LPGOPHER_ATTRIBUTE_TYPE lpAttributeInformation,
    DWORD dwError
);

Defines a callback function that processes attribute information from a Gopher server. This callback function is installed by a call to the GopherGetAttribute function.

  • Returns TRUE to continue the enumeration, or FALSE to immediately stop it. This function is primarily used for returning the results of a Gopher+ ASK item.
lpAttributeInformation
Address of a buffer that contains a single GOPHER_ATTRIBUTE_TYPE structure. The lpBuffer parameter to GopherGetAttribute is used for storing this structure. The lpBuffer size must be equal to or greater than the value of MIN_GOPHER_ATTRIBUTE_LENGTH.
dwError
Error value. This parameter is NO_ERROR if the attribute was parsed and written to the buffer successfully. If a problem was encountered, an error value is returned.


GopherCreateLocator

BOOL GopherCreateLocator(
    IN LPCSTR lpszHost,
    IN INTERNET_PORT nServerPort,
    IN LPCSTR lpszDisplayString,
    IN LPCSTR lpszSelectorString,
    IN DWORD dwGopherType,
    OUT LPCSTR lpszLocator,
    IN OUT LPDWORD lpdwBufferLength
);

Creates a Gopher or Gopher+ locator string from its component parts.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo.
lpszHost
Address of a string that contains the name of the host, or a dotted-decimal IP address (such as 198.105.232.1).
nServerPort
Number of the port on which the Gopher server at lpszHost lives, in host byte order. If nServerPort is INTERNET_INVALID_PORT_NUMBER, the default Gopher port is read from the \etc\services file.
lpszDisplayString
Gopher document or directory to be displayed. If this parameter is NULL, the function returns the default directory for the Gopher server.
lpszSelectorString
Address of the selector string to send to the Gopher server in order to retrieve information. This parameter can be NULL.
dwGopherType
Value that specifies whether lpszSelectorString refers to a directory or document, and whether the request is Gopher+ or Gopher. The default value, GOPHER_TYPE_DIRECTORY, is used if the value of dwGopherType is zero. Can be one of the following values:
GOPHER_TYPE_ASK | Ask+ item.
GOPHER_TYPE_BINARY | Binary file.
GOPHER_TYPE_BITMAP | Bitmap file.
GOPHER_TYPE_CALENDAR | Calendar file.
GOPHER_TYPE_CSO | CSO telephone book server.
GOPHER_TYPE_DIRECTORY | Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE | MS-DOS® archive file.
GOPHER_TYPE_ERROR | Indicator of an error condition.
GOPHER_TYPE_GIF | GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS | Gopher+ item.
GOPHER_TYPE_HTML | HTML document.
GOPHER_TYPE_IMAGE | Image file.
GOPHER_TYPE_INDEX_SERVER | Index server.
GOPHER_TYPE_INLINE | Inline file.
GOPHER_TYPE_MAC_BINHEX | Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE | Movie file.
GOPHER_TYPE_PDF | PDF file.
GOPHER_TYPE_REDUNDANT | Indicator of a duplicated server. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND | Sound file.
GOPHER_TYPE_TELNET | Telnet server.
GOPHER_TYPE_TEXT_FILE | ASCII text file.
GOPHER_TYPE_TN3270 | TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED | UUENCODED file.
GOPHER_TYPE_UNKNOWN | Item type is unknown.
lpszLocator
Address of a buffer that receives the locator string. If lpszLocator is NULL, lpdwBufferLength receives the needed buffer length, but the function performs no other processing.
lpdwBufferLength
Length of the lpszLocator buffer. When the function returns, this parameter receives the number of bytes written to the lpszLocator buffer. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to form the locator successfully.

To retrieve information from a Gopher server, an application must first get a Gopher "locator" from the Gopher server.

The locator, which the application should treat as an opaque token, is normally used for calls to the GopherFindFirstFile function to retrieve a specific piece of information.


GopherFindFirstFile

HINTERNET GopherFindFirstFile(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszSearchString,
    OUT LPGOPHER_FIND_DATA lpFindData,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Uses a Gopher locator and some search criteria to create a session with the server and locate the requested documents, binary files, index servers, or directory trees.

  • Returns a valid search handle if successful, or NULL otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo.
hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Name of the item to locate. Can be one of the following items:
  • Gopher locator returned by a previous call to this function or the InternetFindNextFile function.
  • NULL pointer or zero-length string indicating that the topmost information from a Gopher server is being returned.
  • Locator created by the GopherCreateLocator function.
lpszSearchString
Address of a buffer that contains the strings to search, if this request is to an index server. Otherwise, this parameter should be NULL.
lpFindData
Address of a GOPHER_FIND_DATA structure that receives the information retrieved by this function.
dwFlags
Action flag that can be a combination of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Reloads the FTP resource.
dwContext
Application-defined value that associates this search with any application data.

GopherFindFirstFile closely resembles the Win32 FindFirstFile function. It creates a connection with a Gopher server, and then returns a single structure containing information about the first Gopher object referenced by the locator string.

After calling GopherFindFirstFile to retrieve the first Gopher object in an enumeration, an application can use the InternetFindNextFile function to retrieve subsequent Gopher objects.

Use the InternetCloseHandle function to close the handle returned from GopherFindFirstFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked as closed pending. Any open sessions are terminated, and any data waiting for the caller is discarded. In addition, any allocated buffers are freed.


GopherGetAttribute

BOOL GopherGetAttribute(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszAttributeName,
    OUT LPBYTE lpBuffer,
    IN DWORD dwBufferLength,
    OUT LPDWORD lpdwCharactersReturned,
    IN GOPHER_ATTRIBUTE_ENUMERATOR lpfnEnumerator,
    IN DWORD dwContext
);

Allows an application to retrieve specific attribute information from the server.

  • Returns TRUE if the request is satisfied, or FALSE otherwise. To get extended error information, call GetLastError or InternetGetLastResponseInfo.
hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Address of a string that identifies the item at the Gopher server on which to return attribute information.
lpszAttributeName
Address of a space-delimited string specifying the names of attributes to return. If lpszAttributeName is NULL, GopherGetAttribute returns information about all attributes.
lpBuffer
Address of an application-defined buffer from which attribute information is retrieved.
dwBufferLength
Size, in bytes, of the lpBuffer buffer.
lpdwCharactersReturned
Number of characters read into the lpBuffer buffer.
lpfnEnumerator
Address of a callback function that enumerates each attribute of the locator. This parameter is optional. If it is NULL, all the Gopher attribute information is placed into lpBuffer. If lpfnEnumerator is specified, the callback function is called once for each attribute of the object.
The callback function receives the address of a single GOPHER_ATTRIBUTE_TYPE structure with each call. The enumeration callback function allows the application to avoid having to parse the Gopher attribute information.
dwContext
Application-defined value that associates this operation with any application data.

Generally, applications call this function after calling GopherFindFirstFile or InternetFindNextFile.

The size of the lpBuffer parameter must be equal to or greater than the value of MIN_GOPHER_ATTRIBUTE_LENGTH (currently defined in Wininet.h as 256 bytes).


GopherGetLocatorType

BOOL GopherGetLocatorType(
    IN LPCSTR lpszLocator,
    OUT LPDWORD lpdwGopherType
);

Parses a Gopher locator and determines its attributes.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
lpszLocator
Address of the Gopher locator string to parse.
lpdwGopherType
Address of a variable that receives the type of the locator. The type is a bitmask that consists of a combination of the following values:
GOPHER_TYPE_ASK | Ask+ item.
GOPHER_TYPE_BINARY | Binary file.
GOPHER_TYPE_BITMAP | Bitmap file.
GOPHER_TYPE_CALENDAR | Calendar file.
GOPHER_TYPE_CSO | CSO telephone book server.
GOPHER_TYPE_DIRECTORY | Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE | MS-DOS archive file.
GOPHER_TYPE_ERROR | Indicator of an error condition.
GOPHER_TYPE_GIF | GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS | Gopher+ item.
GOPHER_TYPE_HTML | HTML document.
GOPHER_TYPE_IMAGE | Image file.
GOPHER_TYPE_INDEX_SERVER | Index server.
GOPHER_TYPE_INLINE | Inline file.
GOPHER_TYPE_MAC_BINHEX | Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE | Movie file.
GOPHER_TYPE_PDF | PDF file.
GOPHER_TYPE_REDUNDANT | Indicator of a duplicated server. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND | Sound file.
GOPHER_TYPE_TELNET | Telnet server.
GOPHER_TYPE_TEXT_FILE | ASCII text file.
GOPHER_TYPE_TN3270 | TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED | UUENCODED file.
GOPHER_TYPE_UNKNOWN | Item type is unknown.

GopherGetLocatorType returns information about the item referenced by a Gopher locator. Note that it is possible for multiple attributes to be set on a file. For example, both GOPHER_TYPE_TEXT_FILE and GOPHER_TYPE_GOPHER_PLUS are set for a text file stored on a Gopher+ server.


GopherOpenFile

HINTERNET GopherOpenFile(
    IN HINTERNET hGopherSession,
    IN LPCSTR lpszLocator,
    IN LPCSTR lpszView,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Begins reading a Gopher data file from a Gopher server.

  • Returns a handle if successful, or NULL if the file cannot be opened. To get extended error information, call GetLastError or InternetGetLastResponseInfo.
hGopherSession
Handle to a Gopher session returned by InternetConnect.
lpszLocator
Address of a string that identifies the file to open. Generally, this locator is returned from a call to GopherFindFirstFile or InternetFindNextFile. Because the Gopher protocol has no concept of a current directory, the locator is always fully qualified.
lpszView
Address of a string that describes the view to open if several views of the file exist at the server. If lpszView is NULL, the function uses the default file view.
dwFlags
Conditions under which subsequent transfers occur. Can be any combination of the following values:
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Causes the Gopher resource to be reloaded from the server.
dwContext
Application-defined value that associates this operation with any application data.

GopherOpenFile opens a file at a Gopher server. Because a file cannot actually be opened or locked at a server, this function simply associates location information with a handle that an application can use for file-based operations such as InternetReadFile or GopherGetAttribute.

Use the InternetCloseHandle function to close the handle returned from GopherOpenFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked as closed pending. Any open sessions are terminated, and any data waiting for the caller is discarded. In addition, any allocated buffers are freed.

See also InternetOpenUrl


HTTP Functions

The HTTP functions described in this section control the transmission and content of HTTP requests.
HttpAddRequestHeaders
HttpEndRequest
HttpOpenRequest
HttpQueryInfo
HttpSendRequest
HttpSendRequestEx


HttpAddRequestHeaders

BOOL HttpAddRequestHeaders(
    IN HINTERNET hHttpRequest,
    IN LPCSTR lpszHeaders,
    IN DWORD dwHeadersLength,
    IN DWORD dwModifiers
);

Adds one or more HTTP request headers to the HTTP request handle.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hHttpRequest
Open HTTP request handle returned by HttpOpenRequest.
lpszHeaders
Headers to append to the request. Each header must be terminated by a CR/LF (carriage return/line feed) pair.
dwHeadersLength
Length, in characters, of lpszHeaders. If this parameter is -1L, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is computed.
dwModifiers
Values used to modify the semantics of this function. Can be a combination of the following values:
HTTP_ADDREQ_FLAG_ADD
Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW
Adds the header only if it does not already exist; otherwise, an error is returned.
HTTP_ADDREQ_FLAG_COALESCE
Coalesces headers of the same name.
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA
Coalesces headers of the same name. For example, adding "Accept: text/*" followed by "Accept: audio/*" with this flag results in the formation of the single header "Accept: text/*, audio/*". This causes the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON
Coalesces headers of the same name using a semicolon.
HTTP_ADDREQ_FLAG_REPLACE
Replaces or removes a header. If the header value is empty and the header is found, it is removed. If not empty, the header value is replaced.

HttpAddRequestHeaders appends additional, free-format headers to the HTTP request handle and is intended for use by sophisticated clients that need detailed control over the exact request sent to the HTTP server.

Note that for basic HttpAddRequestHeaders, the application can pass in multiple headers in a single buffer. If the application is trying to remove or replace a header, only one header can be supplied in lpszHeaders.

See also HttpSendRequest


HttpEndRequest

HttpEndRequest(
    IN HINTERNET hRequest,
    OUT LPINTERNET_BUFFERS lpBuffersOut,
    IN DWORD dwFlags,
    IN DWORD dwContext
    );

Ends an HTTP request.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hRequest
HINTERNET handle returned by HttpOpenRequest and sent by HttpSendRequestEx.
lpBuffersOut
Address of an INTERNET_BUFFERS structure.
dwFlags
Can be one of the following values:
HSR_ASYNC | Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC | Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE | Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD | Download resource to file.
HSR_CHUNKED | Send chunked data.
dwContext
Double-word variable that contains the context value to use in asynchronous operations.


HttpOpenRequest

HINTERNET HttpOpenRequest(
    IN HINTERNET hHttpSession,
    IN LPCSTR lpszVerb,
    IN LPCSTR lpszObjectName,
    IN LPCSTR lpszVersion,
    IN LPCSTR lpszReferer,
    IN LPCSTR FAR * lpszAcceptTypes,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Opens an HTTP request handle.

  • Returns a valid (non-NULL) HTTP request handle if successful, or NULL otherwise. To get extended error information, call GetLastError.
hHttpSession
Handle to an HTTP session returned by InternetConnect.
lpszVerb
Address of a string that contains the verb to use in the request. If this parameter is NULL, the function uses "GET" as the verb.
lpszObjectName
Address of a string that contains the name of the target object of the specified verb. This is generally a file name, an executable module, or a search specifier.
lpszVersion
Address of a string that contains the HTTP version. If this parameter is NULL, the function uses "HTTP/1.0" as the version.
lpszReferer
Address of a string that specifies the address (URL) of the document from which the URL in the request (lpszObjectName) was obtained. If this parameter is NULL, no "referrer" is specified.
lpszAcceptTypes
Address of a null-terminated array of LPCSTR pointers indicating content types accepted by the client. If this parameter is NULL, no types are accepted by the client. Servers interpret a lack of accept types to indicate that the client accepts only documents of type "text/*" (that is, only text documents, and not pictures or other binary files).
dwFlags
Internet flag values. Can be any of the following values:
INTERNET_FLAG_CACHE_IF_NET_FAIL
Return the resource from the cache if the network request for the resource fails due to an ERROR_INTERNET_CONNECTION_RESET or ERROR_INTERNET_CANNOT_CONNECT.
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs.
INTERNET_FLAG_KEEP_CONNECTION
Uses keep-alive semantics, if available, for the connection. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_AUTH
Does not attempt authentication automatically.
INTERNET_FLAG_NO_AUTO_REDIRECT
Does not automatically handle redirection in HttpSendRequest.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache.
INTERNET_FLAG_NO_COOKIES
Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database.
INTERNET_FLAG_NO_UI
Disables the cookie dialog box.
INTERNET_FLAG_PRAGMA_NOCACHE
Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
INTERNET_FLAG_READ_PREFETCH
This flag is currently disabled.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
Reloads HTTP resources if the resource has been modified since the last time it was downloaded.
INTERNET_FLAG_SECURE
Uses SSL/PCT transaction semantics.
dwContext
Application-defined value that associates this operation with any application data.

HttpOpenRequest creates a new HTTP request handle and stores the specified parameters in that handle. An HTTP request handle holds a request to be sent to an HTTP server and contains all RFC822/MIME/HTTP headers to be sent as part of the request.

Use the InternetCloseHandle function to close the handle returned by HttpOpenRequest. InternetCloseHandle cancels all outstanding I/O on the handle.

The lpszReferer parameter to InternetOpen is used as the referrer for the HTTP request.

See also HttpAddRequestHeaders, HttpQueryInfo, InternetReadFile


HttpQueryInfo

BOOL HttpQueryInfo(
    IN HINTERNET hHttpRequest,
    IN DWORD dwInfoLevel,
    IN LPVOID lpvBuffer,
    IN LPDWORD lpdwBufferLength,
    IN OUT LPDWORD lpdwIndex,
);

Queries for information about an HTTP request.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hHttpRequest
Open HTTP request handle returned by HttpOpenRequest or InternetOpenUrl.
dwInfoLevel
Combination of the attribute to query and the flags that modify the request. The attributes can be any of the following values:
HTTP_QUERY_ACCEPT
Retrieves the acceptable media types for the response.
HTTP_QUERY_ACCEPT_CHARSET
Retrieves the acceptable character sets for the response.
HTTP_QUERY_ACCEPT_ENCODING
Retrieves the acceptable content-coding values for the response.
HTTP_QUERY_ACCEPT_LANGUAGE
Retrieves the acceptable natural languages for the response.
HTTP_QUERY_ACCEPT_RANGES
Retrieves the types of range requests that are accepted for a resource.
HTTP_QUERY_AGE
Retrieves the Age response-header field, which contains the sender's estimate of the amount of time since the response was generated at the origin server.
HTTP_QUERY_ALLOW
Receives the methods supported by the server.
HTTP_QUERY_AUTHORIZATION
Retrieves the authorization credentials used for a request.
HTTP_QUERY_CACHE_CONTROL
Retrieves the cache control directives.
HTTP_QUERY_CONNECTION
Retrieves any options that are specified for a particular connection and must not be communicated by proxies over further connections.
HTTP_QUERY_COOKIE
Retrieves any cookies associated with the request.
HTTP_QUERY_CONTENT_BASE
Retrieves the base URI for resolving relative URLs within the entity.
HTTP_QUERY_CONTENT_DESCRIPTION
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_CONTENT_DISPOSITION
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_CONTENT_ENCODING
Receives any additional content codings that have been applied to the entire resource.
HTTP_QUERY_CONTENT_ID
Receives the content identification.
HTTP_QUERY_CONTENT_LANGUAGE
Receives the language that the content is in.
HTTP_QUERY_CONTENT_LENGTH
Receives the size of the resource, in bytes.
HTTP_QUERY_CONTENT_LOCATION
Retrieves the resource location for the entity enclosed in the message.
HTTP_QUERY_CONTENT_MD5
Retrieves a MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) for the entity-body. For more information, see RFC1864, The Content-MD5 Header Field, at http://ds.internic.net/rfc/rfc1864.txt External Link for more information.
HTTP_QUERY_CONTENT_RANGE
Retrieves the location in the full entity-body where the partial entity-body should be inserted and the total size of the full entity-body.
HTTP_QUERY_CONTENT_TRANSFER_ENCODING
Receives the additional content coding that has been applied to the resource.
HTTP_QUERY_CONTENT_TYPE
Receives the content type of the resource (such as text/html).
HTTP_QUERY_COST
No longer implemented.
HTTP_QUERY_DATE
Receives the date and time at which the message was originated.
HTTP_QUERY_DERIVED_FROM
No longer supported.
HTTP_QUERY_ETAG
Retrieves the entity tag for the associated entity.
HTTP_QUERY_EXPIRES
Receives the date and time after which the resource should be considered outdated.
HTTP_QUERY_FORWARDED
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_FROM
Retrieves the e-mail address for the human user who controls the requesting user agent if the From header is given.
HTTP_QUERY_HOST
Retrieves the Internet host and port number of the resource being requested.
HTTP_QUERY_IF_MATCH
Retrieves the contents of the If-Match request-header field.
HTTP_QUERY_IF_MODIFIED_SINCE
Retrieves the contents of the If-Modified-Since header.
HTTP_QUERY_IF_NONE_MATCH
Retrieves the contents of the If-None-Match request-header field.
HTTP_QUERY_IF_RANGE
Retrieves the contents of the If-Range request-header field. This header allows the client application to check if the entity related to a partial copy of the entity in the client application's cache has not been updated. If the entity has not been updated, send the parts that the client application is missing. If the entity has been updated, send the entire updated entity.
HTTP_QUERY_IF_UNMODIFIED_SINCE
Retrieves the contents of the If-Unmodified-Since request-header field.
HTTP_QUERY_LINK
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_LAST_MODIFIED
Receives the date and time at which the server believes the resource was last modified.
HTTP_QUERY_LOCATION
Retrieves the absolute URI used in a Location response-header.
HTTP_QUERY_MAX
Retrieves the maximum value of an HTTP_QUERY_* value.
HTTP_QUERY_MAX_FORWARDS
Retrieves the number of proxies or gateways that can forward the request to the next inbound server.
HTTP_QUERY_MESSAGE_ID
No longer implemented.
HTTP_QUERY_MIME_VERSION
Receives the version of the MIME protocol that was used to construct the message.
HTTP_QUERY_ORIG_URI
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_PRAGMA
Receives the implementation-specific directives that may apply to any recipient along the request/response chain.
HTTP_QUERY_PROXY_AUTHENTICATE
Retrieves the authentication scheme and realm returned by the proxy.
HTTP_QUERY_PROXY_AUTHORIZATION
Retrieves the header that is used to identify the user to a proxy that requires authentication.
HTTP_QUERY_PUBLIC
Receives methods available at this server.
HTTP_QUERY_RANGE
Retrieves the byte range of an entity.
HTTP_QUERY_RAW_HEADERS
Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.
HTTP_QUERY_RAW_HEADERS_CRLF
Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.
HTTP_QUERY_REFERER
Receives the URI of the resource where the requested URI was obtained.
HTTP_QUERY_REFRESH
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_REQUEST_METHOD
Receives the verb that is being used in the request, typically GET or POST.
HTTP_QUERY_RETRY_AFTER
Retrieves the amount of time the service is expected to be unavailable.
HTTP_QUERY_SERVER
Retrieves information about the software used by the origin server to handle the request.
HTTP_QUERY_SET_COOKIE
Receives the value of the cookie set for the request.
HTTP_QUERY_STATUS_CODE
Receives the status code returned by the server. For a list of possible values, see HTTP Status Codes.
HTTP_QUERY_STATUS_TEXT
Receives any additional text returned by the server on the response line.
HTTP_QUERY_TITLE
Obsolete. Maintained for legacy application compatibility only.
HTTP_QUERY_TRANSFER_ENCODING
Retrieves the type of transformation that has been applied to the message body so it can be safely transferred between the sender and recipient.
HTTP_QUERY_UPGRADE
Retrieves the additional communication protocols that are supported by the server.
HTTP_QUERY_URI
Receives some or all of the Uniform Resource Identifiers (URIs) by which the Request-URI resource can be identified.
HTTP_QUERY_USER_AGENT
Retrieves information about the user agent that made the request.
HTTP_QUERY_VARY
Retrieves the header that indicates that the entity was selected from a number of available representations of the response using server-driven negotiation.
HTTP_QUERY_VERSION
Receives the last response code returned by the server.
HTTP_QUERY_VIA
Retrieves the intermediate protocols and recipients between the user agent and the server on requests, and between the origin server and the client on responses.
HTTP_QUERY_WARNING
Retrieves additional information about the status of a response that may not be reflected by the response status code.
HTTP_QUERY_WWW_AUTHENTICATE
Retrieves the authentication scheme and realm returned by the server.

The following modifiers can be used with the information values:

HTTP_QUERY_CUSTOM
Causes HttpQueryInfo to search for the header name specified in lpvBuffer and store the header information in lpvBuffer.
HTTP_QUERY_FLAG_COALESCE
Combines the values from headers with the same name into the output buffer.
HTTP_QUERY_FLAG_NUMBER
Returns the data as a 32-bit number for headers whose value is a number, such as the status code.
HTTP_QUERY_FLAG_REQUEST_HEADERS
Queries request headers only.
HTTP_QUERY_FLAG_SYSTEMTIME
Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".
lpvBuffer
Address of the buffer that receives the information.
lpdwBufferLength
Address of a value that contains the length of the data buffer. When the function returns, this parameter contains the address of a value specifying the length of the information written to the buffer. When the function returns strings, the following rules apply:
  • If the function succeeds, lpdwBufferLength specifies the length of the string, in characters, minus 1 for the terminating null.
  • If the function fails and ERROR_INSUFFICIENT_BUFFER is returned, lpdwBufferLength specifies the number of bytes that the application must allocate to receive the string.
lpdwIndex
Address of a zero-based header index used to enumerate multiple headers with the same name. When calling the function, this parameter is the index of the specified header to return. When the function returns, this parameter is the index of the next header. If the next index cannot be found, ERROR_HTTP_HEADER_NOT_FOUND is returned.

HttpQueryInfo is used to return response or request headers from an HTTP request.

You can retrieve different types of data from HttpQueryInfo:

  • strings (default)
  • SYSTEMTIME (for Data: Expires:, headers)
  • DWORD (for STATUS_CODE, CONTENT_LENGTH, and so on if HTTP_QUERY_INFO_NUMBER has been used)

See also HttpOpenRequest


HttpSendRequest

BOOL HttpSendRequest(
    IN HINTERNET hHttpRequest,
    IN LPCSTR lpszHeaders,
    IN DWORD dwHeadersLength,
    IN LPVOID lpOptional,
    DWORD dwOptionalLength
);

Sends the specified request to the HTTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hHttpRequest
Open HTTP request handle returned by HttpOpenRequest.
lpszHeaders
Additional headers to be appended to the request. This parameter can be NULL if there are no additional headers to append.
dwHeadersLength
Length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is calculated.
lpOptional
Address of any optional data to send immediately after the request headers. This parameter is generally used for POST and PUT operations. The optional data can be the resource or information being posted to the server. This parameter can be NULL if there is no optional data to send.
dwOptionalLength
Length, in bytes, of the optional data. This parameter can be zero if there is no optional data to send.

HttpSendRequest sends the specified request to the HTTP server and allows the client to specify additional headers to send along with the request.

The function also lets the client specify optional data to send to the HTTP server immediately following the request headers. This feature is generally used for "write" operations such as PUT and POST.

After the request is sent, the status code and response headers from the HTTP server are read. These headers are maintained internally and are available to client applications through the HttpQueryInfo function.

An application can use the same HTTP request handle in multiple calls to HttpSendRequest, but the application must read all data returned from the previous call before calling the function again.

See also InternetReadFile


HttpSendRequestEx

BOOL HttpSendRequestEx(
    IN HINTERNET hRequest,
    IN LPINTERNET_BUFFERS lpBuffersIn,
    OUT LPINTERNET_BUFFERS lpBuffersOut,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Sends the specified request to the HTTP server.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hRequest
HINTERNET handle returned by HttpOpenRequest.
lpBuffersIn
Optional. Address of an INTERNET_BUFFERS structure.
lpBuffersOut
Optional. Address of an INTERNET_BUFFERS structure.
dwFlags
Can be one of the following values:
HSR_ASYNC | Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC | Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE | Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD | Download resource to file.
HSR_CHUNKED | Send chunked data.
dwContext
DWORD variable that contains the context value to use in asynchronous operations.


Cookie Functions

Cookies are the means by which, under HTTP protocol, a server or a script can maintain state information on the client workstation. The Win32 Internet functions have implemented a persistent cookie database for this purpose. Cookie functions are provided for users of Win32 Internet functions to set cookies into, and access them from, the cookie database. The caller of these functions should be familiar with cookies as outlined in ftp://ds.internic.net/internet-drafts/draft-ietf-http-state-mgmt-*.txt. Please note that the implementation of these functions is evolving; be cautious when using them.
InternetGetCookie
InternetSetCookie


InternetGetCookie

BOOL InternetGetCookie(
    IN  LPCSTR lpszUrlName,
    IN  LPCSTR lpszCookieName,
    OUT LPSTR lpszCookieData,
    IN OUT LPDWORD  lpdwSize
);

Returns the cookie for the specified URL.

  • Returns TRUE if successful, or FALSE otherwise. To get the specific error value, call GetLastError. The following error values apply to InternetGetCookie:
    ERROR_NO_MORE_ITEMS | There is no cookie for the specified URL and all its parents.
    ERROR_INSUFFICIENT_BUFFER | The value passed in lpdwSize is insufficient to copy all the cookie data. The value returned in lpdwSize is the size of the buffer necessary to get all the data.
lpszUrlName
Address of a string that contains the URL to get cookies for.
lpszCookieName
Address of the name of the cookie to get for the specified URL. This has not been implemented in this release.
lpszCookieData
Address of the buffer that receives the cookie data. This value can be NULL.
lpdwSize
Address of a variable that specifies the size of the lpszCookieData buffer. If the function succeeds, the buffer receives the amount of data copied to the lpszCookieData buffer. If lpszCookieData is NULL, this parameter receives a value that specifies the size of the buffer necessary to copy all the cookie data.

InternetGetCookie does not require a call to InternetOpen. InternetGetCookie checks in the windows\cookies directory for cookies and searches memory for any cookies that do not have an expiration date, since these cookies are not written to any files. Rules for creating cookie files are internal to Win32 Internet functions and may change in the future.


InternetSetCookie

BOOL InternetSetCookie(
    IN LPCSTR lpszUrlName,
    IN LPCSTR lpszCookieName,
    IN LPCSTR lpszCookieData
);

Sets a cookie on the specified URL.

  • Returns TRUE if successful, or FALSE otherwise. To get the specific error message, call GetLastError.
lpszUrlName
Address of a null-terminated string that specifies the URL for which the cookie should be set.
lpszCookieName
Address of a string that contains the name to associate with the cookie. If this parameter is NULL, no name is associated with the cookie.
lpszCookieData
Address of the actual data to associate with the URL.

Creating a new cookie might cause a dialog box to appear on the screen if the appropriate registry value, AllowCookies, is set. There is no way to change the registry value from a Win32 Internet function.


Persistent URL Cache Functions

This section describes the functions used by applications that need persistent caching services. These functions allow an application to save data in the local file system for subsequent use, such as in situations where access to the data is over a low bandwidth link, or the access is not available at all. The calling program that inserts data into the persistent cache assigns a source name that is used to do operations such as retrieve the data, set and get some properties on the data, and delete data.

The protocols implemented in Win32 Internet functions use the cache functions to provide persistent caching and offline browsing. Unless explicitly specified not to cache through the INTERNET_FLAG_NO_CACHE_WRITE flag, Win32 Internet functions cache all data downloaded from the network. The responses to POST data are not cached.
CommitUrlCacheEntry
CreateUrlCacheEntry
CreateUrlCacheGroup
DeleteUrlCacheEntry
DeleteUrlCacheEntry
FindCloseUrlCache
FindFirstUrlCacheEntry
FindFirstUrlCacheEntryEx
FindNextUrlCacheEntry
FindNextUrlCacheEntryEx
GetUrlCacheEntryInfo
GetUrlCacheEntryInfoEx
ReadUrlCacheEntryStream
RetrieveUrlCacheEntryFile
RetrieveUrlCacheEntryStream
SetUrlCacheEntryGroup
SetUrlCacheEntryInfo
UnlockUrlCacheEntryFile
UnlockUrlCacheEntryStream


CommitUrlCacheEntry

BOOL CommitUrlCacheEntry(
    IN LPCSTR lpszUrlName,
    IN LPCSTR lpszLocalFileName,
    IN FILETIME ExpireTime,
    IN FILETIME LastModifiedTime,
    IN DWORD CacheEntryType,
    IN LPCBYTE lpHeaderInfo,
    IN DWORD dwHeaderSize,
    IN LPCSTR lpszFileExtension,
    IN DWORD dwReserved
    );

Caches data in the specified file in the cache storage and associates it with the given URL.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_DISK_FULL | The cache storage is full.
    ERROR_FILE_NOT_FOUND | The specified local file is not found.
lpszUrlName
Address of a string that contains the source name of the cache entry. The name string must be unique, and should not contain any escape characters.
lpszLocalFileName
Address of a string that contains the name of the local file that is being cached. This should be the same name as that returned by CreateUrlCacheEntry.
ExpireTime
FILETIME structure that contains the expire date and time (GMT) of the file that is being cached. If the expire date and time is unknown, set this parameter to zero.
LastModifiedTime
FILETIME structure that contains the last modified date and time (GMT) of the URL that is being cached. If the last modified date and time is unknown, set this parameter to zero.
CacheEntryType
Cache type bitmask. Currently, the cache entry type values have not been finalized, so this value does not serve a real purpose at this point, except for STICK_CACHE_ENTRY. Can be a combination of the following values:
COOKIE_CACHE_ENTRY
NORMAL_CACHE_ENTRY
OCX_CACHE_ENTRY
SPARSE_CACHE_ENTRY
STABLE_CACHE_ENTRY
STICKY_CACHE_ENTRY
TRACK_CACHE_ENTRY
TRACK_OFFLINE_CACHE_ENTRY
TRACK_ONLINE_CACHE_ENTRY
URLHISTORY_CACHE_ENTRY

The STICKY_CACHE_ENTRY type is used to make cache entries exempt from scavenging. The default exempt time for entries set using CommitUrlCacheEntry is one day. The exempt time can be changed using the SetUrlCacheEntryInfo function.

lpHeaderInfo
Address of the header information. If this parameter is not NULL, the header information is treated as extended attributes of the URL and is returned in the INTERNET_CACHE_ENTRY_INFO structure.
dwHeaderSize
Size of the header information. If lpHeaderInfo is not NULL, this value is assumed to indicate the size of the header information. An application can maintain headers as part of the data and provide dwHeaderSize together with a NULL value for lpHeaderInfo.
lpszFileExtension
Address of a buffer that contains information maintained in the cache database for future use. In this version of Win32 Internet functions, this information is not used.
dwReserved
Reserved. If redirection has taken place, this parameter should contain the address of a string containing the original URL. Otherwise, must be set to zero.

If the cache storage is full, CommitUrlCacheEntry invokes cache cleanup to make space for this new file. If the cache entry already exists, the function overwrites the entry if it is not in use. An entry is in use when it has been retrieved with either RetrieveUrlCacheEntryStream or RetrieveUrlCacheEntryFile.

Clients who add entries to the cache should set the headers to at least "HTTP/1.0 200 OK\r\n\r\n"; otherwise, Microsoft Internet Explorer and other WinInet clients will disregard the entry.


CreateUrlCacheEntry

BOOL CreateUrlCacheEntry(
    IN LPCSTR lpszUrlName,
    IN DWORD dwExpectedFileSize,
    IN LPCSTR lpszFileExtension,
    OUT LPSTR lpszFileName,
    IN DWORD dwReserved
);

Creates a local file name for saving the cache entry corresponding to the source name and the file extension.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
lpszUrlName
String value that contains the name of the URL. The string should not contain any escape characters.
dwExpectedFileSize
Unsigned long integer value that contains the expected size of the file needed to store the data corresponding to the source entity. If the expected size is unknown, set this value to zero.
lpszFileExtension
String that contains an extension name of the file in the local storage.
lpszFileName
Address of a buffer that receives the file name. The buffer should be large enough (MAX_PATH) to store the path of the created file.
dwReserved
Reserved; must be zero.

After CreateUrlCacheEntry is called, the application can write directly into the file in local storage. When the file is completely received, the caller should call CommitUrlCacheEntry to commit the entry in the cache.


CreateUrlCacheGroup

GROUPID CreateUrlCacheGroup (
    IN DWORD dwFlags,
    IN LPVOID lpReserved
);

Generates cache group identifications.

  • Returns a valid GROUPID if successful, or FALSE otherwise. To get specific error information, use GetLastError.
dwFlags
DWORD value that contains the flags to control the creation of the cache group. No flags are currently implemented. Must be set to zero.
lpReserved
Reserved. Must be set to NULL.


DeleteUrlCacheEntry

BOOL DeleteUrlCacheEntry(
    IN LPCSTR lpszUrlName
);

Removes the file associated with the source name from the cache, if the file exists.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_ACCESS_DENIED | The file is locked or in use. The entry will be marked and will be deleted when the file is unlocked.
    ERROR_FILE_NOT_FOUND | The file is not in the cache.
lpszUrlName
Address of a string that contains the name of the source corresponding to the cache entry.


DeleteUrlCacheGroup

BOOLAPI DeleteUrlCacheGroup (
    IN GROUPID GroupId,
    IN DWORD dwFlags,
    IN LPVOID lpReserved
);

Releases a GROUPID and any associated state in the cache index file.

  • Returns TRUE if successful, or FALSE otherwise. To get specific error information, use GetLastError.
GroupId
GROUPID value that is associated with the cache group to be released.
dwFlags
DWORD value containing the flags to control the cache group deletion. No flags are currently implemented. Must be set to zero.
lpReserved
Reserved. Must be set to NULL.


FindCloseUrlCache

BOOL FindCloseUrlCache(
    IN HANDLE hEnumHandle
);

Closes the specified enumeration handle.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hEnumHandle
Handle returned by a previous call to the FindFirstUrlCacheEntry function.


FindFirstUrlCacheEntry

HANDLE FindFirstUrlCacheEntry (
    IN LPCSTR lpszUrlSearchPattern,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
    IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize
);

Begins the enumeration of the cache.

  • Returns a handle that the application can use in the FindNextUrlCacheEntry function to retrieve subsequent entries in the cache. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

    ERROR_INSUFFICIENT_BUFFER indicates that the size of lpFirstCacheEntryInfo as specified by lpdwFirstCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwFirstCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.

lpszUrlSearchPattern
Address of a string that contains the source name pattern to search for. Can be set to "cookie:" or "visited:" to enumerate the cookies and URL History entries in the cache. If this parameter is NULL, the function uses *.*.
lpFirstCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure.
lpdwFirstCacheEntryInfoBufferSize
Address of a variable that specifies the size of the lpFirstCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.

FindFirstUrlCacheEntry and FindNextUrlCacheEntry return variable size information. If ERROR_INSUFFICIENT_BUFFER is returned, the application should allocate a buffer of the size specified by lpdwFirstCacheEntryInfoBufferSize. For more information, see Appendix B: Using Buffers in the Win32 Internet Functions Overview.


FindFirstUrlCacheEntryEx

HANDLE FindFirstUrlCacheEntryEx (
    IN LPCSTR lpszUrlSearchPattern,
    IN DWORD dwFlags,
    IN DWORD dwFilter,
    IN GROUPID GroupId
    OUT LPINTERNET_CACHE_ENTRY_INFO  lpFirstCacheEntryInfo,
    IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize,
    OUT LPVOID lpGroupAttributes,
    IN OUT LPDWORD pcbGroupAttributes,
    IN LPVOID lpReserved
);

Starts a filtered enumeration of the cache.

  • Returns a valid handle if successful, or NULL otherwise. To get specific error information, use GetLastError. If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.
lpszUrlSearchPattern
String value containing the search pattern. Search patterns are currently not supported, so the value must be set to NULL to indicate all entries with the matching GROUPID.
dwFlags
DWORD value containing the flags controlling the enumeration. No flags are currently implemented. Must be set to zero.
dwFilter
DWORD value that indicates the cache entry types that are allowed. Can be any combination of cache entry types:
NORMAL_CACHE_ENTRY | Normal cache entry; can be deleted to recover space for new entries.
SPARSE_CACHE_ENTRY | Not currently implemented.
STABLE_CACHE_ENTRY | Not currently implemented.
STICKY_CACHE_ENTRY | Not currently implemented.

The following list contains the values that indicate what is being cached. Can be one of the following values:
COOKIE_CACHE_ENTRY | Cookie cache entry.
OCX_CACHE_ENTRY | Not currently implemented.
URLHISTORY_CACHE_ENTRY | Visited link cache entry.

GroupId
GROUPID value indicating the cache group to enumerate. Set the value to zero to enumerate all entries that are not grouped.
lpFirstCacheEntryInfo
Address of the buffer to hold the INTERNET_CACHE_ENTRY_INFO structure that the cache entry information will be stored in.
lpdwFirstCacheEntryInfoBufferSize
Address of a DWORD value that indicates the size of lpFirstCacheEntryInfo.
lpGroupAttributes
Must be set to NULL.
pcbGroupAttributes
Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.

At the end of the enumeration, the application should call FindCloseUrlCache.


FindNextUrlCacheEntry

BOOL FindNextUrlCacheEntry(
    IN HANDLE hEnumHandle,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpNextCacheEntryInfo,
    IN OUT LPWORD lpdwNextCacheEntryInfoBufferSize
);

Retrieves the next entry in the cache.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_INSUFFICIENT_BUFFER | The size of lpNextCacheEntryInfo as specified by lpdwNextCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwNextCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.
    ERROR_NO_MORE_ITEMS | The enumeration completed.
hEnumHandle
Enumeration handle obtained from a previous call to FindFirstUrlCacheEntry.
lpNextCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwNextCacheEntryInfoBufferSize
Address of a variable that specifies the size of the lpNextCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.


FindNextUrlCacheEntryEx

BOOLAPI FindNextUrlCacheEntryEx (
    IN HANDLE hEnumHandle,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpFirstCacheEntryInfo,
    IN OUT LPDWORD lpdwFirstCacheEntryInfoBufferSize,
    OUT LPVOID lpGroupAttributes,
    IN OUT LPDWORD pcbGroupAttributes,
    IN LPVOID lpReserved
);

Finds the next cache entry in a cache enumeration started by FindFirstUrlCacheEntryEx.

  • Returns TRUE if successful, FALSE otherwise. To get specific error information, use GetLastError.
hEnumHandle
HANDLE type value returned by FindFirstUrlCacheEntryEx, which started a cache enumeration.
lpFirstCacheEntryInfo
Address of the buffer to hold the INTERNET_CACHE_ENTRY_INFO structure that the cache entry information will be stored in.
lpdwFirstCacheEntryInfoBufferSize
Address of a DWORD value that indicates the size of the buffer.
lpGroupAttributes
Must be set to NULL.
pcbGroupAttributes
Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.

At the end of the enumeration, the application should call FindCloseUrlCache.


GetUrlCacheEntryInfo

BOOL GetUrlCacheEntryInfo(
    IN LPCSTR lpszUrlName,
    IN LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN OUT LPDWORD lpdwCacheEntryInfoBufferSize
);

Retrieves information about a cache entry.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_FILE_NOT_FOUND | The specified cache entry is not found in the cache.
    ERROR_INSUFFICIENT_BUFFER | The size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.
lpszUrlName
Address of a string that contains the name of the cache entry. The name string should not contain any escape characters.
lpCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwCacheEntryInfoBufferSize
Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.

GetUrlCacheEntryInfo does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL http://example.com/example.htm#sample was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.


GetUrlCacheEntryInfoEx

BOOL GetUrlCacheEntryInfoEx(
    IN LPCSTR lpszUrl,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN OUT LPDWORD lpdwCacheEntryInfoBufSize,
    OUT LPSTR lpszReserved,
    IN OUT LPDWORD lpdwReserved,
    LPVOID lpReserved,
    DWORD dwFlags
);

Searches for the URL after translating any cached redirections that would be applied in offline mode by HttpSendRequest.

  • Returns TRUE if the URL was located, or FALSE otherwise. Call GetLastError for specific error information. Possible errors include:
    ERROR_FILE_NOT_FOUND | The URL, after taking any cached redirections into account, was not found in the cache index.
    ERROR_INSUFFICIENT_BUFFER | One or more of the buffers (lpCacheEntryInfo and lpszRedirectUrl) supplied was not large enough to hold the requested information. The size of the buffer needed will be returned to lpdwCacheEntryInfoBufSize and lpdwRedirectUrlSize.
lpszUrl
Address of a string that contains the name of the cache entry. The name string should not contain any escape characters.
lpCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwCacheEntryInfoBufSize
Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.
lpszReserved
Reserved. Must be set to NULL.
lpdwReserved
Reserved. Must be set to NULL.
lpReserved
Reserved. Must be set to NULL.
dwFlags
Reserved. Must be set to zero.


ReadUrlCacheEntryStream

BOOL ReadUrlCacheEntryStream(
    IN HANDLE hUrlCacheStream,
    IN  DWORD dwLocation,
    IN OUT LPVOID lpBuffer,
    IN OUT LPDWORD lpdwLen,
    IN DWORD dwReserved
    );

Reads the cached data from a stream that has been opened using the RetrieveUrlCacheEntryStream function.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hUrlCacheStream
Handle that was returned by the RetrieveUrlCacheEntryStream function.
dwLocation
Offset to read from.
lpBuffer
Address of a buffer that receives the data.
lpdwLen
Address of a variable that specifies the length of the lpBuffer buffer. When the function returns, the variable contains the number of bytes copied to the buffer, or the required size of the buffer.
dwReserved
Reserved; must be zero.

If the buffer size is not sufficient, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and sets lpdwLen to the size necessary to contain all the information.


RetrieveUrlCacheEntryFile

BOOL RetrieveUrlCacheEntryFile(
    IN LPCSTR lpszUrlName,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN OUT LPDWORD lpdwCacheEntryInfoBufferSize,
    IN DWORD dwReserved
    );

Retrieves a cache entry from the cache in the form of a file.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_FILE_NOT_FOUND | The cache entry specified by the source name is not found in the cache storage.
    ERROR_INSUFFICIENT_BUFFER | The size of the lpCacheEntryInfo buffer as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to get all the information.
lpszUrlName
Source name of the cache entry. This must be a unique name. The name string should not contain any escape characters.
lpCacheEntryInfo
Address of a cache entry information buffer. If the buffer is not sufficient to accommodate all the information associated with the URL, one or more of the embedded pointers will be NULL.
lpdwCacheEntryInfoBufferSize
Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable contains the size of the actual buffer used or required. The caller should check the return value in this parameter. If the return size is less than or equal to the size passed in, all the relevant data has been returned.
dwReserved
Reserved; must be zero.

RetrieveUrlCacheEntryFile does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

If an extension was provided while calling CommitUrlCacheEntry, the file will have the specified extension. If the entry is not available in the cache, this function returns ERROR_FILE_NOT_FOUND; otherwise, it returns the name of the local file. The caller is given only read permission to the local file, so the caller should not attempt to write or delete the file.

The file is locked for the caller when it is retrieved; the caller should unlock the file after it has been used up. The cache manager automatically unlocks the locked files after a certain interval. While the file is locked, the cache manager will not remove the file from the cache. It is important to note that this function may be efficient or expensive, depending on the internal implementation of the cache. For instance, if the URL data is stored in a packed file that contains data for other URLs, the cache will make a copy of the data to a file in a temporary directory maintained by the cache. The cache will eventually delete the copy. It is recommended that this function be used only in situations where a file name is needed to launch an application. RetrieveUrlCacheEntryStream and associated stream functions should be used in most cases.


RetrieveUrlCacheEntryStream

HANDLE RetrieveUrlCacheEntryStream(
    IN LPCSTR lpszUrlName,
    OUT LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN OUT LPDWORD lpdwCacheEntryInfoBufferSize,
    IN BOOL fRandomRead,
    IN DWORD dwReserved
    );

Provides the most efficient and implementation-independent way of accessing the cache data.

  • Returns a valid handle for use in the ReadUrlCacheEntryStream and UnlockUrlCacheEntryStream functions if successful, or NULL otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_FILE_NOT_FOUND | The cache entry specified by the source name is not found in the cache storage.
    ERROR_INSUFFICIENT_BUFFER | The size of lpCacheEntryInfo as specified by lpdwCacheEntryInfoBufferSize is not sufficient to contain all the information. The value returned in lpdwCacheEntryInfoBufferSize indicates the buffer size necessary to contain all the information.
lpszUrlName
Address of a string that contains the source name of the cache entry. This must be a unique name. The name string should not contain any escape characters.
lpCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure that receives information about the cache entry.
lpdwCacheEntryInfoBufferSize
Address of a variable that specifies the size of the lpCacheEntryInfo buffer. When the function returns, the variable receives the number of bytes copied to the buffer, or the required size of the buffer.
fRandomRead
Flag to indicate whether the stream is open for random access. Set the flag to TRUE to open the stream for random access.
dwReserved
Reserved; must be zero.

RetrieveUrlCacheEntryStream does not do any URL parsing, so a URL containing an anchor (#) will not be found in the cache, even if the resource is cached. For example, if the URL, http://example.com/example.htm#sample, was passed, the function would return ERROR_FILE_NOT_FOUND even if http://example.com/example.htm is in the cache.

Cache clients that do not need URL data in the form of a file should use this function to access the data for a particular URL.


SetUrlCacheEntryGroup

BOOLAPI SetUrlCacheEntryGroup (
    IN LPCSTR lpszUrlName,
    IN DWORD dwFlags,
    IN GROUPID GroupId,
    IN LPBYTE pbGroupAttributes,
    IN DWORD cbGroupAttributes,
    IN LPVOID lpReserved
);

Adds entries to or removes entries from a cache group.

  • Returns TRUE if successful, or FALSE otherwise.
lpszUrlName
String value that contains the URL of the cached resource.
dwFlags
DWORD value that determines whether the entry is added to or removed from a cache group. Can be one of the following values:
INTERNET_CACHE_GROUP_ADD | Adds the cache entry to the cache group.
INTERNET_CACHE_GROUP_REMOVE | Removes the entry from the cache group.
GroupId
GROUPID value that indicates the cache group that the entry will be added to or removed from.
pbGroupAttributes
Must be set to NULL.
cbGroupAttributes
Must be set to zero.
lpReserved
Reserved. Must be set to NULL.

A cache entry can belong to more than one cache group.


SetUrlCacheEntryInfo

BOOL SetUrlCacheEntryInfo(
    IN LPCSTR lpszUrlName,
    IN LPINTERNET_CACHE_ENTRY_INFO lpCacheEntryInfo,
    IN DWORD dwFieldControl
);

Sets the specified members of the INTERNET_CACHE_ENTRY_INFO structure.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Possible error values include:
    ERROR_FILE_NOT_FOUND | The specified cache entry is not found in the cache.
    ERROR_INVALID_PARAMETER | The value(s) to be set is invalid.
lpszUrlName
Address of a string that contains the name of the cache entry. The name string should not contain any escape characters.
lpCacheEntryInfo
Address of an INTERNET_CACHE_ENTRY_INFO structure containing the values to be assigned to the cache entry designated by lpszUrlName.
dwFieldControl
Bitmask that indicates the members that are to be set. Can be a combination of the following values:
CACHE_ENTRY_ACCTIME_FC | Sets the last access time.
CACHE_ENTRY_ATTRIBUTE_FC | Sets the cache entry type.
CACHE_ENTRY_EXEMPT_DELTA_FC | Sets the exempt delta.
CACHE_ENTRY_EXPTIME_FC | Sets the expire time.
CACHE_ENTRY_HEADERINFO_FC | Sets the header info.
CACHE_ENTRY_HITRATE_FC | Sets the hit rate.
CACHE_ENTRY_MODTIME_FC | Sets the last modified time.
CACHE_ENTRY_SYNCTIME_FC | Sets the last sync time.


UnlockUrlCacheEntryFile

BOOL UnlockUrlCacheEntryFile(
    IN LPCSTR lpszUrlName,
    IN DWORD dwReserved
    );

Unlocks the cache entry that was locked while the file was retrieved for use from the cache.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. ERROR_FILE_NOT_FOUND indicates that the cache entry specified by the source name is not found in the cache storage.
lpszUrlName
Address of a string that contains the source name of the cache entry that is being unlocked. The name string should not contain any escape characters.
dwReserved
Reserved; must be zero.

The application should not access the file after calling this function.

When this function returns, the cache manager is free to delete the cache entry.


UnlockUrlCacheEntryStream

BOOL UnlockUrlCacheEntryStream(
    IN HANDLE hUrlCacheStream,
    IN DWORD dwReserved
);

Closes the stream that has been retrieved using the RetrieveUrlCacheEntryStream function.

  • Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
hUrlCacheStream
Handle that was returned by the RetrieveUrlCacheEntryStream function.
dwReserved
Reserved; must be zero.


Macros

This section describes the macros included with the Win32 Internet functions.
InternetConnectUrl


InternetConnectUrl

InternetConnectUrl (hInternet, lpszUrl, dwFlags, dwContext) \
    InternetConnect(hInternet, lpszUrl, INTERNET_INVALID_PORT_NUMBER, NULL, NULL,
        INTERNET_SERVICE_URL, dwFlags, dwContext)

Allows the use of a URL instead of supplying the component parts to InternetConnect

hInternet
HINTERNET handle returned by InternetOpen.
lpszUrl
String value containing the URL to connect to.
dwFlags
Flags specific to the service used. When the value of dwService is INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the application to use passive FTP semantics.
dwContext
Application-defined value that is used to identify the application context for the returned handle in callbacks.


Data Types

The following section contains the type definitions used by the Win32 Internet functions.
INTERNET_STATUS_CALLBACK


INTERNET_STATUS_CALLBACK

VOID (CALLBACK * INTERNET_STATUS_CALLBACK)(
    IN HINTERNET hInternet,
    IN DWORD dwContext,
    IN DWORD dwInternetStatus,
    IN LPVOID lpvStatusInformation,
    IN DWORD dwStatusInformationLength
);

Type used for an application-defined status callback function.

hInternet
Handle for which the callback function is being called.
dwContext
Application-defined context value associated with hInternet.
dwInternetStatus
Status code that indicates why the callback function is being called. Can be one of the following values:
INTERNET_STATUS_CLOSING_CONNECTION
Closing the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CONNECTED_TO_SERVER
Successfully connected to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_CONNECTING_TO_SERVER
Connecting to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_CONNECTION_CLOSED
Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CTL_RESPONSE_RECEIVED
Not currently implemented.
INTERNET_STATUS_HANDLE_CLOSING
This handle value is now terminated.
INTERNET_STATUS_HANDLE_CREATED
Used by InternetConnect to indicate it has created the new handle. This lets the application call InternetCloseHandle from another thread, if the connect is taking too long.
INTERNET_STATUS_INTERMEDIATE_RESPONSE
Received an intermediate (100 level) status code message from the server.
INTERNET_STATUS_NAME_RESOLVED
Successfully found the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_PREFETCH
Not currently implemented.
INTERNET_STATUS_RECEIVING_RESPONSE
Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_REDIRECT
An HTTP request is about to automatically redirect the request. The lpvStatusInformation parameter points to the new URL. At this point, the application can read any data returned by the server with the redirect response, and can query the response headers. It can also cancel the operation by closing the handle. This callback is not made if the original request specified INTERNET_FLAG_NO_AUTO_REDIRECT.
INTERNET_STATUS_REQUEST_COMPLETE
An asynchronous operation has been completed. See InternetOpen for details on INTERNET_FLAG_ASYNC.
INTERNET_STATUS_REQUEST_SENT
Successfully sent the information request to the server. The lpvStatusInformation parameter points to a DWORD containing the number of bytes sent.
INTERNET_STATUS_RESOLVING_NAME
Looking up the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_RESPONSE_RECEIVED
Successfully received a response from the server. The lpvStatusInformation parameter points to a DWORD containing the number of bytes received.
INTERNET_STATUS_SENDING_REQUEST
Sending the information request to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_STATE_CHANGE
Moved between a secure (HTTPS) and a nonsecure (HTTP) site. Can be one of the following values:
INTERNET_STATE_ONLINE | Online state (mutually exclusive with offline).
INTERNET_STATE_OFFLINE | Offline because no network connection could be established.
INTERNET_STATE_OFFLINE_USER | Offline by user request.
INTERNET_STATE_IDLE | No network requests are being made by WinInet.
INTERNET_STATE_BUSY | Network requests are being made by WinInet.
lpvStatusInformation
Address of a buffer that contains information pertinent to this call to the callback function.
dwStatusInformationLength
Size of the lpvStatusInformation buffer.

The lpvStatusInformation parameter points to an INTERNET_ASYNC_RESULT structure. The dwStatusInformationLength parameter contains the final completion status of the asynchronous function. If this is ERROR_INTERNET_EXTENDED_ERROR, the application can retrieve the server error information by using InternetGetLastResponseInfo.

In the case of INTERNET_STATUS_REQUEST_COMPLETE, lpvStatusInformation is the address of an INTERNET_ASYNC_RESULT structure.

An application uses the callback function to indicate the progress of synchronous and asynchronous functions, and to indicate the completion of an asynchronous request.

Because callbacks are made during processing of the request, the application should spend as little time as possible in the callback function to avoid degrading data throughput on the network. For example, displaying a dialog box in a callback function may be such a lengthy operation that the server terminates the request.

The callback function can be called in a thread context different from the thread that initiated the request.


Structures

The following section describes the Win32 Internet function data structures and their uses.
GOPHER_ATTRIBUTE_TYPE
GOPHER_FIND_DATA
HTTP_VERSION_INFO
INTERNET_ASYNC_RESULT
INTERNET_AUTHNOTIFY_DATA
INTERNET_BUFFERS
INTERNET_CACHE_ENTRY_INFO
INTERNET_CERTIFICATE_INFO
INTERNET_CONNECTED_INFO
INTERNET_ONLINE_OFFLINE_INFO
INTERNET_PREFETCH_STATUS
INTERNET_PROXY_INFO
INTERNET_SCHEME
INTERNET_VERSION_INFO
URL_COMPONENTS


GOPHER_ATTRIBUTE_TYPE

typedef struct {
    DWORD CategoryId
    DWORD AttributeId
    union {
        GOPHER_ADMIN_ATTRIBUTE Admin;
        GOPHER_MOD_DATE_ATTRIBUTE ModDate;
        GOPHER_SCORE_ATTRIBUTE Score;
        GOPHER_SCORE_RANGE_ATTRIBUTE ScoreRange;
        GOPHER_SITE_ATTRIBUTE Site;
        GOPHER_ORGANIZATION_ATTRIBUTE Organization;
        GOPHER_LOCATION_ATTRIBUTE Location;
        GOPHER_GEOGRAPHICAL_LOCATION_ATTRIBUTE GeographicalLocation;
        GOPHER_TIMEZONE_ATTRIBUTE TimeZone;
        GOPHER_PROVIDER_ATTRIBUTE Provider;
        GOPHER_VERSION_ATTRIBUTE Version;
        GOPHER_ABSTRACT_ATTRIBUTE Abstract;
        GOPHER_VIEW_ATTRIBUTE View;
        GOPHER_VERONICA_ATTRIBUTE Veronica;
        GOPHER_ASK_ATTRIBUTE_TYPE Ask;
        GOPHER_UNKNOWN_ATTRIBUTE Unknown;
    } AttributeType;
} GOPHER_ATTRIBUTE_TYPE, *LPGOPHER_ATTRIBUTE_TYPE;

Contains the relevant information of a single Gopher attribute for an object.

CategoryId
Gopher name for the attribute. The possible values include:
GOPHER_CATEGORY_ID_ABSTRACT
GOPHER_CATEGORY_ID_ADMIN
GOPHER_CATEGORY_ID_ALL
GOPHER_CATEGORY_ID_INFO
GOPHER_CATEGORY_ID_UNKNOWN
GOPHER_CATEGORY_ID_VERONICA
GOPHER_CATEGORY_ID_VIEWS
AttributeId
Identifier of the structure contained in the AttributeType member. The possible values include:
GOPHER_ATTRIBUTE_ID_ABSTRACT
GOPHER_ATTRIBUTE_ID_ADMIN
GOPHER_ATTRIBUTE_ID_GEOG
GOPHER_ATTRIBUTE_ID_LOCATION
GOPHER_ATTRIBUTE_ID_MOD_DATE
GOPHER_ATTRIBUTE_ID_ORG
GOPHER_ATTRIBUTE_ID_PROVIDER
GOPHER_ATTRIBUTE_ID_RANGE
GOPHER_ATTRIBUTE_ID_SCORE
GOPHER_ATTRIBUTE_ID_SITE
GOPHER_ATTRIBUTE_ID_TIMEZONE
GOPHER_ATTRIBUTE_ID_TREEWALK
GOPHER_ATTRIBUTE_ID_TTL
GOPHER_ATTRIBUTE_ID_UNKNOWN
GOPHER_ATTRIBUTE_ID_VERSION
GOPHER_ATTRIBUTE_ID_VIEW
AttributeType
Actual setting for the Gopher attribute. The specific value of AttributeType depends on the AttributeId member. The definitions of the various attribute structures are available in Wininet.h.

See also GopherGetAttribute


GOPHER_FIND_DATA

typedef struct {
    TCHAR DisplayString[MAX_GOPHER_DISPLAY_TEXT + 1];
    DWORD GopherType;
    DWORD SizeLow;
    DWORD SizeHigh;
    FILETIME LastModificationTime;
    TCHAR Locator[MAX_GOPHER_LOCATOR_LENGTH + 1];
} GOPHER_FIND_DATA, FAR *LPGOPHER_FIND_DATA;

Contains information retrieved by the GopherFindFirstFile and InternetFindNextFile functions.

DisplayString
String that contains the friendly name of an object. An application can display this string to allow the user to select the object.
GopherType
Mask of flags that describe the item returned. Can be one of the following values:
GOPHER_TYPE_ASK | Ask+ item.
GOPHER_TYPE_BINARY | Binary file.
GOPHER_TYPE_BITMAP | Bitmap file.
GOPHER_TYPE_CALENDAR | Calendar file.
GOPHER_TYPE_CSO | CSO telephone book server.
GOPHER_TYPE_DIRECTORY | Directory of additional Gopher items.
GOPHER_TYPE_DOS_ARCHIVE | MS-DOS archive file.
GOPHER_TYPE_ERROR | Indicator of an error condition.
GOPHER_TYPE_GIF | GIF graphics file.
GOPHER_TYPE_GOPHER_PLUS | Gopher+ item.
GOPHER_TYPE_HTML | HTML document.
GOPHER_TYPE_IMAGE | Image file.
GOPHER_TYPE_INDEX_SERVER | Index server.
GOPHER_TYPE_INLINE | Inline file.
GOPHER_TYPE_MAC_BINHEX | Macintosh file in BINHEX format.
GOPHER_TYPE_MOVIE | Movie file.
GOPHER_TYPE_PDF | PDF file.
GOPHER_TYPE_REDUNDANT | Indicator of a duplicated server. The information contained within is a duplicate of the primary server. The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_SOUND | Sound file.
GOPHER_TYPE_TELNET | Telnet server.
GOPHER_TYPE_TEXT_FILE | ASCII text file.
GOPHER_TYPE_TN3270 | TN3270 server.
GOPHER_TYPE_UNIX_UUENCODED | UUENCODED file.
GOPHER_TYPE_UNKNOWN | Item type is unknown.
SizeLow
Low 32 bits of the file size.
SizeHigh
High 32 bits of the file size.
LastModificationTime
Time when the file was last modified.
Locator
String that identifies the file. An application can pass the locator string to GopherOpenFile or GopherFindFirstFile.


HTTP_VERSION_INFO

typedef  struct{
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;

Contains the global HTTP version (either 1.0 or 1.1).

dwMajorVersion
Major version number. Must be 1.
dwMinorVersion
Minor version number. Can be either 1 or 0.


INTERNET_ASYNC_RESULT

typedef struct {
    DWORD dwResult;
    DWORD dwError;
} INTERNET_ASYNC_RESULT, * LPINTERNET_ASYNC_RESULT;

Contains the result of a call to an asynchronous function. This structure is used with INTERNET_STATUS_CALLBACK.

dwResult
HINTERNET, DWORD, or BOOL return code from an asynchronous function.
dwError
Error message if dwResult indicates that the function failed. If the operation succeeded, this member usually contains ERROR_SUCCESS.


INTERNET_AUTHNOTIFY_DATA

typedef struct {
    DWORD cbStruct;
    DWORD dwOptions;
    PFN_PUTHNOTIFY pfnNotify;
    DWORD dwConext;
} INTERNET_AUTHNOTIFY_DATA;
cbStruct
Size of the structure.
dwOptions
Reserved; must be set to zero.
pfnNotify
Notification callback to retry InternetErrorDlg.
dwContext
Context to pass to the notification function.


INTERNET_BUFFERS

typedef struct _INTERNET_BUFFERS {
    DWORD dwStructSize;
    struct _INTERNET_BUFFERS * Next;
    LPCTSTR lpcszHeader;
    DWORD dwHeadersLength;
    DWORD dwHeadersTotal;
    LPVOID lpvBuffer;
    DWORD dwBufferLength;
    DWORD dwBufferTotal;
    DWORD dwOffsetLow;
    DWORD dwOffsetHigh;
} INTERNET_BUFFERS, * LPINTERNET_BUFFERS;

Contains both the data and header information.

dwStructSize
Double-word value used for API versioning. Set to the size of the INTERNET_BUFFERS structure.
Next
Address of the next INTERNET_BUFFERS structure.
lpcszHeader
String value containing the headers. This value can be NULL.
dwHeadersLength
Double-word value containing the length of the headers if lpcszHeader is not NULL.
dwHeadersTotal
Double-word value that contains the size of the headers if there is not enough memory in the buffer.
lpvBuffer
Address of the data buffer.
dwBufferLength
Double-word value that contains the length of the buffer if lpvBuffer is not NULL.
dwBufferTotal
Double-word value that contains the total size of the chunk or the content length if it is not chunked.
dwOffsetLow
Double-word value that is used for read ranges.
dwOffsetHigh
Double-word value that is used for read ranges.


INTERNET_CACHE_ENTRY_INFO

typedef struct _CACHE_ENTRY_INFO {
    DWORD dwStructSize;
    LPSTR lpszSourceUrlName;
    LPSTR lpszLocalFileName;
    DWORD CacheEntryType;
    DWORD dwUseCount;
    DWORD dwHitRate;
    DWORD dwSizeLow;
    DWORD dwSizeHigh;
    FILETIME LastModifiedTime;
    FILETIME ExpireTime;
    FILETIME LastAccessTime;
    FILETIME LastSyncTime;
    LPBYTE lpHeaderInfo;
    DWORD dwHeaderInfoSize;
    LPSTR lpszFileExtension;
    union (DWORD dwReserved; DWORD dwExemptDelta;)
} INTERNET_CACHE_ENTRY_INFO, *LPINTERNET_CACHE_ENTRY_INFO;

Contains information about an entry in the cache.

dwStructSize
Size, in bytes, of this structure.
lpszSourceUrlName
Address of a string that contains the URL name. The string occupies memory area at the end of this structure.
lpszLocalFileName
Address of a string that contains the local file name. The string occupies memory area at the end of this structure.
CacheEntryType
Cache type bitmask. Currently, the cache entry type value of resources from the Internet is equal to zero. For History and Cookie entries, the cache entry type is a combination of two values. One value determines how the cache entry is handled; the second value indicates what is being cached.

The value that determines how the cache entry is handled can be one of the following:
NORMAL_CACHE_ENTRY | Normal cache entry; can be deleted to recover space for new entries.
SPARSE_CACHE_ENTRY | Not currently implemented.
STABLE_CACHE_ENTRY | Not currently implemented.
STICKY_CACHE_ENTRY | Sticky cache entry that is exempt from scavenging for amount of time specified by dwExemptDelta. The default value set by CommitUrlCacheEntry is one day.

The value that indicates what is being cached can be one of the following:
COOKIE_CACHE_ENTRY | Cookie cache entry.
OCX_CACHE_ENTRY | Not currently implemented.
URLHISTORY_CACHE_ENTRY | Visited link cache entry.

dwUseCount
Current user count of the cache entry.
dwHitRate
Number of times the cache entry was retrieved.
dwSizeLow
Low-order double word of the file size.
dwSizeHigh
High-order double word of the file size.
LastModifiedTime
Last modified time of this URL, in GMT format.
ExpireTime
Expiration time of this file, in GMT format.
LastAccessTime
Last accessed time, in GMT format.
LastSyncTime
Last time the cache was synchronized.
lpHeaderInfo
Address of a buffer that contains the header information. The buffer occupies memory at the end of this structure.
dwHeaderInfoSize
Size of the lpHeaderInfo buffer.
lpszFileExtension
Address of a string that contains the file extension used to retrieve the data as a file. The string occupies memory area at the end of this structure.
union (DWORD dwReserved; DWORD dwExemptDelta;)
Exemption time, in seconds, from the last accessed time.

There is no cache entry size limit, so applications that need to enumerate the cache must be prepared to allocate variable-sized buffers. For more information, see Appendix B: Using Buffers.


INTERNET_CERTIFICATE_INFO

typedef struct {
    FILETIME ftExpiry;
    FILETIME ftStart;
    LPSTR lpszSubjectInfo;
    LPSTR lpszIssuerInfo;
    LPSTR lpszProtocolName;
    LPSTR lpszSignatureAlgName;
    LPSTR lpszEncryptionAlgName;
    DWORD dwKeySize;
} INTERNET_CERTIFICATE_INFO, * LPINTERNET_CERTIFICATE_INFO;

Contains certificate information returned from the server. This structure is used by the InternetQueryOption function.

ftExpiry
FILETIME structure that contains the date the certificate expires.
ftStart
FILETIME structure that contains the date the certificate becomes valid.
lpszSubjectInfo
Address of a buffer that contains the name of the organization, site, and server for which the certificate was issued.
lpszIssuerInfo
Address of a buffer that contains the name of the organization, site, and server that issued the certificate.
lpszProtocolName
Address of a buffer that contains the name of the protocol used to provide the secure connection.
lpszSignatureAlgName
Address of a buffer that contains the name of the algorithm used for signing the certificate.
lpszEncryptionAlgName
Address of a buffer that contains the name of the algorithm used for doing encryption over the secure channel (SSL/PCT) connection.
dwKeySize
Size, in bytes, of the key.

Applications requesting this information must free pointers that are allocated and placed in the returned structure.


INTERNET_CONNECTED_INFO

typedef struct {
    DWORD dwConnectedState;
    DWORD dwFlags
} INTERNET_CONNECTED_INFO, * LPINTERNET_CONNECTED_INFO;

Contains the information to set the global online/offline state.

dwConnectedState
DWORD value that contains the state information. Can be one of the following values:
INTERNET_STATE_CONNECTED | Connected to network. Replaces INTERNET_STATE_ONLINE.
INTERNET_STATE_DISCONNECTED | Disconnected from network. Replaces INTERNET_STATE_OFFLINE.
INTERNET_STATE_DISCONNECTED_BY_USER | Disconnected by user request. Replaces INTERNET_STATE_OFFLINE_USER.
INTERNET_STATE_IDLE | No network requests are being made by Win32 Internet functions.
INTERNET_STATE_BUSY | Network requests are being made by WinInet.
dwFlags
DWORD value that controls the transition between states. Can be ISO_FORCE_DISCONNECTED, which puts Win32 Internet functions into offline mode. All outstanding requests will be aborted with a canceled error.


*
  * Previous Topic: INTERNET_CONNECTED_INFO
  * Next Topic: INTERNET_PREFETCH_STATUS

INTERNET_ONLINE_OFFLINE_INFO

Replaced by INTERNET_CONNECTED_INFO.


INTERNET_PREFETCH_STATUS

typedef struct {
    DWORD dwStatus;
    DWORD dwSize;
} INTERNET_PREFETCH_STATUS, * LPINTERNET_PREFETCH_STATUS;

Contains the status of a prefetch download operation.

dwStatus
Status of the download. Can be one of the following values:
INTERNET_PREFETCH_ABORTED | Operation was aborted.
INTERNET_PREFETCH_COMPLETE | Operation has completed.
INTERNET_PREFETCH_PROGRESS | Operation is in progress.
dwSize
Size, in bytes, of data downloaded so far.


INTERNET_PROXY_INFO

typedef struct {
    DWORD dwAccessType;
    LPCSTR lpszProxy;
    LPCSTR lpszProxyBypass;
} INTERNET_PROXY_INFO, * LPINTERNET_PROXY_INFO;

Contains information that is supplied with the INTERNET_OPTION_PROXY value to get or set proxy information on a handle obtained from a call to the InternetOpen function.

dwAccessType
Access type. Can be one of the following values:
INTERNET_OPEN_TYPE_DIRECT | Internet accessed through a direct connection.
INTERNET_OPEN_TYPE_PRECONFIG | Applies only when setting proxy information.
INTERNET_OPEN_TYPE_PROXY | Internet accessed using a proxy.
lpszProxy
Proxy server list.
lpszProxyBypass
Proxy bypass list.


INTERNET_SCHEME

typedef enum {
    INTERNET_SCHEME_PARTIAL = -2,
    INTERNET_SCHEME_UNKNOWN = -1,
    INTERNET_SCHEME_DEFAULT = 0,
    INTERNET_SCHEME_FTP,
    INTERNET_SCHEME_GOPHER,
    INTERNET_SCHEME_HTTP,
    INTERNET_SCHEME_HTTPS,
    INTERNET_SCHEME_FILE,
    INTERNET_SCHEME_NEWS,
    INTERNET_SCHEME_MAILTO,
    INTERNET_SCHEME_FIRST = INTERNET_SCHEME_FTP,
    INTERNET_SCHEME_LAST = INTERNET_SCHEME_MAILTO
} INTERNET_SCHEME, * LPINTERNET_SCHEME;

Defines the flags used with the nScheme member of the URL_COMPONENTS structure.

INTERNET_SCHEME_PARTIAL
Partial URL.
INTERNET_SCHEME_UNKNOWN
Unknown URL scheme.
INTERNET_SCHEME_DEFAULT
Default URL scheme.
INTERNET_SCHEME_FTP
FTP URL scheme (ftp:).
INTERNET_SCHEME_GOPHER
Gopher URL scheme (gopher:).
INTERNET_SCHEME_HTTP
HTTP URL scheme (http:).
INTERNET_SCHEME_HTTPS
HTTPS URL scheme (https:).
INTERNET_SCHEME_FILE
File URL scheme (file:).
INTERNET_SCHEME_NEWS
News URL scheme (news:).
INTERNET_SCHEME_MAILTO
Mail URL scheme (mailto:).
INTERNET_SCHEME_FIRST
Lowest known scheme value.
INTERNET_SCHEME_LAST
Highest known scheme value.


INTERNET_VERSION_INFO

typedef struct {
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;
} INTERNET_VERSION_INFO, * LPINTERNET_VERSION_INFO;

Contains the HTTP version number of the server. This structure is used when passing the INTERNET_OPTION_VERSION flag to the InternetQueryOption function.

dwMajorVersion
Major version number.
dwMinorVersion
Minor version number.


URL_COMPONENTS

typedef struct {
    DWORD dwStructSize;
    LPSTR lpszScheme;
    DWORD dwSchemeLength;
    INTERNET_SCHEME nScheme;
    LPSTR lpszHostName;
    DWORD dwHostNameLength;
    INTERNET_PORT nPort;
    LPSTR lpszUserName;
    DWORD dwUserNameLength;
    LPSTR lpszPassword;
    DWORD dwPasswordLength;
    LPSTR lpszUrlPath;
    DWORD dwUrlPathLength;
    LPSTR lpszExtraInfo;
    DWORD dwExtraInfoLength;
} URL_COMPONENTS;

Contains the constituent parts of a URL. This structure is used with the InternetCrackUrl and InternetCreateUrl functions.

dwStructSize
Size, in bytes, of this structure. Used for version checking. The size of this structure must be set to initialize this structure properly.
lpszScheme
Address of a buffer that contains the scheme name.
dwSchemeLength
Length of the scheme name.
nScheme
Enumerated scheme type, if known. For a list of scheme types, see INTERNET_SCHEME.
lpszHostName
Address of a buffer that contains the host name.
dwHostNameLength
Length of the host name.
nPort
Converted port number.
lpszUserName
Address of a buffer that contains the user name.
dwUserNameLength
Length of the user name.
lpszPassword
Address of a buffer that contains the password.
dwPasswordLength
Length of the password.
lpszUrlPath
Address of a buffer that contains the URL path.
dwUrlPathLength
Length of the URL path.
lpszExtraInfo
Address of a buffer that contains the extra information (for example, ?foo or #foo).
dwExtraInfoLength
Length of the extra information.

For InternetCrackUrl, if a pointer member and its corresponding length member are both zero, that component is not returned. If the pointer member is NULL but the length member is not zero, both the pointer and length members are returned. If both pointer and corresponding length members are nonzero, the pointer member points to a buffer where the component is copied. The component may be un-escaped, depending on the dwFlags parameter of InternetCrackUrl.

For InternetCreateUrl, the pointer members should be NULL if the component is not required. If the corresponding length member is zero, the pointer member is the address of a zero-terminated string. If the length member is not zero, it is the string length of the corresponding pointer member.


API Flags

Many of the Win32 Internet functions accept a double-word array of flags as a parameter. The following is a brief description of the defined flags.

INTERNET_FLAG_ASYNC
Makes only asynchronous requests on handles descended from the handle returned from this function. Only the InternetOpen function uses this flag.
INTERNET_FLAG_CACHE_ASYNC
Allows a lazy cache write.
INTERNET_FLAG_CACHE_IF_NET_FAIL
Return the resource from the cache if the network request for the resource fails due to an ERROR_INTERNET_CONNECTION_RESET or ERROR_INTERNET_CANNOT_CONNECT. This flag is used by HttpOpenRequest.
INTERNET_FLAG_DONT_CACHE
Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE. This flag is used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_EXISTING_CONNECT
Attempts to use an existing InternetConnect object if one exists with the same attributes required to make the request. This is useful only with FTP operations, since FTP is the only protocol that typically performs multiple operations during the same session. The Win32 Internet API caches a single connection handle for each HINTERNET handle generated by InternetOpen. Only the InternetOpenUrl function uses this flag.
INTERNET_FLAG_FORMS_SUBMIT
Indicates that this is a forms submit.
INTERNET_FLAG_FROM_CACHE
Does not make network requests. All entities are returned from the cache. If the requested item is not in the cache, a suitable error, such as ERROR_FILE_NOT_FOUND, is returned. Only the InternetOpen function uses this flag.
INTERNET_FLAG_HYPERLINK
Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network. This flag can be used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_KEEP_CONNECTION
Uses keep-alive semantics, if available, for the connection. This flag is used by HttpOpenRequest and InternetOpenUrl (for HTTP requests). This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
INTERNET_FLAG_MAKE_PERSISTENT
No longer supported.
INTERNET_FLAG_MUST_CACHE_REQUEST
Identical to the preferred value, INTERNET_FLAG_NEED_FILE. Causes a temporary file to be created if the file cannot be cached. This flag can be used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_NEED_FILE
Causes a temporary file to be created if the file cannot be cached. This flag can be used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_NO_AUTH
Does not attempt authentication automatically. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_NO_AUTO_REDIRECT
Does not automatically handle redirection in HttpSendRequest. This flag can also be used by InternetOpenUrl for HTTP requests.
INTERNET_FLAG_NO_CACHE_WRITE
Does not add the returned entity to the cache. This flag is used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_NO_COOKIES
Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).
INTERNET_FLAG_NO_UI
Disables the cookie dialog box. This flag can be used by HttpOpenRequest and InternetOpenUrl (HTTP requests only).
INTERNET_FLAG_OFFLINE
Identical to INTERNET_FLAG_FROM_CACHE. Does not make network requests. All entities are returned from the cache. If the requested item is not in the cache, a suitable error, such as ERROR_FILE_NOT_FOUND, is returned. Only the InternetOpen function uses this flag.
INTERNET_FLAG_PASSIVE
Uses passive FTP semantics. Only InternetConnect and InternetOpenUrl use this flag. InternetConnect uses this flag for FTP requests, and InternetOpenUrl uses this flag for FTP files and directories.
INTERNET_FLAG_PRAGMA_NOCACHE
Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy. The InternetOpenUrl function (on HTTP and HTTPS requests only) and HttpOpenRequest functions use this flag.
INTERNET_FLAG_RAW_DATA
Returns the data as a GOPHER_FIND_DATA structure when retrieving Gopher directory information, or as a WIN32_FIND_DATA structure when retrieving FTP directory information. If this flag is not specified or if the call was made through a CERN proxy, InternetOpenUrl returns HTML version of the directory. Only the InternetOpenUrl function uses this flag.
INTERNET_FLAG_READ_PREFETCH
This flag is currently disabled.
INTERNET_FLAG_RELOAD
Forces a download of the requested file, object, or directory listing from the origin server, not from the cache. The GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl functions utilize this flag.
INTERNET_FLAG_RESYNCHRONIZE
Reloads HTTP resources if the resource has been modified since the last time it was downloaded. All FTP and Gopher resources are reloaded. This flag can be used by GopherFindFirstFile, GopherOpenFile, FtpFindFirstFile, FtpGetFile, FtpOpenFile, FtpPutFile, HttpOpenRequest, and InternetOpenUrl.
INTERNET_FLAG_SECURE
Uses secure transaction semantics. This translates to using Secure Sockets Layer/Private Communications Technology (SSL/PCT) and is only meaningful in HTTP requests. This flag is used by HttpOpenRequest and InternetOpenUrl, but this is made redundant if "https://" appears in the URL.
INTERNET_FLAG_TRANSFER_ASCII
Transfers file as ASCII (FTP only). This flag can be used by FtpOpenFile, FtpGetFile, and FtpPutFile.
INTERNET_FLAG_TRANSFER_BINARY
Transfers file as binary (FTP only). This flag can be used by FtpOpenFile, FtpGetFile, and FtpPutFile.
WININET_API_FLAG_ASYNC
Forces asynchronous operations.
WININET_API_FLAG_SYNC
Forces synchronous operations.
WININET_API_FLAG_USE_CONTEXT
Forces the API to use the context value, even if it is set to zero.


HTTP Status Codes

The following list contains the values and corresponding constants for the HTTP status codes returned by servers on the Internet.
Constant | Value | Description
HTTP_STATUS_OK | 200 | The request completed successfully.
HTTP_STATUS_CREATED | 201 | The request has been fulfilled and resulted in the creation of a new resource.
HTTP_STATUS_ACCEPTED | 202 | The request has been accepted for processing , but the processing has not been completed.
HTTP_STATUS_PARTIAL | 203 | The returned meta information in the entity-header is not the definitive set available from the origin server.
HTTP_STATUS_NO_CONTENT | 204 | The server has fulfilled the request, but there is no new information to send back.
HTTP_STATUS_RESET_CONTENT | 205 | The request has been completed, and the client program should reset the document view that caused the request to be sent to allow the user to easily initiate another input action.
HTTP_STATUS_PARTIAL_CONTENT | 206 | The server has fulfilled the partial GET request for the resource.
HTTP_STATUS_AMBIGUOUS | 300 | The server couldn't decide what to return.
HTTP_STATUS_MOVED | 301 | The requested resource has been assigned to a new permanent URI, and any future references to this resource should be done using one of the returned URIs.
HTTP_STATUS_REDIRECT | 302 | The requested resource resides temporarily under a different URI.
HTTP_STATUS_REDIRECT_METHOD | 303 | The response to the request can be found under a different URI and should be retrieved using a GET method on that resource.
HTTP_STATUS_NOT_MODIFIED | 304 | The requested resource has not been modified.
HTTP_STATUS_USE_PROXY | 305 | The requested resource must be accessed through the proxy given by the location field.
HTTP_STATUS_REDIRECT_KEEP_VERB | 307 | The redirected request keeps the same verb. HTTP/1.1 behavior.
HTTP_STATUS_BAD_REQUEST | 400 | The request could not be processed by the server due to invalid syntax.
HTTP_STATUS_DENIED | 401 | The requested resource requires user authentication.
HTTP_STATUS_PAYMENT_REQ | 402 | Not currently implemented in the HTTP protocol.
HTTP_STATUS_FORBIDDEN | 403 | The server understood the request, but is refusing to fulfill it.
HTTP_STATUS_NOT_FOUND | 404 | The server has not found anything matching the requested URI.
HTTP_STATUS_BAD_METHOD | 405 | The method used is not allowed.
HTTP_STATUS_NONE_ACCEPTABLE | 406 | No responses acceptable to the client were found.
HTTP_STATUS_PROXY_AUTH_REQ | 407 | Proxy authentication required.
HTTP_STATUS_REQUEST_TIMEOUT | 408 | The server timed out waiting for the request.
HTTP_STATUS_CONFLICT | 409 | The request could not be completed due to a conflict with the current state of the resource. The user should resubmit with more information.
HTTP_STATUS_GONE | 410 | The requested resource is no longer available at the server, and no forwarding address is known.
HTTP_STATUS_LENGTH_REQUIRED | 411 | The server refuses to accept the request without a defined content length.
HTTP_STATUS_PRECOND_FAILED | 412 | The precondition given in one or more of the request header fields evaluted to false when it was tested on the server.
HTTP_STATUS_REQUEST_TOO_LARGE | 413 | The server is refusing to process a request because the request entity is larger than the server is willing or able to process.
HTTP_STATUS_URI_TOO_LONG | 414 | The server is refusing to service the request because the request URI is longer than the server is willing to interpret.
HTTP_STATUS_UNSUPPORTED_MEDIA | 415 | The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
HTTP_STATUS_SERVER_ERROR | 500 | The server encountered an unexpected condition that prevented it from fulfilling the request.
HTTP_STATUS_NOT_SUPPORTED | 501 | The server does not support the functionality required to fulfill the request.
HTTP_STATUS_BAD_GATEWAY | 502 | The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
HTTP_STATUS_SERVICE_UNAVAIL | 503 | The service is temporarily overloaded.
HTTP_STATUS_GATEWAY_TIMEOUT | 504 | The request was timed out waiting for a gateway.
HTTP_STATUS_VERSION_NOT_SUP | 505 | The server does not support, or refuses to support, the HTTP protocol version that was used in the request message.


Option Flags

The following list contains the options supported by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_ASYNC
Not currently implemented.

INTERNET_OPTION_ASYNC_PRIORITY
Not currently implemented.

INTERNET_OPTION_CACHE_STREAM_HANDLE
No longer supported.

INTERNET_OPTION_CALLBACK
Returns or sets the address of the callback function defined for this handle. This option can be used on all HINTERNET handles. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CALLBACK_FILTER
Not currently implemented

INTERNET_OPTION_CONNECT_BACKOFF
Not currently implemented.

INTERNET_OPTION_CONNECT_LIMIT
Not currently implemented.

INTERNET_OPTION_CONNECT_RETRIES
Returns or sets the retry count to use for Internet connection requests. If a connection attempt still fails after the specified number of tries, the request is canceled. The default is five retries. This option can be used on any HINTERNET handle, including a NULL handle. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONNECT_TIME
Not currently implemented.

INTERNET_OPTION_CONNECT_TIMEOUT
Returns or sets the time-out value, in milliseconds, to use for Internet connection requests. If a connection request takes longer than this time-out value, the request is canceled. This option can be used on any HINTERNET handle, including a NULL handle. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONNECTED_STATE
Returns or sets the connected state. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONTEXT_VALUE
Returns or sets the context value associated with this Internet handle. This option can be used on any HINTERNET handle. Used by InternetQueryOption and InternetSetOption. Previously, this set the context value to the address stored in the DWORD(lpBuffer) pointer. This has been corrected so that the value stored in the buffer will be used and the INTERNET_OPTION_CONTEXT_VALUE flag will be reassigned a new value. The old value, 10, has been preserved so that applications written for the old behavior are still supported.

INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
Identical to INTERNET_OPTION_RECEIVE_TIMEOUT. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONTROL_SEND_TIMEOUT
Identical to INTERNET_OPTION_SEND_TIMEOUT. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
Returns or sets the time-out value, in milliseconds, to use for Internet data download requests. If a data receive request takes longer than this time-out value, the request is canceled. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DATA_SEND_TIMEOUT
Returns or sets the time-out value, in milliseconds, to use for Internet data send requests. If a data send request takes longer than this time-out value, the request is canceled. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DATAFILE_NAME
Returns the name of the file backing a downloaded entity. This flag is valid after InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest has completed. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DISCONNECTED_TIMEOUT
Not currently implemented.

INTERNET_OPTION_END_BROWSER_SESSION
Flushes entries not in use from the password cache on the hard drive. Also resets the cache time used when the synchronization mode is once-per-session. Used by InternetSetOption.

INTERNET_OPTION_ERROR_MASK
Not currently implemented.

INTERNET_OPTION_EXTENDED_ERROR
Returns the Windows Sockets error message that was mapped to the ERROR_INTERNET_ error messages last returned in this thread context. This option is used on a NULL HINTERNET handle by InternetQueryOption.

INTERNET_OPTION_HANDLE_TYPE
Returns the type of the Internet handle passed in. Used by InternetQueryOption on any HINTERNET handle. Possible return values include:

INTERNET_HANDLE_TYPE_CONNECT_FTP
INTERNET_HANDLE_TYPE_CONNECT_GOPHER
INTERNET_HANDLE_TYPE_CONNECT_HTTP
INTERNET_HANDLE_TYPE_FTP_FILE
INTERNET_HANDLE_TYPE_FTP_FILE_HTML
INTERNET_HANDLE_TYPE_FTP_FIND
INTERNET_HANDLE_TYPE_FTP_FIND_HTML
INTERNET_HANDLE_TYPE_GOPHER_FILE
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML
INTERNET_HANDLE_TYPE_GOPHER_FIND
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML
INTERNET_HANDLE_TYPE_HTTP_REQUEST
INTERNET_HANDLE_TYPE_INTERNET

INTERNET_OPTION_HTTP_VERSION
Returns or sets the HTTP version being supported. Must be used on a NULL handle. An HTTP_VERSION_INFO structure is used to set or get the version information. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_IDLE_STATE
Not currently implemented.

INTERNET_OPTION_KEEP_CONNECTION
Not currently implemented.

INTERNET_OPTION_LISTEN_TIMEOUT
Not currently implemented.

INTERNET_OPTION_OFFLINE_MODE
Not currently implemented.

INTERNET_OPTION_OFFLINE_SEMANTICS
Not currently implemented.

INTERNET_OPTION_PARENT_HANDLE
Returns the parent handle to this handle. This option can be used on any HINTERNET handle by InternetQueryOption.

INTERNET_OPTION_PASSWORD
Returns or sets the password associated with a handle returned by InternetConnect. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_POLICY
Not currently implemented.

INTERNET_OPTION_PROXY
Returns or sets the proxy information on an existing InternetOpen handle when the HINTERNET handle is not NULL. If the HINTERNET handle is NULL, the function sets or queries the global proxy information. The lpBuffer parameter is an INTERNET_PROXY_INFO structure that contains the proxy information. This option can be used on the HINTERNET handle returned by InternetOpen. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PROXY_PASSWORD
Returns or sets the password currently being used to access the proxy. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PROXY_USERNAME
Returns or sets the user name currently being used to access the proxy. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_READ_BUFFER_SIZE
Returns or sets the size of the read buffer. This option can be used on HINTERNET handles returned by FtpOpenFile, FtpFindFirstFile, and InternetConnect (FTP session only). Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_RECEIVE_THROUGHPUT
Not currently implemented.

INTERNET_OPTION_RECEIVE_TIMEOUT
Returns or sets the time-out value, in milliseconds, to receive a response to a request. If the response takes longer than this time-out value, the request is canceled. This option can be used on any HINTERNET handle, including a NULL handle. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_REFRESH
Returns or sets the value that determines if the proxy information can be reread from the registry for a handle. The value TRUE indicates that the proxy information can be reread from the registry for a handle. This option can be used on the HINTERNET handle returned by InternetOpen. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_REQUEST_FLAGS
Returns special status flags about the current download in progress. Used by InternetQueryOption. The flag can be one of the following values:

INTERNET_REQFLAG_ASYNC | Not currently implemented.
INTERNET_REQFLAG_FROM_CACHE | Response came from the cache.
INTERNET_REQFLAG_NO_HEADERS | Original response contained no headers.
INTERNET_REQFLAG_PASSIVE | Not currently implemented.
INTERNET_REQFLAG_VIA_PROXY | Request was made through a proxy.

INTERNET_OPTION_REQUEST_PRIORITY
Returns or sets the priority of requests competing for a connection on an HTTP handle. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_SECONDARY_CACHE_KEY
Returns or sets the secondary cache key. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_SECURITY_CERTIFICATE
Returns the certificate for an SSL/PCT (Secure Sockets Layer/Private Communications Technology) server into a formatted string. Used by InternetQueryOption.

INTERNET_OPTION_SECURITY_CERTIFICATE_STRUCT
Returns the certificate for an SSL/PCT server into the INTERNET_CERTIFICATE_INFO structure. Used by InternetQueryOption.

INTERNET_OPTION_SECURITY_FLAGS
Returns the security flags for a handle. Used by InternetQueryOption. Can be a combination of these values:

SECURITY_FLAG_128BIT
Identical to the preferred value SECURITY_FLAG_STRENGTH_STRONG. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_40BIT
Identical to the preferred value SECURITY_FLAG_STRENGTH_WEAK. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_56BIT
Identical to the preferred value SECURITY_FLAG_STRENGTH_MEDIUM. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_IETFSSL4
Not currently implemented.
SECURITY_FLAG_IGNORE_CERT_CN_INVALID
Ignores the ERROR_INTERNET_SEC_CERT_CN_INVALID error message.
SECURITY_FLAG_IGNORE_CERT_DATE_INVALID
Ignores the ERROR_INTERNET_SEC_CERT_DATE_INVALID error message.
SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTP
Ignores the ERROR_INTERNET_HTTPS_TO_HTTP_ON_REDIR error message.
SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTPS
Ignores the ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR error message.
SECURITY_FLAG_IGNORE_REVOCATION
Ignores certificate revocation problems.
SECURITY_FLAG_IGNORE_UNKNOWN_CA
Ignore unknown certificate authority problems.
SECURITY_FLAG_IGNORE_WRONG_USAGE
Ignore incorrect usage problems.
SECURITY_FLAG_NORMALBITNESS
Identical to the value SECURITY_FLAG_STRENGTH_WEAK. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_PCT
Not currently implemented.
SECURITY_FLAG_PCT4
Not currently implemented.
SECURITY_FLAG_SECURE
Uses secure transfers. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_SSL
Not currently implemented.
SECURITY_FLAG_SSL3
Not currently implemented.
SECURITY_FLAG_STRENGTH_MEDIUM
Uses medium (56 bit) encryption. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_STRENGTH_STRONG
Uses strong (128 bit) encryption. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_STRENGTH_WEAK
Uses weak (40 bit) encryption. Only returned in a call to InternetQueryOption.
SECURITY_FLAG_UNKNOWNBIT
The bit size used in the encryption is unknown. Only returned in a call to InternetQueryOption.
INTERNET_OPTION_SECURITY_KEY_BITNESS
Returns the bit size of the encryption key. The larger the number, the greater the encryption strength being used. Used by InternetQueryOption.

INTERNET_OPTION_SECURITY_SELECT_CLIENT_CERT
Sets the client certification. Used by InternetSetOption.

INTERNET_OPTION_SEND_THROUGHPUT
Not currently implemented.

INTERNET_OPTION_SEND_TIMEOUT
Returns or sets the time-out value, in milliseconds, to send a request. If the send takes longer than this time-out value, the send is canceled. This option can be used on any HINTERNET handle, including a NULL handle. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_SETTINGS_CHANGED
Informs WinInet that the registry settings have been changed, so that it will check the settings on the next call to InternetConnect. Used by InternetSetOption.

INTERNET_OPTION_URL
Returns the full URL of a downloaded resource. If the original URL contained any extra information (such as search strings or anchors) or if the call was redirected, the URL returned will differ from the original. This option is valid on HINTERNET handles returned by InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest. Used by InternetQueryOption.

INTERNET_OPTION_USER_AGENT
Returns or sets the user agent string on handles supplied by InternetOpen and used in subsequent HttpSendRequest functions, as long as it is not overridden by a header added by HttpAddRequestHeaders or HttpSendRequest. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_USERNAME
Returns or sets the user name associated with a handle returned by InternetConnect. Used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_VERSION
Returns the version number of Wininet.dll. The lpBuffer parameter is the address of an INTERNET_VERSION_INFO structure. This option can be used on a NULL HINTERNET handle. Used by InternetQueryOption.

INTERNET_OPTION_WRITE_BUFFER_SIZE
Returns or sets the size of the write buffer. This option can be used on HINTERNET handles returned by FtpOpenFile and InternetConnect (FTP session only). Used by InternetQueryOption and InternetSetOption.


Error Messages

The Win32 Internet functions return Win32 error messages where appropriate. The following error messages are specific to the Win32 Internet functions.

INTERNET_ERROR_BASE
Base value of the Internet error codes.
ERROR_FTP_DROPPED
The FTP operation was not completed because the session was aborted.

ERROR_FTP_TRANSFER_IN_PROGRESS
The requested operation cannot be made on the FTP session handle because an operation is already in progress.

ERROR_GOPHER_ATTRIBUTE_NOT_FOUND
The requested attribute could not be located.

ERROR_GOPHER_DATA_ERROR
An error was detected while receiving data from the Gopher server.

ERROR_GOPHER_END_OF_DATA
The end of the data has been reached.

ERROR_GOPHER_INCORRECT_LOCATOR_TYPE
The type of the locator is not correct for this operation.

ERROR_GOPHER_INVALID_LOCATOR
The supplied locator is not valid.

ERROR_GOPHER_NOT_FILE
The request must be made for a file locator.

ERROR_GOPHER_NOT_GOPHER_PLUS
The requested operation can only be made against a Gopher+ server, or with a locator that specifies a Gopher+ operation.

ERROR_GOPHER_PROTOCOL_ERROR
An error was detected while parsing data returned from the Gopher server.

ERROR_GOPHER_UNKNOWN_LOCATOR
The locator type is unknown.

ERROR_HTTP_DOWNLEVEL_SERVER
The server did not return any headers.

ERROR_HTTP_HEADER_ALREADY_EXISTS
The header could not be added because it already exists.

ERROR_HTTP_HEADER_NOT_FOUND
The requested header could not be located.

ERROR_HTTP_INVALID_HEADER
The supplied header is invalid.

ERROR_HTTP_INVALID_QUERY_REQUEST
The request made to HttpQueryInfo is invalid.

ERROR_HTTP_REDIRECT_FAILED
The redirection failed because either the scheme changed (for example, HTTP to FTP) or all attempts made to redirect failed (default is five attempts).

ERROR_HTTP_REDIRECT_NEEDS_CONFIRMATION
The redirection requires user confirmation.

ERROR_HTTP_INVALID_SERVER_RESPONSE
The server response could not be parsed.

ERROR_INTERNET_ASYNC_THREAD_FAILED
The application could not start an asynchronous thread.

ERROR_INTERNET_BAD_OPTION_LENGTH
The length of an option supplied to InternetQueryOption or InternetSetOption is incorrect for the type of option specified.

ERROR_INTERNET_BAD_AUTO_PROXY_SCRIPT
There was an error in the automatic proxy configuration script.

ERROR_INTERNET_BAD_REGISTRY_PARAMETER
A required registry value was located but is an incorrect type or has an invalid value.

ERROR_INTERNET_CANNOT_CONNECT
The attempt to connect to the server failed.

ERROR_INTERNET_CHG_POST_IS_NON_SECURE
The application is posting and attempting to change multiple lines of text on a server that is not secure.

ERROR_INTERNET_CLIENT_AUTH_CERT_NEEDED
The server is requesting client authentication.

ERROR_INTERNET_CLIENT_AUTH_NOT_SETUP
Client authorization is not set up on this computer.

ERROR_INTERNET_CONNECTION_ABORTED
The connection with the server has been terminated.

ERROR_INTERNET_CONNECTION_RESET
The connection with the server has been reset.

ERROR_INTERNET_DIALOG_PENDING
Another thread has a password dialog in progress.

ERROR_INTERNET_DISCONNECTED
The Internet connection has been lost.

ERROR_INTERNET_EXTENDED_ERROR
An extended error was returned from the server. This is typically a string or buffer containing a verbose error message. Call InternetGetLastResponseInfo to retrieve the error text.

ERROR_INTERNET_FAILED_DUETOSECURITYCHECK
The function failed due to a security check.

ERROR_INTERNET_FORCE_RETRY
The Win32 Internet function needs to redo the request.

ERROR_INTERNET_HANDLE_EXISTS
The request failed because the handle already exists.

ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR
The application is moving from a non-SSL to an SSL connection because of a redirect.

ERROR_INTERNET_HTTPS_TO_HTTP_ON_REDIR
The application is moving from an SSL to an non-SSL connection because of a redirect.

ERROR_INTERNET_INCORRECT_FORMAT
The format of the request is invalid.

ERROR_INTERNET_INCORRECT_HANDLE_STATE
The requested operation cannot be carried out because the handle supplied is not in the correct state.

ERROR_INTERNET_INCORRECT_HANDLE_TYPE
The type of handle supplied is incorrect for this operation.

ERROR_INTERNET_INCORRECT_PASSWORD
The request to connect and log on to an FTP server could not be completed because the supplied password is incorrect.

ERROR_INTERNET_INCORRECT_USER_NAME
The request to connect and log on to an FTP server could not be completed because the supplied user name is incorrect.

ERROR_INTERNET_INSERT_CDROM
The request requires a CD-ROM to be inserted in the CD-ROM drive to locate the resource requested.

ERROR_INTERNET_INTERNAL_ERROR
An internal error has occurred.

ERROR_INTERNET_INVALID_CA
The function is unfamiliar with the Certificate Authority that generated the server's certificate.

ERROR_INTERNET_INVALID_OPERATION
The requested operation is invalid.

ERROR_INTERNET_INVALID_OPTION
A request to InternetQueryOption or InternetSetOption specified an invalid option value.

ERROR_INTERNET_INVALID_PROXY_REQUEST
The request to the proxy was invalid.

ERROR_INTERNET_INVALID_URL
The URL is invalid.

ERROR_INTERNET_ITEM_NOT_FOUND
The requested item could not be located.

ERROR_INTERNET_LOGIN_FAILURE
The request to connect and log on to an FTP server failed.

ERROR_INTERNET_MIXED_SECURITY
The content is not entirely secure. Some of the content being viewed may have come from unsecured servers.

ERROR_INTERNET_NAME_NOT_RESOLVED
The server name could not be resolved.

ERROR_INTERNET_NEED_UI
A user interface or other blocking operation has been requested.

ERROR_INTERNET_NO_CALLBACK
An asynchronous request could not be made because a callback function has not been set.

ERROR_INTERNET_NO_CONTEXT
An asynchronous request could not be made because a zero context value was supplied.

ERROR_INTERNET_NO_DIRECT_ACCESS
Direct network access cannot be made at this time.

ERROR_INTERNET_NOT_PROXY_REQUEST
The request cannot be made via a proxy.

ERROR_INTERNET_OFFLINE
Identical to the preferred value ERROR_INTERNET_DISCONNECTED.

ERROR_INTERNET_OPERATION_CANCELLED
The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed.

ERROR_INTERNET_OPTION_NOT_SETTABLE
The requested option cannot be set, only queried.

ERROR_INTERNET_OUT_OF_HANDLES
No more handles could be generated at this time.

ERROR_INTERNET_POST_IS_NON_SECURE
The application is posting data to a sever that is not secure.

ERROR_INTERNET_PROTOCOL_NOT_FOUND
The requested protocol could not be located.

ERROR_INTERNET_PROXY_SERVER_UNREACHABLE
The designated proxy server cannot be reached.

ERROR_INTERNET_REDIRECT_SCHEME_CHANGE
The function could not handle the redirection, because the scheme changed (for example, HTTP to FTP).

ERROR_INTERNET_REGISTRY_VALUE_NOT_FOUND
A required registry value could not be located.

ERROR_INTERNET_REQUEST_PENDING
The required operation could not be completed because one or more requests are pending.

ERROR_INTERNET_SEC_CERT_CN_INVALID
SSL certificate common name (host name field) is incorrect—for example, if you entered www.server.com and the common name on the certificate says www.different.com.

ERROR_INTERNET_SEC_CERT_DATE_INVALID
SSL certificate date that was received from the server is bad. The certificate is expired.

ERROR_INTERNET_SEC_CERT_REVOKED
SSL certificate was revoked.

ERROR_INTERNET_SEC_INVALID_CERT
SSL certificate is invalid.

ERROR_INTERNET_SECURITY_CHANNEL_ERROR
The application experienced an internal error loading the SSL libraries.

ERROR_INTERNET_SERVER_UNREACHABLE
The Web site or server indicated is unreachable.

ERROR_INTERNET_SHUTDOWN
The Win32 Internet function support is being shut down or unloaded.

ERROR_INTERNET_TCPIP_NOT_INSTALLED
The required protocol stack is not loaded and the application cannot start WinSock.

ERROR_INTERNET_TIMEOUT
The request has timed out.

ERROR_INTERNET_UNABLE_TO_CACHE_FILE
The function was unable to cache the file.

ERROR_INTERNET_UNABLE_TO_DOWNLOAD_SCRIPT
The automatic proxy configuration script could not be downloaded. The INTERNET_FLAG_MUST_CACHE_REQUEST flag was set.

ERROR_INTERNET_UNRECOGNIZED_SCHEME
The URL scheme could not be recognized, or is not supported.

ERROR_INVALID_HANDLE
The handle that was passed to the API has been either invalidated or closed. (Win32 error code)

ERROR_NO_MORE_FILES
No more files have been found. (Win32 error code)

ERROR_NO_MORE_ITEMS
No more items have been found. (Win32 error code)


XML Object Model

This document defines the Extensible Markup Language (XML) Object Model for Microsoft® Internet Explorer 4.0. XML is a simplified subset of SGML, designed specifically for Web applications. Unlike HTML, in which every tag or element needs to be known in advance, the XML elements or attributes do not. An XML parser can use a document type definition (DTD) for a specific XML document if one is available.

Overview

Reference


Overview

The most generic object model for an XML document will be able to take in any XML document as input and provide to the application a means of manipulating this XML document. For more information on XML, see http://www.microsoft.com/sitebuilder/standards/xml/.

Note Applications should not use fibers on any thread on which the XML Object Model is created by calling IPersistMoniker::Load, since the Msxml.dll uses fibers for asynchronous downloads and they may interfere with each other.

XML-based documents are currently being used for at least two different applications for Microsoft Internet Explorer 4.0:

  • CDF files (Channel Definition Format), where a channel is a Web site that has been enabled for Webcasting to information-receiving programs such as Internet Explorer 4.0. The mechanism that makes this possible in Internet Explorer 4.0 is the CDF file. The CDF file provides an index of resources available in the channel, and a recommended schedule for when the channel should be updated on the local computer.
  • XML-based documents are also being used in Internet Explorer 4.0 for describing download modules for download of code in the form of cabinet files, Java packages, and so on. This new format is meant to supersede .inf files and is called the Open Software Description (OSD) format.

The interfaces in the following section describe a minimal set of objects that can be used to construct an object model for XML. In the future (post Internet Explorer 4.0), this object model will be extended to allow for a richer set of methods. The goals for the design of this set of interfaces as well as the justification for those goals are, in order of priority:

  • The object model should enable the ability to manipulate any generic XML document. However, the methods needed for manipulating a CDF were highest in priority.
  • The feel of the object model should mimic that of the IE4/MSHTML object model as closely as possible. This is to enable a programmer familiar with IE4/MSHTML to get started easily.

Object Model Overview

The object model is free-threaded, thus no marshaling is required.

An XML document can be thought of as a tree. A container tag is a nonleaf node in this tree. Tags that do not contain any other tags end up as leaf nodes of this tree. A root element whose children are all the top-level nodes is imposed.

Samples

This section contains some simple implementations of the XML object model. The samples are:

  • Sample 1: Parsing an XML file
  • Sample 2: Parsing a CDF file for specific tags
  • Sample 3: Using IPersistMoniker::Load to load a document
  • Sample 4: Parsing an XML file using JScript


Sample 1: Parsing an XML file

#define UNICODE

#include <windows.h>
#include <windowsx.h>
#include <stdlib.h>
#include <stdio.h>
#include <io.h>
#include <urlmon.h>
#include <hlink.h>
#include <dispex.h>
#include "mshtml.h"
#include "msxml.h"

#define ASSERT(x)  if(!(x)) DebugBreak()
#define CHECK_ERROR(cond, err) if (!(cond)) {pszErr=(err); goto done;}
#define SAFERELEASE(p) if (p) {(p)->Release(); p = NULL;} else ;

int _cdecl main (int argc, char **argv)
{
    PSTR pszErr = NULL;
    IXMLDocument           *pDoc = NULL;
    IStream                *pStm = NULL;
    IPersistStreamInit     *pPSI = NULL;
    CHAR                   buf[MAX_PATH];
    CHAR                   *pszURL;

    HRESULT hr;

    //
    // Check usage.
    //
    if (argc != 2)
    {
        fprintf (stderr, "Usage:   %s URL\n", argv[0]);
        fprintf (stderr, "Eg %s c:\\nt\\private\\inet\\xml\\test\\channel.cdf\n", argv[0]);
        fprintf (stderr, "or %s http://ohserv/users/julianj/msnbc.cdf\n", argv[0]);
        exit (1);
    }

    //
    // HACK if passed in a file name; expand if it doesn't look like a URL.
    //
    if (CompareStringA(LOCALE_USER_DEFAULT, NORM_IGNORECASE, argv[1], 7, "http://", 7) == CSTR_EQUAL)
    {
        pszURL = argv[1];
    }
    else
    {
        pszURL = buf;
        GetFullPathNameA(argv[1], MAX_PATH, pszURL, NULL);
    }

    hr = CoInitialize(NULL);
    ASSERT(SUCCEEDED(hr));

    //
    // Create an empty XML document.
    //
    hr = CoCreateInstance(CLSID_XMLDocument, NULL, CLSCTX_INPROC_SERVER,
                                IID_IXMLDocument, (void**)&pDoc);

    CHECK_ERROR (pDoc, "CoCreateInstance Failed");

    //
    // Synchronously create a stream on a URL.
    //
    hr = URLOpenBlockingStreamA(0, pszURL, &pStm, 0,0);
    CHECK_ERROR(SUCCEEDED(hr) && pStm, "Couldn't open stream on URL")
    //
    // Get the IPersistStreamInit interface to the XML doc.
    //
    hr = pDoc->QueryInterface(IID_IPersistStreamInit, (void **)&pPSI);
    CHECK_ERROR(SUCCEEDED(hr), "QI for IPersistStreamInit failed");

    //
    // Init the XML doc from the stream.
    //
    hr = pPSI->Load(pStm);
    //CHECK_ERROR(SUCCEEDED(hr), "Couldn't load XML doc from stream");

    if(SUCCEEDED(hr))
    {
        printf("%s : XML File is well formed \r\n",argv[0]);

    }
    else
    {
        // Print error information !
        IXMLError *pXMLError = NULL ;
        XML_ERROR xmle;

        hr = pPSI->QueryInterface(IID_IXMLError, (void **)&pXMLError);
        CHECK_ERROR(SUCCEEDED(hr), "Couldn't get IXMLError");

        ASSERT(pXMLError);

        hr = pXMLError->GetErrorInfo(&xmle);
        SAFERELEASE(pXMLError);
        CHECK_ERROR(SUCCEEDED(hr), "GetErrorInfo Failed");

        printf("%s :", argv[0]);
        wprintf(TEXT(" Error on line %d. Found %s while expecting %s\r\n"),
                            xmle._nLine,
                            xmle._pszFound,
                            xmle._pszExpected);

        SysFreeString(xmle._pszFound);
        SysFreeString(xmle._pszExpected);
        SysFreeString(xmle._pchBuf);
    }

done: // Clean up.
    //
    // Release any used interfaces.
    //
    SAFERELEASE(pPSI);
    SAFERELEASE(pStm);
    SAFERELEASE(pDoc);

    if (pszErr)
        fprintf (stderr, "%s, last error %d\n", pszErr, GetLastError());
    return 0;
}


Sample 2: Parsing a CDF file for specific tags

//*******************************
// XML OM test code
//
// *******************************

#include <windows.h>
#include <windowsx.h>
#include <stdlib.h>
#include <stdio.h>
#include <io.h>
#include <urlmon.h>
#include <hlink.h>
#include <dispex.h>
#include "mshtml.h"
#include "msxml.h"

#define ASSERT(x)  if(!(x)) DebugBreak()
#define CHECK_ERROR(cond, err) if (!(cond)) {pszErr=(err); goto done;}
#define SAFERELEASE(p) if (p) {(p)->Release(); p = NULL;} else ;

#define WALK_ELEMENT_COLLECTION(pCollection, pDispItem) \
    {\
        long length;\
        \
        if (SUCCEEDED(pChildren->get_length(&length)) && length > 0)\
        {\
            VARIANT vIndex, vEmpty;\
            vIndex.vt = VT_I4;\
            vEmpty.vt = VT_EMPTY;\
                                 \
            for (long i=0; i<length; i++)\
            {\
                vIndex.lVal = i;\
                IDispatch *pDispItem = NULL;\
                if (SUCCEEDED(pCollection->item(vIndex, vEmpty, &pDispItem)))\
                {

#define END_WALK_ELEMENT_COLLECTION(pDispItem) \
                    pDispItem->Release();\
                }\
            }\
        }\
    }

void Indent(int indent)
{
    while (indent-->0)
    {
        printf("   ");
    }
}

void Output(int indent, const char *format, ...)
{
    va_list argptr;

    va_start(argptr, format);

    Indent(indent);

     (void)vprintf(format, argptr);
}

void OutputLn(int indent, const char *format, ...)
{
    va_list argptr;

    va_start(argptr, format);

    printf("\n");

    Indent(indent);

    (void)vprintf(format, argptr);
}

//
// Dump an element attribute member if present.
//
void DumpAttrib(IXMLElement *pElem, BSTR bstrAttribName)
{
    VARIANT vProp;

    VariantInit(&vProp);

    if (SUCCEEDED(pElem->getAttribute(bstrAttribName, &vProp)))
    {
        if (vProp.vt == VT_BSTR)
        {
            printf(" %S=\"%S\"", bstrAttribName, vProp.bstrVal);
        }
        VariantClear(&vProp);
    }
}

//
// Helper routine to quickly find out if this is a named element
// currently only used to improve the format of the output.
//
BOOL IsNamedElement(IXMLElement *pElem)
{
    BSTR bstrName;

    if (SUCCEEDED(pElem->get_tagName(&bstrName)))
    {
        if (bstrName)
        {
            SysFreeString(bstrName);
            return TRUE;
        }
    }
    return FALSE;
}

//
// Returns TRUE if this element had children.
//
void DumpElement
(
    IXMLElement *pElem, // the XML element to dump
    int indent          // indentation level
)
{
    BSTR bstrTagName = NULL;
    BSTR bstrContent = NULL;
    IXMLElementCollection * pChildren;
    //
    // Note this nonsense with children and grandchildren is just so we get
    // nicely formatted output!
    //
    BOOL fHadNamedChild = FALSE;

    //
    // Dump the name of the NODE.
    //
    pElem->get_tagName(&bstrTagName);
    if (bstrTagName)
    {
        //
        // Special case the output of the special tags.
        //
        if (wcscmp(bstrTagName, L"XML") == 0)
        {
            Output(indent, "<\?XML version=\"1.0\"\?>\n");
            SysFreeString(bstrTagName);
            return;
        }
        else if (wcscmp(bstrTagName, L"DOCTYPE") == 0)
        {
            Output(indent,
              "<!DOCTYPE CHANNEL SYSTEM \"http://www.w3c.org/Channel.dtd\">\n");
            SysFreeString(bstrTagName);
            return;
        }
        else
        {
            OutputLn(indent, "<%S", bstrTagName);
        }
    }

    //
    // Dump the attributes if present.
    //
    DumpAttrib(pElem, L"VALUE");
    DumpAttrib(pElem, L"HREF");
    DumpAttrib(pElem, L"HOUR");
    DumpAttrib(pElem, L"DAY");
    DumpAttrib(pElem, L"IsClonable");
    DumpAttrib(pElem, L"Type");

    //
    // Dump the text contents if present.
    //
    XMLELEM_TYPE xmlElemType;
    if (SUCCEEDED(pElem->get_type((long *)&xmlElemType)))
    {
        if (xmlElemType == XMLELEMTYPE_TEXT)
        {
            if (SUCCEEDED(pElem->get_text(&bstrContent)))
            {
                if (bstrContent)
                {
                    printf("%S", bstrContent);
                    SysFreeString(bstrContent);
                }
            }
        }
    }

    //
    // Find the children if they exist.
    //
    if (SUCCEEDED(pElem->get_children(&pChildren)) && pChildren)
    {
        //
        // Close the tag if present but with "children present" closure
        // that is use > instead of />.
        //
        if (bstrTagName) printf(">");

        WALK_ELEMENT_COLLECTION(pChildren, pDisp)
        {
            //
            // pDisp will iterate over an IDispatch for each item in the collection.
            //
            IXMLElement * pChild;
            if (SUCCEEDED(pDisp->QueryInterface(
                                     IID_IXMLElement, (void **)&pChild)))
            {
                if (IsNamedElement(pChild))
                    fHadNamedChild = TRUE;

                //
                // Recursively dump children.
                //
                DumpElement(pChild, indent+1);

                pChild->Release();
            }
        }
        END_WALK_ELEMENT_COLLECTION(pDisp);
        pChildren->Release();

        //
        // Display closing tag.
        //
        if (bstrTagName)
        {
            if (fHadNamedChild)
            {
                OutputLn(indent, "</%S>", bstrTagName);
            }
            else
            {
                printf("</%S>", bstrTagName);
            }
        }
    }
    else
    {
        //
        // No children so terminate tag on same line.
        //
        if (bstrTagName) printf("/>");
    }

    if (bstrTagName)
        SysFreeString(bstrTagName);
}

int MyStrToOleStrN(LPOLESTR pwsz, int cchWideChar, LPCTSTR psz)
{
    int i;
    i=MultiByteToWideChar(CP_ACP, 0, psz, -1, pwsz, cchWideChar);
    if (!i)
    {
        //DBG_WARN("MyStrToOleStrN string too long; truncated");
        pwsz[cchWideChar-1]=0;
    }
    else
        ZeroMemory(pwsz+i, sizeof(OLECHAR)*(cchWideChar-i));

    return i;
}

int _cdecl main (int argc, char **argv)
{
    PSTR pszErr = NULL;
    IXMLDocument           *pDoc = NULL;
    IStream                *pStm = NULL;
    IPersistStreamInit     *pPSI = NULL;
    IXMLElement            *pElem = NULL;
    TCHAR                  buf[MAX_PATH];
    TCHAR                  *pszURL;
    WCHAR                  *pwszURL=NULL;
    BSTR                   pBURL=NULL;

    HRESULT hr;

    //
    // Check usage.
    //
    if (argc != 2)
    {
        fprintf (stderr, "Usage:   omtest2 URL\n");
        fprintf (stderr, "Eg omtest2 c:\\nt\\private\\inet\\xml\\test\\channel.uni\n");
        fprintf (stderr, "or omtest2 http://ohserv/users/julianj/channel.xml\n");
        exit (1);
    }

    //
    // HACK if passed in a file name, expand if it doesn't look like a URL.
    //
    if (CompareString(LOCALE_USER_DEFAULT, NORM_IGNORECASE, argv[1], 7, "http://", 7) == CSTR_EQUAL)
    {
        pszURL = argv[1];
    }
    else
    {
        pszURL = buf;
        GetFullPathName(argv[1], MAX_PATH, pszURL, NULL);
    }

    hr = CoInitialize(NULL);
    ASSERT(SUCCEEDED(hr));

    //
    // Create an empty XML document.
    //
    hr = CoCreateInstance(CLSID_XMLDocument, NULL, CLSCTX_INPROC_SERVER,
                                IID_IXMLDocument, (void**)&pDoc);

    CHECK_ERROR (pDoc, "CoCreateInstance Failed");

    //
    // Synchronously create a stream on a URL.
    //
    //hr = URLOpenBlockingStream(0, pszURL, &pStm, 0,0);
    //CHECK_ERROR(SUCCEEDED(hr) && pStm, "Couldn't open stream on URL")

    //
    // Get the IPersistStreamInit interface to the XML doc.
    //
    //hr = pDoc->QueryInterface(IID_IPersistStreamInit, (void **)&pPSI);
    //CHECK_ERROR(SUCCEEDED(hr), "QI for IPersistStreamInit failed");

    //
    // Init the XML doc from the stream.
    //
    //hr = pPSI->Load(pStm);

    pwszURL = (WCHAR *)LocalAlloc(LMEM_FIXED, ((sizeof(WCHAR))*(strlen(pszURL) + 2)));
    CHECK_ERROR(pwszURL, "Mem Alloc Failure");

    hr = MyStrToOleStrN(pwszURL, (strlen(pszURL) + 1), pszURL);
    CHECK_ERROR(SUCCEEDED(hr), "Failed to convert to UNICODE");
    pBURL = SysAllocString(pwszURL);
    CHECK_ERROR(pBURL, "Mem Alloc Failure");
    LocalFree(pwszURL);

    hr = pDoc->put_URL(pBURL);

    if (SUCCEEDED(hr))
    {
        //
        // Now walk the OM and look at interesting things.
        //
        hr = pDoc->get_root(&pElem);
        CHECK_ERROR(SUCCEEDED(hr), "Failed to get_root of XML object");

        //
        // Dump the top level meta nodes of the document.
        //
        BSTR bstrVal;
        hr = pDoc->get_version(&bstrVal);
        if(FAILED(hr) || !bstrVal)
        {
            bstrVal = SysAllocString(L"1.0");
        }
        //
        Output(0, "<\?XML version=\"%S\" ",bstrVal);
        SysFreeString(bstrVal);
        bstrVal = NULL;

        hr = pDoc->get_encoding(&bstrVal);
        if(SUCCEEDED(hr) && bstrVal)
        {
            Output(0, "encoding=\"%S\" ",bstrVal);
            SysFreeString(bstrVal);
        }
        Output(0, "\?>\n");

        //
        // Look for doctype information.
        //

        // Disabled till DavidSch makes a fix
        /*
        bstrVal = NULL;
        hr = pDoc->get_doctype(&bstrVal);
        if(SUCCEEDED(hr) && bstrVal)
        {
            Output(0, "<!DOCTYPE %S>",bstrVal);
            SysFreeString(bstrVal);

        }
        */
        //
        // Dump the root element and all children of the XML object.
        //

        DumpElement(pElem, 0); // -1 to counteract nameless outer container
    }
    else
    {
        //
        // Failed to parse stream, output error information.
        //
        IXMLError *pXMLError = NULL ;
        XML_ERROR xmle;

        hr = pDoc->QueryInterface(IID_IXMLError, (void **)&pXMLError);
        CHECK_ERROR(SUCCEEDED(hr), "Couldn't get IXMLError");

        ASSERT(pXMLError);

        hr = pXMLError->GetErrorInfo(&xmle);
        SAFERELEASE(pXMLError);
        CHECK_ERROR(SUCCEEDED(hr), "GetErrorInfo Failed");

        printf("%s: Error on line %d. Found %S while expecting %S\r\n",
                argv[0],
                xmle._nLine,
                xmle._pszFound,
                xmle._pszExpected);

        SysFreeString(xmle._pszFound);
        SysFreeString(xmle._pszExpected);
        SysFreeString(xmle._pchBuf);
    }

done: // Clean up.
    //
    // Release any used interfaces.
    //
    SAFERELEASE(pPSI);
    SAFERELEASE(pStm);
    SAFERELEASE(pElem);
    SAFERELEASE(pDoc);
    SysFreeString(pBURL);
    if (pszErr)
        fprintf (stderr, "%s, last error %d\n", pszErr, GetLastError());
    return 0;
}


Sample 3: Using IPersistMoniker::Load to load a document

//****************************************
// MSXML OM test code
//
// adapted for multithreaded urlmon testing
//****************************************

#include <windows.h>
#include <windowsx.h>
#include <stdlib.h>
#include <stdio.h>
#include <io.h>
#include <urlmon.h>
#include <hlink.h>
#include <dispex.h>
#include "mshtml.h"
#include "msxml.h"

int MyStrToOleStrN(LPOLESTR pwsz, int cchWideChar, LPCTSTR psz);
#define ASSERT(x)  if(!(x)) DebugBreak()
#define CHECK_ERROR(cond, err) if (!(cond)) {pszErr=(err); goto done;}
#define SAFERELEASE(p) if (p) {(p)->Release(); p = NULL;} else ;
//
// SAFECAST(obj, type)
//
// This macro is extremely useful for enforcing strong typechecking on other
// macros.  It generates no code.
//
// Simply insert this macro at the beginning of an expression list for
// each parameter that must be typechecked.  For example, for the
// definition of MYMAX(x, y), where x and y absolutely must be integers,
// use:
//
//   #define MYMAX(x, y)    (SAFECAST(x, int), SAFECAST(y, int), ((x) > (y) ? (x) : (y)))
//
//
#define SAFECAST(_obj, _type) (((_type)(_obj)==(_obj)?0:0), (_type)(_obj))

#define WALK_ELEMENT_COLLECTION(pCollection, pDispItem) \
    {\
        long length;\
        \
        if (SUCCEEDED(pCollection->get_length(&length)) && length > 0)\
        {\
            VARIANT vIndex, vEmpty;\
            vIndex.vt = VT_I4;\
            vEmpty.vt = VT_EMPTY;\
                                 \
            for (long i=0; i<length; i++)\
            {\
                vIndex.lVal = i;\
                IDispatch *pDispItem = NULL;\
                if (SUCCEEDED(pCollection->item(vIndex, vEmpty, &pDispItem)))\
                {

#define END_WALK_ELEMENT_COLLECTION(pDispItem) \
                    pDispItem->Release();\
                }\
            }\
        }\
    }

//==========================================================================

class CTestBindStatusCallback : public IBindStatusCallback
                              , public IAuthenticate
                              , public IHttpSecurity

    {
    public:
        // *** IUnknown methods ***
        STDMETHOD(QueryInterface)(REFIID riid, LPVOID * ppvObj);
        STDMETHOD_(ULONG, AddRef)(void) ;
        STDMETHOD_(ULONG, Release)(void);

        // *** IAuthenticate ***
        STDMETHOD(Authenticate)(
            HWND *phwnd,
            LPWSTR *pszUsername,
            LPWSTR *pszPassword);

        // *** IBindStatusCallback ***
        STDMETHOD(OnStartBinding)(
            /* [in] */ DWORD grfBSCOption,
            /* [in] */ IBinding *pib);

        STDMETHOD(GetPriority)(
            /* [out] */ LONG *pnPriority);

        STDMETHOD(OnLowResource)(
            /* [in] */ DWORD reserved);

        STDMETHOD(OnProgress)(
            /* [in] */ ULONG ulProgress,
            /* [in] */ ULONG ulProgressMax,
            /* [in] */ ULONG ulStatusCode,
            /* [in] */ LPCWSTR szStatusText);

        STDMETHOD(OnStopBinding)(
            /* [in] */ HRESULT hresult,
            /* [in] */ LPCWSTR szError);

        STDMETHOD(GetBindInfo)(
            /* [out] */ DWORD *grfBINDF,
            /* [unique][out][in] */ BINDINFO *pbindinfo);

        STDMETHOD(OnDataAvailable)(
            /* [in] */ DWORD grfBSCF,
            /* [in] */ DWORD dwSize,
            /* [in] */ FORMATETC *pformatetc,
            /* [in] */ STGMEDIUM *pstgmed);

        STDMETHOD(OnObjectAvailable)(
            /* [in] */ REFIID riid,
            /* [iid_is][in] */ IUnknown *punk);

        /* *** IHttpSecurity ***  */
        STDMETHOD(GetWindow)(REFGUID rguidReason, HWND* phwnd);

        STDMETHOD(OnSecurityProblem)(DWORD dwProblem);

        // Worker routines

        IBinding*       m_pib;
        IMoniker*        m_pmk;
        IBindCtx*       m_pbc;
        HANDLE          m_hEvent;

        ULONG m_cRef;

        VOID Abort(); // Aborts the binding
        ~CTestBindStatusCallback();
        CTestBindStatusCallback(IBindCtx *pbc, IMoniker *pmkIn, HANDLE hEvent);
    };

void Indent(int indent, FILE *fileID)
{
    while (indent-->0)
    {
        fprintf(fileID, "    ");
    }
}

//
// Dump an element attribute member if present.
//
void DumpAttrib(IXMLElement *pElem, BSTR bstrAttribName, FILE *fileID)
{
    VARIANT vProp;

    VariantInit(&vProp);

    if (SUCCEEDED(pElem->getAttribute(bstrAttribName, &vProp)))
    {
        if (vProp.vt == VT_BSTR)
        {
            fprintf(fileID, "%S=\"%S\" ", bstrAttribName, vProp.bstrVal);
        }
        VariantClear(&vProp);
    }
}

HRESULT DumpElement(IXMLElement *pElem, int indent, FILE *fileID)
{
    BSTR bstr = NULL;
    IXMLElementCollection * pChildren;

    Indent(indent, fileID);

    //
    // Dump the name of the NODE.
    //
    pElem->get_tagName(&bstr);
    fprintf(fileID, "<%S ", bstr?bstr:L"XML");

    //
    // Dump the attributes if present.
    //
    DumpAttrib(pElem, L"VALUE", fileID);
    DumpAttrib(pElem, L"HREF", fileID);
    DumpAttrib(pElem, L"HOUR", fileID);
    DumpAttrib(pElem, L"DAY", fileID);
    DumpAttrib(pElem, L"IsClonable", fileID);
    DumpAttrib(pElem, L"Type", fileID);

    //
    // Find the children if they exist.
    //
    if (SUCCEEDED(pElem->get_children(&pChildren)) && pChildren)
    {
        fprintf(fileID, ">\n");

        WALK_ELEMENT_COLLECTION(pChildren, pDisp)
        {
            //
            // pDisp will iterate over an IDispatch for each item in the collection.
            //
            IXMLElement * pChild;
            if (SUCCEEDED(pDisp->QueryInterface(IID_IXMLElement, (void **)&pChild)))
            {
                DumpElement(pChild, indent+1, fileID);
                pChild->Release();
            }
        }
        END_WALK_ELEMENT_COLLECTION(pDisp);
        pChildren->Release();
        //
        // Have output children display closing tag.
        //
        Indent(indent, fileID);
        fprintf(fileID, "</%S>\n", bstr?bstr:L"XML");
    }
    else
    {
        //
        // No children so terminate tag on same line.
        //
        fprintf(fileID, "/>\n");
    }

    if (bstr)
        SysFreeString(bstr);

    return S_OK;
}

HANDLE g_hMutex = NULL;
ULONG g_ulNextThreadId = 0;

DWORD WINAPI LoadFunc(CHAR *pszUrl)
{

FILE *fileID = stdout;
    HRESULT hr;
    IXMLElement *pElem = NULL;
    IUnknown *pUnk = NULL;
    IXMLDocument *pDoc = NULL;
    IMoniker *pmk = NULL;
    HANDLE hEvent = NULL;
    IBindStatusCallback *pPreviousCallback = NULL;
    IPersistMoniker *pPersistmk = NULL;
    PSTR pszErr = NULL;
    IBindCtx *pbc = NULL;
    IBindStatusCallback *pbsc = NULL;
    DWORD dwRet;
    LONG len;
    WCHAR *pwszUrl;

    ASSERT(SUCCEEDED(hr));
    len = lstrlenA(pszUrl);

    pwszUrl = (WCHAR *)LocalAlloc(LMEM_FIXED, (len + 1)*sizeof(WCHAR));
    ASSERT(pwszUrl);
    MyStrToOleStrN(pwszUrl, len + 1, pszUrl);

    //
    // Dump the root element and all children of the XML object.
    //

    ASSERT(SUCCEEDED(hr));
    if (!pDoc)
    {
        hr = CoCreateInstance(CLSID_XMLDocument, NULL, CLSCTX_INPROC_SERVER,
                                IID_IUnknown, (void**)&pUnk);
    }

    CHECK_ERROR (pUnk, "CoCreateInstance");

    hr = pUnk->QueryInterface(IID_IXMLDocument, (void **)&pDoc);

    ASSERT(SUCCEEDED(hr));
    pUnk->Release();
    pUnk = NULL;
    CHECK_ERROR (pDoc, "QI for IXMLDocument");

    hr = pDoc->QueryInterface(IID_IPersistMoniker, (void **)&pPersistmk);
    ASSERT(SUCCEEDED(hr));

    CHECK_ERROR(pPersistmk, "QI for IPersistMoniker");

    hr = CreateURLMoniker(NULL, pwszUrl, &pmk);
    ASSERT(SUCCEEDED(hr));
    CHECK_ERROR(pmk, "CreateURLMoniker");

    hr = CreateBindCtx(0, &pbc);
    if((!pbc) || FAILED(hr))
        goto done;

    pbc->AddRef();

    hEvent = CreateEventA(0, 0, 0, 0);
    pbsc = new CTestBindStatusCallback(pbc, pmk, hEvent);
    ASSERT(pbsc);
    if(!pbsc)
    {
        fprintf (stderr, "Out of memory ");
        goto done;
    }
    pbsc->AddRef();

    hr = RegisterBindStatusCallback(pbc, pbsc, &pPreviousCallback, 0);
    if(FAILED(hr))
    {
        fprintf (stderr, "RegisterBindStatusCallback : Failed");
        goto done;
    }

    hr = pPersistmk->Load(FALSE, pmk, pbc, 0);

    ASSERT(SUCCEEDED(hr));

    if(pPersistmk)
    {
        pPersistmk->Release();
        pPersistmk = NULL;
    }

    while(1)
    {
        MSG msg;
        dwRet =  MsgWaitForMultipleObjects(1, &hEvent, FALSE, INFINITE, QS_ALLINPUT);
        if(dwRet == WAIT_OBJECT_0)
        {
            // We're done
            break;
         }
         else
         {
            GetMessage(&msg, NULL, 0, 0);
            DispatchMessage(&msg);
         }
    }
    // Ready to start dumping the document.

    //
    // Now walk the OM and look at interesting things.
    //
    hr = pDoc->get_root(&pElem);
    CHECK_ERROR(pElem, "Thread Failed to get_root of XML object");

    DumpElement(pElem, 0, fileID);

done: // Clean up.
    fclose(fileID);
    pElem->Release();
    LocalFree(pwszUrl);
    pbsc->Release();
    return 0;
}

int MyStrToOleStrN(LPOLESTR pwsz, int cchWideChar, LPCTSTR psz)
{
    int i;
    i=MultiByteToWideChar(CP_ACP, 0, psz, -1, pwsz, cchWideChar);
    if (!i)
    {
        //DBG_WARN("MyStrToOleStrN string too long; truncated");
        pwsz[cchWideChar-1]=0;
    }
    else
        ZeroMemory(pwsz+i, sizeof(OLECHAR)*(cchWideChar-i));

    return i;
}

#define NUM_THREADS 1
const WCHAR *szUrls[NUM_THREADS] = {  L"http://ie_tools/bharats/msnbc0.cdf",
                                      //L"http://ie_tools/bharats/msnbc1.cdf",
                                     // L"http://ie_tools/bharats/msnbc2.cdf",
                                      //L"http://ie_tools/bharats/msnbc3.cdf",
                                      //L"http://ie_tools/bharats/msnbc4.cdf"
                                    };

int _cdecl main (int argc, char **argv)
{
    PSTR pszErr = NULL;
    IStream                *pStm = NULL;
    IPersistStreamInit     *pPSI = NULL;
    IXMLElement            *pElem = NULL;
    char                  buf[MAX_PATH];
    char                  *pszURL;
    UINT uNumThreads = NUM_THREADS; // Atleast three threads
    UINT ui;// iterator
    DWORD dwThreadId;
    HANDLE hThd;
    WCHAR *pwszStrUrlCopy = NULL;
    LONG len;

    HRESULT hr;

    //
    // Check usage.
    //
    if (argc < 2)
    {
        fprintf (stderr, "Usage:   %s URL\n",argv[0]);
        fprintf (stderr, "Eg %s c:\\nt\\private\\inet\\xml\\test\\channel.uni\n", argv[0]);
        fprintf (stderr, "or %s http://ohserv/users/julianj/channel.xml\n", argv[0]);
        exit (1);
    }

    // HACK if passed in a file name, expand if it doesn't look like a URL.
    //

    if (CompareString(LOCALE_USER_DEFAULT, NORM_IGNORECASE, argv[1], 7, "http://", 7) == CSTR_EQUAL)
    {
        pszURL = argv[1];
    }
    else
    {
        pszURL = buf;
        GetFullPathName(argv[1], MAX_PATH, pszURL, NULL);
    }

    hr = CoInitialize(NULL);
    ASSERT(SUCCEEDED(hr));

    //
    // Create an empty XML document.
    //
    LoadFunc(pszURL);

    len = lstrlen(pszURL) + 1;

    //
    // Dump the root element and all children of the XML object onto screen.

done: // Clean up.
    //
    // Release any used interfaces.
    //
    SAFERELEASE(pPSI);
    SAFERELEASE(pStm);
    SAFERELEASE(pElem);

    if (pszErr)
        fprintf (stderr, "%s, last error %d\n", pszErr, GetLastError());

    return 0;
}

STDMETHODIMP CTestBindStatusCallback::QueryInterface(
                                REFIID riid,
                                LPVOID * ppvObj)
{
    if (IsEqualIID(riid, IID_IBindStatusCallback) ||
        IsEqualIID(riid, IID_IUnknown))
    {
        *ppvObj = SAFECAST(this, IBindStatusCallback*);
    }
    else if (IsEqualIID(riid, IID_IAuthenticate))
    {
        *ppvObj = SAFECAST(this, IAuthenticate*);
    }
    else if (IsEqualIID(riid, IID_IHttpSecurity))
    {
        *ppvObj = SAFECAST(this, IHttpSecurity*);
    }
    else
    {
        *ppvObj = NULL;
        return E_NOINTERFACE;
    }

    ((LPUNKNOWN)*ppvObj)->AddRef();
    return NOERROR;
}

ULONG CTestBindStatusCallback::AddRef(void)
{
    return ++m_cRef;
}

ULONG CTestBindStatusCallback::Release(void)
{
    if( 0L != --m_cRef )
        return m_cRef;

    delete this;
    return 0L;
}

VOID CTestBindStatusCallback::Abort()
{
    if(m_pib)
    {
        m_pib->Abort();
    }
}

CTestBindStatusCallback::CTestBindStatusCallback(IBindCtx *pbc, IMoniker *pmkIn, HANDLE hEvent)
{

    // Initialize object.
    m_cRef=0L;

    m_pib = NULL;
    m_pbc = pbc;
    if(m_pbc)
        m_pbc->AddRef();

    m_pmk = pmkIn;
    if(m_pmk)
        m_pmk->AddRef();

    m_hEvent = hEvent;
}

CTestBindStatusCallback::~CTestBindStatusCallback()
{
    SAFERELEASE(m_pib);
    SAFERELEASE(m_pbc);

    SAFERELEASE(m_pmk);
    if(m_hEvent)
        CloseHandle(m_hEvent);
}

// IAuthenticate Methods
STDMETHODIMP CTestBindStatusCallback::Authenticate(
    HWND *phwnd,
    LPWSTR *pszUsername,
    LPWSTR *pszPassword)
{
    return E_NOTIMPL;
}

// IBindStatusCallback Methods
STDMETHODIMP CTestBindStatusCallback::OnStartBinding(DWORD grfBSCOption,
IBinding *pibIn)
{

    return S_OK;

}

STDMETHODIMP CTestBindStatusCallback::GetPriority(LONG *pnPriority)
{
    return S_OK;
}

STDMETHODIMP CTestBindStatusCallback::OnLowResource(DWORD reserved)
{
    return S_OK; //BUGBUG
}

STDMETHODIMP CTestBindStatusCallback::OnProgress(
    ULONG ulProgress,
    ULONG ulProgressMax,
    ULONG ulStatusCode,
    LPCWSTR szStatusText)
{
    return S_OK;
}

STDMETHODIMP CTestBindStatusCallback::OnStopBinding(
    HRESULT hresult,
    LPCWSTR szError)
{
    HRESULT hr = S_OK;
    if(SUCCEEDED(hresult))
    {
        OutputDebugString(TEXT("Done Loading succesfully"));
    }
    // Signal event to wake up thread to navigate children.
    SetEvent(m_hEvent);

    SAFERELEASE(m_pib);
    return hr;
}

STDMETHODIMP CTestBindStatusCallback::GetBindInfo(
    DWORD *grfBINDF, /* [out] */
    BINDINFO *pbindinfo /* [unique][out][in] */ )
{
    return E_NOTIMPL;

}

STDMETHODIMP CTestBindStatusCallback::OnDataAvailable(
    /* [in] */ DWORD grfBSCF,
    /* [in] */ DWORD dwSize,
    /* [in] */ FORMATETC *pformatetc,
    /* [in] */ STGMEDIUM *pstgmed)
{
    return S_OK;
}

STDMETHODIMP CTestBindStatusCallback::OnObjectAvailable(
    /* [in] */ REFIID riid,
    /* [iid_is][in] */ IUnknown *punk)
{
    return S_OK;
}

/* *** IHttpSecurity ***  */
        // BUGBUG - Do we need to implement this interface
STDMETHODIMP CTestBindStatusCallback::GetWindow(REFGUID rguidReason, HWND*
phwnd)
{
    if (!phwnd)
        return E_POINTER;

    *phwnd = NULL; // BUGBUG
    return S_OK;
}

STDMETHODIMP CTestBindStatusCallback::OnSecurityProblem(DWORD dwProblem)
{
    // Force UI - return S_FALSE for all problems.
    return S_FALSE;
}


Sample 4: Parsing an XML file using JScript

<HTML>
<HEAD>
<TITLE>JScript XML Sample</TITLE>
</HEAD>
<BR>
<H1><B><CENTER>JScript XML Sample</B></H1>
<P>This page demonstrates using XML in JScript. Enter a valid XML or CDF file in the
text box below and it will be parsed using MSXML and JScript. CDF is based on XML.
Information about each element in the file will be displayed in another window. For more
information on CDF, please see the <A HREF="http://www.microsoft.com/ie/authors/">Internet
Explorer 4.0 authors and developers </A> site.

<P>Enter an XML or CDF file name:<BR>
<INPUT TYPE=TEXT NAME="cdfURL" VALUE="" size=50><BR>

<OBJECT
    classid="clsid:CFC399AF-D876-11D0-9C10-00C04FC99C8E"
    id="MSXML"
    Name="xmlDoc">
</OBJECT>

<BR><BR>

<INPUT TYPE = "BUTTON"
    NAME = "ParseCDF"
    VALUE = "Parse The XML/CDF File"
    onClick = "WalkXMLMain(cdfURL.value)">

</CENTER>

<SCRIPT>
var win;                                // status goes here
var doc;                                // document to write on
var knownAttrs = new Object;            // element attribute variable

//
// Display the attribute.
//
function dumpAttrs(elem)
{
    var i, val, result = "";

    for (i in knownAttrs)
    {
    val = elem.getAttribute(knownAttrs[i]);
        if ((val != "") && (val != null))
            result = result + knownAttrs[i] + "=" + val + " ";
    }

    return result;
}

//
// Display the element information for each element in the file.
//
function dumpElement(elem)
{
    var children, cChildren, child
    var i, length;

    if (elem == null)
    {
        alert("elem == null");
        window = document;              //      Force a run-time error to bail
    }

    children = elem.children;
    if (children != null)
    length = children.length;
    else
    length = 0;

// Display the element information in the table.
    doc.write("<TR><TD>" + GetTagName(elem) + "</TD>");
    doc.write("<TD>" + GetType(elem.type) + "</TD>");
    if (elem.parent != null) // skip text for root node
    doc.write("<TD>" + elem.text + "</TD>");
    else
    doc.write("<TD>" + " " + "</TD>");
    doc.write("<TD>" + dumpAttrs(elem) + "</TD>");
    doc.write("<TD>" + GetParentTag(elem) + "</TD>");
    doc.write("<TD>" + length + "</TD></TR>");

// If the element has children, call dumpElement again
    if (children != null)
    {

        cChildren = children.length;

        for (i = 0; i < cChildren; i++)
        {
            child = children.item(i);
            dumpElement(child);
        }
    }
}

//
// Initialize the knownAttrs variable.
//
function loadKnownAttrs()
{
// Incomplete list, just for example.
    knownAttrs[0] = "HREF";
    knownAttrs[1] = "STYLE";
    knownAttrs[2] = "HOUR";
    knownAttrs[3] = "DAY";
    knownAttrs[4] = "MIN";
    knownAttrs[5] = "IsClonable";
    knownAttrs[6] = "Type";
    knownAttrs[7] = "BASE";
    knownAttrs[8] = "SELF";
}

//
// Write information to the browser status bar.
//
function setStatus(s)
{
    win.status = s;
}

//
// Main function, calls dumpElement.
//
function WalkXMLMain(cdfName)
{
    var startTime = new Date();
    var CDFFile, xmlDoc;

    win = window.open("", "XMLOutput");
    doc = win.document;

    doc.writeln("<HTML>");
    doc.writeln("<TITLE>XML Output</TITLE>");
    doc.writeln("<BODY>");
    doc.writeln("<PRE>");

    setStatus("Loading known attributes...");
    loadKnownAttrs();

    setStatus("Creating XML object...");
    xmlDoc = MSXML;

    setStatus("Loading XML document...");
    xmlDoc.URL = cdfName;
    setStatus("File has been assigned to xmlDoc.URL");

// Show the document information.
    ShowDocInfo(xmlDoc);

// Initialize the table for the element information.
    MakeNodeHeader(win);

// Traverse the XML tree showing the element information.
    dumpElement(xmlDoc.root);

    doc.writeln("</TABLE>");
    var stopTime = new Date();
    doc.writeln("<FONT SIZE=&quot+1&quot><P>Start: " + startTime + "   Stop: " + stopTime + "</FONT>");
    doc.writeln("</PRE>");
    doc.writeln("</BODY>");
    doc.writeln("</HTML>");

    xmlDoc = null;
    setStatus("Done!");
}

//
// Initialize the table for the element information.
//
function MakeNodeHeader(win)
{
    doc.writeln("<BR><BR><H2>Element Information</H2></CENTER>");
    doc.write("<FONT SIZE=&quot+1&quot><P>The properties of each node in the XML file is listed in the following table.<BR><BR></FONT>");

    doc.write("<TABLE BORDER CELLSPACING=2 CELLPADDING=2>");
    doc.write("<TR><TD ALIGN=LEFT><B>Tag Name</B></TD>");
    doc.write("<TD ALIGN=LEFT><B>Type</B></TD>");
    doc.write("<TD ALIGN=LEFT><B>Text (if any)</B></TD>");
    doc.write("<TD ALIGN=LEFT><B>Attribute</B></TD>");
    doc.write("<TD ALIGN=LEFT><B>Parent</B></TD>");
    doc.write("<TD ALIGN=LEFT><B># of Children</B></TD></TR>");
}

//
// Return the element type.
//
function GetType(type)
{

  if (type == 0)
    return "ELEMENT";

  if (type == 1)
    return "TEXT";

  if (type == 2)
    return "COMMENT";

  if (type == 3)
    return "DOCUMENT";

  if (type == 4)
    return "DTD";
  else
    return "OTHER";
}

//
// Return the tag name.
//
function GetTagName(elem)
{
  if (elem.type == 0)
    return elem.tagName;
  else
    return " ";
}

//
// Return the parent tag name.
//
function GetParentTag(elem)
{
  if (elem.parent != null)
    return GetTagName(elem.parent);
  else
    return " ";
}

//
// Display document information about the XML file.
//
function ShowDocInfo(xmlDoc)
{
  doc.writeln("<FONT FACE=&quottimes&quot SIZE=&quot+1&quot><CENTER><H2>Document Information</H2>");
  if (xmlDoc.URL != null)
    doc.writeln("<P>URL is: " + xmlDoc.URL);
  doc.writeln("<P>Version is: " + xmlDoc.version);
  if (xmlDoc.doctype != null)
    doc.writeln("<P>Doc Type is: " + xmlDoc.doctype);
  if (xmlDoc.readyState != null)
    doc.writeln("<P>Ready State is: " + GetReadyState(xmlDoc.readyState));
  if (xmlDoc.charset != null)
    doc.writeln("<P>Character Set is: " + xmlDoc.charset);
}

//
// Return the ready state of the document.
//
function GetReadyState(state)
{
  if (state == 0)
    return "READYSTATE_UNINTIALIZED";
  if (state == 1)
    return "READYSTATE_LOADING";
  if (state == 2)
    return "READYSTATE_LOADED";
  if (state == 3)
    return "READYSTATE_INTERACTIVE";
  if (state == 4)
    return "READYSTATE_COMPLETE";
  else
    return "undefined";
}

</SCRIPT>
</BODY>
</HTML>


Reference Reference *
  * Previous Topic: Sample 4: Parsing an XML file using JScript
  * Next Topic: Objects

Reference

Objects

Interfaces

Methods


Objects

The following list contains the objects associated with the XML object model.

XML Document

XML Element

Element Collections

XML Document

The object model allows an application to load an XML document and manipulate it. The document can be loaded by specifying a URL moniker or by simply providing a stream. The application can then get several properties of the document, such as URL, mime type, and created/accessed/modified time. The entire XML document is navigated by starting at the root element. In addition, the object model provides for notifications on the addition of immediate children of any given node.

The XML object inherits from the following interfaces:
IUnknown
IDispatch
IXMLDocument
IXMLError
IPersistMoniker
IPersistStream
IPersistStreamInit

The application can use either IPersistMoniker::Load or IPersistStreamInit::Load to load an XML document. It can use IPersistStreamInit::Save to save the XML document to a stream. You can also use IXMLDocument::put_URL.

XML Element

Each XML tag is represented by an object. This object derives from the following interfaces:
IUnknown
IDispatch
IXMLElement

Element Collections

The children of an element are manipulated in this object model by using collections. It is possible to enumerate the members of a collection as well as to access them by index. It is also possible to create a specialized collection of all the elements that have a certain name. Such a specialized collection is then manipulated in an identical fashion.

The XML object derives from the following interfaces:
IDispatch
IXMLElementCollection

A collection of the children of an element's pElem is obtained by using the IXMLElement::get_children method as follows:

IXMLElement *pElem = NULL;
IXMLElementCollection *pChildren = NULL;
    .
    .
    .
hr = pElem->get_children(&pChildren);
if(SUCCEEDED(hr) && pChildren)
{

}

Between calls to IXMLElement::addChild, the client application must call IXMLElementCollection::get_length on the parent collection to ensure that the application has the correct length and can request the correct index to an element when needed.

When it is guaranteed that no further elements will be added as children to this parent node, this API is called with a NULL parameter. It is guaranteed that this sink will be called at least once with a NULL parameter. The sink should then disconnect itself from this connection point when it knows that no further children are being added.


Interfaces

The following section contains the interfaces associated with the XML object model.

IXMLDocument

IXMLElement

IXMLElementCollection


IXMLDocument

IXMLDocument Methods
get_root
get_fileSize
get_fileModifiedDate
get_fileUpdatedDate
get_URL
put_URL
get_mimeType
get_readyState
get_charset
put_charset
get_version
get_doctype
createElement


IXMLElement

IXMLElement Methods
get_tagName
put_tagName
get_parent
setAttribute
getAttribute
removeAttribute
get_children
get_type
get_text
put_text
addChild
removeChild


IXMLElementCollection IXMLElementCollection *
  * Previous Topic: IXMLElement
  * Next Topic: Methods

IXMLElementCollection

IXMLElementCollection Methods
get_length
put_length
get_newEnum
item


Methods

IXMLDocument::get_root

IXMLDocument::get_fileSize

IXMLDocument::get_fileModifiedDate

IXMLDocument::get_fileUpdatedDate

IXMLDocument::get_URL

IXMLDocument::put_URL

IXMLDocument::get_mimeType

IXMLDocument::get_readyState

IXMLDocument::get_charset

IXMLDocument::put_charset

IXMLDocument::get_version

IXMLDocument::get_doctype

IXMLDocument::createElement

IXMLElement::get_tagName

IXMLElement::put_tagName

IXMLElement::get_parent

IXMLElement::setAttribute

IXMLElement::get_Attribute

IXMLElement::removeAttribute

IXMLElement::get_children

IXMLElement::get_type

IXMLElement::get_text

IXMLElement::put_text

IXMLElement::addChild

IXMLElement::removeChild

IXMLElementCollection::get_length

IXMLElementCollection::put_length

IXMLElementCollection::get_newEnum

IXMLElementCollection::item


IXMLDocument::get_root

HRESULT IXMLDocument::get_root(
    IXMLElement **ppElem)

Returns the root element of the document. The CHANNEL element is considered the root element. The caller must call IUnknown::Release on the document.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
ppElem
Indirect pointer in which to return the address of the root element's IXMLElement interface.


IXMLDocument::get_fileSize

HRESULT IXMLDocument::get_fileSize(
    BSTR  * p)

Returns the file size of the document.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing the file size.


IXMLDocument::get_fileModifiedDate

HRESULT IXMLDocument::get_fileModifiedDate(
    BSTR  * p)

Returns the date when the file was last modified.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing the modified date.

This method is not yet implemented.


IXMLDocument::get_fileUpdatedDate

HRESULT IXMLDocument::get_fileUpdatedDate(
    BSTR  * p)

Returns the date when the file was last updated.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing the updated date.

This method is not yet implemented.


IXMLDocument::get_URL

HRESULT IXMLDocument::get_URL(
     BSTR  * p)

Returns the URL associated with the document, if one exists.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing a URL value.


IXMLDocument::put_URL

HRESULT IXMLDocument::put_URL(
     BSTR  p)

Loads a new document based on the URL provided. The current document is destroyed and the new document is loaded in its place.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
String containing a URL address.


IXMLDocument::get_mimeType

HRESULT IXMLDocument::get_mimeType(
    BSTR   p)

Returns the MIME (Multipurpose Internet Mail Extension) type.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
String containing a MIME type.

MIME is a set of enhancements to SMTP allowing an Internet message to include a mixture of audio, image, video, and text components, and to accommodate a variety of international character sets. MIME messages are identified by a MIME header in the top level of the SMTP header. The MIME mechanisms are specified in the RFC 1341 document.


IXMLDocument::get_readyState

HRESULT IXMLDocument::get_readyState(
    LONG *pl)

Determines if the document is done loading.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
pl
Address of a storage area in which to return the readystate property.

The returned readystate property, such as READYSTATE_LOADED, READYSTATE_LOADING, or READYSTATE_COMPLETE, indicates whether the document has been loaded completely. If the document is still loading, the returned value is READYSTATE_LOADING; if it is successfully loaded, it is READYSTATE_COMPLETE.


IXMLDocument::get_charset

HRESULT IXMLDocument::get_charset(
    BSTR *pOutString)

Returns a string that specifies the character set of the input document according to ISO standards.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
pOutString
Address of a string containing the character set format.


IXMLDocument::put_charset

HRESULT IXMLDocument::put_charset(
    BSTR *p)

Specifies the output character set of the document according to ISO standards.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing the character set format.


IXMLDocument::get_version

HRESULT IXMLDocument::get_version(
    BSTR *p)

Returns the version of the XML specification being used.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string containing the version of XML being used.

The caller needs to deallocate the string by using SysFreeString.


IXMLDocument::get_doctype

HRESULT IXMLDocument::get_doctype(
    BSTR *p)

Returns the content specified in the !DOCTYPE element.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
p
Address of a string that contains document-specific information.


IXMLDocument::createElement

HRESULT IXMLDocument::createElement(
    [in] VARIANT vType,
    [optional, in] VARIANT var1,
    [retval, out] IXMLElement **ppElem)

Creates a new element that can then be added to a portion of the tree.

  • Returns S_OK if successful. Possible error codes include E_OUTOFMEMORY and E_INVALIDARG.
vType
Variant of type VT_I4, which contains an integer from the xmlelemTYPE enumeration, and indicates the type of the element that is desired:
typedef enum xmlelemTYPE {
    XMLELEMTYPE_ELEMENT,
    XMLELEMTYPE_TEXT,
    XMLELEMTYPE_COMMENT,
    XMLELEMTYPE_DOCUMENT,
    XMLELEMTYPE_DTD,
    XMLELEMTYPE_OTHER
} XMLELEM_TYPE;
var1
Optional. String used by IXMLElement::put_tagName to bind the name to the newly formed element.
ppElem
Indirect pointer in which to return the desired element.


IXMLElement::get_tagName

HRESULT IXMLElement::get_tagName(
    BSTR * pTagName)

Returns the name of the tag as a string.

  • Returns S_OK if successful. Error return values include E_OUTOFMEMORY and E_INVALIDARG.
pTagName
Indirect pointer in which to return the tag name.

The caller can use SysFreeString to free the string. The name is always all uppercase. The name of the comment element is returned as "!". The other META tags have names that correspond to the special character followed by the META tag name, such as the following:

The name of <?XML ...> is "?XML".


IXMLElement::put_tagName

HRESULT IXMLElement::put_tagName(
    BSTR  pTagName)

Sets the name of the tag and stores a copy of the string.

  • Returns S_OK if successful, or E_FAIL on failure.
pTagName
Address of a string containing the tag name.

The caller can use SysFreeString to free the string. The name is always all uppercase. The name of the comment element is returned as "!". The other META tags have names that correspond to the special character followed by the META tag name, such as the following:

The name of <?XML ...> is "?XML".


IXMLElement::get_parent

HRESULT IXMLElement::get_parent(
    IXMLElement ** pParent)

Every element in the tree, except the root of a document, has a parent. This parent element is AddRef'ed before being returned, and it is up to the caller to call IUnknown::Release on the returned parent element.

  • Returns S_OK if successful. Error return values include E_OUTOFMEMORY and E_INVALIDARG.

    Can also return S_FALSE if no parent exists (for the root or for a newly created element). pParent is set to zero to prevent errors when scripting agents (such as JScript or VBScript) call this method on behalf of a script.

pParent
Indirect pointer in which to return an address of the parent element. The parent element is always nonnull except for the root.


IXMLElement::setAttribute

HRESULT IXMLElement::setAttribute(
    BSTR strPropertyName,
    VARIANT PropertyValue)

Allows the setting of an attribute of this element.

  • Returns S_OK if successful. Error return values include E_OUTOFMEMORY and E_INVALIDARG.
strPropertyName
Name of the attribute
PropertyValue
Value of the attribute. The allowed input type is VT_BSTR.

The attribute's name and its new value are provided. The previous value of this attribute is lost. A private copy of the input value is made. The attribute value is always stored as a string, thus it should be sent in as a string.


IXMLElement::get_Attribute

HRESULT IXMLElement::get_Attribute(
    BSTR strPropertyName,
    VARIANT* PropertyValue)

Allows for the retrieval of an attribute's value.

  • Returns S_OK if successful. Other returned error values include E_OUTOFMEMORY and S_FALSE if no such attribute exists to prevent scripting errors.
strPropertyName
Name of the attribute.
PropertyValue
Indirect pointer in which to return the value. Always returned as a BSTR.

An attribute's name is provided. The value of the attribute is returned as a variant, which is always of type VT_BSTR. The caller must release the value by calling VariantClear.


IXMLElement::removeAttribute

HRESULT IXMLElement::removeAttribute(
    BSTR strPropertyName)

Deletes an attribute from an element. The attribute is specified by using the attribute name.

  • Returns S_OK if successful. Other returned error values include E_OUTOFMEMORY and E_INVALIDARG if no such attribute exists.
strPropertyName
Name of the attribute.


IXMLElement::get_children

HRESULT IXMLElement::get_children(
    IXMLElementCollection * * ppChildren)

Retrieves the collection of an element's children.

  • Returns one of the following values:
    S_OK | Success.
    E_FAIL | No children are present.
    E_OUTOFMEMORY | Not enough memory to process this request.
    S_FALSE | If no children exist, ppChildren is set to NULL.
ppChildren
Indirect pointer in which to return an address of the element collection. The ppChildren parameter is NULL if no children are present.

The collection allows the application to make queries about the size of the collection as well as enumerate through the children or access any of them by index. If no children exist, ppChildren is set to NULL and the return code is S_FALSE. The caller must call (ppChildren)->Release when it is done using this collection. Further discussion of IXMLElementCollection is available later in this document.


IXMLElement::get_type

HRESULT IXMLElement::get_type(
    long *plType)

  • Returns S_OK if successful.
plType
Indirect pointer to return the type.

Each node of the tree is labeled as being one of the following types:

typedef  enum xmlelemTYPE {
    XMLELEMTYPE_ELEMENT,
    XMLELEMTYPE_TEXT,
    XMLELEMTYPE_COMMENT,
<!--    XMLELEMTYPE_DOCUMENT,
    XMLELEMTYPE_DTD, -->
    XMLELEMTYPE_OTHER
} XMLELEM_TYPE;

For Internet Explorer 4.0, the interesting element types are XMLELEMTYPE_ELEMENT, XMLELEMTYPE_TEXT, and XMLELEMTYPE_COMMENT.

In the following example, both the CHANNEL and the TITLE elements are marked as being of type XMLELEMTYPE_ELEMENT. Their names are returned as "CHANNEL" and "TITLE", respectively. (The names are always all uppercase.) The TITLE element has one child, which is a text element marked as being of type XMLELEMTYPE_TEXT.

<CHANNEL>
    <title> Breaking News </title>
    <!-- This is a comment element-->
</CHANNEL>


IXMLElement::get_text

HRESULT IXMLElement::get_text(
    BSTR *pContent)

Returns the content of text and comment elements.

  • Returns S_OK if successful. Error values include E_INVALIDARG, E_OUTOFMEMORY, and E_FAIL.
pContent
Indirect pointer in which to return the content. The caller must free any returned content by using SysFreeString.

The content of a text element is the text between the tags. Consider the following elements:

<CHANNEL>
<TITLE>Top Stories</TITLE>
    .
    .
    .
</CHANNEL>

The text element child of the TITLE element has the content "Top Stories". Here the TITLE element has one child, which is the text element, and this child has the content "Top Stories".

However, calling IXMLElement::get_text on the TITLE element strips markup from the content within the TITLE tag. Use this method to get all the text in a tag. For example:

<TITLE>
This is <H> bold </H> text
</TITLE>

A good downlevel client should use "This is bold text" after stripping away any markup by calling IXMLElement::get_text on the TITLE element.

Finally, the content of a comment element is the comment. For example, the following example has the name "!" and has the content " This is a comment ".

<! This is a comment />


IXMLElement::put_text

HRESULT IXMLElement::put_text(
    BSTR pContent)

Adds or changes the content of text and comment elements.

  • Returns S_OK if successful. Error values include E_OUTOFMEMORY and E_INVALIDARG.
pContent
Content. A private copy of this string is made.


IXMLElement::addChild

HRESULT IXMLElement::addChild(
    [in] IXMLElement *pChildElem,
    long lIndex,
    long lReserved)

Adds a child to this element.

  • Returns S_OK if successful. E_INVALIDARG is returned if the index is inappropriate.
pChildElem
Address of the new child element.
lIndex
Index of the child collection at which this child should be added. If this is zero, it is added at the first element of the collection. If this is less than zero, the element is simply added to the end of the child collection.
lReserved
Should always be -1.

All the children and descendants of this new child element remain attached as before. Any element can have only one parent element, so the previous parent will lose this child from its subtree. Any threads that have already traversed the tree and expect this element to have the old parent will fail unpredictably. Note that it is possible to use this method to break off a subtree from one XML document and attach it to another XML document. However, there are some stringent restrictions on when this can be done:

  • There can be no outstanding references on collections on the child element or any of its descendants.
  • There can be no reference on any of the descendant elements of this child.

If these are not adhered to, an error will be returned.

The results when using the IXMLElementCollection::get_newEnum method from a collection obtained from this element are undefined if the enumerator is not reset.

Finally, the implementation of breaking off a node that has many children and attaching it to a tree of another document is somewhat more expensive than breaking off a node and attaching it to another node of the same document.


IXMLElement::removeChild

HRESULT IXMLElement::removeChild(
    [in] IXMLElement *pChildElem)

Removes a child of this element.

  • Returns S_OK if successful.
pChildElem
Address of the child element that should be removed.

The element remains in memory and can be reattached to a tree by using IXMLElement::addChild. All the children and descendants of this child element remain attached as before. Any threads that have already traversed the tree and expect this element to have the old parent will fail unpredictably. It is possible to use this method to break off a subtree from one XML document and attach it to another XML document. However, there are restrictions as explained in IXMLElement::addChild.

The results when using the IXMLElementCollection::get_newEnum method from a collection obtained from this element (the parent) are undefined if the enumerator is not reset.


IXMLElementCollection::get_length

HRESULT IXMLElementCollection::get_length(
    long *plLength)

Obtains the number of elements in the collection.

  • Returns S_OK if successful.
plLength
Indirect pointer in which to return the size of the collection.


IXMLElementCollection::put_length

HRESULT IXMLElementCollection::put_length(
    long length)

This method has no effect.


IXMLElementCollection::get_newEnum

HRESULT IXMLElementCollection::get__newEnum(
    IUnknown ** ppUnk)

Returns a pointer to an IEnumVARIANT enumerator that is obtained by calling IUnknown::QueryInterface on the returned object.

  • Returns S_OK if successful. Error values include E_FAIL if there are no children, and E_OUTOFMEMORY and E_INVALIDARG.
ppUnk
Indirect pointer in which to return the enumerator.

IEnumvariant is documented in the Microsoft Developer Network (MSDN). It allows the enumeration of variants. Each variant that is returned is of type VT_DISPATCH. This returned object is merely an element object, and the IXMLElement interface on the returned object can be obtained by calling IUnknown::QueryInterface on it. It is up to the caller to call IUnknown::Release on the returned enumeration. It is also the responsibility of the caller to call VariantClear on every returned element.


IXMLElementCollection::item

HRESULT IXMLElementCollection::item(
    VARIANT Var1,
    VARIANT Var2,
    IDispatch **ppDisp)

  • Returns S_OK if successful. Error values include E_OUTOFMEMORY, E_INVALIDARG, and E_FAIL. ppDisp is set to NULL if the call fails.
Var1
Index or a name. The preferred variant type of an index is VT_I4; the preferred variant type of a name is VT_BSTR.
Var2
Empty (type VT_EMPTY) or an index.
ppDisp
Indirect pointer in which to return an address of the collection or element that is to be returned.

This method is fairly involved and can be used in different ways to retrieve members of a collection or another collection. If Var1 specifies an index and Var2 is empty, the item at that index is returned if such an element does exist. Var1 can also specify a name, in which case the returned object is a collection of all elements in this collection that have the specified name. However, if there is only one element with that name, the returned object is an XML element. It is also possible to specify Var1 as a name and Var2 as an index. In that case, the returned object is an XML element that is the Var2th object of the name specified by Var1. The caller must call IUnknown::Release on any returned objects.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.