content_dev_ref

Reviews

SEE ALSO :

Preventing Image Cursors
SYNOPSIS: DESCRIPTION:

<input type="image" nocursor . . .> Images in forms are typically image maps; different parts of the image are mapped to different actions. An on-screen cursor is required for the user to navigate within the image.

Content Developer’s Reference

HTML for TV Display

The presence of the nocursor attribute indicates that the image should not behave like an image map and that a cursor is, therefore, not needed. Logically, an image map requires three user actions—one to navigate to the image, another to select a part of the image, and finally an action to invoke (or “click”) that part. On a personal computer with a mouse, users can move to the image and select a part of it with a single gesture. However, it’s not that easy in the generally cursorless environment of Interactive TV. After focusing on the image, users must take a separate action to select part of it, typically by maneuvering a temporary cursor with the arrow keys. The nocursor attribute eliminates this cumbersome step if it’s not necessary. If nocursor is not specified, the form is submitted along with the coordinates of the cursor when the user “clicks” the image. If nocursor is specified, the coordinates are not submitted (since there’s no cursor).

Highlighting Links
SYNOPSIS:

<a highlightable=["true" | "false"] . . .> <a highlightable . . .> This attribute indicates whether or not the focus rectangle will automatically highlight a link anchor when it’s the focus of the user’s attention. Only anchors with href attributes—link sources, not destinations—are focusable and can be highlighted. If the highlightable attribute is omitted, listed without a value, or set to “true”, the link can be highlighted. However, if set to “false”, the focus rectangle will not be drawn. A “false” setting allows a “bug” to be displayed over the TV picture without a distracting highlight. A “bug” is a small, semi-transparent graphic that overlays the full-screen TV image and generally resides in one corner of the screen. Pressing the Enter key selects the link associated with the bug. The “bug” should be the only focusable element the user sees. In other words, a page that sets highlightable to “false” should contain only one focusable element so that highlighting is not needed to indicate where the focus lies. A parallel property of the Link object allows you to dynamically determine whether or not an anchor should be highlighted.

DESCRIPTION:

Chapter 2: TV Display

HTML for TV Display

HISTORY: SEE ALSO :

Introduced in the 1.2 release. Link.highlightable on page 47, “Highlighting the Cell in Focus” on page 122

Preventing Focus on a Text Area
SYNOPSIS:

<textarea focusable=["true" | "false"] . . .> <textarea focusable . . .> Text areas are fields where the user can enter text in a form. Since they accept the user’s input, they’re focusable by default. However, you might want to use a text area to simply display information to the user, rather than display what the user types. Liberate extensions to the JavaScript Textarea object make it relatively easy to manage the text within a text area for this purpose. The focusable attribute gives you a choice. If it’s set to “true”, listed without a value, or not listed at all, the text area can become the focus for user input. However, if it’s set to “false”, it won’t become the focus and won’t display any characters the user types. The Textarea object has a property that matches this attribute. With it, you can dynamically determine when the text field should accept input from the user.

DESCRIPTION:

HISTORY: SEE ALSO :

Introduced in the 1.2 release. Textarea.focusable on page 99

Adjustments for the TV Screen
Web content must be laid out a bit differently for a TV screen than for a computer monitor. For one thing, many elements—especially text—need to be larger and less tightly spaced. For another, horizontal scrolling isn’t permitted, so everything on a page must fit within the width of the screen. This requires reinterpretation of some standard HTML tags and attributes. HTML is, generally, an underspecified layout language. However, when horizontal scrolling is disallowed, it is overspecified in certain situations. In these cases, TV Navigator tries to adhere first to TV-centric constraints, then to authorial intent (as far as it can be determined), and lastly to customary HTML heuristics.

Content Developer’s Reference

HTML for TV Display

All of the HTML tags and most of the attributes documented in this section are part of the standard language. The only thing that’s new is how TV Navigator interprets them.

Font Size
SYNOPSIS:

<font size=["1"–"7"]> <basefont size=["1"–"7"] | "+number" | "–number" | "small" | "medium" | "large"]> When text is shown on a TV screen, it needs to be larger than when it’s displayed on a monitor for a personal computer. The increased size is required because of the characteristics of TV monitors and the much greater distance between the user and the screen. In standard HTML, the font size for body text is set by a number in the range 1 (smallest) through 7 (largest), with size 3 as the default. TV Navigator keeps the same default, but maps all seven font sizes to larger fonts. The actual size of a font as it appears on the TV screen depends on a number of factors—the font family, the rendering mechanism, the video format, and the platform. TV Navigator lets each platform determine the actual font sizes that correspond to the relative sizes set in HTML. These values are configured using a wizard on the Liberate Command server. Although actual font sizes may vary from platform to platform, you can get a general idea of how font sizes are increased for the TV screen by noting that the default font (medium, size 3) is 12 points for Netscape Navigator but typically translates to about an 18-point font for TV Navigator on an NTSC display. The “small”, “medium”, and “large” values for the <basefont> tag permit pages to choose a scale for the font mapping. The scale determines what HTML font sizes in the range 1 through 7 mean. It also affects the size of headings (<h1> through <h6>). As you’d expect, a given font size—say, size 3 or <h4>—in the large scale is bigger than it would be in the medium scale, and bigger in the medium scale than it would be in the small scale. The medium scale is the default. The <basefont> settings affect only the current page. They should be used with care. In general, the “small” scale should never be set except as a user option, since it could make your text illegible on the user’s TV screen. You might want to set the scale to “large”, if you have material that won’t lay out well with medium or small-scale fonts.

DESCRIPTION:

Chapter 2: TV Display

HTML for TV Display

Headings
SYNOPSIS:

<h1>. . .</h1> <h2>. . .</h2> ... <h6>. . .</h6> TV Navigator increases the size of fonts used in headings to match the increase for body fonts. The scale that’s chosen for the base font size—”small”, “medium”, or “large”—affects the size of headings just as it affects the size of body text. In general, headings <h1> through <h6> match font sizes 6 through 1, but invert the order.

DESCRIPTION:

SEE ALSO :

“Font Size” on page 31

Image Spacing
SYNOPSIS: DESCRIPTION:

<img hspace="pixels" . . .> The hspace attribute of the <img> element puts space between the image and any text to its left or right. The default, if a more explicit value is not specified, is 3 pixels if the image is aligned left or right; otherwise, the default is 0 pixels. This matches the behavior of Netscape Navigator. For instance, the following line of HTML automatically gives you a 3-pixel space between the right edge of the image and the H of “Here.”
<img align="left" src="something.gif">Here is text.

This can present problems if you’re trying to get a left- or right-aligned image to fit in a table cell or line up with other images. To explicitly set the image to display without the 3 pixels of space, set hspace to 0, as follows:
<img align="left" src="something.gif" hspace="0">Here is text.

This line above displays the image with no empty pixels between the image and the letter H. If a left- or right-aligned image is in a table cell that’s too small for it, the Netscape browsers still add the 3 pixels of space, but allow the image to draw over the table cell border. TV Navigator adds the 3 pixels but scales the image to contain it within the table cell.

Content Developer’s Reference

HTML for TV Display

Image Width
SYNOPSIS: DESCRIPTION:

<img width="pixels" . . .> If an image is too wide to fit within its frame on-screen, it’s scaled to fit. The scaling retains the original proportion of width to height; in other words, the image isn’t distorted, just made smaller. If a table contains nothing but images and spacers (no text), they are all resized proportionally.

SEE ALSO:

“Preventing Line Breaks” on page 34, “Table Width and Height” on page 36

Image and Frame Borders
SYNOPSIS:

<img border="pixels" . . .> <frameset border="pixels" . . .> A border can take up valuable space on the television screen. Moreover, as explained in the Content Developer’s Guide, the sharply contrasting vertical and horizontal lines of a border can create unwanted visual artifacts when displayed on TV, especially if the border is narrow. For this reason, TV Navigator does not display borders around images; it ignores the border attribute of the <img> tag. If an image absolutely requires a border, you can include it as part of the image. For clarity, adjacent frames usually need to be separated by a border, so TV Navigator honors the border attribute of the <frameset> tag. However, to keep the border from taking up too much room, its width is limited to a maximum of 5 pixels. If the border attribute is set to a value greater than 5, a border 5 pixels wide will be displayed. Similarly, to prevent the display problems associated with 1-pixel-wide lines, the minimum border width is 2. If the border attribute is set to 1, a border 2 pixels wide is displayed. Therefore, the choices for a frame border are no border (when the border attribute is set to 0) or a border 2, 3, 4, or 5 pixels wide. The default is a 2-pixelwide border.

DESCRIPTION:

Chapter 2: TV Display

HTML for TV Display

Horizontal Rules
SYNOPSIS: DESCRIPTION:

<hr size="pixels" noshade . . .> Because the TV display is interlaced, a horizontal line that’s just one pixel wide will visibly flicker on a TV screen (or will be blurred by a flicker filter). To prevent this problem, TV Navigator disallows 1-pixel lines in a number of contexts—such as frameset and table borders and the spacing between cells in a table. One of those contexts is a horizontal rule, the <hr> tag. If you set the size attribute of this tag to 0 or 1, the rule will nevertheless be 2 pixels wide. The default size is also 2. In addition, TV Navigator always draws the line in a solid color, without any shading, as if the noshade attribute was always specified.

Preventing Line Breaks
SYNOPSIS:

<nobr>. . .</nobr> <td nowrap . . .> <pre>. . .</pre>   The <nobr> element normally prevents a line from breaking. On personal computers, this can sometimes mean that a line will extend well beyond the boundaries of its frame, so users have to scroll to see all of it. TV Navigator doesn’t allow horizontal scrolling, so it must confine everything to the width of the viewing frame. It tries to honor the <nobr> request, but will disregard it if there’s no other way to fit the entire line on-screen. It handles the tag as follows: • If only images (without any text) are bracketed by <nobr> and </nobr>, the images are kept on the same line. If the sum of their widths is wider than the available space, they’re scaled to fit. Bracketed spacers are also scaled. • If <nobr> marks text (including text with images), TV Navigator attempts to keep the sequence on one line. However, if the content is too wide, it wraps the text to a new line, despite <nobr>. The text is not scaled; the images may be. The treatment of the nowrap attribute for table cells (<td> and <th>) is similar. If nowrap is specified for a cell (or if the cell’s contents are bracketed by <nobr> and </nobr>), TV Navigator tries not to scale images or wrap text within the

DESCRIPTION:

Content Developer’s Reference

HTML for TV Display

cell, as long as that doesn’t require squeezing other cells in the table so their contents become unreadable or too small. The <pre> tag displays text just as it appears in the source file—which means that lines are normally wrapped only where the source has an explicit newline or carriage return. However, TV Navigator will wrap preformatted lines if necessary to keep them within the viewing frame. It’s as if the wrap attribute was always on. When wrapping text, TV Navigator tries to break the line on a space. Failing that, it tries for a nonbreaking space (  or  ). Failing even a nonbreaking space, it breaks the line wherever necessary.

Table Borders, Cell Separation, and Cell Margins
SYNOPSIS:

<table border="pixels" . . .> <table cellspacing="pixels" . . .> <table cellpadding="pixels" . . .> The border and cellspacing attributes of the <table> tag interact to some extent, due to TV Navigator’s policy of avoiding horizontal lines that are 1-pixel-wide wherever it’s possible to do so. The policy is aimed at reducing onscreen flicker. (Flicker on the TV screen and its causes are discussed in Chapter 4 of the Content Developer’s Guide.) The border attribute specifies grid lines around each cell, around the caption if there is one, and around the entire table. For TV Navigator, these lines are either 1 pixel wide or they don’t exist. You have no control over border width. To ask for a border, simply specify border without a value, or use any value other than 0:
<table border> <table border="1">

DESCRIPTION:

To make sure there’s no border, don’t mention the border attribute, or set it to 0:
<table> <table border="0">

The cellspacing attribute is the amount of space (in pixels) lying between the cells in a table, and between the edge of the table and the cells. The space is

Chapter 2: TV Display

HTML for TV Display

transparent, so it lets the background behind the table (not the table background) show through. If a table has a border, TV Navigator doesn’t display any space between cells; it treats the cellspacing setting as 0, no matter what it actually is. This forces the grid lines around adjacent cells (and around the caption and the whole table) to lie right next to each other, without any intervening space. The grid lines are 1 pixel wide, so the cell borders appear to be 2 pixels wide (1 pixel contributed by each cell). In effect, if you choose a bordered table, you’re choosing a 2pixel-wide border with no space between the cells. If a table doesn’t have a border, cellspacing can be set to any value, including 0. However, in its attempt to avoid 1-pixel-wide lines, TV Navigator doesn’t honor a cellspacing setting of 1. If cells could be separated by a single pixel, the separation might appear as a line 1 pixel wide. Imagine, for example, cells with a red background displayed over a green page. Thin green lines would separate the red cells (and would undoubtedly flicker). Therefore, if cellspacing is set to 1, TV Navigator increases the space to 2 pixels. The default value is also 2. The cellpadding attribute determines the width of the margin (in pixels) that separates the contents of a cell from the cell’s edge. Here, again, TV Navigator won’t honor a setting of 1. If a 1-pixel margin is specified, 2 pixels are used. This prevents the margin from appearing as a 1-pixel-wide line when, for example, the cell has a background color and the content of the cell is a rectangular image.

Table Width and Height
SYNOPSIS:

<table width="pixels | percent" . . .> <table height="pixels | percent" . . .> The width attribute of the <table> element is taken only as a suggestion. TV Navigator usually respects it as a minimum, but may find it necessary to make the table wider or narrower: • Tables that are too wide for the screen are reduced in size so they fit, regardless of the width specified. • Because the default font size is larger for TV Navigator than for other browsers, it sometimes takes more space to display a table than the width specification allows. If necessary, the table is resized, ignoring the requested table width.

DESCRIPTION:

Content Developer’s Reference

HTML for TV Display

If a table is located in a document, percentage specifications of its width and height are relative to the frame that contains the document. However, if a table is embedded within another table, the percentages are relative to the size of the cell where it’s located. If the size of that cell isn’t explicitly given in HTML, the percent size of the inner table is completely ignored. Note that the table border (the border attribute), the spacing between cells (the cellspacing attribute), and the padding within a cell (the cellpadding attribute) all take space from the specified width and height.
SEE ALSO:

“Table Cell Width,” Chapter 4, “Dynamic Tables”

Table Cell Width
SYNOPSIS:

<td width="pixels" . . .> <th width="pixels" . . .> To make tables fit within the width of the screen, TV Navigator may reduce the size of cells, ignoring the values set for the width attribute. Normally, width is taken as a minimum. Computer-oriented browsers widen a cell beyond the width specified if it’s necessary to display the contents of any cell in the same column (since all cells in a column have the same width). But they don’t reduce a cell below the requested width and height. TV Navigator tries to honor the requested width, but will reduce it if that’s the only way to keep everything in view and avoid horizontal scrolling. This can especially affect empty cells. For example, to add white space to a table, some content developers use empty cells with a specific width or height. For instance, if a table has 12 rows of cells and you want a left gutter of 20 pixels wide before each row, the first cell in the table could have this form:
<td width="20" rowspan="12"></td>

DESCRIPTION:

However, if table cells with content require more space than is available, TV Navigator tries to find the best fit, even if it means ignoring specified cell sizes. This can result in a loss of the 20 pixels of white space. To ensure that some white space exists in this worst case, add a spacer or a nonbreaking space as the only content in the cell:
<td width="20" rowspan="12"> </td>

Chapter 2: TV Display

HTML for TV Display

In this case, even if there isn’t enough room for the 20 pixels you asked for, at least the cells get the width of a space character in the default font setting.
SEE ALSO :

“Table Width and Height” on page 36

Content Developer’s Reference

Display Object
Overview
The Display object holds information about the display device—a TV screen in the case of TV Navigator—and controls some aspects of video output from the set-top box to the screen. It can report the screen size and video format, make adjustments to screen settings, turn video output to the display device on and off, and choose default display options. The output video signal carries everything that’s displayed on the screen, including both Web and television content. This object is a read-only property of the Navigator array:
var theScreen = navigator.display;

It’s paired with a Speaker object, which controls audio output from the set-top box. Audio and video input is governed by TvTuner objects.

Properties
alpha
SYNOPSIS:

alpha controlled-read/controlled-write number The opaqueness of Web content when it appears in front of the television picture. The value can range from 0 (totally transparent) to 255 (completely opaque), although some set-top boxes may support only a limited set of intermediate values. If the hardware doesn’t support variable opaqueness to television at least to some degree, alpha is undefined. The alpha setting controls the extent to which television will show through Web content. For example, if alpha is 153, Web content will contribute 60% of the coverage of each shared pixel (153/255 = 0.60) and television will contribute the remaining 40%. By varying alpha over time, you can make Web content fade in or out over the TV picture. This property applies to the whole screen; it affects Web content in every window and frame. However, it affects only content that’s directly in front of television—for example, a page that has tv: in the background or a frame belonging to a frameset with tv: in the background. If a window appears in

DESCRIPTION:

Chapter 2: TV Display

Display Object

front of another window and the window in back has tv: in an image or frame, the portion of the front window that overlaps the image or frame will be affected, but nothing else will. On the other hand, if the window in front has the tv: image, the alpha setting won’t affect anything; it applies only to content in front of television. Moreover, this property applies only to Web content that would otherwise be opaque. It doesn’t affect transparency in images and “transparent” backgrounds; they remain completely transparent. The default alpha value is 255 (totally opaque). It may automatically revert to the default whenever a new JavaScript context is created for any window or frame on-screen, or it may persist across contexts. It depends on the settingsAlwaysRetained property and whether retainSettings() has been called. See settingsAlwaysRetained for details.
ACCESS:

Reading is controlled by the principal ACL; writing is controlled by a combination of the principal and minor ACLs. settingsAlwaysRetained, retainSettings()

SEE ALSO :

format
SYNOPSIS:

format read-only TvFormat object The format of the video signal sent to the display device (the TV set). Currently, the TvFormat object has a single property—system, a read-only string that names one of the standard formats for encoding video: • “NTSC” (National Television Standards Committee), • “PAL” (Phase Alternation Line”), • “PAL 16:9”, the PAL variant that encodes the picture in a wide-screen 16:9 aspect ration (width to height), or • “SECAM” (Sequentiel Couleur Avec Mémoire). TvTuner objects have a similar property to report the format of the input video signal. Generally, the two formats are the same, but a set-top box might receive video in one format (PAL, for example) and send another format (SECAM perhaps) to the TV monitor.

DESCRIPTION:

Content Developer’s Reference

Display Object

HISTORY:

The TvFormat object had a variant property that was deprecated in release 1.2.1. preferredFormat, TvTuner.format on page 273

SEE ALSO:

preferredFormat
SYNOPSIS:

preferredFormat read/exclusive-write string The favored format for the output video signal. This property has the same set of values as Display.format.system—“NTSC”, “PAL”, “PAL 16:9”, or “SECAM”. TV Navigator uses it to choose the format for the video signal the set-top box sends to the TV set, when more than one possibility is present. In practice, it’s used only to choose between “PAL” and “PAL 16:9” when both the standard PAL format (with a 4:3 aspect ratio) and a wide-screen PAL format (with 16:9 aspect ratio) are both available. The “PAL 16:9” format should be set as a preference only for wide display devices (wide-screen TVs) that can handle the 16:9 format. It defaults to the standard “PAL” format if a wide signal is not available. The default value depends on the platform. Setting this property to a value the platform doesn’t support has no effect. The value assigned to this property persists until it is explicitly altered; it doesn’t fall within the scope of settingsAlwaysRetained.

DESCRIPTION:

ACCESS:

Reading is unrestricted; writing is reserved for pages from the Service Manager’s domain. format, wideScreenStyle

SEE ALSO:

programDefaults
SYNOPSIS:

programDefaults read-only object A collection of settings that affect how program content will be displayed by default when there’s more than one choice available—for example, which audio stream to pick, whether captions should be displayed, and which language is preferred.

DESCRIPTION:

Chapter 2: TV Display

Display Object

At present, the programDefaults object has just one property, language. It records the language that should be chosen for audio and subtitles, if a choice is available. Its value is a 3-character language code as specified by the ISO 639– 2/T standard—for example, “deu” for German or “swe” for Swedish. Other defaults will be added in future releases. Although the programDefaults object is read-only, its properties are read/write. The values that are recorded in this object determine how the television subsystem will choose program components by default. Those choices can be overridden on a program-by-program basis by setting the TvChannel.selectedComponents property.
AVAILABILITY: HISTORY: SEE ALSO :

The language setting is currently ignored. Introduced in the 1.2.2 release. TvChannel.availableComponents on page 224, User.sysLanguagePreferences on page 362

screenArea, safeArea
SYNOPSIS:

screenArea read-only ScreenArea object safeArea read-only SafeArea object

DESCRIPTION:

These objects define the dimensions of the full screen (the frame buffer) and the safe area of the screen, the part that’s certain to be visible on the user’s monitor. Dimensions are measured in pixels and the safe area is located relative to the left top corner of the full screen. “ScreenArea and SafeArea Objects” on page 49

SEE ALSO :

settingsAlwaysRetained
SYNOPSIS:

settingsAlwaysRetained read-only boolean Reports whether or not certain display settings persist when a new JavaScript context is created—that is, when a new page is loaded into a window or frame anywhere on-screen. The settings persist if settingsAlwaysRetained is true, but

DESCRIPTION:

Content Developer’s Reference

Display Object

revert to their default values if it’s false. Currently, the only setting that comes within the scope of this property is Display.alpha. Suppose, for example, that a window is divided into two frames, one on the left and one on the right. If the document in the left frame sets alpha to 98, that value applies to the entire screen, including the frame on the right. settingsAlwaysRetained determines what happens when either frame (or the parent window) loads a new document. If it’s false, alpha automatically reverts to its default value (255). If it’s true, the current value (98) persists until alpha is explicitly reset. If settings would ordinarily revert to default values (settingsAlwaysRetained is false), you can nevertheless force them to persist by calling retainSettings(). In other words, if settings are always retained, they are under your complete control as a content developer. You must make sure that all display settings are appropriate for any content that may happen to be displayed on-screen. If settings are not always retained, they fall back to a safe value (the default) whenever new content appears on-screen. By calling retainSettings(), you can override this automatic behavior so that it doesn’t interfere with the display when it’s not appropriate. The value of settingsAlwaysRetained is fixed for the set-top box and will not change in the course of a session.
VARIATIONS:

Currently, settings are always retained (this property is true) in all deployments. retainSettings()

SEE ALSO:

tvVisible
SYNOPSIS:

tvVisible read-only boolean Whether or not a visible window contains a document that asks for the TV image (with the tv: URL)—true if there is such a window and false if not. This property could be true even if the TV picture is not actually shown onscreen. For example, it might be completely covered by other windows, it might be located in an area of the document that’s currently scrolled out of view, or the current program or channel might be blocked.

DESCRIPTION:

Chapter 2: TV Display

Display Object

HISTORY: SEE ALSO :

Introduced in the 1.2.6 release. Window.visible on page 104

videoOn
SYNOPSIS:

videoOn read/controlled-write boolean Turns the video signal to the monitor on and off and reports whether it’s currently on (true) or off (false). When videoOn is false (off), the monitor is blank. It not only doesn’t display television, it doesn’t display anything at all— including any Web content. The videoOn setting persists in all cases; it’s not subject to the settingAlwaysRetained value. Therefore, if you turn video off for any reason, you should be sure to turn it back on again.

DESCRIPTION:

ACCESS: SEE ALSO :

Reading is unrestricted; writing is regulated by the principal and minor ACLs. Speaker.mute on page 53

wideScreenStyle
SYNOPSIS:

wideScreenStyle read/exclusive-write string Determines how video is displayed on-screen when the aspect ratio of the incoming television signal is wider than the aspect ratio of the display device (as indicated by the preferredFormat property). There are three possible ways to make a wide picture fit the screen: • Letterbox. The television picture can be scaled smaller. Since it’s scaled proportionally, it retains its shape and appears like a “letterbox” on-screen. Although the picture covers the full width of the screen, it doesn’t cover the full height. Unused margins appear above and below the letterbox. • Center cutout. The left and right edges of the picture can be cropped, so that only the center part is shown on-screen. In this case, the picture is not scaled and it fills the whole screen, but the entire picture is not shown.

DESCRIPTION:

Content Developer’s Reference

Display Object

• Pan and scan. Instead of always showing the center section of the picture, it may be possible to vary the part that’s shown so that viewers always see what’s most interesting or important. For example, if two people are filmed facing each other in conversation, the center-cutout option might crop the back of both their heads and show only their faces (or perhaps only their noses) at the left and right edges of the screen. The pan-and-scan option could jump back and forth to show whoever happened to be talking at the time. Clearly, this last option is possible only if the incoming signal includes data indicating which part of the picture to show (where to pan and scan). If this data is available, it’s always used. Pan and scan trumps both the letterbox and center-cutout options. However, if pan-and-scan vectors are not available, a choice must be made between the other two possibilities. If wideScreenStyle is “letterbox”, the letterbox option is chosen. If it’s “centerCutout”, the center-cutout option is chosen. Setting this property to a value other than “letterbox” or “centerCutout” has no effect. The default value depends on the platform. Note that the wideScreenStyle setting comes into play only if the video signal has a wider aspect ratio than the preferred output format and only if pan-andscan data is not available. This property does not fall within the scope of settingsAlwaysRetained; it persists in all cases.
ACCESS:

Reading is unrestricted; writing is reserved for pages from the Service Manager’s domain. preferredFormat

SEE ALSO:

Methods
retainSettings()
SYNOPSIS: DESCRIPTION:

controlled boolean retainSettings(string settings) Ensures that the properties listed in the settings string will not revert to their default values when a new JavaScript context is created (when any window or frame loads a new document). The string is a list of comma-separated property

Chapter 2: TV Display

Display Object

names. (Currently, the only property that may revert to its default setting is alpha.) This method has no effect on platforms where the settingsAlwaysRetained property is true; settings persist whether or not this function is called. If you want a property to revert to its default value, you must set it yourself. However, on platforms where settingsAlwaysRetained is false, settings automatically revert to their defaults when a context changes—unless this method tells them to persist. If it succeeds in marking every property in the settings list for retention, retainSettings() returns true. If not, it returns false. Once it’s called (and it returns true), it remains in effect until the JavaScript context that called it is destroyed. Settings will persist even while other frames and windows load new documents. Typically, you would call this method only when you know the page that’s about to be loaded and know that it belongs to the same set of documents, designed to share the same display settings. It’s safest to call it just before fetching the document—for example, in an onclick() handler immediately before invoking a new URL:
<a target="anotherFrame" href="anotherPageFromTheSameSet.html" onclick="if ( navigator.display.retainSettings(’alpha’) == true ) . . ."><img src="clickableImage.gif"></a>

Note that the onclick() handler in this example is called before the link is followed. If you’re not absolutely sure what the next page will be, it’s almost always best to let settings revert to their defaults.
ACCESS: AVAILABILITY:

Controlled by the writing sublist of the principal ACL. Not implemented. Currently, settings are always retained in all deployments, so you would never need to call this function. settingsAlwaysRetained

SEE ALSO :

Content Developer’s Reference

Link Object Additions
Overview
Link objects are a part of standard JavaScript. One is created for each HTML <a> and <area> element that has an href attribute—that is, for each source (or “tail”) of a hypertext link. Links are located in the Document object’s links array:
var firstLink = document.links[0];

TV Navigator adds just two properties and a pair of methods to the Link object. The methods make it possible to assign input focus to links dynamically. Without them, applications would not be able to move the focus from link to link.

Properties
highlightable
SYNOPSIS:

highlightable read/write boolean Whether or not the link can be highlighted with the focus rectangle—true if it can, and false if not. If false, the page must use some other means to indicate that the link is in focus. For example, the link could be represented by a distinctive graphic and the only element on the page that could be the focus of user input. In such a case, the meaning would be clear to the user and the focus rectangle a distraction. Introduced in the 1.2 release. “Highlighting Links” on page 29, TableCell.highlightable on page 139

DESCRIPTION:

HISTORY: SEE ALSO:

name
SYNOPSIS:

name read-only string The string assigned in HTML to the name attribute of the <a> or <area> element. If a name wasn’t assigned, this property is undefined.

DESCRIPTION:

Chapter 2: TV Display

Link Object Additions

Unlike the names of other HTML elements (like images and tables), link names cannot be used to find the associated JavaScript object. Neither of the following expressions will work:
var theLink = document.links["nameOfLink"]; var theLink = document.nameOfLink; // fails // also fails

A link source is typically given a name so that it can be assigned to the initialfocus attribute of the <meta> tag.
SEE ALSO :

“Setting the Initial Focus” on page 27

Methods
focus(), blur()
SYNOPSIS:

void focus(void) void blur(void)

DESCRIPTION:

The focus() method assigns input focus to the link, and blur() removes it. In an environment without a cursor, hypertext links must be able to take input focus. For these functions to work, the page where the link is located has to be fully rendered and ready to display the focus (draw the focus rectangle). To assign focus at the time the page is fetched and before it’s rendered, assign the link a name and use the initialfocus attribute of the <meta> tag instead.

HISTORY: SEE ALSO :

The blur() method was added in the 1.2 release of TV Navigator–S. “Setting the Initial Focus” on page 27

Content Developer’s Reference

ScreenArea and SafeArea Objects
Overview
These two objects record the size of the TV screen and locate the safe area—the part of the screen that’s guaranteed to be visible to the user. Both areas are rectangles measured in pixels. The ScreenArea object records the full width and height of the TV picture as it’s carried in the video signal; the SafeArea is a smaller rectangle centered in the full screen. These two objects are read-only properties of the Display object:
var fullScreen = navigator.display.screenArea; var visibleArea = navigator.display.safeArea;

They’re both global objects without constructors or HTML counterparts.

Judging the Safe Area
The safe area is the area in which it’s safe to place Web content. It’s smaller than the full screen because TV sets, unlike VGA monitors for personal computers, may “overscan”—that is, they may project the picture on an area that’s slightly larger than the screen, so that part of the picture literally falls off the edge of the screen. In addition, some (not all) TV sets are constructed so that the enclosing case obscures some of the screen where images are projected. The safe area must subtract the margins of the picture and screen that are likely to be hidden from the viewer. This safe area might be termed the safe web area. Broadcasters often recognize two other slightly different safe areas for movies and programs produced for television. The larger of the two, the safe action area, is the area of the screen where important dramatic action can take place. Its width and height are about 90% of the width and height of the full screen. The smaller of the two areas, the safe title area, is the area where text can be safely displayed without getting it too close to the edge of the screen. It’s about 80% of the width and height of the full screen. Experience has shown that the safe area for Web content is closer to the safe action area than the safe title area. Its width and height range from 85% to 90% of the width and height of the full screen. It can vary a bit from system to system, and differs in absolute terms depending on the video format. It’s best to check with the SafeArea object.

Chapter 2: TV Display

ScreenArea and SafeArea Objects

Using the Safe Area
TV Navigator does not automatically confine content to the safe area. It gives applications the ability to put windows anywhere at all on-screen. The safe area should be considered when creating a new window; it’s a hint of where it’s safe to locate the window. Confining windows to the safe area doesn’t preclude letting background colors and images fill the entire screen. Using the overscan attribute of the <body> and <frameset> tags, you can cause the background to bleed from the edge of a window to the edge of the screen.

Screen Size and Aspect Ratio
The screen size doesn’t necessarily reflect the aspect ratio of the screen. To find the aspect ratio, you need to check the TvTuner and Display format properties. For the standard NTSC, PAL, and SECAM formats, the aspect ratio is 4:3, width to height. For the wide-screen PAL variation, it’s 16:9. A wider screen doesn’t necessarily imply a greater number of horizontal pixels.

ScreenArea Properties
width, height
SYNOPSIS:

width read-only number height read-only number

DESCRIPTION:

The full width and height of the screen (the frame buffer) in pixels, including areas outside the safe area. The screen for the NTSC video format is 640 × 480. For the PAL format, it’s usually either 720 × 576 or 768 × 576, depending on the hardware and video drivers. Display.format on page 40

SEE ALSO :

Content Developer’s Reference

ScreenArea and SafeArea Objects

SafeArea Properties
left, top, width, height
SYNOPSIS:

left read-only number top read-only number width read-only number height read-only number

DESCRIPTION:

These four properties jointly describe the location and size of the largest area of the screen that it’s safe to assume is visible on the user’s monitor; some areas at the margin of the safe area may also be visible. The following illustration shows a full screen 640 pixels wide and 480 pixels high. Trimming a little over 6% from each edge leaves a 560 × 420 safe area:

420

560

640

The width and height properties give the dimensions of the safe area. The dimensions depend on the video format and screen size, and possibly on the

480

Chapter 2: TV Display

ScreenArea and SafeArea Objects

platform and version of TV Navigator. Nevertheless, TV Navigator tries for the safe areas described in the following chart:

Format
NTSC PAL

Screen Size
640 × 480 768 × 576 720 × 576

Safe Area
560 × 420 688 × 516 640 × 516

However, these dimensions may vary for certain platforms and products. The left and top properties position the safe area on the screen. They locate the left-top pixel of the safe area assuming a coordinate system where (0, 0) is the left-top pixel of the full screen. The enlargement below shows the upper left corner of the same screen illustrated above.
(0, 0)

(40, 30)

Coordinate units count pixels.
SEE ALSO :

“Backgrounds beyond Window Borders” on page 23, Window.open() on page 105

Content Developer’s Reference

Speaker Object
Overview
The global Speaker object holds the master controls for audio output. The controls can be accessed only from trusted sites, although access to the Speaker object itself is not restricted. It’s a read-only property of the navigator array:
var theSpeaker = navigator["speaker"];

There is no constructor.

Properties
mute
SYNOPSIS:

mute controlled-read/controlled-write boolean Mutes audio output to the TV set (turns it off) if set to true, and unmutes it (turns it on) if set to false. By default, audio is on (false). Every TvTuner object has a similar control to mute audio from the input source it represents. Setting this property to true or false doesn’t change the volume setting.

DESCRIPTION:

ACCESS:

Reading is controlled by the principal ACL; writing is controlled by both the principal and minor ACLs. TvTuner.mute on page 275

SEE ALSO:

volume
SYNOPSIS:

volume controlled-read/controlled-write number Sets and reports the current volume, hardware permitting. Volume values range from 0 (none) to 127 (loud). If this property is assigned a value greater than 127, the volume will be set to 127. If it’s assigned a value less than 0, the results are indeterminate.

DESCRIPTION:

Chapter 2: TV Display

Speaker Object

Setting the volume (even to 0) doesn’t affect the mute setting.
ACCESS:

Reading is controlled by the principal ACL; writing is controlled by both the principal and minor ACLs.

Content Developer’s Reference

Extending the Standard API

CHAPTERM

In addition to defining a number of new objects for client-side JavaScript and a handful of new HTML tags, TV Navigator also extends and adapts some standard HTML constructs and familiar JavaScript objects. It does so for a variety of reasons—to add functionality, to provide a better programming interface, to accommodate the kinds of applications being developed for the settop box, and so on. This chapter looks at these extensions to standard HTML and JavaScript, in particular the following: • Properties added to the Navigator object. These properties provide access to most of the objects that deal with television, the Internet, indicators, users, services, the cache, and other staples of the set-top environment. • Additions to and restrictions on Window.open() and other modifications to the Window object. • An object interface for getting and setting cookies (instead of the Document.cookie string). Cookie objects are located in the Document.cookies (note the plural) array. • An addition to the String object for encrypting password strings. • Dynamic control of text areas through additions to the Textarea object. Among other things, the additions can scroll the display and easily append new text. • A more flexible way of handling entries in the history list (through the History and HistoryEntry objects), and a way of making entries in the list transient (though the <meta> tag). • More control over the appearance of selection lists through attributes added to the <select> tag.

Chapter 3: Extending the Standard API

Extending the Standard API

This list omits one important innovation—HTML tables with focusable cells that can be dynamically modified. Dynamic tables are important enough to deserve their own chapter; it follows this one. Extensions and reinterpretations of HTML tags that facilitate the display of Web content on the TV screen were discussed in the previous chapter.

Content Developer’s Reference

HTML Extensions
Transient History
SYNOPSIS: DESCRIPTION:

If history is set to “transient” (as shown), the page is only temporarily added to the history list; it’s in the list while it’s the current page, but is removed from the list when the user leaves the page. This prevents auxiliary and peripheral pages—for example, a help page—from contaminating the user’s history list. The user will skip those pages when navigating backward or forward in the list.
SEE ALSO:

“History and HistoryEntry Objects” on page 79

HTTP Header Equivalents
SYNOPSIS: DESCRIPTION:

Chapter 3: Extending the Standard API

HTML Extensions

• Servers typically don’t parse HTML, so they’re generally not affected by the <meta> tag. HTML content is intended for the client only. However, transcoded content for TV Navigator is a partial exception to this general rule. The way that these attributes may affect server behavior is discussed later, in the “Caching on the server” section. • The <meta> tag can be inserted only in HTML files, so it cannot govern how the client treats other kinds of content, such as images and JavaScript files. To include these other types of data, the source server must set an actual header.

Client behavior. All but one of the http-equiv directives that TV Navigator responds to affect whether the client will cache the requested document and, if so, for how long. These fields are especially useful while developing content— particularly if you’re repeatedly editing a page, downloading the revised version, then editing and downloading it again. Because they can prevent TV Navigator from keeping a copy of the page, they force it to fetch a new version—the one with your latest changes—each time you reload or revisit the URL.
The following table summarizes the cache-related http-equiv and content combinations that TV Navigator supports:

http-equiv

content

Description
Prevents the document from being cached. Similar to “no-cache”. Sets the number of seconds the document should remain in the cache before expiring. Indicates that the document is shared and therefore can be cached, even if it would normally not be cacheable. For example, documents that are delivered with cookies are not cached unless (a) they’re marked “public” and (b) another header indicates how long they should stay in the cache.

“cache-control” “no-cache” “no-store” “max-age=seconds”

“public”

Content Developer’s Reference

HTML Extensions

http-equiv

content

Description
Indicates that the document is intended for just one user and should be removed from the cache when the user changes. Prevents the document from being cached. This header is an older (HTTP 1.0) form of “cache-control: no-cache” Sets the date when the cache for the document should expire. Indicates when the document was last modified. TV Navigator considers the age of the document when determining how long to keep it in the cache.

“cache-control” “private” (continued)

“pragma”

“no-cache”

“expires” “last-modified”

“date” “date”

Documents without any of these settings, either in the <meta> tag or as HTTP headers, are not cached. Typically, the originating server supplies at least one caching directive as an HTTP header. If there are multiple directives and they are in conflict with each other, TV Navigator honors them in the following order: “cache-control: no-cache” (and its “pragma: no-cache” equivalent) “cache-control: max-age=seconds” “expires: date” “last-modified: date” If there’s a <meta> setting and a true header for the same directive—“expires”, for example—the <meta> setting will override the header when the document reaches the client. You can also control the cache on the client from JavaScript. The Cache.remove() method deletes specific items from the cache.

Chapter 3: Extending the Standard API

HTML Extensions

Another http-equiv value that TV Navigator honors—one not related to caching—is “refresh”:

http-equiv
“refresh”

content
“seconds”

Description
Sets the number of seconds separating automatic downloads of the page. For example, if seconds is “7”, TV Navigator will download the page every seven seconds, presumedly getting a slightly different version each time (provided the old version is not cached). Names the URL that should be used to refresh the document.

“seconds;url=URL”

Caching on the server. HTTP requests from the set-top box pass through a proxy server and the Liberate Transcode™ server before going out to the Internet. The response to a request retraces this route, so the Transcode server sees the response before the proxy does. As part of its transcoding operations, the Transcode server translates caching-related http-equiv and content settings to true HTTP headers and adds them to the response. The purpose is to simplify the work of the client, so that it can just look at the HTTP headers to determine how to cache the document and not bother with the HTML.
However, there’s a side effect: Because the proxy server stands between the Transcode server and the client, it will be affected by any http-equiv fields that the Transcode server turns into true HTTP headers. This makes it possible to turn caching off on both the client and the proxy with the same http-equiv directive. If you want to use this trick, here are some considerations to keep in mind: • Current releases of TV Navigator rely on the Transcode server to lay out HTML pages. However, in the future, on some set-top boxes, TV Navigator will be able to do the work itself, on the set-top box. At that time, the trick will no longer work. Only the client will be affected by http-equiv directives. • All proxy servers do not respond to the caching headers in the same way. If you want to prevent caching on both the proxy and the client, it’s generally

Content Developer’s Reference

HTML Extensions

safest to use an “expires” header, rather than “cache-control”, because it’s compatible with a wider range of servers. For example:
<meta http-equiv="expires" content="0">

The 0 in this construction indicates that the document has already expired (as would any date in the past), which should prevent it from being cached. • The document may be cached by intermediate servers before it reaches the Transcode server. For example, http-equiv settings are unlikely to affect a Liberate parental proxy server. The best way to prevent these servers from caching the document is to have the source server set the “expires: 0” header.
SEE ALSO:

Cache.remove() on page 147

Images and Colors in Selection Lists
SYNOPSIS:

<select <select <select <select <select <select

text="color" . . .> bgcolor="color" . . .> background="url" . . .> popupbg="url" . . .> seltext="color" . . .> selbgcolor="color" . . .>

DESCRIPTION:

These new attributes for the <select> tag determine the appearance of a list of options. By default, an options list is a pop-up list. Only one item—generally the item that was last selected—is displayed within the <select> element itself. When the user focuses on that element and selects it, a list with all the options pops up on-screen. The user can then make another selection from the list; the popup list disappears and the <select> element displays the newly selected item. However, if the <select> element allows users to select more than one option (the multiple attribute is set) or if it displays more than one option (the size attribute is set to a value greater than 1), there is no pop-up. The <select> element displays all the options, scrolling them if necessary.

Chapter 3: Extending the Standard API

HTML Extensions

The attributes listed above affect both the <select> element itself and its pop-up list, if there is one. The text, bgcolor, and background attributes work just like their counterparts for the <body> tag: • The text attribute specifies the color used to draw option text. It applies to all text in the <select> display and the pop-up list. If not set, the color defaults to black. • The bgcolor attribute specifies a color to display in the background of the <select> element and the pop-up list it controls. Currently, the color cannot be “transparent”. If a background color isn’t set, it defaults to light grey. • The background attribute can be set to a URL for an image to display in the background of the <select> element. It applies only to that element, not the pop-up list. To put a background image in a pop-up list, use the popupbg attribute instead of background. In both cases, the image is tiled to fill the entire area displayed and cropped to fit. The height of the <select> element is determined by the size attribute, which defaults to 1. The height of the pop-up list is determined by the number of options. A maximum of six are displayed; if there are over six items, the list scrolls. The width of both the element and its pop-up list is determined by the width of the widest option (the widest text string). If a background color (bgcolor) and a background image (background or popupbg) are both set, the color is drawn first and the image is placed on top, so that transparency in the image lets the background color show through. For example, this HTML code,
<select bgcolor="olive" popupbg="images/optionsBg.gif">

would show the background color in the <select> display and an image, possibly against that color, in the pop-up list. The seltext and selbgcolor attributes are similar to text and bgcolor, except that they specify the colors used to highlight an option when it’s selected: • The seltext attribute sets the color used to display the text of a selected option. The default color is white. • The selbgcolor attribute specifies a background color for the selected option. It defaults to a dark grey.
SEE ALSO :

“TableCell Objects” on page 133

Content Developer’s Reference

HTML Extensions

Prefetching
SYNOPSIS: DESCRIPTION:

If the value of rel is “next”, as shown above, the URL specified by href is taken to be the next document in a sequence. This hint enables the browser to fetch and store the document before the user explicitly asks to see it, thus improving the response time when the user does make the request. When it prefetches the href document, TV Navigator follows as many links in the document as memory allows. Any user request to fetch another document aborts the prefetch.

Chapter 3: Extending the Standard API

HTML Extensions

Content Developer’s Reference

Cookie Objects
Overview
Cookie objects present a simpler interface to HTTP cookies than the document.cookie string of standard JavaScript. Each object represents one cookie and has a set of properties—name, value, path, and so on—for the various components that define the cookie. It also has methods to load, store, and remove the cookie as a whole.

Access to Cookies
Web sites and applications create cookies to contain user-specific data on the client machine. The client keeps the cookie on behalf of its creator and exposes it in two ways: • It delivers the cookie as header information in HTTP requests. • It lets JavaScript code look at the cookie (through Cookie objects and the document.cookie string). In both cases, the client is careful about who it allows to see the cookie. First, the cookie is visible only while the user it was created for is the current user. Second, a cookie has an associated domain and path that limit its scope. Third, it may also set a security flag that further limits access. These constraints apply both when transmitting the cookie to a server and making it visible in JavaScript: • The client passes a cookie in an HTTP request only if the current user is the user associated with the cookie and the URL of the request falls within the scope set by the domain and path of the cookie. If the security flag is set, the request must be a secure one (HTTPS instead of HTTP proper). • Similarly, a page can look at a cookie using JavaScript only if its URL places it within the scope of the cookie’s domain and path and the cookie belongs to the current user. If the security flag is set, only pages retrieved using a secure protocol are allowed to see the cookie. More information on these restrictions can be found under the domain, path, and secure properties, discussed later.

Chapter 3: Extending the Standard API

Cookie Objects

Transmitted and Untransmitted Cookies
It’s clear, from the preceding section, that if a cookie is transmitted in an HTTP request, the page that’s retrieved in response to the request can look at the cookie using JavaScript (provided, of course, that the URL of the retrieved page is the same as the URL of the request). The cookie is sent to the server where the requested page resides; when the page arrives at the client, it can examine the cookie. Often, a server never looks at the cookie; it simply delivers the requested page. In this circumstance, you may want to avoid the overhead of transmitting cookie data in the HTTP request and instead have a cookie that’s visible only using JavaScript. Such a cookie would always stay with the client. The Cookie object gives you this option. By setting the transmitted property to false (or by setting a flag when constructing the object), you can specify that you don’t want the cookie transmitted in HTTP requests. Unless this property is true (as it is by default), servers that get HTTP requests won’t be able to see the cookie. (As explained under “Storing Cookie Data,” later in this overview, the cookie must be stored for this option to take effect.)

Setting Up a Cookie Object
You can obtain a Cookie object in two ways:

A. The Document.cookies array (note that cookies is plural here) has one Cookie object for
each cookie that’s within the scope of the document and available to the current user. It’s an array of named objects, so you can access cookies by index or by name:
var firstCookie = document.cookies[0]; var particularCookie = document.cookies["chocolateChip"]; var sameCookie = document.cookies.chocolateChip;

The cookies (plural) array holds the same cookies as the Document.cookie (singular) string, but in an object format.

B. You can also construct an empty Cookie object,
var myCookie = new Cookie();

and initialize its properties,
myCookie.name = "chocolateChip"; myCookie.value = ". . ."; myCookie.path = ". . ."; . . .

Content Developer’s Reference

Cookie Objects

or load the data from an existing cookie:
myCookie.load("chocolateChip");

Each time you ask for a particular cookie, no matter how you ask for it, you get a different Cookie object with its own copy of the data. For example, if you happened to write some code like the following,
var firstObj = document.cookies.favorite; var secondObj = document.cookies.favorite;

and then modified one of the objects, the other object would not be affected.

Storing Cookie Data
Although Cookie objects provide a convenient syntax for dealing with cookie data, they retain the semantics of HTTP cookies; the underlying data representations remain the same. The object is just a copy of the real cookie. Creating a Cookie object and initializing it doesn’t create a cookie in the underlying data and modifying a Cookie object doesn’t modify the cookie it represents. To copy object values into the cookie data, you must call the store() method:
if ( myCookie.store() ) // the cookie was created (or updated) else // oops

This method is a counterpart to load(). The load() method copies cookie data into the object, while the store() method copies object data into the cookie.

The Cookie Database and Cache
Cookie data is typically stored in a persistent database. It therefore is not lost when the cookie is no longer visible because the current document is unloaded, the current user changes, or the set-top box is turned off. When the box is turned back on, the user returns as the current user, and the document is reloaded, the cookie will again be visible in the Document.cookies array (provided it has not expired in the meantime). Computer-oriented browsers keep cookies on the client machine. However, because TV Navigator is a thin client, it pushes some client-oriented tasks to a server. Therefore, the database may physically reside on a server—in this case, the Datapoint server, where other user-specific data is kept. Or, if the set-top box has enough memory, it may reside on the client—or on both client and server. It’s transparent to the applications and pages that use cookies.

Chapter 3: Extending the Standard API

Cookie Objects

Cookies kept on the set-top box are backed up on the server—provided a communication channel makes that possible, as is typically the case for cable systems. TV Navigator also caches the cookies for the current user on the client so they’re readily available. When the user changes, the cache is replenished with the cookies for the new user. Unlike the database, the cache contains only cookies relevant to the current user (and for other recent users). When the store() method is called, it puts the cookie data in the cache and, from the cache, into the persistent database. However, if the cookie does not have an expiration date in the future, the cookie is transient; it’s placed only in the cache, not in the database. A transient cookie lasts only for the duration of the current session—until the current user changes or the set-top box is turned off. For example, if you load cookie data into a Cookie object, modify the value property, set the expiration property to an empty string, and then call store(), the new value and expiration will be cached and will be operative for the duration of the session, but they won’t affect the cookie in the persistent database. At the end of the session, the cached data will be deleted. When the cookie again becomes visible at a later time, its original value and expiration will resurface. Note that a session does not end when the current document is unloaded. When the user returns to the document, the transient cookie will again be visible—provided that the user has not changed and the set-top box has not been turned off in the meantime.

Memory Limitations
Each cookie is limited to 4 KB. If it would take more memory to store data for a cookie, the store() method arbitrarily truncates it at 4 KB. This is a standard limitation, not one that’s specific to TV Navigator. There are no limitations on the total number of cookies, the number per user, or the number per page. However, memory constraints on the set-top box impose a practical limit on the amount of cookie data that can be cached. Transient cookies generally don’t run up against a memory limit. They’re cached separately from persistent cookies and, because they’re created only for the current session, they’re typically few in number. The limit more likely affects persistent cookies. When persistent cookies have to be removed from the cache to make room for new ones, TV Navigator first gets rid of cookies that belong to users other than the current user. The data remains in persistent storage and will be retrieved if any of those users returns as the current user.

Content Developer’s Reference

Cookie Objects

If the cache still doesn’t have enough room for all the current user’s cookies after the cookies for other users have been removed, TV Navigator gets rid of some of the current user’s cookies by applying a least-recently-used algorithm. It deletes cookies starting with the ones that were last accessed (last read or written) in the most distant past, until enough memory is available for more recent cookies. The cookies are deleted both from the cache and from the persistent database.

Constructor
Cookie()
SYNOPSIS:

void Cookie(void) void Cookie(boolean transmitted) Initializes a new Cookie object by setting just two of its properties. If the page that creates the object was retrieved using a secure protocol, the secure property of the object is set to true; if not, it’s set to false. If a transmitted value is passed as an argument, the transmitted property is set accordingly. If a value isn’t passed, transmitted is set to true. When load() is called, these initial values are reset to whatever values are stored with the cookie. Apart from secure and transmitted, all properties of the new object are left undefined. If any property remains undefined when store() is called, a default value is generally written to the underlying cookie data for that property. The default value will be present only in the underlying data, not in the Cookie object (unless you reload the data back into the object).

DESCRIPTION:

SEE ALSO:

store(), load(), transmitted, secure

Chapter 3: Extending the Standard API

Cookie Objects

Properties
domain, path
SYNOPSIS:

domain read/write string path read/write string

DESCRIPTION:

These properties designate the documents that have access to the cookie—the range of documents to which it applies. domain specifies the servers and path specifies the directories on those servers where the documents can reside. For security reasons, both are limited to substrings of the domain and path of the current document (the one that creates or modifies the cookie). For example, if the document at the following URL sets a cookie, http://database.trees.lorax.com/southAmerica/conifers/pines/index.html the domain of the cookie can be any of the following: “.lorax.com” (or “lorax.com”) “.trees.lorax.com” (or “trees.lorax.com”) “database.trees.lorax.com” If the domain is “database.trees.lorax.com”, the cookie applies only to documents on the same server as the current document. If it’s “.trees.lorax.com” or “.lorax.com”, it can also apply to documents on other servers that share that domain—products.trees.lorax.com or admin.lorax.com, for example. However, the domain cannot be set to those servers, or to anything else that doesn’t include the document’s own server. It also can’t be set to “.com”. (When writing to the domain property, you can omit the period (“dot”) in front of a name like “.lorax.com”; “lorax.com” works just as well. However, the period will be present when reading the property.) The path of the cookie in this example can be: “/” “/southAmerica” “/southAmerica/conifers” “/southAmerica/conifers/pines”

Content Developer’s Reference

Cookie Objects

If the path is “/southAmerica”, the cookie is shared by all documents on the designated servers that live anywhere under a /southAmerica directory— /southAmerica/economics/index.html, for example. If domain is not set when store() is called, the cookie will be restricted to just the server named in the URL of the document (“database.trees.lorax.com” in the example). If path is not set, the cookie will be restricted to the directory of the document (“/southAmerica/conifers/pines” in the example). Neither property can be longer than 128 characters.
SEE ALSO:

secure, “Access to Cookies” in the “Overview” section

expiration
SYNOPSIS:

expiration read/write Date object A JavaScript Date object that records the time when the cookie should expire. For example, to have the cookie destroyed in a week, you could set its expiration as follows:
myCookie.expiration = new Date((new Date).getTime() + 7 * 24 * 60 * 60 * 1000);

DESCRIPTION:

If an expiration isn’t set when store() is called or the expiration date is in the past, a default time won’t be assigned to the cookie and the cookie won’t be stored in persistent data. It will be valid for the user’s current session with the browser, but will expire when the session ends. If there happens to be a cookie with the same name in persistent data, it won’t be affected.
SEE ALSO:

store()

name
SYNOPSIS:

name read/write string The name of the cookie. This is a required property; cookies without names cannot be stored. The name cannot be longer than 128 characters. value

DESCRIPTION:

SEE ALSO:

Chapter 3: Extending the Standard API

Cookie Objects

path secure

see domain

SYNOPSIS:

secure read/write boolean Whether the cookie should be visible only to pages that are retrieved using a secure protocol (HTTPS instead of HTTP)—true if it should and false if not. This property also determines whether the cookie should be transmitted to the server only when a secure protocol is used, or whether it can be transmitted in either secure or insecure requests. path, the Cookie() constructor, “Access to Cookies” in the “Overview” section

DESCRIPTION:

SEE ALSO :

transmitted
SYNOPSIS:

transmitted read/write boolean Whether or not the cookie can be transmitted as header information in an HTTP (or HTTPS) request—true if it can, and false if not. The default value is true; cookies are ordinarily transmitted. A cookie that cannot be transmitted is visible only using client-side JavaScript; since it’s not sent to the server, the server can’t see it.

DESCRIPTION:

SEE ALSO :

the Cookie() constructor, “Transmitted and Untransmitted Cookies” in the “Overview” section

value
SYNOPSIS:

value read/write string The data that’s stored in the cookie. If left undefined when store() is called, the stored value will be an empty string. Cookie data cannot contain white space characters, commas, or semicolons. Typically, the data is encoded to save space and eliminate these characters (for

DESCRIPTION:

Content Developer’s Reference

Cookie Objects

example, with the global escape() function); it therefore must be decoded before being used.
SEE ALSO:

name

Methods
load()
SYNOPSIS: DESCRIPTION:

boolean load(string name) Loads the name cookie into the Cookie object, so that the object matches all attributes of the named cookie. If the cookie data is larger than 4 KB, only the first 4 KB will be loaded. A Cookie object can be reused; each time you call load() with a different name, it takes on the guise of a different cookie. When a cookie is loaded, all properties of the object are set. For example, if you create a Cookie object and store it without first setting its path property, and then load the stored cookie into another object, the path field of that object will be set with the default value, the path of the page that called store(). This function fails and returns false if there’s no cookie within the purview of the document with the specified name or if it can’t load the data for some other reason. If successful, it returns true.

SEE ALSO:

store()

remove()
SYNOPSIS: DESCRIPTION:

boolean remove(void) Causes the cookie to be removed from the cookie database and from the local cache. The cookie to be removed is identified only by its name. For example, the following code gets rid of the cookie named “butterscotch” without first loading it or examining it:
var tempCookie = new Cookie(); tempCookie.name = "butterscotch"; tempCookie.remove(); tempCookie = null;

Chapter 3: Extending the Standard API

Cookie Objects

This method returns true if it succeeds in marking the underlying cookie for removal, and false if not. Once marked for removal, the cookie cannot again be loaded or accessed. It will be deleted as soon as it’s convenient to do so. If it succeeds, remove() resets all properties of the Cookie object to null. To reuse the object, you must reinitialize its properties or call load() to copy data from an existing cookie.

store()
SYNOPSIS:

boolean store(void) boolean store(boolean local) Copies data from the Cookie object into the local cache and, if a future expiration date is set for the cookie, through the cache into the persistent database. Default values are stored for any properties of the object that were left undefined. If there’s already a cookie with the name assigned to the Cookie object, that cookie will be overwritten with values from the object (including default values). If the name doesn’t match an existing cookie, a new cookie with that name is created. Stored cookies generally persist from session to session (provided they don’t expire in the meantime). However, if an expiration date (the expiration property) isn’t set for the cookie or it’s set in the past, the cookie won’t persist. It will be cached for the current session, but it won’t modify persistent cookie data. A session ends when the current user changes or TV Navigator exits (the set-top box is turned off). If the local flag is true, an attempt will be made to put the cookie in persistent storage on the set-top box. Local storage makes a cookie readily available, even before the server can supply all of the cookies for the current user. The flag is a request that will be honored only if space is available. If the flag is false or not specified, the persistent cookie will be stored wherever it’s most convenient— on a server or on the set-top box, but most likely on a server. On set-top boxes with limited memory, local storage may be reserved for the Service Manager and essential services. This method fails and returns false if a name has not been set for the cookie, if the domain and path properties of the object, if set, don’t include the domain and path of the current document, or if there’s another reason why it can’t modify the cache to match the Cookie object. Otherwise, it caches the cookie,

DESCRIPTION:

Content Developer’s Reference

Cookie Objects

begins the process of writing it to the database, and returns true. It commonly returns before the Cookie data is placed in persistent storage, especially if the database resides on a server rather than on the set-top box. Whenever possible, cached data is communicated to the server lazily, at a convenient time when it won’t slow down anything that has the user’s attention. A stored cookie (including the name, value, and all other properties) can be no larger than 4 KB. If the data exceeds this maximum, store() arbitrarily truncates it.
SEE ALSO:

load(), “Storing Cookie Data” in the “Overview” section

Chapter 3: Extending the Standard API

Cookie Objects

Content Developer’s Reference

Document Object Additions
Overview
The Document object is the standard JavaScript object that represents a downloaded document. It has been modified in two ways: It contains properties for Table objects and adds an array of Cookie objects. The Table properties are named after the tables they represent; the Cookie array is described here.

Properties
cookies
SYNOPSIS:

cookies read-only array of Cookie objects cookies.length read-only number

DESCRIPTION:

An array of Cookie objects, one for each cookie within the scope of the document and associated with the current user. Cookie objects are a convenient way to interact with HTTP cookie data structures. The objects in the array can be accessed by index,
var fifthCookie = document.cookies[4];

or by the cookie name:
var snack = document.cookies["sugar"]; var dessert = document.cookies.thumbDrop;

TV Navigator sets aside a certain amount of memory to cache the cookies that are currently being used, including those represented by objects in the cookies array. However, the amount of memory may be limited. If a page has a large number of cookies, or a number of large cookies, this restriction may affect how many can be seen in the cookies array. The length property counts the number of objects in the cookies array.
SEE ALSO:

“Cookie Objects” on page 65

Chapter 3: Extending the Standard API

Document Object Additions

Content Developer’s Reference

History and HistoryEntry Objects
Overview
The History object is a standard property of every Window object. It’s primary purpose is to permit users to return to previously visited pages, which it does with methods like back(), forward(), and go():
window.history.go(-3);

The index passed to go() is relative; if you pass –3 to the method and, when that page is reloaded, pass –3 again, you’ll wind up 6 pages back in the history list. In its traditional implementation, the History object is an ordered list of URL strings that record the documents that have been previously displayed in the window. For security reasons, it reveals those strings only to trusted inquirers, though anyone can call back(), forward(), and go() to navigate the list. TV Navigator has modified the implementation of the History object, without changing its security protections or standard behavior. Instead of a list of URLs, it’s now an indexable array of HistoryEntry objects. Each object holds a URL and regulates access to it. This makes it possible to get a particular entry from the history list, yet keep the URL hidden. HistoryEntry’s go() method navigates to the URL. With these changes, even insecure documents can save an absolute location in the history list and return to it at will. For example:
var i = top.frames[2].history.curIndex; var comeback = top.frames[2].history[i]; . . . comeback.go();

This can be useful in various situations—for example, to get back to a partially filled-in form after displaying several layers of help in the same frame. Indexes for the History object, unlike those passed to history.go(), are absolute—0 is the first entry in the history list (the first Web page that the window displayed, unless some early entries have been dropped from the list due to memory constraints) and curIndex is the page currently displayed. The HistoryEntry version of go() doesn’t take an index.

Chapter 3: Extending the Standard API

History and HistoryEntry Objects

History Properties
curIndex
SYNOPSIS:

curIndex read-only number The index of the current page in the history list. This property parallels the standard History.current property (a URL string), but it doesn’t need to be restricted to trusted pages as that property is. All standard properties and methods of the History object are preserved and work as expected.

DESCRIPTION:

HISTORY:

First implemented in the 1.2 release.

History Methods
add(), remove()
SYNOPSIS:

void add(string url) void remove(string url)

DESCRIPTION:

These functions add entries to and remove them from the history list. add() creates an entry for the URL passed as an argument, inserts it immediately after the current entry, and makes it the last entry in the list. In other words, if there are any entries in the list after the current entry, the new entry replaces them. remove() looks for an entry with a URL that matches the URL passed as an argument and removes it from the list. It removes only the first matching entry it finds, even if other entries in the list also happen to match the argument URL. remove() searches backwards in the list beginning with the current entry. If it reaches the beginning of the list without finding a matching entry and the current entry isn’t the last one in the list, it begins again at the end of the list until all entries have been tried once. It does nothing if it can’t find a matching entry.

SEE ALSO :

“Transient History” on page 57, the history feature for Window.open() on page 107

Content Developer’s Reference

History and HistoryEntry Objects

back(), forward(), go()
SYNOPSIS:

boolean back(void) boolean forward(void) boolean go(number relativePosition) boolean go(string substring)

DESCRIPTION:

These are the standard History methods, with one modification: They each return a boolean value indicating whether or not the history list contains an entry at the requested position, or matching the specified substring. If the entry exists, they return true; if not, they return false. A return of true means that the process of navigating to the requested page has begun. It does not mean that the page has been loaded or that curIndex has been updated.

HISTORY: SEE ALSO:

The boolean return value was added to these methods in the 1.2.3 release. fullGo(), HistoryEntry.go() on page 84

forward() fullGo()
SYNOPSIS: DESCRIPTION:

see back()

exclusive boolean fullGo(number relativePosition) This is a variant of the standard go() method. But unlike go(), it has all frames (all Window objects) associated with the physical window within its scope. It can step through all recent changes to the window, regardless of which frame the change affected. Suppose, for example, that a window displaying document D, as illustrated in the diagram at the top of the next page, loads another page that’s split horizontally into two frames. The document in the top frame then changes from K to L, followed by the document in the bottom frame changing from R to S.

Chapter 3: Extending the Standard API

History and HistoryEntry Objects

D
if ( top.go(-1) ) . . .

K R

L R

L S

At this point, passing –1 to the go() method for the top-level Window object,

would unload the frameset and reload D—that is, it would undo the last change to the top-level window, ignoring changes to the individual frames. However, passing the same value to fullGo(),
if ( top.fullGo(-1) ) . . .

would reload R in the bottom frame; it wouldn’t alter the top-level window. Repeating this call would then reload K in the top frame. Repeating it once more would finally reload D. Because it encompasses the entire window, fullGo() more exactly matches the meaning of “back” and “forward” in the user interface than the other History methods. It’s designed precisely for the service that provides that interface. The fullGo() method works only for the top-level Window object and only if the window was opened with the history feature set to “full” (see the Window.open() method for information on this feature). If these conditions aren’t met, it does nothing and returns false. It also returns false if it’s requested to reload a page that’s no longer present in the history record. If successful, it returns true. When this method reloads a page, the history record of the affected Window object is updated. However, it may return before the change it initiates has been completed. Therefore, a return of true doesn’t necessarily mean that the page has been loaded or the Window object’s curIndex has been updated.

Content Developer’s Reference

History and HistoryEntry Objects

ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.2.3 release. go(), Window.open() on page 105

go()

see back() see add()

remove()

HistoryEntry Properties
appData
SYNOPSIS:

appData controlled-read/controlled-write object An object where the master application can record any information about the entry that it may need. For example, it could keep track of whether the entries are channels (tv: URLs). The default value is null. Regulated by the privacy ACL. Added to the API in the 1.2.2 release, but currently unimplemented. This property is not implemented in the 1.2.6 and 1.3 releases.

DESCRIPTION:

ACCESS: HISTORY: AVAILABILITY:

title
SYNOPSIS:

title controlled-read-only string The title assigned to the entry in HTML (the string bracketed by the <title> and </title> tags in the document head). Regulated by the privacy ACL. Introduced in the 1.2 release.

DESCRIPTION:

ACCESS: HISTORY:

Chapter 3: Extending the Standard API

History and HistoryEntry Objects

HistoryEntry Methods
go()
SYNOPSIS: DESCRIPTION:

boolean go(void) Begins reloading the page and returns true, provided the entry is still in the history list. If it’s not in the list, the page will not be reloaded and this method returns false. Since that means the HistoryEntry object is no longer useful, it’s recommended that you delete all references to it:
if ( theEntry.go() ) { . . . } else theEntry = null;

HISTORY:

First implemented in the 1.2 release. The boolean return value was added in the 1.2.2 release. History.go() on page 81

SEE ALSO :

toString()
SYNOPSIS: DESCRIPTION:

controlled string toString(void) Returns the URL kept by the HistoryEntry object, if it is safe to do so, or an empty string if not. toString() is the function the JavaScript interpreter invokes to convert an object to a string. Therefore, if someone at an untrusted site tries to discover a URL with code like this,
document.write("the previous URL is: " + history[history.curIndex-1]);

all they will get is an empty string. However, it’s possible to navigate to that same URL using go():
history[history.curIndex-1].go()
ACCESS: HISTORY:

Controlled by the privacy ACL. First implemented in the 1.2 release.

Content Developer’s Reference

Navigator Object Additions
Overview
The Navigator object is a standard JavaScript entity that represents the browser itself. It holds properties that pertain to the entire software environment, rather than just one window or document. There’s only one Navigator object; every window has a navigator property, but they all refer to the same underlying object. The window is therefore typically not specified. The Navigator object has been extended with a variety of properties for Interactive TV. All the extensions are read-only objects and are part of an array; they can be accessed either as identifiers,
var displayObj = navigator.display;

or with a numerical or string index:
var firstObj = navigator[0]; var displayObj = navigator["display"];

Standard properties of the Navigator object, like mimeTypes, are not part of the array; they’re not counted in the array’s length. They can always be accessed as identifiers, but not with a numerical index:
navigator.mimeTypes navigator["mimeTypes"] navigator[index] // this will work // this will too // this won’t yield the mimeTypes property

Most of the properties added to the navigator array represents capabilities of the Navigator software and set-top box. For example, Navigator.tvTuners is a collection of TvTuner objects, each one representing a connection to a television tuner; Navigator.input is a center for responding to the user’s input on a remote control or keyboard; and Navigator.cache represents the local cache of downloaded data. Therefore, you can test the capabilities of the client machine by seeing which Navigator properties are defined.

Properties
appCodeName appName appVersion see userAgent see userAgent see userAgent

Chapter 3: Extending the Standard API

Navigator Object Additions

cache
SYNOPSIS:

cache read-only Cache object An object that represents the cache of downloaded data. Its methods— currently only remove()—give applications a measure of control over the caching mechanism and the contents of the cache. “Cache Object” on page 147

DESCRIPTION:

SEE ALSO :

curUser
SYNOPSIS:

curUser read-only User object A User object representing the currently recognized user—or null if there is no current user. This property may be null in the early stages of start-up and briefly when switching from one user to another. Among other things, the current user determines which cookies are visible, which services are available, and whether there are restrictions on access to any Web sites. The Service Manager (or a designated service that shares its domain) can coordinate other properties, such as TvChannel.blocked, with the current user.

DESCRIPTION:

ACCESS:

There are no access restrictions on the curUser property. However, all but one or two properties of the User object are protected with the “exclusive” access privilege. “UserManager Object” on page 369

SEE ALSO :

Content Developer’s Reference

Navigator Object Additions

display
SYNOPSIS:

display read-only Display object An object that represents the screen where television and Web output is displayed. This object can report the video format and the size of the screen in pixels. It also permits you to turn the display on and off. “Display Object” on page 39

DESCRIPTION:

SEE ALSO:

extensions
SYNOPSIS:

extensions controlled-read-only array of strings extensions.length controlled-read-only number

DESCRIPTION:

An array identifying the extensions that are incorporated into the TV Navigator client. Extensions are add-on modules built using the TV Extender kit; they extend the capabilities of the TV Navigator application engine and may export an independent JavaScript API. Typically, they’re implemented to provide the necessary underpinnings for a particular application or service However parts of the core API are also implemented as extensions—for example, the MusicText and VodSession objects. Each string in the extensions array identifies one extension and has the following form,
companyID_extensionName/version

where companyID identifies the developer of the extension, extensionName is the name of the extension, and version is the version number. For example:
Acme_Player/2.5b Dtv_CaExtn/1.8.3

The string is determined by the extension developer. Liberate reserves the letters “Dtv” as the companyID to identify the extensions it implements.
ACCESS: HISTORY:

Controlled by the principal ACL. Introduced in the 1.2.5 release.

Chapter 3: Extending the Standard API

Navigator Object Additions

indicators
SYNOPSIS:

indicators read-only array of Indicator objects indicators.length read-only number

DESCRIPTION:

An array of objects representing the indicators on the set-top box. An indicator is any device that conveys information to the user. It might be a clock, an LED text field, a small light, or perhaps even a beeper or siren. Indicator objects provide a way to programmatically read and set their values. Each value is represented by a separate object in this array. In addition, Indicator objects may be used to manage arbitrary settings that don’t necessarily correspond to actual indicators on the set-top box. The set of indicators is specific to each deployment. The length property records the number of objects in the array.

SEE ALSO :

“Indicator Objects” on page 301

input
SYNOPSIS:

input read-only Input object An object that provides a mechanism for customizing an application’s response to user input and a “focus stack” for shifting the input focus from one window to another. “Input Object” on page 305

DESCRIPTION:

SEE ALSO :

length
SYNOPSIS:

length read-only number The number of elements in the Navigator array. The count includes only those Navigator properties that can be obtained through a numerical index:
var firstObj = navigator[0];

DESCRIPTION:

Content Developer’s Reference

Navigator Object Additions

The same properties can be indexed using a name:
var localCache = navigator["cache"];

It excludes the traditional properties of the object, such as mimeTypes and appName. They’re available through the “dot” (.) notation, as are all Navigator properties:
var types = navigator.mimeTypes; var obj = navigator.cache;

net
SYNOPSIS:

net read-only Net object A central point for managing the Internet connection and setting up asynchronous requests for data. “Net Object” on page 151

DESCRIPTION:

SEE ALSO:

serviceManager
SYNOPSIS:

serviceManager controlled-read/exclusive-write Window object The Window object for the persistent JavaScript context where the Service Manager is running. The Service Manager sets this property at start-up. Individual services can access the variables and functions that the Service Manager defines as properties and methods of this object. For example, a service would call the sFadeIn() method as follows:
var sm = navigator.serviceManager; sm.sFadeIn(. . .);

DESCRIPTION:

ACCESS:

Reading is governed by the principal ACL; writing is reserved for pages from the Service Manager’s domain. Introduced in the 1.2.6.1 release. Service Developer’s Guide in the TV Customizer kit

HISTORY: SEE ALSO:

Chapter 3: Extending the Standard API

Navigator Object Additions

speaker
SYNOPSIS:

speaker read-only Speaker object An object containing the master controls for audio output. It parallels the Display object, which is concerned with video output. “Speaker Object” on page 53

DESCRIPTION:

SEE ALSO :

sysServices
SYNOPSIS:

sysServices exclusive-read-only array of Service objects sysServices.length read-only number

DESCRIPTION:

An array of Service objects representing all services in the deployment. Objects in the array represent the same services as the objects in the individual User.sysServices arrays and are arranged in the same order, but they’re not associated with any particular user. Setting a property of a Service object in this array sets a default value for every User object on the set-top box, unless another value has been explicitly set for that user. Registered users and guest users are equally affected, as are all new users who are subsequently added. You can override the default by setting different values for individual users. Reading a property of a Service object in this array yields the value previously set, or null if a value was not set at this level. It doesn’t yield the value set for any individual user, nor the default value set for the deployment. Although they’re not associated with a particular user, the Service objects in this sysServices array contain “user data” and are subject to the same constraints as all Service objects. For example, access restrictions based on the current user apply; this generally means that the current user must have administrative privileges to access the object. Similarly, any changes made to the object will not be written to the server until UserManager.syncUserData() is called or another event forces synchronization.

ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl.

Content Developer’s Reference

Navigator Object Additions

HISTORY: SEE ALSO:

Introduced in the 1.2.6 release. “Service Objects” on page 339, User.sysServices on page 365, Service.sysTrustedUrl on page 356, UserManager.syncUserData() on page 373

system
SYNOPSIS:

system read-only System object An object with systemwide controls—such as a general onerror() handler, a handler for external events, a set-top box control() method, and a machine ID. “System Object” on page 313

DESCRIPTION:

SEE ALSO:

tvTuners
SYNOPSIS:

tvTuners read-only array of TvTuner objects tvTuners.length read-only number

DESCRIPTION:

An array that contains one TvTuner object for each television tuner in the settop box and each additional source of video input (such as an S-video or SCART port) that might be connected to an external tuner. In addition to the array, this object also holds the constructor for TvProgram objects and properties that keep track of the current tuner. The length property reports the number of objects in the array. For current deployments, the number should always be 1.

SEE ALSO:

“TvTuners Array” on page 283, “TvTuner Objects” on page 269

Chapter 3: Extending the Standard API

Navigator Object Additions

userAgent, appName, appCodeName, appVersion
SYNOPSIS:

userAgent read-only string appName read-only string appCodeName read-only string appVersion read-only string

DESCRIPTION:

These are standard properties of the Navigator object. For TV Navigator, they have the following values in the 1.2.6 and 1.3 releases: 1.2.6 The appName is “Netscape”, to indicate the TV Navigator is compatible with Netscape Navigator. The appCodeName varies depending on the hardware—for example, it’s “Emmy” for the set-top emulator. The appVersion is “3.00 [en] ( . . . )” where the parentheses enclose fields of information separated by semicolons and spaces. One of the fields is “Liberate” and another begins with “DTV”. The userAgent is “Mozilla/3.0 ( . . . )” where the parentheses enclose fields similar to, but not exactly the same as, the fields of the appVersion string. One of these fields also begins with “DTV”. 1.3 The appName is “Netscape” and the appCodeName is “Mozilla”, since TV Navigator is compatible with the Netscape browser. The appVersion is “3.0 ( . . . )”, since TV Navigator currently supports the same versions of HTML and JavaScript that Netscape Navigator 3.0 supports. The userAgent string is a combination of the code name and version, separated by a slash: “Mozilla/3.0 ( . . . )”. Liberate-specific and deployment-specific information is located within the parentheses of the appVersion and userAgent strings. The information is organized into distinct fields, which are separated from each other by a semicolon and a space. Spaces also separate the first and last fields from the parentheses:
( field1; field2; field3; . . . fieldn )

Content Developer’s Reference

Navigator Object Additions

The fields are ordered. The first five are well-defined and provide details about Liberate, the software version, and the deployment:
( company; code_base; version; platform; service_provider[; field6[; field7[; . . .[; fieldn]]]] )

The company is “Liberate”. The code_base for TV Navigator Standard is “DTV”, and the version for this release is “1_3”. Note that numbers in the version are separated by underscores rather than periods. The platform and service_provider depend on the deployment. The platform field identifies the set-top box. (For the set-top emulator, it’s “WIN32”.) The box name may be followed by a slash (/) and additional information about the model, the operating system, or any other information that may be of use to developers. For example:
HAL/2001_v6

The service_provider field gives the cable or satellite company deploying TV Navigator a place to identify itself and provide version and other information about the deployment. For example:
UniTv_PAL_2_5

A full userAgent string could look something like this:
Mozilla/3.0 ( Liberate; DTV; 1_3; HAL/2001_v6; UniTv_PAL_2_5 )

Additional fields with other deployment-specific information may also be present, following the five standard fields. Contact the service provider for the position and format of any user-agent information you might need to look for. Your code should search for particular fields by locating the open parenthesis, (, then counting fields from left to right until the closing parenthesis, ). Since the fields are not guaranteed to be unique strings—for example, field4 in one deployment may contain the same sequence of characters as field7 in another deployment—it’s important to locate the particular field you want to look at, rather than simply search for substrings.

Chapter 3: Extending the Standard API

Navigator Object Additions

For example, the following code locates the fourth field within the parentheses:
var ua = navigator.userAgent; var idx = ua.indexOf("("); for ( i = 0; i < 4; i++ ) { idx = ua.indexOf(" ", idx); idx++; } ua.charAt(idx); // the first character of the 4th field

The search is made simpler by the fact that the fields contain only letters, numbers, slashes, and underscores; they never contain spaces, parentheses, or semicolons.
HISTORY:

The contents of the parentheses were modified and formalized in the 1.3 release.

userManager
SYNOPSIS:

userManager read-only object An object that keeps track of the registered users of the machine. It can add users, delete them, and switch from one user to another. Each user is represented by a User object, which the UserManager provides. Although anyone can read the UserManager object from the Navigator array, only the Service Manager and those closely associated services that share its domain have access to the object’s methods and properties.

DESCRIPTION:

SEE ALSO :

“UserManager Object” on page 369

Content Developer’s Reference

String Object Additions
Overview
The String object collects a variety of methods that operate on character strings. See the String object on page 435 in Appendix B, “JavaScript Catalog,” for a list of the String methods that TV Navigator supports. TV Navigator adds just one method, encrypt(), to the standard String repertoire.

Methods
encrypt()
SYNOPSIS: DESCRIPTION:

string encrypt(string salt)

1.3

Encrypts the string using two salt characters as a seed and returns the encrypted string. For example, this code
var foobleEncrypted = "fooble".encrypt("mi");

would encrypt “fooble” to, say, “08a73950ce2cd98f96d608ddb1cb33f7” and return that string. The salt string must be at least two characters long; only the first two characters are used. Any two characters will do; there are no restrictions. If it contains less than two characters, a JavaScript error is generated. This method uses an encryption algorithm similar to the MD5 message-digest algorithm described in RFC 1321. It’s believed that it produces a unique encryption for every string and that it’s computationally impossible to discover the starting string from the encryption. The encrypt() method is intended for password security, so that passwords and other private strings can be transmitted in the clear. However, it doesn’t solve all security problems; it's a complement to other techniques like link encryption (SSL) and encrypted databases.

Chapter 3: Extending the Standard API

String Object Additions

Typically, an application would use this method by:

1. Asking the user to type in the password, 2. Retrieving the stored, encrypted password and the salt string, 3. Calling encrypt() on the string the user typed in, passing it the retrieved salt
characters, and

4. Comparing the string encrypt() returns to the stored string.
The salt characters could be appended to the encrypted string before that string is stored—or, for an added measure of security, they could be managed and stored separately. Different characters could be used to encrypt the passwords of different users, so that the encryptions will differ even if two users choose the same password.
HISTORY:

Introduced in the 1.3 release.

Content Developer’s Reference

Text and Textarea Object Additions
Overview
The Text and Textarea objects add a bgColor property that lets you dynamically control the color behind the text. This property matches the bgcolor attribute of the <input> and <textarea> tags. In addition, the Textarea object has been expanded to give interactive applications more control over other aspects of the text display—including the ability to append text, scroll lines, and append new text. For the most part, these extensions are available only in JavaScript; they’re not paired with new attributes of the HTML <textarea> element. Text and Textarea objects are properties of a Form. They can be accessed either by name or through the Form object’s elements array:
var myTextElement = document.theForm.nameOfTextOrTextarea; var anElement = document.theForm.elements[index];

Text and Textarea objects have a number of standard properties common to other form elements—including a name, a type that identifies the object as a “text” or “textarea” object, a reference to the form it belongs to, and a value that holds all the text assigned to the object. In addition, they have focus() and blur() methods and onfocus() and onblur() event handlers— plus an onchange() handler that’s invoked whenever the user changes the text. The properties and method listed next are additions to these standard properties and methods.

Text Object Properties
bgColor
SYNOPSIS:

bgColor read/write string The background color of the text field. This property matches the bgcolor attribute of the <input> tag and can be set to “transparent”, among other color values. “Transparent and Opaque Backgrounds” on page 22

DESCRIPTION:

SEE ALSO:

Chapter 3: Extending the Standard API

Text and Textarea Object Additions

Textarea Object Properties
bgColor
SYNOPSIS:

bgColor read/write string The background color of the text area. This property matches the bgcolor attribute of the <textarea> tag. “Transparent and Opaque Backgrounds” on page 22

DESCRIPTION:

SEE ALSO :

bottomLine

see topLine

curLineCount, maxLineCount
SYNOPSIS:

curLineCount read-only number maxLineCount read/write number

DESCRIPTION:

These properties record the number of lines currently in the buffer for the text area and the maximum number of lines allowed. Only lines that are separated by a carriage return (\r) are counted; lines that are wrapped without a carriage return count as a single line. There’s always at least one implicit line; curLineCount will never drop below 1 even if there’s no text in the buffer. When the current number of lines reaches the maximum, one line is deleted from the beginning of the buffer for each new line that’s appended. If maxLineCount is set to 0, TV Navigator will attempt to keep as much text as it can for the Textarea. It won’t impose a limit on the number of lines. The default is 0.

SEE ALSO :

topLine

Content Developer’s Reference

Text and Textarea Object Additions

focusable
SYNOPSIS:

focusable read/write boolean Whether or not the text area can be the focus of user input—true if it can, and false if not. Text areas in a form generally must be able to accept the user’s typed input and therefore must be focusable. However, a text area that simply displays messages to the user and doesn’t record the user’s input should not be focusable. The initial value of this attribute mirrors the value set in HTML. Text areas are focusable by default.

DESCRIPTION:

HISTORY: SEE ALSO:

Introduced in the 1.2 release. “Preventing Focus on a Text Area” on page 30

maxLineCount

see curLineCount

topLine, bottomLine
SYNOPSIS:

topLine read/write number bottomLine read/write number

DESCRIPTION:

The indexes of the lines currently showing at the top and bottom of the visible text area on-screen. The text can be scrolled by setting either property. The beginning of the line that sets topLine will be shown at the top of the text area; the end of the line that sets bottomLine will be displayed at the bottom of the area. When either property is set, the other is automatically updated to reflect the line (or partial line) showing at the bottom or top. curLineCount

SEE ALSO:

Chapter 3: Extending the Standard API

Text and Textarea Object Additions

wrap
SYNOPSIS:

wrap read/write string Matches the wrap attribute of the <textarea> element. The permitted values are: “off” “soft” Lines of text won’t wrap. A new row of text is created only where the text explicitly includes a carriage return (\r). Lines are wrapped to fit within the viewing area. A carriage return is not inserted at the end of each row of text within a wrapped line. Text that’s wrapped between carriage returns counts as a single line. Lines are wrapped by inserting a carriage return at the end of each row of text. Each row counts as a separate line.

DESCRIPTION:

“hard”

The default value is “soft”. However, if another value is set in HTML, this property will reflect the value that was set.
SEE ALSO :

curLineCount

Textarea Methods
append()
SYNOPSIS: DESCRIPTION:

boolean append(string newText) Appends the newText string to the end of the text already in the Textarea’s buffer. If the last character in the buffer was visible within the text area before the new text was appended, this method scrolls the text so that the last characters of the appended text are visible. However, if the last character in the buffer was not visible before append() was called, the text is not scrolled. This method returns true if it succeeds in adding text to the buffer, and false if not. The newText string can include carriage-return characters (\r) to separate lines of text. Appending new lines of text to the text area may cause other lines to be deleted from the beginning of the buffer, if the additions cause the line count to exceed the maximum.

100

Content Developer’s Reference

Text and Textarea Object Additions

A carriage return is not automatically inserted when text is appended. The newText string extends the last line currently in the buffer—unless the last character of the current text is a carriage return, or the first character in newText is one.

Chapter 3: Extending the Standard API

101

Text and Textarea Object Additions

102

Content Developer’s Reference

Window Object Additions
Overview
The Window object is a standard JavaScript object representing a window or a frame within a window. Because of its position in the client-side object hierarchy, it’s also the repository for global variables and functions. The Liberate additions to the Window object are of both types. Some are window-specific and deal with the window’s position and presence on-screen. Others are more global in scope.

Properties
layer
SYNOPSIS:

layer read-only number The front-to-back tier in which the window resides. The higher the number, the closer the window is to the front of the screen (to the user). A layer can contain more than one window. Typically a single window, one that fills the whole screen, resides in tier 0 at the very back. The layer can be set when the window is created with the open() method; it can be read but not written thereafter. (Note that this property is not related to the HTML <layer> tag or the JavaScript Layer object, neither of which are supported.)

DESCRIPTION:

SEE ALSO:

open()

overscan
SYNOPSIS:

overscan read/write string Lets background colors and images spread from the edge of the window to the edge of the screen. This property is meaningful only for top-level Window objects (not for frames). It’s similar to the overscan attribute of <body> and <frameset> tags and takes the same set of values. The default value is “none”.

DESCRIPTION:

Chapter 3: Extending the Standard API

103

Window Object Additions

If a page that’s loaded into the top-level window sets an overscan value in HTML, that value takes precedence over any value set in JavaScript. The JavaScript setting is ignored while that page is loaded; it’s used only for pages that don’t mention the overscan attribute. When read, this property reports the value set in JavaScript, or “none” if a value was not set. It never reports a value set in HTML.
SEE ALSO :

“Backgrounds beyond Window Borders” on page 23

visible
SYNOPSIS:

visible read/write boolean Whether the window is displayed on-screen—true if it is, and false if not. The visible feature passed to the open() method determines whether the window is initially visible when it’s created and the initial value of this property. Setting visible to true places the window on-screen and pushes it on the focus stack of Window objects so that it becomes the focus of user input. Setting it to false removes the window from the screen without losing its content or context. If the window happens to be at the top of the focus stack, it is popped from the stack. If it’s in the focus stack but not at the top, it retains its position in the stack. However, it must be made visible before it can again become the focus window. When it is made visible again, another reference to the Window object is pushed on the stack, so the window will then occupy two positions in the stack. The onvisible() handler for the window is called each time its visibility is changed. If a window is displaying TV when it’s made invisible, the TV resource may be shifted to another, visible window. If it retains the television picture (because no visible windows ask for it) the audio component is turned off. The sound is “hidden” along with the picture.

DESCRIPTION:

SEE ALSO :

open(), onvisible(), “The Focus Stack” on page 295

104

Content Developer’s Reference

Window Object Additions

Methods
close()
SYNOPSIS: DESCRIPTION:

controlled void close(void) Closes the window, provided the Window object corresponds to a top-level window and not a frame. This is a standard JavaScript method and it behaves as it does on other browsers. The only difference is the way access to the method is controlled. Regulated by the minor ACL. This is not the same list that controls access to the open() method. Therefore, a page can be given the right to close the window where it’s displayed, without also being given the right to open other windows.

ACCESS:

open()
SYNOPSIS: DESCRIPTION:

controlled object open(string url, string name [, string features]) This is a standard JavaScript method. It loads the document specified by its first argument, url, into the window or frame that has the name specified in the second argument; it returns the Window object for the window or frame where it put the document. On a computer-oriented browser, open() creates a new window if an existing window or frame with the given name can’t be found. It assigns the name to the window and endows it with any properties listed in the features argument. The features list is ignored if the document can be loaded into a window that already exists. TV Navigator modifies this behavior a bit so that existing windows are preferred and window clutter is reduced. Two conditions must be met for a new window to be created: • TV Navigator first applies the standard condition on creating a new widow: The name cannot designate an existing Window object. If it does, the document is opened in that window or frame. • TV Navigator then imposes an additional condition: The features list must include at least one key feature to indicate that a new window is required. If not, it loads the document in the current window or frame (the window or frame from which open() was called). The key features that can cause a new

Chapter 3: Extending the Standard API

105

Window Object Additions

window to be created are marked in the table below; they’re a subset of the features Liberate has added to the API. The following table lists all the features that TV Navigator supports and marks those that can cause a new window to be created; other features defined for JavaScript 1.1 or 1.2 are ignored.

Feature name
width height left top layer visible history progressReported autofocus

Feature value
“number of pixels” “number of pixels” “column index” “row index” “a number” “true” or “false” “off”, “simple”, or “full” “true” or “false” “true” or “false”

New window Introduced in
JS 1.0 and 1.1 JS 1.0 and 1.1 √ √ √ √ √ √ TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2

Each feature is a “name=value” pair. If the features argument lists more than one, they’re separated by commas. For example:
"left=80,top=110,width=400,height=170,visible=false"

Only one of the key features needs to be present to trigger a new window. The supported features are: left top width height These features locate the window on-screen. They assume a coordinate system where coordinate units match pixels and (0, 0) is the left-top pixel of the full screen. That is to say, left and top position the window relative to the full screen, not the safe area. If any of these features is not specified, TV Navigator picks default values. It currently does not pick values that ensure the window will open within the safe area, so some of it may not be visible to the user. Therefore, it’s

106

Content Developer’s Reference

Window Object Additions

important to always specify the left and top coordinates as well as the width and height to precisely position the window on-screen. layer visible These features determine the front-to-back layer the window will reside in and whether it will initially be visible on-screen. The visibility of the window can be changed after the window is opened, but the layer is fixed. Layers are numbered back-to-front, so that a window in layer 0 stays in back of windows in all other layers. A layer can contain more than one window. For example, if only one of a group of three windows can be visible at any given time, all three might be assigned to the same layer. By default, windows are visible and are assigned to layer 0. (However, the pop-up windows that the Service Manager creates are initially hidden.) history The history feature determines two things: (1) whether or not a history record will be kept for the window and (2), if a record is kept, whether or not the History.fullGo() method will work. Setting history to “off” turns off the history mechanism; the new window’s history property will be undefined, as will the history properties of any frames within the window. This is appropriate for panels that have an unchanging display and for windows that are displayed only temporarily. Avoiding the overhead of the history mechanism can result in a significant memory savings and also a small improvement in performance. Setting history to either “simple” or “full” means that a history record will be kept and the history property will be defined for the top-level Window object and for the Window objects corresponding to every frame. The difference between the two settings is that “full” enables the History.fullGo() method for the top-level window, whereas “simple” does not. Like the other History methods, fullGo() navigates to previously visited URLs. However, its scope embraces all frames within the window (all Window objects in the physical window). Going back one step in “full” history undoes the most recent change to any frame, not just to the toplevel window. This is the behavior usually associated with “Forward” and “Back” buttons in the user interface. In contrast, the three common History methods—go(), back(), and forward()—also navigate to previously visited Web sites, but limit their scope to just one particular Window object or frame. Going back one step

Chapter 3: Extending the Standard API

107

Window Object Additions

with these methods undoes the most recent change to that particular frame, even if there have been more recent changes to another frame. These methods work for both “simple” and “full” history. Currently, only one window can be set to “full” history at a time. The results are undefined if an attempt is made to open a window with “full” history when another window with that feature is already open. The default value if the history feature is not mentioned, or is listed without a value, is “simple”. progressReported This feature determines whether the Net.onprogress() handler will be called to report the progress of network activity that targets the window. If “true”, the handler is invoked; if “false”, it’s not. The default value is “false”. However, if progressReported is listed without a value, it will be set to “true”. autofocus The autofocus feature determines whether the window can automatically be made the focus window, without explicitly calling Input.pushFocus() or Window.focus(). If this feature is “true”, the window will automatically be pushed on the focus stack, making it the focus window, in two circumstances: • When open() creates it, if it’s a visible window. • When it changes state from invisible to visible. Similarly, if it’s at the top of the focus stack, it will automatically be popped from the stack in the opposite circumstances: • When it is closed. • When it changes state from visible to invisible. If autofocus is “false”, the window can become the focus window only if Input.pushFocus() (or Window.focus()) is called to explicitly put it on the focus stack—it won’t automatically get the focus when it’s opened or made visible. Similarly, it will take an explicit Input.popFocus() call to remove it from the stack. (However, once it’s on the focus stack, the window will automatically relinquish the focus when another window is pushed on the stack, and it will automatically regain the focus when the windows above it are popped, leaving it again at the top of the stack.)

108

Content Developer’s Reference

Window Object Additions

The default value if the autofocus feature is not mentioned or is listed without a value, is “true”. The default behavior is strongly preferred. Windows that don’t autofocus must be managed carefully; they should not be left in the stack when they don’t have the focus. For more detailed information on window focus, see “The Focus Stack” on page 295 in Chapter 7, “System Capabilities.” Mentioning any of the boolean features (visible, progressReported, or autofocus) without setting a value is equivalent to setting them to “true”. However, windows are visible and autofocus by default, so those features need to be mentioned only to set the value to “false” or to make sure that a new window is created. For example, this code produces a new window,
open("tv:", "", "visible");

but this does not:
open("tv:", "");
ACCESS: HISTORY:

Controlled by the reading sublist of the principal ACL. The autofocus feature was added in release 1.2. Release 1.2.3 filled out the full set of values for the history feature. layer, visible, “ScreenArea and SafeArea Objects” on page 49, “History and HistoryEntry Objects” on page 79, Net.onprogress() on page 153

SEE ALSO:

releaseContext()
SYNOPSIS: DESCRIPTION:

void releaseContext(void) Releases the JavaScript context for the current document, freeing all the pagespecific data structures used by the JavaScript interpreter. The JavaScript context for a document can occupy a relatively large amount of memory; this function reclaims that memory. However, you can safely call it only after it is certain that no further JavaScript code will be executed for the page—or that any JavaScript that will be executed won’t call any functions or refer to any variables defined on the page. When a new page is loaded and it contains JavaScript code, the browser builds a JavaScript context for the document. The context covers the entire document, no matter where the JavaScript may appear—for example, in more than one <script> section, event handler, or javascript: protocol. The browser

Chapter 3: Extending the Standard API

109

Window Object Additions

automatically destroys the context when it replaces the document with another. The context therefore may occupy memory even after all the JavaScript code on the page has been executed. releaseContext() frees that memory. It fails only if, at the time it’s evaluated, any additional JavaScript code is in the queue awaiting execution. It won’t normally fail, even if called at the beginning of a <script> section, since its evaluation is delayed until the closing </script> tag is encountered. Nevertheless, it may succeed before all the JavaScript for the document has been executed—for example, there may be more than one <script> tag or the user might subsequently take an action that causes an event handler to be called. In these cases, the browser rebuilds the JavaScript context, but without its original content. The results are therefore undefined if any of that content is assumed by the JavaScript that must be executed. It’s up to you to make sure that releaseContext() is called only when the context is no longer needed.

Event Handlers
onkeyout()
SYNOPSIS:

boolean onkeyout(void) read/write handler A handler for input keys that’s specific to a document. The mechanism for responding to input keys—including the role of this handler—is described under “Input Handling” in the introduction to Chapter 7. Input.onkeyout() on page 310, “Input Handling” on page 298

DESCRIPTION:

SEE ALSO :

onvisible()
SYNOPSIS:

void onvisible(void) read/write handler Called when the visibility of a window changes. The new state of the window can be read from the Window.visible property; the handler is called after the change is made—after the window is placed on-screen if visible is true, and after it is removed from the screen if visible is false.

DESCRIPTION:

110

Content Developer’s Reference

Window Object Additions

This handler can be defined in JavaScript or in HTML as an attribute of the <body> tag,
<body . . . onvisible="doUpdate();" . . .>

provided that the document is in the topmost window, not a frame. It can also be defined as an attribute of the <frameset> tag, provided that it’s the topmost frameset. onvisible() is not called when a new window is opened.
SEE ALSO:

visible

Chapter 3: Extending the Standard API

111

Window Object Additions

112

Content Developer’s Reference

Dynamic Tables

CHAPTERM

TV Navigator supports dynamic tables—tables the user can navigate and that JavaScript can modify at run time. A dynamic table is characterized by three main features: • It can have focusable cells. The user can move the focus from one cell to another and invoke a desired cell. Each user action in the table is reported as an event. • JavaScript objects correspond to the table and to each of its rows and cells. These objects control the table display and have event handlers that can respond to the user’s actions. • It has a name. Giving the table a name signals that you want it to be dynamic. The name also makes it possible to locate the JavaScript object for the table. For example, the interface to an electronic programming guide (EPG) might be implemented using a dynamic table. As the user navigates from cell to cell, the guide can scroll to bring more programs into view—not by repositioning cells, but by altering the appearance of cells in fixed positions. When the user selects a particular cell, it can provide more information about the selected program, tune to the program, add it to a list of preferred programs, or take some other appropriate action.

Note: Version 1 of the Document Object Model (DOM 1) introduced JavaScript objects for
tables, rows, columns, cells, captions, and other parts of a table. While there is some overlap between DOM 1 objects and the objects documented here, TV Navigator’s implementation of dynamic tables is an independent, and simpler, model.

Named Tables and JavaScript Objects
Assigning a name to a table in HTML, as shown below,
<table name="infoGrid" . . .>

triggers the creation of a JavaScript Table object. The object is a property of the Document object and can be accessed by name:
var myTable = Document.infoGrid;

Chapter 4: Dynamic Tables

113

Limitations on Content

The only thing you need to do to make a table dynamic is give it a name. Note that Table objects are direct properties of the Document object; there is no Document.tables array. The Table object has a rows array of TableRow objects, one for each row of cells in the table. In turn, a TableRow object has a cells array of TableCell objects, one for each cell in the row. The first cell in the third row of a table would be retrieved as follows:
var firstInThird = document.infoGrid.rows[2].cells[0];

A TableCell object controls a cell’s appearance on-screen—including the text it displays, the number of columns it spans, its background and foreground colors, and so on. User actions in the table invoke event handlers in the Table object, which can respond to what the user has done by modifying the TableCells.

Limitations on Content
As it’s set up in HTML, a dynamic table is indistinguishable from any other table (except that it has a name). It can contain anything that any other table can—images, multiple fonts in one cell, even other tables. However, the dynamic content that JavaScript can place in a table cell is limited to plain text. No images, forms, hypertext links, embedded tables, or other HTML elements are allowed. The TableCell.write() method can place new text in a cell, but the new text cannot contain any HTML tags. Even character entities (like   and &) and tags that format the text (like <tt> and <br>) are not permitted. At present, TV Navigator doesn’t have dynamic access to the static content of a cell (the content assigned in HTML), even if that content is plain text. For example, it can change the color of text that TableCell.write() puts in a cell, but can’t modify the color of text assigned with the <td> tag. Similarly, the Table.scrollRows() method cannot scroll any text placed in cells when the table was set up in HTML. A cell’s static content is wiped away when the cell is first dynamically modified in any way. If you intend a table to be dynamic, you generally would not assign it images and other elements that would be very different from the contents it can display dynamically. It usually makes the most sense to simply lay out the table and assign font characteristics in HTML, but provide all the content through JavaScript. Even the initial content the user sees can be set dynamically, in an onload() handler.

114

Content Developer’s Reference

Font Attributes of Cells

Font Attributes of Cells
Because TableCell.write() disallows even HTML tags that format text (such as <b> and <tt>), it cannot modify the font used to display text in table cells. Each cell retains the font characteristics that it was assigned when it was set up in HTML. You can use any of the following tags to attach font attributes to a cell when you define the table: <font> <b> <i> <u> <tt> <code> <kbd> <samp> <em> <cite> <var> <strong> <s> <strike> <big> <small>

However, these tags set cell attributes only if they appear before the first character of text in the cell. For example, if a row in a dynamic table is set up as follows,
<tr> <td><b>first</td> <td>second</td> <td><u><i>third</td> . . . </tr>

whatever text write() places in these cells will adopt the specified font characteristics—bold in the first cell, plain text in the second, and both underlined and italic in the third. These attributes stay with the cell and cannot be changed. However, if the font tags appear after the first character, they format the static text that HTML puts in the table, but don’t affect any text subsequently written to the cell. The only font attribute that escapes this restriction is the color of the text. It can be modified at any time through the TableCell.fgColor property.

Scrolling
A table cannot move its cells. For example, the third cell in the fourth row always remains the third cell in the fourth row. Therefore, to scroll the contents of the table, you must modify the contents of the cells.

Chapter 4: Dynamic Tables

115

Scrolling

Suppose, for example, that a table has four rows but logically lists all the months of the year, one month per row. It might look something like this: Months January February March Days 31 28 31

When the user wants to scroll down in the table to see the months after March, you would replace the contents of each cell in the 2nd row by the contents of the cell directly beneath it in the 3rd row, replace the contents of cells in the 3rd row by the contents of the cells beneath them in the 4th row, and write new contents into the cells in the 4th row, as illustrated below: Months January February March April Days 31 28 31 30 Months February March April Days 28 31 30

This would convey the illusion that the 2nd row of cells was scrolled off-screen, the 3rd and 4th rows were scrolled up, and a new row brought into view. But the cells remain in place; only their contents change. When scrolling a cell, you probably want to move not only the text it displays, but also the color of the text, its alignment, the background color or image in the cell, the number of columns it spans, and whether or not it’s focusable. TableCell objects have properties that allow you to set each of these cell attributes.

116

Content Developer’s Reference

Matching Cells to Columns

The one thing you cannot set is the font properties associated with the cell. For example, if you scrolled text into the heading row of the table above, the previously plain text would become bold and italic: Months January February March Days 31 28 31 January February March 31 28 31

Normally, to scroll a table, you would turn on the displayDisabled property of the Table object so that all changes to the cells would be “batched” into a single update. TV Navigator also has a scrollRows() method that can both simplify scrolling and do it more efficiently than individually modifying each cell. It moves the contents and attributes of all cells up or down a given number of rows, leaving vacated rows for you to fill individually.

Matching Cells to Columns
Each row in a table is an array of cells represented by TableCell objects. The first object in the array is used in the leftmost column of the table, and the other TableCell objects follow in order from left to right. None of the objects are skipped and the array has no gaps. Therefore, if a cell at the left changes the number of columns it spans, the TableCell objects to its right will jump from one column to another. For example, imagine a table showing the morning schedules of the doctors at a clinic: Staff Dr. Ng Dr. Paine Dr. Tejada 9:30 T. Martinez Mrs. Draper S. Natarajan 10:00 Mr. Sosa unscheduled D. Kakishiba 10:30 B. Kelmendi H. Aaron M. O’Malley 11:00 K. Schwarz P. Rizzuto unscheduled

If Dr. Paine in this example decides to spend a full hour with Mrs. Draper, the table might be updated to reflect this change by increasing the column span of the “Mrs. Draper” cell from

Chapter 4: Dynamic Tables

117

Matching Cells to Columns

1 to 2. This pushes the cells to its right over one column. For example, if no other changes are made to the table, the “H Aaron” cell moves from the 10:30 to the 11:00 column: Staff Dr. Ng Dr. Paine Dr. Tejada 9:30 T. Martinez Mrs. Draper S. Natarajan D. Kakishiba 10:00 Mr. Sosa 10:30 B. Kelmendi unscheduled M. O’Malley 11:00 K. Schwarz H. Aaron unscheduled

Note that the table doesn’t grow by a column; the “P. Rizzuto” cell simply disappears. A dynamic table never increases (or decreases) the number of columns and rows from the number set in HTML. If the “Mrs. Draper” cell reduced its column span from 2 back to 1, the “unscheduled” and “H. Aaron” cells would be pulled back one column to the left and the “P. Rizzuto” cell would reappear. TV Navigator never creates new TableCell objects. Rather, it insists that all cells that a table will ever have must be known when the table is defined in HTML. Those cells may disappear from the screen (as the “P. Rizzuto” cell did), but they’re not destroyed until the entire table is disposed of. Therefore, if a row is set up in HTML with cells that span multiple columns, and those spans are subsequently reduced, TV Navigator won’t be able to create any new cells at the end of the row. (In this situation, you would need to specify a minimum number of cells for all rows. See the “Minimum Number of Cells” section on page 120.)

118

Content Developer’s Reference

HTML for Dynamic Tables
Overview
To support dynamic tables, the <table>, <td>, and <th> tags have been endowed with a handful of new attributes—including a name and a set of event handlers for the <table> tag and an attribute that makes cells focusable for <td> and <th>. Some of the attributes animate the text that a cell displays—so that it slides into view, scrolls past the user, or bounces from side to side. A dynamic table with a single cell can implement a “ticker” or “marquee” (an area on-screen that text moves through, like news bulletins on a marquee above a building or stock quotes on a ticker). All the additions, plus many of the standard attributes of the <table> and <td> tags, are matched by JavaScript properties in the Table and TableCell objects. For the JavaScript complement of this HTML API and a fuller explanation of dynamic tables, see “Table Objects” on page 125 and “TableCell Objects” on page 133.

Table Attributes
Table Name
SYNOPSIS: DESCRIPTION:

<table name="name" . . .> The name attribute assigns a name to the JavaScript object for the table:
<table name="name" . . . >

Table objects are properties of the Document object:
var myTable = document.name;

A table without a name isn’t dynamic. None of the other <table> and <td> (<th>) attributes discussed in this section have an effect if a name isn’t assigned.
SEE ALSO:

“Table Objects” on page 125

Chapter 4: Dynamic Tables

119

HTML for Dynamic Tables

Minimum Number of Cells
SYNOPSIS: DESCRIPTION:

<table name="name" dynamicCols="minimumCellsPerRow" . . .> TV Navigator ensures that each row in a dynamic table will have at least the dynamicCols number of TableCell objects. A row has one TableCell object for each <td> or <th> element assigned to the row in HTML, or the number of objects specified by dynamicCols, whichever is greater. The number of TableCells for the row is fixed when the table is set up; TV Navigator currently cannot produce new TableCell objects on the fly. This attribute therefore permits you to set up a dynamic table with cells spanning more than one column. For example: one plus two one one two three three

two plus three

<table name="myTable" border dynamicCols="3" cellpadding="4"> <tr> <td colspan="2">one plus two</td> <td>three</td> </tr> <tr> <td>one</td> <td colspan="2">two plus three</td> </tr> <tr> <td>one</td> <td>two</td> <td>three</td> </tr> </table>

When the column spans are reduced and more cells are needed in the first two rows, the TableCell objects will be available because the <table> tag specified a minimum of three cells per row. The dynamicCols attribute has second purpose: It lets the Table.scrollRows() method know the minimum number of cells to scroll. If this attribute is not set, scrollRows() will not work. Therefore, it should be set whether or not any cells span more than one column in the initial table.

120

Content Developer’s Reference

HTML for Dynamic Tables

AVAILABILITY:

In a future release, TV Navigator may be able to create new TableCell objects as needed; in that case, the dynamicCols attribute might no longer be needed. “Table Objects” on page 125

SEE ALSO:

Table Event Handlers
SYNOPSIS:

<table name="name" onfocus="JavaScript code" . . .> <table name="name" onblur="JavaScript code" . . .> <table name="name" onnavigate="JavaScript code" . . .> <table name="name" onclick="JavaScript code" . . .> A dynamic table has a set of event handlers that respond to user actions within the table—moving the focus from one cell to another and selecting (“clicking”) a particular cell. These handlers are described in detail in the section on the Table object.

DESCRIPTION:

SEE ALSO:

“Event Handlers” for the Table object on page 130

Cell Attributes
Focusable Cells
SYNOPSIS:

<td <th <td <th

focusable=["true" | "false"] . . .> focusable=["true" | "false"] . . .> focusable . . .> focusable . . .>

DESCRIPTION:

A cell in a dynamic table can take input focus and be selected by the user—if the cell’s focusable attribute is set to “true” or is simply present without an assigned value. If the attribute is absent or set to “false”, the cell cannot take the focus. As the user navigates from cell to cell, the focus will jump over it. The focusability of a cell can be changed dynamically through a TableCell property that matches this attribute.

SEE ALSO:

“TableCell Objects” on page 133

Chapter 4: Dynamic Tables

121

HTML for Dynamic Tables

Highlighting the Cell in Focus
SYNOPSIS:

<td <th <td <th

highlightable=["true" | "false"] . . .> highlightable=["true" | "false"] . . .> highlightable . . .> highlightable . . .>

<table highlightable=["true" | "false"] . . .> <table highlightable . . .>
DESCRIPTION:

The highlightable attribute determines whether the focus rectangle will be drawn around the cell when it’s the focus of user attention. Setting it to “false” prevents the rectangle from being drawn. In all other cases—setting it to “true”, mentioning it with no value set, or not mentioning it at all—highlighting is automatic. This attribute gives you a way to turn off automatic highlighting if you have an alternative way of marking the cell when it’s in focus. For example, you could implement TableCell.onfocus() and onblur() handlers that would change the background image or color of the cell. You can dynamically determine whether or not a cell will be highlighted with the focus rectangle through a TableCell property that matches this attribute. The highlightable attribute for the <table> tag is merely a convenient way to set this behavior for all cells in the table. The settings for individual cells override the <table> setting.

SEE ALSO :

“TableCell Objects” on page 133

Cell Background
SYNOPSIS:

<td background="url" . . .> <th background="url" . . .> The background attribute assigns a background image or color to the cell:
<td background="inback.gif" . . . > <td background="color:#C357A6" . . . >

DESCRIPTION:

It’s similar to the background attribute of the <body> tag and can be used to put TV in the background of a cell:
<td background="tv:" . . . >

122

Content Developer’s Reference

HTML for Dynamic Tables

This attribute goes hand in hand with the standard bgcolor attribute. Both are mapped to properties of the TableCell object and are discussed in greater detail in the section on that object.
SEE ALSO:

“TableCell Objects” on page 133

Animated Text in Cells
SYNOPSIS:

DESCRIPTION:

These five attributes animate text within a cell. The presence of any one of them is sufficient to cause cell text to move; a default value is used for any of the five that isn’t explicitly set. However, if none of the five attributes is set, the text in the cell won’t be animated. Text can be assigned to the cell in HTML or with the TableCell.write() method. It’s limited to a maximum of 4 kilobytes. The behavior attribute says how the text is to move. There are three sanctioned values:
<td behavior="scroll” . . . > <td behavior="slide” . . . > <td behavior="alternate” . . . >

For “scroll”, the cell starts out empty. Text scrolls into view from one side, moves through the cell, and exits on the other side. It then begins over again. For “slide”, the text also begins off to one side. It scrolls into view and stops before the first character can exit the other side. For “alternate”, the text bounces from one side of the cell to the other and back again. The default behavior is “scroll”.

Chapter 4: Dynamic Tables

123

HTML for Dynamic Tables

The direction attribute indicates the direction the text should scroll, slide, or move before its first bounce. It can be either “left” or “right”:
<td behavior="scroll" direction="right" . . .>

The default is “left”. The loop attribute is the number of times the text will scroll past the user, slide into place, or bounce from side to side. It can be set to a specific number or, for continuous animation, to either –1 or “infinite”:
<td behavior="scroll" loop="infinite" . . .> <td behavior="slide" direction="right" loop="20" . . .>

The default loop is “infinite”. The scrollamount attribute is the number of pixels the text should move horizontally each time it’s redrawn and scrolldelay is the number of milliseconds separating one redraw from the next. Together they determine how smoothly and how fast the text moves.
<td behavior="slide" scrollamount="3" scrolldelay="50" . . .>

The default scrollamount is 4 pixels and the default scrolldelay is 66 milliseconds.
AVAILABILITY:

Although they’re now assigned to the <td> tag, these five attributes may, in a future release, also be assigned to an independent HTML tag for tickers and marquees. “TableCell Objects” on page 133

SEE ALSO :

124

Content Developer’s Reference

Table Objects
Overview
Table objects correspond to <table> HTML elements. Each table that’s given a name in HTML, as shown here,
<table name="nameOfTable" . . . >

can be examined and manipulated as a JavaScript Table object with that name. The name identifies a property of the Document object:
var myTable = window.document.nameOfTable;

Tables without names don’t produce Table objects. Along with the HTML extensions described earlier in this chapter, Table objects make tables dynamic. Users can navigate through the table (move the focus rectangle from cell to cell) and select a desired cell. In response, an application can change the look of the cells, scroll cell contents, and initiate other actions. In this scheme, the Table object plays four roles: • It provides access to the table’s cells through each row. The rows are TableRow objects and each cell is a TableCell object. TableCells are the agents that can dynamically modify cells. • It centralizes responses to the user’s actions within the table. A set of event handlers can be defined for the Table; they’re called for actions affecting any cell. A TableCell object doesn’t need (nor can it have) its own event handlers. • It can “batch” changes made by several TableCell objects by temporarily disabling onscreen updates to the table. • It can move the properties and contents of all cells up or down a given number of rows for efficient scrolling. Dynamic tables support EPG grids, lists of mail headers, and various other forms requiring context-sensitive navigation. For the HTML complement of this API, see the “HTML for Dynamic Tables” section on page 119.

Chapter 4: Dynamic Tables

125

Table Objects

Properties
drawingDisabled
SYNOPSIS:

drawingDisabled read/write boolean Enables multiple changes to be made to a table before an update occurs. Setting this property to true prevents on-screen updates to any of the table’s cells; resetting it to false causes an update that reflects all changes made to the cells while drawing was disabled. The default value is false. The scripts you write should explicitly set drawingDisabled to true before making a group of changes to the cells of a table, and explicitly set it to false immediately afterwards. Don’t assume that drawing is automatically disabled or that it will automatically be re-enabled. When a page with a dynamic table is loaded, the table is not displayed until the entire page is parsed and the onload() handler, if there is one, returns. This allows the handler to modify table cells before the user sees them. It’s not necessary for the handler to set drawingDisabled to false before it writes to the cells; however, it’s good programming practice to do so.

DESCRIPTION:

SEE ALSO :

TableCell.write() on page 141

name
SYNOPSIS:

name read-only string The name of the table. This matches the name assigned in HTML. It’s also the name of the property of the Document object for the table. “Table Name” on page 119

DESCRIPTION:

SEE ALSO :

126

Content Developer’s Reference

Table Objects

rows
SYNOPSIS:

rows read-only array of TableRow objects rows.length read-only number

DESCRIPTION:

A list of TableRow objects associated with the table. There’s one object in the array for each row of cells in the table. The TableRows do little except provide access to the cells. For example:
var myFirstCell = document.nameOfTable.rows[0].cells[0];

The length property records the number of TableRow objects in the rows array.
SEE ALSO:

“TableRow Objects” on page 143

Methods
blur() clear()
SYNOPSIS: DESCRIPTION:

see focus()

void clear(void) Sets all cells to empty strings and sets the colSpan of the first cell in each row to a number that’s large enough to ensure that it will be the only cell displayed for that row.

focus(), blur()
SYNOPSIS:

void focus(number row, number column) void blur(number row, number column)

DESCRIPTION:

The first method puts a cell in focus, if it’s focusable; the second removes focus from a cell, if it’s in focus. For both methods, the first argument, row, is a top-tobottom index to the row of the cell; the second, column, is a left-to-right index to the column.

Chapter 4: Dynamic Tables

127

Table Objects

If focus() can put the target cell in focus, it first removes the focus from the cell that currently has it. Calling blur() doesn’t automatically assign focus to another cell. These methods don’t result in an onfocus() or onblur() event handler being called. The handlers are called only to respond to user actions. Therefore, you don’t need to fear recursion when calling either method inside a handler.
SEE ALSO :

onfocus(), onblur()

scrollRows()
SYNOPSIS:

boolean scrollRows(number moveBy [, number firstRow [, number lastRow [, boolean backgroundsStay]]]) Scrolls the table by moving the contents of cells up or down the moveBy number of rows. If moveBy is positive, cell contents migrate downward, vacating rows toward the top of the table. If moveBy is negative, cell contents move upward, vacating rows toward the bottom. The span of rows to scroll is delimited by the firstRow and lastRow arguments; they pick rows the same way as indexes to the Table.rows property do. The default firstRow is the top row of the table and the default lastRow is the bottom row. Currently, this method assumes the default values in all cases; it ignores these two arguments and always scrolls all the rows. By default, all dynamic properties of a cell—that is, all properties that can be set by a TableCell object—move with the cell contents. Therefore, if the word “Fire!” is displayed in red against a black background in a focusable cell that spans three columns, it will be displayed in red against a black background in a focusable cell spanning three columns after scrollRows() moves it to another row. However, if the optional backgroundsStay argument is true, background images and colors are exempt; they don’t scroll. The word “Fire!” would appear against the background of whatever cell it is moved to. The default value is false, meaning that backgrounds scroll along with the rest of the cell contents. This method can perform vertical scrolling operations much more efficiently than is possible by modifying the cells individually. It returns true if it can scroll the table, and false if it fails. In the normal course of operation, it should always return true.

DESCRIPTION:

128

Content Developer’s Reference

Table Objects

This method imposes two constraints on how the table is set up: • You must set the dynamicCols attribute of the <table> tag to specify the actual number of columns in the table. Without this information, scrollRows() will fail with undefined results. • You should set up the initial contents of the table dynamically, in an onload() handler, rather than in HTML. This method can scroll cell contents that are dynamically written (with TableCell.write()) and attributes that are dynamically set (with TableCell properties like fgColor and colSpan), but it cannot scroll any static contents or attributes specified with the <th> and <td> tags. When cells are scrolled upward, some at the bottom of the table are vacated— they don’t have their contents replaced by those of other cells. Similarly, when cells are scrolled downward, some at the top of the table are vacated. This method places an empty string in all vacated cells. However, those cells retain all their previous properties—background, focusability, column span, foreground color, and so on. At minimum, you’ll need to call TableCell.write() to fill the empty cells with the appropriate content. You may also need to modify other cell properties. For example, if the scrolled cells have varying column spans, you’ll have to adjust the column placement of some cells. Currently, scrollRows() touches every cell in the table. Therefore, table headings that you don’t want scrolled should not be part of a dynamic table. Use a separate <table> definition for the heading. If a cell in the table is in focus, scrollRows() will move the focus with the contents of the cell. If the cell contents are scrolled out of the table, scrollRows() will put the focus on another, nearby cell. It’s best to call Table.blur() to remove the focus from the table before scrolling, then call Table.focus() to reinstate it where desired when scrolling is finished.
HISTORY:

The optional firstRow, lastRow, and backgroundFixed arguments were added in the 1.2.5 release. TableCell.write() on page 141

SEE ALSO:

Chapter 4: Dynamic Tables

129

Table Objects

Event Handlers
onnavigate(), onfocus(), onblur(), onclick()
SYNOPSIS:

boolean onnavigate(number row, number column, string direction) read/write handler void onfocus(number row, number column) read/write handler void onblur(number row, number column) read/write handler void onclick(number row, number column) read/write handler

DESCRIPTION:

These event handlers respond to the user’s actions within the table. onnavigate() is called once if the user attempts to move the focus rectangle in any direction from the cell that currently is in focus. It can prevent the focus from changing by returning false. If the focus does change, onblur() is called for the cell that loses focus and onfocus() for the cell that gains it. onclick() is called when the user presses a key to invoke the cell that’s currently in focus. Each of these handlers is passed indexes to the row and column of the affected cell. Indexes begin at 0 and count rows from top to bottom, and columns from left to right. In addition, onnavigate() is passed a string that identifies the direction in which the focus will move. The direction can be “up”, “down”, “left”, “right”, “pageUp”, or “pageDown”. For example, if column specifies the rightmost cell in a row and direction is “right”, onnavigate() might scroll the contents of the table and return false so the focus will stay on the same cell. If you define these handlers as strings in HTML, you can refer to the row, column, and direction parameters in your definition. Variables with these names are within the scope of the handler. For example, this version of onblur refers to row and column:
<table . . . onblur="doBlur(row, column);" . . . >

130

Content Developer’s Reference

Table Objects

In this case, the doBlur() call would become the body of the onblur() handler, which would be passed the row and column arguments, as follows:
function onblur(row, column) { doBlur(row, column); }

If you define any of these handlers in JavaScript, the code must be on the same page as the HTML <table> definition.
SEE ALSO:

“Table Event Handlers” on page 121

Chapter 4: Dynamic Tables

131

Table Objects

132

Content Developer’s Reference

TableCell Objects
Overview
TableCells correspond to <td> and <th> HTML elements and are accessed only through the cells array of a TableRow object:
var aCell = document.nameOfTable.rows[index].cells[anotherIndex];

There is no constructor. A TableCell object is able to modify the layout of the cell and change its content. Each change updates the on-screen display. Since you would normally modify more than one cell at a time—and make more than one modification to each cell—it’s a good idea to disable drawing in the table (with the Table.drawingDisabled property) until all the changes have been made. It’s also a good idea, if any cells span more than one column, to lay out a simple, mostly empty table in HTML with cells just one column wide, and then modify the cells using JavaScript in an onload() handler for the same page. The table won’t be displayed until the JavaScript is executed, so viewers won’t see the simple grid you started with. This technique simplifies the task of the graphics engine that lays out the table and therefore improves performance. Most TableCell properties correspond—in name and value—to attributes of the <td> and <th> tags. Their initial values are the values set in HTML.

Properties
align, valign
SYNOPSIS:

align read/write string valign read/write string

DESCRIPTION:

The horizontal and vertical alignment of text in the cell: • align can be “left” for text aligned at the left edge of the cell, “right” for text aligned at the right edge, or “center” for text centered between the two edges.

Chapter 4: Dynamic Tables

133

TableCell Objects

• valign can be “top”, “middle”, “bottom”, or “baseline”. For some browsers, “baseline” ensures that text written to the cell will line up with text written to other cells in the row even if the cells have different font sizes. TV Navigator ensures that text written to the cell always lines up with text written to other cells in the row with the same valign value, no matter what that value is. These properties correspond to the align and valign attributes of <td> and <th> HTML tags.

background, bgColor
SYNOPSIS:

background read/write string bgColor read/write string

DESCRIPTION:

These properties correspond to the background and bgcolor attributes of <td> and <th> tags. They’re analogous to identically named attributes of the <body> tag. The background property places a background image in the cell. The image is identified by its URL:
myCell.background="art/something.gif"; myCell.background="tv:";

If the image is television (a tv: URL), TV Navigator scales it to the dimensions of the cell—or, if the platform can scale TV only to certain sizes, to the largest scalable size that will fit within the cell. However, it doesn’t scale other types of images; it tiles or crops them, as necessary, to fit the cell. It’s most efficient to design background images that exactly fit the cell—and design tables to fit on the TV screen so that the cells won’t be automatically resized—rather than rely on TV Navigator cropping or tiling them. The bgColor property specifies a background color for the cell. It can be “transparent”,
myCell.bgColor="transparent";

another color name,
myCell.bgColor="cyan";

134

Content Developer’s Reference

TableCell Objects

or a hexadecimal representation of an RGB color:
myCell.bgColor="#EF90A2";

However, only a limited number of color names are understood dynamically. For example, although “darkcyan” would produce the desired background color when set in HTML,
<td bgcolor="darkcyan" . . .> // OK

it fails when assigned in JavaScript:
myCell.bgColor="darkcyan"; // won’t work

Therefore, it’s almost always advisable to set a color using the hexadecimal notation (it would be “#008B8B” for “darkcyan”). If both a background and a bgColor are set, the background color is drawn in the cell before the image is rendered. The color will show through any transparent portions of the background image. TV Navigator also allows the background property (or HTML attribute) to be set with a color: URL. It names a background color, just like bgColor does, rather than an image:
myCell.background="color:transparent"; myCell.background="color:cyan"; myCell.background="color:#EF90A2";

This syntax makes it relatively simple to switch from a background image to a background color. However, background colors set in this way belong to the background attribute, not bgColor. Since the background attribute can have only one value at a time (either an image or a color, but not both), a color: URL cannot set a color that will be drawn before a background image. For example, this sequence of assignments,
theCell = document.myTable.rows[2].cells[0]; theCell.bgColor="green"; theCell.background="color:cyan"; theCell.background="art/something.gif";

yields the something.gif image against a green background, not cyan. If the platform doesn’t support full 24-bit colors, the color value that’s read from background or bgColor may not exactly match the value that’s set. The value you assign will be translated to the closest color value available on the platform.

Chapter 4: Dynamic Tables

135

TableCell Objects

behavior, direction, loop, scrollAmount, scrollDelay
SYNOPSIS:

behavior read/write string direction read/write string loop read/write number write-only string scrollAmount read/write number scrollDelay read/write number

DESCRIPTION:

These five properties correspond to similarly named attributes of the <td> tag. If the HTML that sets up the cell mentions any of those attributes, text in the cell is animated (like a ticker or marquee) and all these properties of the TableCell object are defined. The properties initially have the values set in HTML, including default values for attributes not explicitly mentioned. Modifying the properties will modify the behavior of the animated text. To change the text itself, call the write() method. However, if the HTML that sets up the cell doesn’t mention any of the corresponding attributes, these TableCell properties are undefined and inoperative. Setting them will have no affect on the cell. You can’t set up an animated cell from JavaScript; it can only be done in HTML. See the discussion of the attributes earlier in this chapter for information on permitted values for these TableCell properties. The properties mirror their HTML counterparts. When set in HTML, the loop attribute records the number of times the text will loop through the animation. When read in JavaScript, the loop property reports the number of loops yet to be executed; it counts down to 0 over time (if a finite number of loops were set). Setting this property resets the counter. The new value determines the number of loops that should be executed in the future; it doesn’t count those that have already been performed.

136

Content Developer’s Reference

TableCell Objects

For continuous looping, loop can be set to –1 or to “infinite”. For either setting, it returns –1 when read; this value does not decrement over time.
SEE ALSO:

write(), “Animated Text in Cells” on page 123, “TableRow Objects” on page 143

bgColor colSpan
SYNOPSIS:

see background

colSpan read/write number The number of columns the cell occupies. This property corresponds to the colspan attribute of <td> and <th> HTML elements. It must be a positive integer (greater than 0). The findColsNeeded() method can calculate how many columns the cell must span to display the string you want to write.

DESCRIPTION:

SEE ALSO:

write(), findColsNeeded()

direction see behavior elisionString
SYNOPSIS:

elisionString read/write string The string that the write() method should append to the text it places in the cell when it cannot fit all the text it is requested to write. By default, the string is a single character, the ellipsis character (…) from the ISO 8859–1 (Latin 1) character set. For convenience, so that you don’t have to remember that \x85 is the JavaScript escape sequence for this character, null is used to indicate the default.

DESCRIPTION:

Chapter 4: Dynamic Tables

137

TableCell Objects

This property gives you the freedom to set your own elision marker. For example, you could put a space before the ellipsis character:
theCell = document.myTable.rows[2].cells[1]; theCell.elisionString = " \x85";

Or you could set it to the canonical form of ellipsis, which separates the dots with spaces,
theCell.elisionString = ". . .";

for a total of five characters. To instruct write() not to append an elision marker, set it to the empty string:
theCell.elisionString = "";

Setting it to null restores the default, the single-character ellipsis:
theCell.elisionString = null;
HISTORY: SEE ALSO :

Introduced in the 1.2 release. write()

fgColor
SYNOPSIS:

fgColor read/write string The color for drawing text in the cell. This property matches the color attribute of the <font> tag. It can be set either as a color name or as a hexadecimal representation of an RGB color. For example:
myCell.fgColor="maroon"; myCell.fgColor="#800000";

DESCRIPTION:

However, for reasons of efficiency, dynamic tables understand only a limited set of color names. Therefore, it’s better to set this property with a hexadecimal string. If the platform doesn’t support full 24-bit colors, the color value that’s read from fgColor may not exactly match the value that’s set. It will be the supported value that most closely matches the value that was assigned. Setting this property won’t change the color of the static text specified for the cell (the text assigned in HTML with the <td> and <th> tags). It affects only text

138

Content Developer’s Reference

TableCell Objects

that was dynamically assigned (with the write() and Table.scrollRows() methods).
SEE ALSO:

bgColor

focusable
SYNOPSIS:

focusable read/write boolean Whether users can navigate to and focus on the cell—true if they can and false if not. This property corresponds to the HTML attribute of the same name. “Focusable Cells” on page 121

DESCRIPTION:

SEE ALSO:

highlightable
SYNOPSIS:

highlightable read/write boolean Whether or not the cell should be highlighted with the gold focus rectangle when it’s the focus for user input—true if it should, and false if not. This property corresponds to the HTML attribute of the same name. If highlightable is false, the onfocus() and onblur() handlers should be implemented to mark the cell in some other way when it obtains the focus, and to remove the marking when it loses the focus.

DESCRIPTION:

HISTORY: SEE ALSO:

Introduced in the 1.2 release. “Highlighting the Cell in Focus” on page 122

loop

see behavior see behavior

scrollAmount scrollDelay valign

see behavior

see align

Chapter 4: Dynamic Tables

139

TableCell Objects

wrappingEnabled
SYNOPSIS:

wrappingEnabled read/write boolean Whether or not write() is permitted to wrap the text it places in the cell to more than one line—true if it is, and false if not. The initial setting of this property depends on the HTML that set up cell. If the nowrap attribute was specified, wrappingEnabled will be false; otherwise, it will be true. One version of the write() method takes an argument that can override the wrappingEnabled setting. However, that version will be deprecated in a future release. If possible, use this property and the simpler version of write() instead. Introduced in the 1.2 release. write()

DESCRIPTION:

VARIATIONS:

HISTORY: SEE ALSO :

Methods
findColsNeeded()
SYNOPSIS: DESCRIPTION:

number findColsNeeded(string text) Returns the minimum colSpan required for the cell to display all of the text string, or null if even the maximum possible colSpan wouldn’t provide enough room to accommodate the complete string.
span = myCell.findColsNeeded(someString); if ( span != null ) { myCell.colSpan = span; myCell.write(someString); }

The value returned depends on the layout of the table, the sizes of the cells, and the current wrappingEnabled setting. It’s not necessarily valid for any other cell in the table.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. colSpan, findFit(), wrappingEnabled

140

Content Developer’s Reference

TableCell Objects

findFit()
SYNOPSIS: DESCRIPTION:

number findFit(string text) Returns how many characters of the text string will fit in the cell, given the cell’s current column span and size and the current wrappingEnabled setting. If the full string will not fit within the cell, this method allows space for the elision string. However, it does not count the elision characters in the return value. If none of the text characters fit, it returns 0. findFit() uses the same algorithm for calculating fit as the write() method. Both methods try to break lines and truncate strings at spaces and other natural word boundaries. If the text is broken at a space, the space is not counted in the number that findFit() returns. If you intend to display the rest of the text in another cell or elsewhere, you will need to skip over the initial white space at the beginning of the remaining string.

HISTORY: SEE ALSO:

Introduced in the 1.2 release. write(), findColsNeeded(), elisionString, wrappingEnabled

read()
SYNOPSIS: DESCRIPTION:

string read(void) Returns the text string that’s currently displayed in the cell. This method can return only text strings that write() or TableCell.scrollRows() have placed in the cell; it currently cannot read the static contents of the cell specified in HTML. It returns null if the cell’s text has not been dynamically written.

SEE ALSO:

write(), Table.scrollRows() on page 128

write()
SYNOPSIS:

void write(string text) void write(boolean wrap, string text) Displays the text string in the cell. The wrap argument indicates whether the string can wrap to more than one line of text—true if write() is free to split the

DESCRIPTION:

Chapter 4: Dynamic Tables

141

TableCell Objects

text between lines, and false if it should write only one line. If the wrap argument is absent, the wrappingEnabled property determines whether the text can wrap. (Whether or not the text actually wraps also depends on the height of the cell and the length of the string relative to the width of the cell.) If the entire text string doesn’t fit within the cell, it is truncated and the characters specified by the elisionString property are appended to those that are written. write() tries to break lines and truncate text on natural word boundaries, like spaces. However, if necessary, it will break or truncate on any character. The text string must be pure text; HTML tags and character entities within the string are not interpreted; they’re displayed literally. However, the string can contain JavaScript escape sequences, including conventional sequences (such as \t for a tab and \" for a double quote) and octal and hexadecimal character codes. For example, an inverted question mark (¿) can be coded \277 or \xBF and a multiplication sign (×) is \327 or \xD7. A line break can be specified as \r (carriage return) or \n (newline). Both specifications work alike and are retained in the string that read() returns. If the text cannot wrap, no characters are displayed beyond the first line break in the text string, even though the cell may have plenty of room.
HISTORY:

The version of write() that takes a single argument was introduced in the 1.2 release. The version that takes two arguments will eventually be deprecated. read(), wrappingEnabled, elisionString, Table.scrollRows() on page 128

SEE ALSO :

142

Content Developer’s Reference

TableRow Objects
Overview
TableRow objects correspond to <tr> HTML elements. They’re accessed only through the rows array of a Table object:
var aRow = document.nameOfTable.rows[index];

There is no constructor. A TableRow object has just one purpose: to provide access, through its cells property, to the cells in the row. For example:
var aCell = document.nameOfTable.rows[index].cells[anotherIndex];

Properties
cells
SYNOPSIS:

cells read-only array of TableCell objects cells.length read-only number

DESCRIPTION:

An array of TableCell objects for the row. Cells are indexed from left to right. If any cells span more than one column, some TableCell objects at the end of the array may not correspond to a visible cell on-screen. The length property reports the number of TableCell objects in the array. That number in the array is fixed when the table is set up in HTML. It’s the number of <td> and <th> elements in the row, or the number specified by the dynamicCols attribute of the <table> tag, whichever is greater.

SEE ALSO:

“TableCell Objects” on page 143, “Minimum Number of Cells” on page 120

Chapter 4: Dynamic Tables

143

TableRow Objects

144

Content Developer’s Reference

The Network

CHAPTERM

The Navigator array has two properties—cache and net—that relate directly to network activity. Navigator.cache provides a handle on the cache of downloaded data. At present, all this object can do is remove data from the cache—either to force the browser to download a fresh copy from its source or to simply reclaim the memory. Navigator.net represents the network itself. It currently plays three roles: • It oversees TV Navigator’s connection to the Internet. It has properties that reveal the state of the connection and a method that can make sure a connection is established. • It has a handler that reports on the progress of network activity. The handler lets applications keep users apprised of the status of their network requests. However, the handler is called only if progress reports were requested when Window.open() was called to open the window that initiated the request. • It has constructors for four objects—NetRequest, NetSession, NetMsgSession, and NetEvent—that applications can use to interact with the network, apart from any interactions the user might initiate from HTML. These objects are vehicles for uploading and downloading data over the Internet. Downloaded data is simply passed to an event handler (and possibly cached). It’s not automatically presented to the user.

Requests and Sessions
NetRequest, NetSession, and NetMsgSession objects offer applications three different ways of interacting with the network. • NetRequest objects are designed for request-response transactions, where a single request is followed by one or more responses. They’re used to request particular items of data identified by their URLs. HTTP requests are the most typical example of this type of interaction. Currently, HTTP and its secure counterpart, HTTPS, are the only protocols that NetRequests support.

Chapter 5: The Network

145

NetEvent Objects

• NetSession objects are designed for more lengthy interchanges, where data may be sent or received repeatedly over a period of time. A URL identifies the particular connection that the session should establish. In the current release, NetSessions are used only to receive broadcast data identified by mcast: URLs. For this purpose, the object doesn’t need to connect to a server or send any data. In future releases, it may support protocols that permit data to be sent as well as received. • NetMsgSession objects use Liberate’s messaging architecture to send and receive messages. All messages are mediated by a dedicated Liberate server, which handles all the messaging mechanics. Unlike NetRequests and NetSessions, a NetMsgSession isn’t bound to a particular URL. It first establishes a session with the messaging server. Then, during the session, it can send messages to any number of destinations and receive messages from multiple sources. This object is designed especially for interactive applications—such as games, chat, mail, instant messaging, and so on. Requests and sessions are not tied to the user interface. Received data may be cached, but it is not automatically displayed. By the same token, network activity initiated by the user (such as following a link or submitting a form) doesn’t produce NetRequest, NetSession, or NetMsgSession objects.

NetEvent Objects
NetEvent objects are the containers that hold the data that’s received by NetRequests and both sent and received by NetMsgSession and NetSession objects. When data is received, TV Navigator calls an event handler—onload() for a NetRequest and onreceive() for NetSession and NetMsgSession—and passes it a NetEvent object with the data. To send data, you construct a NetEvent object, initialize it, and pass it to a send() method. A NetEvent lets you look at the data either as text or as binary data (an array of bytes). It separates out any headers that accompany the body of the message and presents them as an array of strings. For NetRequest objects (but not for NetSessions or NetMsgSessions), NetEvent objects are also passed to the handlers that report events that occur during the request, such as errors and cancellations.

146

Content Developer’s Reference

Cache Object
Overview
The Cache object represents the cache where fetched data is temporarily stored on the set-top box. It’s a read-only object in the navigator array:
var theCache = navigator["cache"];

Currently, this object has just one method, remove(), which removes data from the cache before it normally would be freed. More cache-management functionality may be added in future releases.

Methods
remove()
SYNOPSIS:

void remove(void) void remove(string url) Makes downloaded data inaccessible and marks it for removal from the cache. If this method is called without any arguments, all the data in the cache is marked for removal. If it’s passed the URL of a particular piece of cached data, only that piece will be removed. The data will be deleted as soon as all those who currently refer to it no longer do so. In the meantime, no further references are allowed; if the URL happens to be used again, the data will be fetched from its source, not from the cache. You don’t need to call this function to remove data from the cache. It will be removed automatically in due course. However, if you fetched some data and then did something to modify it at its source on the server, you may want to call remove() to get rid of the cached copy so that any further references to the data will get the updated version—especially if you don’t know when the cached copy is set to expire. This method deals only with the client cache; it cannot remove data cached on a proxy server.

DESCRIPTION:

Chapter 5: The Network

147

Cache Object

HISTORY:

The version of this method that takes no arguments was introduced in the 1.2.5 release. NetRequest.cache on page 177

SEE ALSO :

148

Content Developer’s Reference

Headers Array
Overview
NetRequest, NetSession, and NetEvent objects all have a headers property, an array of strings. The strings hold headers that are relevant to the request, session, or event. Headers are most commonly associated with the HTTP protocol, but the array can be used with other protocols as well. Each header string is name-value pair in the following format,
name: value

where the colon (:) is obligatory, but the space following it is not. To simplify the task of searching through the array, each headers array object has a getValue() method that returns the value portion of a header string when passed the name portion.

Properties
length
SYNOPSIS:

length read-only number The number of strings in the array. The default length for the headers arrays of all constructed NetRequest, NetSession, and NetEvent objects is 0.

DESCRIPTION:

Methods
getValue()
SYNOPSIS: DESCRIPTION:

string getValue(string name) Parses the headers array and returns the value associated with the name keyword passed as an argument, or null if name doesn’t match the name

Chapter 5: The Network

149

Headers Array

portion of any header string (the portion of the string up to, but not including, the colon). For example:
var language = theEvent.headers.getValue("Content-Language"); if ( language ) . . .

This method ignores case when comparing the argument name to the name portion of a header string—uppercase letters match their lowercase equivalents and lowercase letters match their uppercase equivalents. HTTP header names are not case-sensitive. An empty string is a valid value, but not a valid name. This method works identically for the headers properties of NetEvent, NetRequest, and NetSession objects.
SEE ALSO :

NetEvent.headers on page 161, NetRequest.headers on page 178, NetSession.headers on page 187

150

Content Developer’s Reference

Net Object
Overview
The Net object represents the Internet connection, much as a TvTuner object represents a connection to the television broadcast system. It currently can be used to test the connection, discover the data rate, receive progress reports on network activity, request data from sites on the net, and establish sessions for sending and receiving data. This object has no HTML counterpart and no constructor. It’s a read-only property of the Navigator array:
var theNet = navigator["net"];

Properties
connected
SYNOPSIS:

connected read-only boolean Whether or not a two-way connection to the Internet is open—true if it is, and false if not. Cable and satellite systems always have a one-way Internet connection, since Web content is embedded in the broadcast signal. This property ignores that connection and reports only whether a two-way connection that would allow you to request data for an arbitrary URL is in place.

DESCRIPTION:

SEE ALSO:

ensureConnection()

Methods
ensureConnection()
SYNOPSIS: DESCRIPTION:

boolean ensureConnection(void) Makes sure that a two-way connection to the Internet is in place. If it is, this function returns true. If not, it tries to establish a connection and return true. If it can’t connect, it returns false.

Chapter 5: The Network

151

Net Object

This function is concerned with more or less unrestricted access to the Internet. It therefore doesn’t regard a one-way connection—such as Web content contained in the broadcast stream—as sufficient reason to return true. On some hardware and for some modem connections, this function could block for a considerable amount of time.
SEE ALSO :

connected

NetEvent()
SYNOPSIS: DESCRIPTION:

void NetEvent(void) Constructs a NetEvent object that can be passed to NetSession.send(). All properties of the object are set to meaningless values; it must be initialized before it can be used. “NetEvent Objects” on page 157

SEE ALSO :

NetRequest(), NetSession(), NetMsgSession()
SYNOPSIS:

void NetRequest(void) void NetSession(void) void NetMsgSession(void)

DESCRIPTION:

These functions construct NetRequest, NetSession, and NetMsgSession objects. Except for some boolean properties, the new objects are not initialized with meaningful values. In general, all string properties are empty (“”), all arrays have a length of 0, and all handlers are undefined. (However, see the individual objects for details.) See the chapter introduction for guidelines on when to use one of these objects versus another.

SEE ALSO :

“Requests and Sessions” on page 145 in the chapter introduction, “NetRequest Objects” on page 175, “NetSession Objects” on page 185, “NetMsgSession Objects” on page 165

152

Content Developer’s Reference

Net Object

Event Handlers
onprogress()
SYNOPSIS:

void onprogress(string state, object target, string targetType, object topWindow) exclusive-read/exclusive-write handler Called when there’s network activity on behalf of a window that asked for progress reports when it was created (by setting the progressReported feature when Window.open() was called). This handler lets services notify (and reassure) the user when an operation is taking a noticeable amount of time. It has no other purpose. (The Service Manager defines the onprogress() handler, but it lets individual services register their own functions that onprogress() will call.) Progress is reported for network activity initiated in HTML or JavaScript anywhere within the window—any link, image or frame source, handler, and so on—except for: • NetRequest and NetSession objects. These objects have their own handlers. • JavaScript entities (&{...};). • JavaScript URLs (javascript:...). • Other fetches that don’t relate directly to a user action—for example, downloading a font. Four arguments are passed to onprogress() when it’s called: state A string that reports the stage of the network activity—”started”, “loading”, or “done”. The handler is called once with a “started” state when a request is sent to the network and once with a “done” state when all the requested data has arrived (or the fetch is cancelled). In between, it may or may not be called with a “loading” state. It depends on how long the activity takes. If the fetch takes some time, multiple “loading” calls may occur. However, if the fetch is completed quickly, “loading” calls are skipped; only “started” and “done” are reported. If the fetch includes a series of subfetches—for example, a page that loads documents into frames, with each document loading a number of images, and so on—the entire series is taken together. A single “started” state and “done” state is reported for the group.

DESCRIPTION:

Chapter 5: The Network

153

Net Object

Similarly, if a <meta> refresh occurs during a fetch, or a timer goes off, or an impatient user follows a link before everything is loaded, a new “started” state won’t be reported. In essence, the new fetch is appended to the original one. Eventually, a single “done” state will be reported for everything. target The JavaScript object that’s most concerned with the fetch. When the state argument is “started”, the target is the Window object or Image object that’s the destination of the fetch. When state is “loading”, it’s the target of the particular data that’s being loaded at the time—perhaps a Window object for an embedded subframe or an Image object for an image in a fetched document. It can be a different object for each “loading” call. When state is “done”, target is the initial destination of the fetch—the same as the target for the “started” state (unless the last fetch overlapped previous fetches and didn’t get its own “started” call). The target object is read-only. You can use it to get information about the target, such as the identity of a window (from its name property) or the URL of the fetched data (from the location.href of a Window object or the src property of an Image). However, you should not attempt to set any of the object’s properties or call any of its methods. targetType A string that names the type of the target object—currently, just “window” or “image”. topWindow The Window object corresponding to the topmost window where the network activity was initiated. This is the window that asked for progress reports when it was created (by Window.open()) and the window that directly or indirectly contains the target object. This handler enables applications to display progress indicators for a fetch. However, because it indiscriminately reports all kinds of network activity, some discretion is required. One way to exercise discretion is to set a timer for a short period of time, say a half second or so, when the “started” state is reported, and do nothing if “done” occurs before the timer expires. This should eliminate minor activity from consideration, including image roll-overs (simple image substitutions by handlers like onclick() and onmouseover() that track the focus on-screen).

154

Content Developer’s Reference

Net Object

Because onprogress() is called for most network activity, and called repeatedly, it can consume an unexpected amount of time. To reduce the overhead and improve performance, avoid setting the handler until you know you need it— until you might need to provide progress notifications to the user. If onprogress() is undefined (as it is by default), it won’t be called. Similarly, if there are periods when you don’t need the handler, reset it to null,
navigator.net.onprogress = null;

then set it again when it’s again needed. It’s more work for the JavaScript interpreter to repeatedly call the handler and have it decide to do nothing each time, than to set and reset the onprogress property.
VARIATIONS: ACCESS: HISTORY:

The set of arguments passed to this handler may be modified in a future release. Reserved for pages from the Service Manager’s domain. Originally, the information that’s now passed to this handler was made available as a set of variables with fixed names. The variables were removed and recast as arguments in the 1.2.3 release. the progressReported feature for Window.open() on page 108

SEE ALSO:

Chapter 5: The Network

155

Net Object

156

Content Developer’s Reference

NetEvent Objects
Overview
NetEvent objects package data transmitted over the network and report the ongoing progress of network activity. They work both with requests (NetRequest objects) and with sessions (NetSession and NetMsgSession objects): • After a NetRequest object initiates a fetch, NetEvents with information about the fetch are passed to its onstart(), onerror(), oncancel(), and onload() handlers. The object passed to onload() carries the fetched data. • A NetEvent object is passed to the NetMsgSession and NetSession onreceive() handlers to report data received during the session. To send data during a session, you can construct a NetEvent object, initialize it, and pass it to the object’s send() method. (Currently, NetSession objects are used only to receive broadcast data, so the NetSession.send() method is temporarily inoperative. Use a NetMsgSession object to send messages.) The NetEvent objects that are passed to event handlers have read-only properties. However, you can set the properties of the objects you construct.

Received NetEvents
The NetEvent objects that are arguments to event handlers convey data to the NetRequest, NetSession, or NetMsgSession. The also convey information about the data and the event. For example, a NetRequest.onload() handler might check on the type of data being downloaded as follows:
function doLoad(event) { if ( event.contentType == "audio/x-wav" ) { . . . } else . . . } var myRequest = new navigator.net.NetRequest(); myRequest.onload = doLoad;

Here, event refers to the NetEvent object that bundles the response to the request and is in the scope of the onload() handler; contentType is a property of the NetEvent object. Note that for

Chapter 5: The Network

157

NetEvent Objects

the function that’s defined in this example to become an onload() handler, it had to be assigned to the onload property of a NetRequest object. When the handler exits, the NetEvent object becomes inaccessible and will soon be destroyed—unless a more permanent reference to it is saved. Thus, you can save downloaded data simply by saving the NetEvent object; you don’t need to explicitly copy data from the object. For example:
var lastEvent: function doLoad(event) { lastEvent = event; . . . }

Constructed NetEvents
NetEvent objects are constructed for only one purpose—to hold data that will be transmitted during a session. After constructing the object, you need to initialize it with the data you want to send and with any desired information about the data, such as its size and MIME media type. You would then pass the NetEvent to NetMsgSession.send() (or, in a future release, to NetSession.send()). It’s generally a good idea to get rid of all references to the object after send() returns, so that it can be garbage-collected. For example:
var info = new navigator.net.NetEvent(); if ( info != null ) { info.contentType = "text/plain"; info.textData = theMessage; . . . if ( theSession.send(info) == true ) . . . info = null; }

Two Views of the Data
The data that a NetEvent holds can be viewed either as a string (through the textData property) or as an array of bytes (through the binaryData property). These two properties look at the same data, but look at it differently. For example, it would be possible to construct a NetEvent, set textData, and then replace the data through binaryData. It’s most efficient to treat the data as a string. However, strings are terminated at the first null byte. The binaryData property permits a NetEvent to hold data with valid null bytes.

158

Content Developer’s Reference

NetEvent Objects

Constructor
NetEvent()
SYNOPSIS: DESCRIPTION:

void navigator.net.NetEvent(void) Initializes a new NetEvent object by setting all its properties to null or empty values. Unlike NetEvents that the system creates, those you construct have properties you can set. You must provide meaningful values before passing the object to a send() method. “Constructed NetEvents” in the “Overview” section

SEE ALSO:

Properties
binaryData
SYNOPSIS:

binaryData for constructed objects, a read/write array of numbers for received objects, a read-only array of numbers binaryData.length read-only number

DESCRIPTION:

The data that was received through the network or the body of a message that NetMsgSession.send() will send—treated as binary data (an array of bytes). Use this property in place of textData if the data can include null values (other than the null terminator for a string). binaryData is valid for constructed NetEvent objects and for the objects passed to NetSession and NetMsgSession event handlers. However, for a NetRequest object, it’s valid only for the object passed to the onload() handler. Downloaded data is not available when the other NetRequest event handlers are called. For a constructed object, the default value is a 0-length array. However, the binaryData property can be set only by assigning a new array; you cannot modify the current one. Operations like the following will fail:
constructedNetEvent.binaryData[4] = 0x8E; constructedNetEvent.binaryData.length = 9; // won’t work // don’t try it

Chapter 5: The Network

159

NetEvent Objects

Use the Array constructor to build a new array and assign it to the property. For example:
constructedNetEvent.binaryData = new Array(0xE3, 0x8E, 0x38, 0xE3, 0x8E, 0x38, 0xE3, 0x8E, 0x38);

Note that each element in the array is an 8-bit number—a byte. If values greater than 0xFF are assigned, only the least significant byte will be retained. The length property reports the number of bytes in the binaryData array.
SEE ALSO :

textData

contentType
SYNOPSIS:

contentType for constructed objects, a read/write string for received objects, a read-only string The MIME media type of the data—for example, “text/html”, “image/gif”, or “audio/x-pn-realaudio”. For NetEvent objects passed to a NetRequest or NetSession event handler, this information is taken from the return header, if the server provides it—as it generally will for HTTP requests. If the media type isn’t reported, contentType is null. For a NetEvent passed to a NetMsgSession object, this property is undefined. Servers are known to misreport data types on occasion, whether because the data source provides erroneous information or because they try to guess the type and guess wrong. For constructed NetEvent objects, the default value of this property is an empty string (“”). If you want it set, you must set it explicitly; it’s not automatically filled in as a consequence of setting the headers array.

DESCRIPTION:

160

Content Developer’s Reference

NetEvent Objects

headers
SYNOPSIS:

headers for constructed objects, a read/write array of strings for received objects, a read-only array of strings headers.length read-only number string headers.getValue(string name)

DESCRIPTION:

Header information arranged as an array of name-value pairs. The array has the same structure as the NetRequest and NetSession headers arrays. The name is separated from the value by a colon and possibly some white space:
"name: value"

The array takes numerical indexes only. By default for a newly constructed NetEvent, the array is empty (its length is 0), but ready to use. You can simply initialize it; you don’t need to call the Array constructor. For example:
var theMsg = new navigator.net.NetEvent(); if ( theMsg != null ) { theMsg.headers[0] = "my_name: S. Narasimhan"; theMsg.headers[1] = "my_job: doctor"; . . . }

Although HTTP is the classic example of a protocol that makes extensive use of headers, this property may be used for any protocol. It’s valid for constructed NetEvent objects, for NetEvents passed to NetSession and NetMsgSession event handlers, and for NetEvents within the scope of a NetRequest’s onstart() and onload() handlers. However, it may not be valid for the NetRequest oncancel() and onerror() handlers. To make it simpler to get the value of a known header, the headers object includes a getValue() method that returns just the value portion of the namevalue string when passed the name portion.
SEE ALSO:

contentType, “Headers Array” on page 149, NetRequest.headers on page 178, NetSession.headers on page 187

Chapter 5: The Network

161

NetEvent Objects

textData
SYNOPSIS:

textData for constructed objects, a read/write string for received objects, a read-only string The data that was received through the network or the body of a message that NetMsgSession.send() will send. This property treats the data as if it were true text; it terminates the string at the first null byte it encounters. Therefore, if the data can include valid null values, you should look at it through the binaryData array instead of textData. textData is valid for constructed NetEvent objects and for the objects passed to NetSession and NetMsgSession event handlers. However, for a NetRequest object, it’s valid only for the object passed to the onload() handler. Downloaded data is not available when the other NetRequest event handlers are called.

DESCRIPTION:

SEE ALSO :

binaryData

type
SYNOPSIS:

type read-only string The name of the handler that has dominion over the NetEvent object— “onstart”, “onerror”, “oncancel”, or “onload” for an object delivered to a NetRequest handler, “onreceive” for an object delivered to a NetSession. The NetMsgSession object doesn’t use or set this property. For constructed NetEvent objects, this property is an empty string.

DESCRIPTION:

url
SYNOPSIS:

url for constructed objects, a read/write string for received objects, a read-only string

DESCRIPTION:

The URL of the data. This may be different than the URL used to make a request (NetRequest.url) and almost certainly will be different than the URL that sets up a session (NetSession.url). Each piece of data that’s received from a broadcast

162

Content Developer’s Reference

NetEvent Objects

(mcast:) stream has its own URL. This property is not used by NetMsgSession objects. For a constructed object, the default value is an empty string.
SEE ALSO:

NetRequest.url on page 181, NetSession.url on page 187

Chapter 5: The Network

163

NetEvent Objects

164

Content Developer’s Reference

NetMsgSession Objects
Overview
A NetMsgSession object sends and receives data using Liberate’s messaging architecture. All communications are mediated by a specialized Liberate server that acts as a gateway to other servers and clients.

The Messaging System
In simplified form, the messaging model looks something like this:
client application set-top box client application set-top box client application

client application

set-top box

Liberate’s messaging server

application server

As this diagram indicates, all messages pass through the messaging server. There’s no limit on the number of concurrent connections the server can maintain (other than the limitations imposed by available memory and processing power). Each potential message sender and receiver (whether client or server) introduces itself to the messaging server. The introduction begins a session with the server. During the session, messages are transmitted using a private protocol that hides the details from the sender and receiver. Servers use Liberate’s messaging library to send and receive messages. Client applications use NetMsgSession objects.

Chapter 5: The Network

165

NetMsgSession Objects

A deployment would typically have a group of messaging servers, as the following modification of the earlier diagram illustrates. Each set-top box has a connection to one of the servers. All the sessions running on a particular box are layered on top of that single connection.
client application set-top box client application set-top box client application

client application

set-top box

messaging server

messaging library application server

The messaging library enables an application server to communicate with any messaging server in the group and, through the group, with any targeted client.

Using a NetMsgSession
The nodes in this system—the application servers and client applications—are identified by three pieces of information: • An application ID. All participants in an application (the server and the applications on settop boxes) share the same ID. • A node ID. This ID identifies a node within an application. It’s unique among all nodes with the same application ID. • A node type—either “client” or “server”. Typically, an application running on the set-top box will be a “client”. But not always. Imagine, for example, a game that a small number of users on different set-top boxes can play together. When a user initiates a game and

166

Content Developer’s Reference

NetMsgSession Objects

advertises for other players to join, the application server for the game may download the game engine to that user’s machine. While the game is being played, that machine acts as the game server for the other users. Typically, an application on the set-top box will get these three pieces of information from the application server or other source using an independent channel (typically an HTTP request). It then constructs a NetMsgSession object and calls register() to inform the messaging server of its presence. The registration process initiates a session and produces a fourth identifier, a session ID, that’s valid until the session ends. After it has registered, the NetMsgSession object is ready to send and receive messages, using the messaging server as the middleman. NetEvent objects serve as message containers. A message is sent by constructing a NetEvent, initializing it, and passing it to the send() method. The message is addressed using the same four identifiers mentioned earlier—the destination’s application ID, node ID, node type, and session ID. Messages are received by an onreceive() event handler that’s called each time a message arrives. The handler is passed a NetEvent object containing the message and the address of the sender—the source application ID, node ID, node type, and session ID. To efficiently send a series of messages to the same destination, the NetMsgSession object can first attach itself to the destination using the attach() method. This method ensures that the destination receives messages in the same order they were sent. Because it informs the messaging server of the intended destination, it makes sending subsequent messages to that destination simpler. Only the message has to be passed to send(), not the address.

Asynchronous Methods
All NetMsgSession methods communicate with the messaging server and operate asynchronously. If they can prepare a communication for the server, they return true without waiting for it to be dispatched or for the server’s reply. If something goes wrong after the method returns, the onerror() event handler is called to report the error. If a method fails before initiating communication with the server, it returns false. In this case, the onerror() handler is not called.

NetEvent Objects
The messaging system uses NetEvent objects only as message containers. It ignores all the properties of the object except for textData and binaryData (the body of the message) and the headers array of name-value pairs. Only those three properties are defined for a NetEvent passed to the onreceive() handler. If you set any other properties of a NetEvent you pass to the send() method, that information will be missing when the message is delivered.

Chapter 5: The Network

167

NetMsgSession Objects

The messaging system wraps message data in an envelope that insulates it from the messaging mechanism. None of the properties of the NetEvent you pass to the send() method influence how the message is sent. Nothing in the NetEvent passed to the onreceive() event handler reports anything about the event itself.

Constructor
NetMsgSession()
SYNOPSIS: DESCRIPTION:

void navigator.net.NetMsgSession(void)

1.3

Initializes a new NetMsgSession object by setting all its string properties to an empty string (“”) and the sessionId property to 0, which indicates that the object has not yet been registered. Its properties will be set when register() is called. Like all constructors, it’s used with the new operator. For example:
var theSession = new navigator.net.NetMsgSession();

HISTORY: SEE ALSO :

Introduced in the 1.3 release. register()

Properties
appId, nodeId, nodeType
SYNOPSIS:

1.3 appId read-only string 1.3 nodeId read-only string 1.3 nodeType read-only string

DESCRIPTION:

Strings that identify the NetMsgSession object to the messaging server. All three properties are set when the register() method is called to register the object and begin a session. The appId identifies the application that the session is part of. The nodeId identifies the NetMsgSession object within the application. The nodeType is

168

Content Developer’s Reference

NetMsgSession Objects

either “client” or “server”, depending on the role that the node plays within the application. Before register() is called the first time, each of these properties is an empty string.
HISTORY: SEE ALSO:

Introduced in the 1.3 release. register(), “Using a NetMsgSession” in the “Overview” section

nodeId

see appId see appId

nodeType sessionId
SYNOPSIS:

1.3 sessionId read-only number

DESCRIPTION:

An identifier assigned when the NetMsgSession is registered. It’s specific to the NetMsgSession object and the particular session that the registration initiated. The identifier is likely to be different each time register() is called. Its value is 0 if the object is not currently registered (if a session is not in progress). Introduced in the 1.3 release. register()

HISTORY: SEE ALSO:

Methods
attach(), detach()
SYNOPSIS:

boolean attach(string destinationAppId, string destinationNodeId, string destinationNodeType, number destinationSessionId [, string options]) boolean detach(void)
1.3

1.3

DESCRIPTION:

These methods attach the session to a specific destination and detach it again. While the session is attached, a simple form of the send() method can efficiently dispatch any number of messages to the same destination.

Chapter 5: The Network

169

NetMsgSession Objects

Attaching to a destination has two benefits: • It ensures that all messages sent to the specified destination are delivered in the same order in which they’re sent. • It reduces the bandwidth required to send a message, since information about the intended destination doesn’t have to accompany each message. The destination is identified by the same four kinds of information that identify any messaging node: an application ID (destinationAppId), a node ID (destinationNodeId), a node type (destinationNodeType), and a session ID (destinationSessionId). The options argument is a string containing a list of comma-separated namevalue pairs that instruct the messaging server. Currently, there are no valid options for the attach() method. This argument is a placeholder that anticipates options to be added in future releases. The detach() method reverses the action of a previous attach() call. It detaches the session from the current destination without replacing it with another one. However, it’s not necessary to call detach() before calling attach() a second time. Each attach() call replaces the current destination with a new one. These methods return true if successful, and false if they fail. They return false, for example, if they’re called before register() or the arguments are not wellformed. Because these methods are asynchronous, it’s possible that they might return true but still fail to accomplish what they set out to do. In that case, the onerror() handler is invoked to report the error.
HISTORY: SEE ALSO :

Introduced in the 1.3 release. send()

detach()

see attach()

boolean register(string appId, string nodeId, string nodeType) boolean unregister(void)
1.3

1.3

DESCRIPTION:

These methods register the NetMsgSession object with the messaging server and cancel a previous registration. A session begins when the object is

170

Content Developer’s Reference

NetMsgSession Objects

registered and ends when the registration is canceled or the connection to the messaging server is dropped. A NetMsgSession must be registered before it can send or receive messages. The register() method informs the messaging server of the presence of the NetMsgSession object and sets the appId, nodeId, and nodeType properties with the values passed as arguments. In addition, if the registration is successful, it sets the sessionId with a session-specific value. The unregister() method withdraws the object’s registration and resets the sessionId to 0. It’s possible to register and reregister a NetMsgSession any number of times, possibly with a different application ID, node ID, and node type each time. However, each registration must be explicitly canceled by calling unregister() before calling register() again. These methods return true if they succeed, and false if they fail. register() fails, for example, if it’s called during a session (before unregister() is called to cancel the current session). Because these methods are asynchronous, it’s possible for them to return true but still fail to register or unregister the NetMsgSession. In the case of a failure to cancel the current registration, the onerror() handler will be called to report the error. However, onerror() is not called for a registration failure; this handler reports errors only during a session.
HISTORY: SEE ALSO:

Introduced in the 1.3 release. sessionId

send()
SYNOPSIS:

boolean send(object netEvent [, string destinationAppId, string destinationNodeId, string destinationNodeType, number destinationSessionId] 1.3 [, string options]) Sends the message encapsulated in the NetEvent object passed as the first argument, netEvent. This method can either specify a specific destination for the message—by its application ID (destinationAppId), node ID (destinationNodeId), node type (destinationNodeType), and session ID (destinationSessionId)—or it can omit these

DESCRIPTION:

Chapter 5: The Network

171

NetMsgSession Objects

arguments and rely on a destination previously set with the attach() method. If a destination is specified, it takes precedence over the attached destination, but only for the message being sent. If a destination is not specified and the NetMsgSession is not attached to a destination, send() fails. If you intend to send a series of messages to the same destination and want to guarantee the order in which the messages arrive, you must attach to that destination before sending any of the messages. If you specify the destination in the send() calls, the order can’t be guaranteed. The options argument is a list of comma-separated name-value pairs that govern how the message is treated. In the current release, only one option is recognized:
"secondsToLive=integer"

The integer is the number of seconds the message remains valid after the messaging server receives it. The server destroys the message when the time period expires. This method returns true if it can initiate the message, and false if not. It returns false, for example, if the first argument is not a NetEvent object, if a destination is neither specified nor attached, or if the options string does not hold valid options. If the message fails after send() returns true, the onerror() handler is called to report the failure.
AVAILABILITY:

Currently, messages can be sent only to the opposite node type: A “client” can send to a “server” and a “server” to a “client”, but a “client” can’t send to another “client” nor a “server” to another “server”. Introduced in the 1.3 release. attach(), onerror()

HISTORY: SEE ALSO :

unregister()

see register()

172

Content Developer’s Reference

NetMsgSession Objects

Event Handlers
onerror()
SYNOPSIS: DESCRIPTION:

void onerror(object netEvent, number errorCode, string errorString)

1.3

Called when there’s a failure after any NetMsgSession method (except register()) returns true. If the failure occurs while sending a message, the netEvent argument is an exact copy of the NetEvent object passed to send(). Otherwise, netEvent is null. Introduced in the 1.3 release. register(), attach(), send()

HISTORY: SEE ALSO:

onreceive()
SYNOPSIS:

void onreceive(object netEvent, string sourceAppId, string sourceNodeId, string sourceNodeType, number sourceSessionId)

1.3

DESCRIPTION:

Called when a message arrives. The netEvent argument is the NetEvent object that holds the message. Only its textData, binaryData, and headers properties are valid. The remaining arguments identify the source of the message by its application ID (sourceAppId), node ID (sourceNodeId), node type (sourceNodeType), and session ID (sourceSessionId).

HISTORY:

Introduced in the 1.3 release.

Chapter 5: The Network

173

NetMsgSession Objects

174

Content Developer’s Reference

NetRequest Objects
Overview
NetRequest objects set up asynchronous, point-to-point transactions over the network and listen to broadcast (mcast:) streams. They provide a mechanism for applications to request and transmit data independent of any HTML element or any particular aspect of the user interface. Currently, HTTP and HTTPS are the only protocols that can be used for the request. Multipart requests are supported. NetRequests are completely under the application’s control. They’re not automatically created as a consequence of user actions, and the requested data is not automatically rendered when it arrives. A NetRequest is not used, for example, to load a new document when the user follows a link. In other words, the NetRequest mechanism is an elemental system. Received data can be cached, but nothing else follows automatically from making a request. It’s up to you what you do with the fetched data. Therefore, NetRequests can be used for remote procedure calls (RPCs) for any purpose.

Preparing the Object
NetRequests don’t correspond to HTML elements and the system doesn’t create any by default. The constructor is a method of the Net object:
var myRequest = new navigator.net.NetRequest();

The constructor doesn’t assign many meaningful values to the new object. You must initialize it after construction with two types of information: • Data needed to set up the network request—minimally a URL. • A set of handlers that can be executed to report progress in the request. The handlers respond to errors, accept or refuse incoming data, take possession of the data, and clean up after the fetch.

Initiating the Request
When the object is ready, the request is initiated by calling fetch():
if ( myRequest.fetch() ) . . .

Chapter 5: The Network

175

NetRequest Objects

fetch() returns after setting up the request; it doesn’t wait for a response. All futher information about the fetch, including downloaded data, is received through the handlers. A NetRequest object can be used just once, for only one fetch. When all data for the request has arrived, or the request is otherwise terminated, the object should be dereferenced so that it can be destroyed:
myRequest = null;

This is typically done inside the ondone() handler; ondone() is called when the fetch is finished.

Server Constraints
NetRequest objects depend on the server delivering a set standard HTTP headers in the response. Because the required headers are the ones that servers customarily return, this generally does not pose a problem.

Constructor
NetRequest()
SYNOPSIS: DESCRIPTION:

void navigator.net.NetRequest(void) Initializes a new NetRequest object by giving a few of its properties meaningful values but setting most of them to null or empty strings. Before it can be used, the new object must, at minimum, be assigned a URL and be given a set of event handlers. The constructor leaves the event handlers undefined. After constructing a NetRequest object and initializing it, you make the request by calling the fetch() method:
var theRequest = new navigator.net.NetRequest(); if ( theRequest != null ) { . . . theRequest.fetch(); }

It’s important to save a reference to the new object to prevent it from being destroyed (garbage collected) before the fetch it inaugurates is complete and

176

Content Developer’s Reference

NetRequest Objects

the handlers are called. For example, the previous example could be elaborated as follows:
var theRequest; function setUpTheRequest() { theRequest = new navigator.net.NetRequest(); if (theRequest != null ) . . . }

Note that placing the var declaration inside the function would give it a very short and inadequate life; it would last only until the function exited.
SEE ALSO:

url

Properties
cache
SYNOPSIS:

cache read/write boolean Determines whether fetched data should be placed in the cache. The default value is true, meaning that the data will be cached. If this property is reset after fetch() is called, the new value won’t affect the treatment of any data packages that have already started arriving. This property affects only the cache on the client machine, not the cache on a proxy server.

DESCRIPTION:

SEE ALSO:

“Cache Object” on page 147

direct
SYNOPSIS:

direct read/write boolean Determines whether or not the request should be sent directly to its destination, bypassing (or tunneling through) all proxy servers—true if it should, and false if not. The default value is false.

DESCRIPTION:

Chapter 5: The Network

177

NetRequest Objects

Direct requests are typically required only for secure (HTTPS) transactions. Ordinarily, a secure request would go first to the Liberate Transcode Security server, which would decrypt it to find out what its destination is and what to do with it. A direct request avoids this step. The request is instead “tunneled” through another designated proxy; the proxy does not look at the request, but simply passes it untouched to its destination. This is accomplished using a protocol that sets up the tunnel before sending the request. For direct requests that are not secure, the url property must be an IP address, not a host name. Currently, bypassing a proxy entirely means that a domain name service is not available.

headers
SYNOPSIS:

headers read/write array of strings headers.length read-only number string headers.getValue(string name)

DESCRIPTION:

An array of strings, where each string is a name-value pair. The name is separated from the value by a colon:
"name: value"

Typically, one or more white space characters follow the colon, as shown above, but the space is not mandatory. If the protocol set in the url property is http: or https:, these name-value pairs are passed in the request as HTTP headers. If another protocol is used (not a current possibility), they’re handled according to that protocol. This property is the same kind of array as the headers properties defined for NetSession and NetRequest objects. It takes only numerical indexes and is empty by default. To help you search through the array of strings, headers has a getValue() method that returns the value portion of a header string when passed the name portion.

178

Content Developer’s Reference

NetRequest Objects

The default length of the headers array is 0.
SEE ALSO:

“Headers Array” on page 149, NetEvent.headers on page 161, NetSession.headers on page 187

post
SYNOPSIS:

post read/write boolean Determines the method used to make an HTTP request. If this property is true, the POST method is used. If false, the GET method is used. The default value is false (GET). In either case, the value is ignored if the protocol specified in the url property isn’t http: or https:.

DESCRIPTION:

SEE ALSO:

postData

postData
SYNOPSIS:

postData read/write string read-only array of numbers postData.length read-only number void postData.set(arg1 [, arg2 [, . . . [ argN]]]) string postData.toString(void)
1.3 1.3

DESCRIPTION:

The data that should be passed in the body of the HTTP request message when the POST method is used. (The body of the request is empty for the GET method.) This property is ignored unless the url property specifies the HTTP protocol (http: or https:) and the post property is true. postData is an object that holds the data assigned to it as an array of bytes. It can be set in either of two ways: • As a string,
myRequest.postData = "birthdate=6%2F8%2F1979&birthplace=Washington,+DC";

Chapter 5: The Network

179

NetRequest Objects

• Using the set() method:
myRequest.postData.set(. . .);

This method takes one to many arguments and concatenates them into the byte array. The arguments can be strings, numbers, or binary data, in any combination. For example:
myRequest.postData.set("birthdate", 0x3D, "6%2F8%2F1979", 0x26, "birthplace", 0x3D, "Washington,+DC");

Only the least significant byte of a number argument is set; passing 0xFF7A as an argument would have the same result as passing 0x7A. Binary data is obtained either from a NetEvent object or from the object returned by TvTuner.captureStill(), which captures the television picture as a still image. In both cases, the binary data is taken from a property appropriately named binaryData. For example:
theTuner.frozen = true; var thePicture = theTuner.captureStill("", 92); theTuner.frozen = false; if ( thePicture ) { myRequest.postData.set("prologue", thePicture.binaryData, "epilogue"); . . . }

Each time set() is called, it resets the entire array. Any data that was previously set is thrown away. It’s not possible to set particular values in the array; all the data must be specified at the same time. For example, this code will fail:
myRequest.postData[5] = 0x7F; // error

However, it is possible to get the length of the array,
var numBytes = myRequest.postData.length;

and read it byte-by-byte:
var value; for ( i = 0; i < numBytes; i++ ) value = myRequest.postData[i]; . . . }

180

Content Developer’s Reference

NetRequest Objects

You can also read the array as a string:
var theData = "The data is: " + myRequest.postData + ".";

However, since null bytes terminate strings, the string will end with the first null byte in the data—that is, the first null byte that was passed to the set() method as a number or in binary data (when merging the data, set() drops the null bytes that terminate string arguments). No matter how postData is set, you must describe it in strings assigned to the headers property. For example, these two strings,
"content-type: application/x-www-form-urlencoded" "content-length: 48"

would describe the date and place shown in one of the examples above:
"birthdate=6%2F8%2F1979&birthplace=Washington,+DC"

For binary data (including combinations of binary data and strings), the headers would need to provide a description that the receiving servers will understand. The content-length header can typically be set from the length property:
"content-length: " + myRequest.postData.length
HISTORY: SEE ALSO:

The set() and toString() methods were added in the 1.3 release. headers, url, TvTuner.captureStill() on page 276

url
SYNOPSIS:

url read/write string The URL for the request. The URL must be absolute—that is, it must be complete, beginning with a protocol name. Currently, the only permitted protocols are http: and https:. A multipart HTTP request can receive a number of different data items in response. Each package of data that’s received is reported as a separate NetEvent object. The url must be set before fetch() is called; it’s undefined by default.

DESCRIPTION:

SEE ALSO:

NetEvent.url on page 162

Chapter 5: The Network

181

NetRequest Objects

Methods
cancel()
SYNOPSIS: DESCRIPTION:

void cancel(void) Terminates the entire request. cancel() is taken as a hint; it’s ignored if it’s more trouble to abort the request than to finish getting the data. If cancel() is called after data has started to arrive, and if the hint is heeded, the request will terminate and the oncancel() handler will be invoked. However, the handler is not invoked if the request is cancelled before a response is received. If called before fetch(), cancel() has no effect.

SEE ALSO :

fetch(), oncancel()

fetch()
SYNOPSIS: DESCRIPTION:

boolean fetch(void) Initiates a fetch as instructed by the properties of the object—url, headers, cache, post, and postData. If it successfully sets up the network request, fetch() returns true. If not, it returns false. The request is asynchronous; fetch() returns immediately after initiating it. The response to the request is reported through event handlers, like onstart() and onload(). fetch() can be called only once for each NetRequest object.

SEE ALSO :

onstart()

182

Content Developer’s Reference

NetRequest Objects

Event Handlers
onstart(), onerror(), oncancel(), onload(), ondone()
SYNOPSIS:

boolean onstart(object event) read/write handler void onerror(object event) read/write handler void oncancel(object event) read/write handler void onload(object event) read/write handler void ondone(void) read/write handler

DESCRIPTION:

These handlers are invoked to report progress during a fetch. ondone() After fetch() is called, it’s guaranteed that at least one handler, ondone(), will be invoked. It signals the end of the fetch, no matter what the reason. It’s an appropriate place to dereference the NetRequest object so it can be garbage collected, as shown in the following example:
var myRequest = new navigator.net.NetRequest(); function onDone() { . . . myRequest = null; } myRequest.ondone = onDone;

After ondone(), no other handlers will be executed. onstart() and onload() If fetching a single data type, onstart() is executed when the first bit of data is received for the fetch (including the initial line of the response and possibly some headers); onload() is invoked when all the data has arrived. If making a multipart HTTP request or fetching broadcast (mcast:) data, onstart() and onload() are each invoked once for each logical bundle in the fetched data (each image, HTML page, MPEG frame, etc.).

Chapter 5: The Network

183

NetRequest Objects

If onstart() returns false, it cancels the fetch for that particular data package—and oncancel() will be called instead of onload(). If onstart() returns true, the fetch goes forward. Once onstart() has been invoked, it’s guaranteed that there will be a matching invocation of onload() or oncancel()—or, possibly, onerror(). If the data arrives quickly, onload() may be executed without a prior invocation of onstart(). oncancel() The oncancel() handler signals that the entire request has been canceled (cancel() was called) or that a particular data item was canceled (onstart() returned false). If cancel() is called before onstart() is executed, the oncancel() handler is not invoked; only ondone() is. onerror() The onerror() handler reports that the request has been terminated because of an error, or that there was an error loading a particular data item. It’s not invoked for global broadcast (mcast:) errors, since broadcast is presumed to be lossy. A NetEvent object, event, is passed to the onstart(), oncancel(), and onload() handlers to provide information about the current state of the fetch and to identify the data item being loaded or canceled. However, the fields of the object that return fetched data are valid only for onload(). A NetEvent with empty data fields is also passed to the onerror() handler if it’s executed after onstart(); if the error occurs before onstart(), the event argument will be null. The NetEvent object follows the normal rules for JavaScript objects—its data won’t be destroyed and it won’t be garbage-collected until the handler exits and there are no lingering references to the object. In other words, you can save the data simply by saving a reference to the object (there’s no need to copy the data from the object). Within a handler, this refers to the NetRequest object, not the NetEvent. All handlers are undefined by default.
SEE ALSO :

“NetEvent Objects” on page 157

184

Content Developer’s Reference

NetSession Objects
Overview
A NetSession object sets up an encounter during which data may be repeatedly sent and received over the network. Data is received without being explicitly requested (other than by the start of the session). Currently, NetSessions are used for just one purpose: listening to broadcast (mcast:) streams. In future releases, it may support protocols that allow data to be sent as well as received, but, for now, it only receives. Its send() method is dormant. There are no ready-made NetSessions; they don’t correspond to HTML elements and are not produced as a by-product of user actions or any other process. To set up a session, you have to construct a NetSession object. The constructor is a method of the Net object:
var theSession = new navigator.net.NetSession();

A newly constructed NetSession doesn’t have meaningful values. At minimum, it must be assigned a URL:
theSession.url = "mcast://provider/carousel_a";

It must also be assigned a set of event handlers that can receive data, respond to errors, and take any necessary action when the session begins and ends. (In addition, if the protocol requires header information to start the session, the headers would also have to be set. Headers are not required to start an mcast: session.) When the object is ready, you can begin the session by calling start(),
if ( theSession.start() == true ) . . .

and later end it by calling stop():
if ( theSession.stop() == true ) . . .

An onstart() handler reports when the session has started and onstop() announces when it has ended. Before onstop(), two other handlers may be called any number of times. The onreceive() handler is invoked to receive data and onerror() to report errors. Data is received as NetEvent objects.

Chapter 5: The Network

185

NetSession Objects

Constructor
NetSession()
SYNOPSIS: DESCRIPTION:

void navigator.net.NetSession(void) Sets up a NetSession object by initializing the headers property to an empty array, but leaving the url property and all event handlers undefined. The handlers and a valid URL must be set before calling start(). Only a limited number of NetSessions can be supported at a time. The exact number may vary from deployment to deployment, but it is not large. If the maximum number of NetSession objects already exist, this constructor will refuse to initialize another one and the new operator will return null:
var theSession; function makeSession() { theSession = new navigator.net.NetSession(); if ( theSession == null ) // it failed else // go ahead }

After constructing a NetSession object and initializing it, you establish the session by calling the start() method:
fucntion makeSession() { theSession = new navigator.net.NetSession(); if ( theSession != null ) { theSession.url = "mcast://. . ."; . . . if ( theSession.start() ) . . . } }

It’s important to keep a reference to the new object so that it won’t be garbagecollected before the session ends. However, when the session ends, you should get rid of the reference; NetSession objects cannot be reused.
SEE ALSO :

url, headers

186

Content Developer’s Reference

NetSession Objects

Properties
headers
SYNOPSIS:

headers read/write array of strings headers.length read-only number string headers.getValue(string name)

DESCRIPTION:

An array of strings with information needed to establish the session. The specific headers that are permitted or required depend on the protocol. Because setting up a session to get broadcast data (the mcast: protocol) doesn’t involve any contact with a server, the headers are currently ignored. The headers array is empty by default (its length is 0).

SEE ALSO:

“Headers Array” on page 149, NetEvent.headers on page 161, NetRequest.headers on page 178

url
SYNOPSIS:

url read/write string The URL of the data you want to receive. This property must be set before start() is called. Currently, only mcast: URLs are supported. This property is undefined by default.

DESCRIPTION:

SEE ALSO:

NetRequest.url on page 181, NetEvent.url on page 162

Methods
send()
SYNOPSIS: DESCRIPTION:

boolean send(object event) Sends the message encoded in the event NetEvent object.

Chapter 5: The Network

187

NetSession Objects

Because the mcast: protocol doesn’t permit messages to be sent, this method is currently unused. If called, it fails and returns false.
SEE ALSO :

“NetEvent Objects” on page 157

start()
SYNOPSIS: DESCRIPTION:

boolean start(void) Begins the session using the information recorded in the url property (and, if the protocol requires or supports it, the headers property). This method works asynchronously; it returns without waiting for an indication that the session was successfully established. If all goes well, it returns true and the onstart() handler is called when the session is in place. If the session can’t be established, onerror() is called instead of onstart(). Under any of the following conditions, start() returns false and neither handler is called: • The session has already started. • You’re attempting to restart a session that was stopped. A NetSession object can be used for only one session. • The url property is not set or not well-formed. • Header information required by the protocol isn’t specified. (The mcast: protocol requires no header information to start a session.)

SEE ALSO :

onstart()

stop()
SYNOPSIS: DESCRIPTION:

boolean stop(void) Terminates the session. This method almost always returns true and is followed by an onstop() call to indicate that the session has been shut down. However, if you call it before calling start(), or call it more than once on the same NetSession, it returns false and the onstop() handler is not invoked.

188

Content Developer’s Reference

NetSession Objects

This method is the only way to end a session gracefully; you must call it when a fatal error occurs.
SEE ALSO:

onstop()

Event Handlers
onstart(), onreceive(), onerror(), onstop()
SYNOPSIS:

void onstart(void) read/write handler void onreceive(object event) read/write handler void onerror(number errorCode) read/write handler void onstop(void) read/write handler

DESCRIPTION:

These handlers are invoked when data arrives, errors occur, and the session begins and ends. onstart() Called to mark the successful start of the session after the start() method returns true. onreceive() Called whenever data is received. The event argument is a NetEvent object that contains the data and describes it. This handler may be invoked numerous times during the session. For broadcast data, onreceive() is called once for each object in the data carousel. The headers array of the NetEvent holds whatever headers the server sent, which for the Mediacast server may be both application-defined namevalue pairs and standard HTTP directives.

Chapter 5: The Network

189

NetSession Objects

onerror() Called whenever an error occurs. The errorCode argument indicates the nature of the error. Currently, four codes are used, as outlined in the following table:

Code
1 2 3 4

Meaning
The session was aborted. This error may occur at any time during the session. The server is busy and won’t accept the connection. This error occurs only while start() is setting up the session. There was a critical error reading data. This error can occur at any time. There was a critical error writing data. This error also may occur at any time.

All four errors are fatal; they cripple the NetSession object. In response, you should call stop() to gracefully exit from the session, then get rid of the object in the ensuing onstop() handler, as discussed below. It’s important to call stop() for all errors, even those that occur as the session is being set up (before the onstart() handler is called). When the error notification is received, the session will have progressed far enough for it to require explicit termination. onstop() Called to mark the end of the session. No other handlers will be called after this one. It’s a good place to remove all references to the NetSession object so that it can be deleted. For example:
var theSession = new navigator.net.NetSession(); function onStop() { theSession = null; } theSession.onstop = onStop;

A NetSession object cannot be reused. To restart a session, you must construct a new object.
SEE ALSO :

start(), stop()

190

Content Developer’s Reference

TV Information and Control

CHAPTERM

This chapter is concerned with television input to the set-top box and, in particular, with the objects that supply information about channels and programs and enable you to control them. (Earlier, Chapter 2, “TV Display,” discussed output from the set-top box to the TV set.) TvTuner objects are the central entry points for all television information and control. They reside in the Navigator.tvTuners array:
var firstTuner = Navigator.tvTuners[0];

At least one object in the array represents a tunable source of broadcast television—received through cable, satellite, or antennae. Some objects in the array may represent other potential sources of television input—even if the source is not, strictly speaking, a television tuner. For example, depending on the circumstances, S-video, composite video, and SCART input ports on the set-top box could each be represented by separate TvTuner objects. Or those ports could be represented as channels associated with the primary tuner. A TvTuner contains other objects with more specialized roles. It has: • An array of TvChannel objects that describe the available channels on the tuner. The TvTuner can find particular channels and select the channel that should be displayed. • A TvInfo object that can search for program information. Programs are described by TvProgram objects. • A ConditionalAccess object that allows premium channels and pay-per-view programs to be purchased online. • An ETv object that provides an interface for handling Web content that enhances, and is 1.3 timed to correspond with, television content. • A MusicText object that can get information about the music playing on an audio-only channel.

Chapter 6: TV Information and Control

191

TV Information and Control

All these objects, and other objects that support them, are described in this chapter. Begin with “TvTuners Array” on page 283 and “TvTuner Objects” on page 269.

192

Content Developer’s Reference

ConditionalAccess Object
Overview
The ConditionalAccess object provides a programming interface for purchasing pay-per-view programs and premium channels online—that is, an interface to the conditional-access system on the set-top-box. This system is able to grant or deny access to programs and channels within its purview—notably programs and channels the user must pay to see, but possibly others as well. The accessControlled property of TvProgram and TvChannel objects indicates whether the program or channel is subject to conditional access. The ConditionalAccess object is a controlled and read-only property of a TvTuner object:
var ca = navigator.tvTuners["primary"].access;

If the ConditionalAccess object is undefined, it means one of two things: • The set-top box doesn’t have conditional-access capabilities (or the software doesn’t support them). • The JavaScript interface to the conditional-access system is implemented as an extension (through the TV Extender kit), and the extension defines some other JavaScript object rather than this one. The extension will be listed in the Navigator.extensions array, but you’ll have to contact the service provider for information on the API it exports. The ConditionalAccess object, when it’s defined, may have deployment-specific properties and methods in addition to those documented here.

Properties
credit
SYNOPSIS:

credit controlled-read-only string The amount of credit that users have available for buying pay-per-view programs and premium channels, presented as a string that can be displayed on-screen. The credit figure is specific to the set-top box, not to any particular user. Controlled by the principal ACL.

DESCRIPTION:

ACCESS:

Chapter 6: TV Information and Control

193

ConditionalAccess Object

Methods
cancelPurchase()
SYNOPSIS: DESCRIPTION:

controlled boolean cancelPurchase(number purchaseId) Cancels a previous online purchase, essentially reversing what the purchase() method did. The purchase being cancelled is identified by the purchaseId number that purchase() returned. Cancellation may not be possible if too much time has passed since the purchase. If it’s successful in cancelling the purchase, cancelPurchase() returns true. If not, it returns false.

ACCESS: SEE ALSO :

Controlled by the writing sublist of the principal ACL. purchase()

changePin(), checkPin()
SYNOPSIS:

controlled boolean changePin(number which, string oldPin, string newPin) controlled boolean checkPin(number which, string pin)

DESCRIPTION:

These methods set a personal identification number (PIN) and check whether the number passed as an argument matches the PIN previously set. The first argument to both methods, which, determines which PIN is being changed or checked. For example, a conditional-access system might require one PIN to make purchases of one class of programs, another PIN to purchase another class, and a third to exercise parental control over the programs that others can view. PIN categories are determined by the service provider. changePin() fails and returns false if the oldPin string it’s passed doesn’t match the PIN currently in force or if there’s another reason why it can’t change the PIN. It returns true if it succeeds in installing the newPin string as the PIN for the which category. checkPin() returns true if the pin string it’s passed exactly matches the current PIN, and false if not.

ACCESS: HISTORY:

Regulated by the writing sublist of the principal ACL. Introduced in release 1.2.6.

194

Content Developer’s Reference

ConditionalAccess Object

getInfo()
SYNOPSIS: DESCRIPTION:

controlled object getInfo(object programOrChannel) Returns an object containing information about a program or channel that’s under the purview of the conditional-access system—typically a pay-per-view program or a premium channel. The structure of the returned object may vary from deployment to deployment, depending on the details of the conditional-access system. Generally, it should have at least the following two properties: price A read-only string that presents the price of the program or channel in a form that can be displayed to users. The sting omits a local currency symbol, but otherwise is appropriately formatted for the locale (with the right number of digits, the correct placement of decimal points and commas, and so on). purchased A read-only boolean that indicates whether the program or channel can be shown unscrambled on the set-top box—true if it can, or false if not. Other properties might indicate the expiration of the purchase, eligibility criteria, access restrictions, and so on. Consult the service provider for deployment-specific details. The returned object captures the status of the program or channel at the time getInfo() is called; it does not reflect subsequent changes. For example, if a program is purchased after you got information about it, the purchased property of the object that this method returned will not change from false to true. To get updated information about the program, you must call getInfo() again. The argument, programOrChannel, should be a TvProgram or TvChannel object that’s subject to access control; its accessControlled property should be true. The TvProgram object must be one that you obtain from a TvChannel, TvInfo, or TvInfoIndex object, not one you construct. If the argument does not meet these criteria, getInfo() returns null.

ACCESS:

Controlled by the reading sublist of the principal ACL.

Chapter 6: TV Information and Control

195

ConditionalAccess Object

HISTORY: SEE ALSO :

Introduced in the 1.2 release. TvChannel.accessControlled on page 223, TvProgram.accessControlled on page 258

purchase()
SYNOPSIS: DESCRIPTION:

controlled number purchase(object programOrChannel) Purchases the pay-per-view program or premium channel identified by the programOrChannel argument. The argument must be a TvProgram or TvChannel object representing a program or channel subject to conditional access. The conditional-access system associates the purchase with the set-top box, not with any particular user of the box. If it fails for any reason, purchase() returns 0. If it succeeds, it returns an integer (other than 0) that uniquely identifies the purchase. The returned purchase identifier can be passed to cancelPurchase() to undo what purchase() has done.

ACCESS: SEE ALSO :

Controlled by the writing sublist of the principal ACL. “TvChannel Objects” on page 221 and “TvProgram Objects” on page 255

Event Handlers
onalarm(), oncommand()
SYNOPSIS:

void onalarm(string message) controlled-read/controlled-write handler void oncommand(string message) controlled-read/controlled-write handler

DESCRIPTION:

Called when something happens in the conditional-access system that requires the attention of the user. onalarm() is called to report an alarm and oncommand() to report a command: • Alarms occur because of something the user is doing (or has failed to do). For example, the conditional-access system might generate one because the current user isn’t authorized to watch the program being purchased, or because it doesn’t detect the smart card necessary for a transaction in the

196

Content Developer’s Reference

ConditionalAccess Object

smart-card reader. Similarly, an alarm might give the user a phone number to call to complete a purchase, or mention other information that should be shared with the user. It’s up to the application that presents a user interface to the conditionalaccess system to define an onalarm() handler that will pass these notifications to the user. • Commands are concerned with the state of the conditional-access system and generally require some corrective action. They originate in messages from the server to the client—for example, a direction to clear the master password, or a notice that a new version of the application is available and can be loaded. Not all oncommand() calls necessarily involve the user. The application can handle some on its own (such as, clearing the master password). However, some require the user to be notified—for example, if a purchased program was dropped from the schedule. Each handler takes a message argument that carries the content of the alarm or command. Messages may vary from platform to platform. The ConditionalAccess object doesn’t provide a way for the conditional-access system to get a response from the user. If a response is needed, a platformspecific Indicator object with a writable value can be used. Some platforms may not define one or both of these handlers. It depends on the conditional-access system for that platform.
ACCESS:

Reading is regulated by the principal ACL; writing is controlled by both the principal and the minor ACLs. “Indicator Objects” on page 301

SEE ALSO:

Chapter 6: TV Information and Control

197

ConditionalAccess Object

198

Content Developer’s Reference

ETv Object
Overview
The ETv object (for “enhanced TV”) manages the notifications that coordinate Web content with television programs. For example, suppose that at some point during a program on furniture making, a certain kind of tool is demonstrated. The program producer not only wants to inform viewers about a Web page where they can get more information about the tool, but also give them a link that lets them jump immediately to that page. The page might have a tv: image in one corner so that viewers can continue to see the same show, although on a smaller canvas, while the rest of the screen has details about the tool and how to buy it. The link must be presented to the user at the right time—when the program discusses the tool. To take another example, suppose that a game show lets viewers play along with the show’s contestants. When viewers tune to the show, they’re presented with a link to a Web page. Part of the page displays the TV image and part is an interactive area where users can respond to the same questions being asked on the show. That area is updated each time the contestant is asked a new question. The notifications that make it possible to coordinate Web and television content in this way are called triggers. Triggers are delivered to the set-top box at the same time as the television content they’re associated with. Each trigger contains a few essential pieces of information— such as the channel it’s associated with, some text to display to viewers, the URL of the page viewers can go to, and an expiration date and time. Upon receiving the trigger, a service in the master application places a panel on-screen with information gleaned from the trigger, including the text and the link. If the user doesn’t select the link, the panel disappears after a moment or two. If the user follows the link and the page is loaded, subsequent triggers may contain JavaScript code that the service can execute to update the page. For example, the page for the game show could define a set of functions that follow-up triggers could call to display new questions as they’re being asked on the program. The ETv object provides a programming interface to the trigger mechanism. Principally, it has an ontrigger() handler that’s called when the set-top box receives a trigger. The handler is passed the contents of the trigger in the form of a Trigger object. In addition, the ETv object has properties and methods that can disable ontrigger() calls or block them for certain URLs and channels.

Chapter 6: TV Information and Control

199

ETv Object

This interface is used exclusively by the service that manages triggers for the user and responds to triggers when they arrive. It defines the ontrigger() handler. When appropriate, this service displays the trigger URL as a link on-screen. If the user has followed the link and loaded the page, and a subsequent trigger contains a script intended for that page, the service executes the script within the page’s context. The ETv object is a read-only property, eTv, of TvTuner objects:
var enhancedTv = navigator.tvTuners.primary.eTv;

There is no constructor. For more information on how enhanced television works, see the Content Developer’s Guide.

Note: Liberate’s implementation of enhanced TV is based on standards set by the Advanced
Television Enhancement Forum (ATVEF), of which Liberate is a founding member. For more information, see the ATVEF Web site, http://www.atvef.com.

Properties
enabled
SYNOPSIS:

1.3 enabled exclusive-read/exclusive-write boolean

DESCRIPTION:

Determines whether or not triggers received for the TvTuner’s channels are processed. If this property is set to true, the ontrigger() event handler can be called for those triggers (unless they are otherwise blocked). The default value is false, meaning that the handler will not be called. If the page that defines the ontrigger() handler is unloaded, triggers are automatically disabled. If the page is loaded again, it must reenable triggers.

ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.3 release.

200

Content Developer’s Reference

ETv Object

triggerUrl
SYNOPSIS:

1.3 triggerUrl exclusive-read/exclusive-write string

DESCRIPTION:

A URL indicating the data stream where TV Navigator should listen for arriving triggers—for example, mcast://etv_triggers. TV Navigator expects triggers to arrive in either of two ways: Some triggers are inserted into the vertical blanking interval (VBI) of an analog video signal. That signal, even when it is converted to a digital format, contains the trigger. Triggers can also be carried by a data stream that is independent of program content—for example, a broadcast (mcast:) stream. TV Navigator always knows where to look for VBI-based triggers. This property tells it where to look for triggers that are not VBI based. triggerUrl is null by default, which means that TV Navigator will use its own built-in notion of where a data stream carrying triggers for the current channel is located. Set it to something other than null only to override the default behavior. The value you set will take effect when trigger processing is next enabled or the current channel changes, whichever comes first. If the URL depends on the channel, this property could be set in the TvTuner.onbeforechannelchange() handler.

ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.3 release.

unmatchedUrlsAccepted
SYNOPSIS:

1.3 unmatchedUrlsAccepted exclusive-read/exclusive-write boolean

DESCRIPTION:

Determines whether or not ontrigger() can be called for triggers that don’t match any entries in the URL filter—true if it can be, and false if not. In other words, this property states the default value for the URL filter set up by addToUrlFilter() and resetUrlFilter(). Its own default is true. Reserved for pages from the Service Manager’s domain.

ACCESS:

Chapter 6: TV Information and Control

201

ETv Object

HISTORY: SEE ALSO :

Introduced in the 1.3 release. addToUrlFilter()

Methods
addToUrlFilter(), resetUrlFilter()
SYNOPSIS:

exclusive boolean addToUrlFilter(string url, boolean flag) exclusive boolean resetUrlFilter(void)
1.3

1.3

DESCRIPTION:

These methods set up one of two filters that determine which triggers received by the client will result in ontrigger() calls. This filter is a list of URLs where each URL has an associated boolean flag. If the URL of an arriving trigger (the Trigger.url property) matches a URL on the list and the flag is false, the handler is blocked. If the flag is true, the handler can be called (provided it’s not blocked by the other filter or because enhanced TV is currently disabled). The default for trigger URLs that don’t match any entries on the list is governed by the unmatchedUrlsAccepted property. The URL list is scanned in linear order, from beginning to end, and matches are calculated by the same rules used for determining the scope of a cookie (see “Cookie Objects” on page 65 for a full description of those rules). Therefore, the judicious placement of related URLs can capture exceptions to general rules. For example, if the following two entries are in the list in the order shown, http://coleslaw.cabbage.mil/stuffed http://cabbage.mil true false

all triggers associated with the http://cabbage.mil domain would be blocked except for those that match http://coleslaw.cabbage.mil/stuffed. By default, the list of URLs is empty. addToUrlFilter() appends the first argument, url, to the end of the list and associates it with the flag of the second argument. resetUrlFilter() empties the list of all entries. To accept all URLs, make sure unmatchedUrlsAccepted is true (as it is by default) and that the list remains empty. To accept only a certain set of URLs, set unmatchedUrlsAccepted to false and add the selected URLs to the list. These methods return true if successful, and false if not. They should almost always return true unless, for example, they are not passed the correct number

202

Content Developer’s Reference

ETv Object

of arguments or arguments of the correct type. An empty string is not an acceptable url.
ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.3 release. unmatchedUrlsAccepted

resetUrlFilter()

see addToUrlFilter()

setChannelFilter()
SYNOPSIS: DESCRIPTION:

exclusive boolean setChannelFilter(string channels, boolean flag)

1.3

Sets a filter that determines which channels accept or block triggers. The channels argument is a list of comma-separated channel identifiers—usually strings matching the TvChannel.name property. If the flag argument is true, the ontrigger() handler can be called only for the channels on the list, and for no others. If flag is false, the handler can be called for all channels except those on the list. By default, triggers are processed for all channels. For example, the following code would block the processing of all triggers except for those associated with the WOOD and WKLV channels:
setChannelFilter("wood,wklv", true);

The channels list can be empty. For example, this line of code would restore the default:
setChannelFilter("", false);

This method resets the filter each time it’s called. It returns true if successful, which should always be the case if the arguments are well formed, and false if not.
ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.3 release.

Chapter 6: TV Information and Control

203

ETv Object

Event Handlers
ontrigger()
SYNOPSIS:

1.3 void ontrigger(object trigger) exclusive-read/exclusive-write handler

DESCRIPTION:

Called to report the arrival of a trigger. This handler is not called for triggers that a filter has blocked or if trigger processing is not currently enabled. The argument is a Trigger object with the following read-only properties: channel read-only number The channel that’s showing the program that the trigger is associated with. The number is an index into the TvTuner.channels array. If the indexed channel doesn’t match the current channel for the tuner, the enhanced TV service should ignore the trigger. expiration read-only Date object The date and time after which the trigger is no longer valid. The enhanced TV service should not take any action for an expired trigger. The Date object is local time, not UTC time. name read-only string A message that can be displayed to the user—for example, “Find out more!,” “Do you want to play?” or “Buy a McGumphrey router.” The message invites viewers to go to the url page and is displayed with a link to that page. If this property is null, it may indicate that the trigger contains a script that can be executed in the context of the url page, if the user has already loaded that page. script read-only string JavaScript code that the enhanced TV service can execute to update a Web page associated with a TV program. In this case, the name property should be null and the url property should designate a page that’s currently loaded, most typically a page that a previous trigger invited the user to go to.

204

Content Developer’s Reference

ETv Object

url read-only string The URL of the page associated with the channel. If the page is not currently loaded and name is not null, the enhanced TV service should display an on-screen link that allows users to go to the page.
ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.3 release.

Chapter 6: TV Information and Control

205

ETv Object

206

Content Developer’s Reference

MusicText Object
Overview
The MusicText object provides a way for a service to get text that it can display on-screen when the user tunes to an audio-only channel. Generally, audio-only channels broadcast music and the text describes the composition currently playing—the title, artist, composer, record company, and so on. If the service permits users to purchase the music they’re listening to, it may also include information needed to make the purchase (like an ID number, a price, and other descriptive information). The text is delivered through an onreceive() handler that’s called whenever new information is available—that is, when the user first tunes to the music channel and whenever one song ends and another begins. The service that defines the handler must determine how to display the text. However, the handler is called only if notifications have been enabled by the start() method. This method should be called as soon as the user tunes to an audio-only channel. For example:
theTuner = navigator.tvTuners.primary; function channelDidChange(targetChannel) { . . . if ( theTuner.curChannel.serviceType == "digitalRadio" ) { // it’s an audio channel if ( musicText.start() ) // onreceive() calls will begin else // oops; the handler won’t be called } . . . } theTuner.onafterchannelchange = channelDidChange;

The TvTuner.onafterchannelchange() handler is called whenever the current channel changes, immediately after the change takes effect. It’s therefore the appropriate place to check whether the new channel is a “digitalRadio” channel—that is, a channel without a video component.

Chapter 6: TV Information and Control

207

MusicText Object

When the user tunes away from the channel, it’s necessary to terminate the onreceive() notifications by calling stop(). For example:
function channelWillChange(targetChannel) { . . . if ( theTuner.curChannel.serviceType == "digitalRadio" ) { if ( musicText.stop() ) // onreceive() notifications will stop } . . . } theTuner.onbeforechannelchange = channelWillChange;

TvTuner.onbeforechannelchange() is called immediately before a channel change takes effect. It’s the appropriate place to turn off onreceive() notifications for a “digitalRadio” channel. Those notifications should be turned off even if the user is tuning to another “digitalRadio” channel. Notifications must be started and stopped independently for each channel. The musicText variable that holds the MusicText object is read-only. There’s just one object for all input sources. There is no constructor.

Note: The examples above show musicText as an independent variable, unattached to any
object. However, in a future release, this variable will become a property of the TvTuners array object:
var mt = navigator.tvTuners.musicText;

Methods
start(), stop()
SYNOPSIS:

boolean start(void) boolean stop(void)

DESCRIPTION:

These methods turn onreceive() notifications on and off. They should be called in the TvTuner handlers that bracket channel changes, as described on page 207 in the overview. Introduced in the 1.2.6 release. the examples in the “Overview” section, TvTuner.onbeforechannelchange() on page 279

HISTORY: SEE ALSO :

208

Content Developer’s Reference

MusicText Object

Event Handlers
onreceive()
SYNOPSIS:

void onreceive(object textStrings) read/controlled-write handler Called when new music text is received. The textStrings argument is an object with a set of read-only string properties that describe the music currently being played on the channel. The properties are: title The title of the song or composition. artist The artist or group performing the music. composer The composer of the music. album The album that contains the music being played. id A combination of the record label plus an identifier for the particular album or song being played. The label and identifier are separated by spaces and a slash, as follows:
“label / identifier”

DESCRIPTION:

The label could be, for example, “Decca”, “Atlantic”, or “Deutsche Grammophon”. The identifier could be a catalog number like “1419–2” or anything the music provider or record company chooses to use. Together, these two pieces of information can identify the music in other contexts— for example, on a Web site that permits users to buy the album. notice Additional text that could be displayed to the user—such as more information about the music, directions on how to purchase it, a price, or the URL of a related Web site. This property may be used differently in different deployments. If any of this information is not available, the corresponding property is an empty string (“”).

Chapter 6: TV Information and Control

209

MusicText Object

Some deployments may have additional properties for other information. Consult with the service provider for details on the structure of the textStrings object.
PERMISSIONS: HISTORY:

Writing the handler is controlled by the minor ACL. Introduced in the 1.2.6 release.

210

Content Developer’s Reference

ProgramStream Objects
Overview
A ProgramStream object controls a stream of audio and video data delivered to the set-top box, typically from a server. The object can play the stream at various speeds, rewind, fast forward, pause, stop, and navigate to specific positions. In addition, it can define and keep track of key frames in the stream, although this feature may not be available in all implementations. Although ProgramStream objects can control the data stream, they don’t set up the server connection or configure the stream. Other objects do that, then create the ProgramStream object that goes with the stream. Therefore, there is no constructor for ProgramStream objects; they’re created as a consequence of other actions when control over an incoming data stream is needed. Currently, only the VodSession.createStream() method creates ProgramStream objects. The VodSession records the object as its stream property; it also records the channel that receives the stream as its channelId property.

Methods and Handlers
The methods that exercise control over the stream—play(), pause(), and so on—work asynchronously. The success or failure of the method is initially reported through a boolean return value, but ultimately through an event handler. An initial return of true indicates only that a handler will be called. For example, if the rewind() method returns true, either the onrewind() handler will be called when the stream begins rewinding or onerror() will be called to report that the server was unable to rewind the stream. An initial return of false indicates immediate failure, so no handler is called. A return of false or the onerror() handler means only that the stream could not enter the requested state. It doesn’t indicate a conflict with the current state. For example, if the stream is currently stopped, stop() will return true and the onstop() handler will be called to report success.

Chapter 6: TV Information and Control

211

ProgramStream Objects

Playing Speeds
The speed at which a stream is played, fast forwarded, or rewound is represented as a number. The normal playing speed is 1. Other speeds are multiples or fractions of 1. Positive numbers go forward in the stream; negative numbers go in reverse. For example: 1.1 –2 3 0.25 Plays at a rate that’s 10% faster than the normal speed. Rewinds twice as fast as the normal playing speed. Fast forwards three times faster than the normal playing speed. Plays at a quarter of the normal speed.

Time Strings
Positions within the stream are represented by time offsets from the beginning of the stream, assuming the normal playing speed (a speed of 1). The offsets are recorded as normal play time (NPT) strings in any of the following formats:
"hours:minutes:seconds.fractions_of_a_second" "seconds.fractions_of_a_second" "now"

For example, “0:42:15.68” indicates a position 42 minutes and 15.68 seconds from the beginning of the stream. The same position could be recorded only as seconds—“2535.68”. The decimal point and at least one digit to its right is required—for example, “0:9:0.0” for 9 minutes from the start of the stream. The special value “now” means the current moment for broadcasts of live events. For example, if the viewer paused or rewound the stream during a live broadcast, “now” would pick up the action again as it was occurring.

Properties
curSpeed
SYNOPSIS:

curSpeed read-only number The speed at which the stream is currently playing, fast forwarding, or rewinding. The normal playing speed is 1. If the stream is paused or stopped, the value is 0. Negative numbers indicate the stream is being rewound or playing in reverse.

DESCRIPTION:

212

Content Developer’s Reference

ProgramStream Objects

HISTORY: SEE ALSO:

Introduced in release 1.2.6. play(), “Playing Speeds” in the “Overview” section

curTime, totalTime
SYNOPSIS:

curTime read-only string totalTime read-only string

DESCRIPTION:

These properties report the current position of the stream and its total length, both as times in NPT format. For example, if curTime is “73.29”, the current position is 73.29 seconds from the beginning of the stream. When the ProgramStream object is created, the initial curTime is “0.0”, the very beginning of the stream. It changes as the stream is played, fast forwarded, and rewound. Pausing or stopping the stream doesn’t alter the current position. It can be set explicitly with the play() method, and when the stream is stopped, with the stop() method. Since the starting position is always “0.0”, totalTime is also the last position in the stream. If the total time is unknown, this property is null.

HISTORY: SEE ALSO:

Introduced in release 1.2.6. “Time Strings” in the “Overview” section

fastForwardSpeed, rewindSpeed
SYNOPSIS:

fastForwardSpeed read-only number rewindSpeed read-only number

DESCRIPTION:

The speeds established by the implementation for fast forwarding and rewinding the stream. These values can provide reference points for the speeds passed to the play() method. For example, a JavaScript service could provide users with a double-fast-forward mode by reading the fastForwardSpeed value, doubling it, and passing that value to the play() method as the speed.

Chapter 6: TV Information and Control

213

ProgramStream Objects

HISTORY: SEE ALSO :

Introduced in release 1.2.6. fastForward(), rewind(), “Playing Speeds” in the “Overview” section

id
SYNOPSIS:

id read-only string The ID of the stream. Since the stream is specific to a particular program, the ID also identifies the content being played. This property is set by the method that creates the stream. (In the case of video on demand, it’s set by an argument passed to VodSession.createStream().) Introduced in release 1.2.6. VodSession.createStream() on page 291

DESCRIPTION:

HISTORY: SEE ALSO :

keyFrames
SYNOPSIS:

keyFrames read-only array of strings An array of stream positions represented as NPT-formatted strings. The key frames mark positions in the stream that may be of particular interest to the viewer. They enable the controlling service to move quickly to a known location. If key frames are not supported by the implementation, this array will be null.

DESCRIPTION:

HISTORY: SEE ALSO :

Introduced in release 1.2.6. curTime

mute
SYNOPSIS:

mute read/write boolean Whether or not the audio portion of the stream is currently muted—true if it is, and false if not. Setting this property will mute or unmute the stream.

DESCRIPTION:

214

Content Developer’s Reference

ProgramStream Objects

HISTORY: SEE ALSO:

Introduced in release 1.2.6. Speaker.mute on page 53

rewindSpeed title
SYNOPSIS:

see fastForwardSpeed

title read-only string The title of the content being played, in a form that can be displayed to the user. For example, the string might be the exact title of a movie. This property is set by the method that creates the stream. (In the case of video on demand, it’s set by an argument passed to VodSession.createStream().) Introduced in release 1.2.6. VodSession.createStream() on page 291

DESCRIPTION:

HISTORY: SEE ALSO:

totalTime

see curTime

Methods
fastForward(), rewind()
SYNOPSIS:

boolean fastForward(void) boolean fastForward(string untilTime) boolean rewind(void) boolean rewind(string untilTime)

DESCRIPTION:

These methods begin fast forwarding or rewinding the stream from the current position. If an untilTime argument is specified, the stream will stop when it reaches that position and freeze the picture on-screen (as if pause() were called). The argument is in NPT format, as discussed in the overview. The implementation may define a timeout for the pause. If the user doesn’t act before the timeout expires, the onerror() handler will be called with

Chapter 6: TV Information and Control

215

ProgramStream Objects

“pauseTimedOut” as the error message. The controlling service might then want to prompt the user to do something. If an untilTime argument is omitted, the stream will fast forward or rewind until it reaches the very end or very beginning of the stream, and then stop without displaying a freeze frame (as if stop() were called). Other ProgramStream methods, such as play() or pause(), can interrupt these actions before they stop of their own accord. However, if the stream fast forwards or rewinds to the untilTime position or to the end or beginning of the stream without being interrupted, the ondone() handler is called to report that the requested action has been completed and the stream is no longer fast forwarding or rewinding. These methods return false if there’s something obviously wrong that prevents them from initiating the requested action (for example, a wrongly formatted untilTime string). Otherwise, they return true and an event handler is called to report whether they were successful or not. The onfastforward() and onrewind() handlers are called when the stream starts to fast forward or rewind; onerror() reports a failure.
HISTORY: SEE ALSO :

Introduced in release 1.2.6. fastForwardSpeed, rewindSpeed, onfastforward(), onrewind()

pause()
SYNOPSIS:

boolean pause(void) boolean pause(number timeout) Pauses the stream at the current location, but keeps displaying the current frame (unlike stop(), which removes the picture from the screen). This method returns false if it fails immediately. Otherwise, it returns true and either the onpause() handler is called when the stream has successfully been paused, or onerror() is called if it can’t be paused. If a timeout argument is passed to this method, the onerror() handler will be called with the message “pauseTimedOut” after the picture has been paused for the specified period of time. The stream is still paused, but the error notification gives the controlling service the opportunity to prompt the user for an action to take—perhaps to stop the stream, begin playing again, or continuing pausing.

DESCRIPTION:

216

Content Developer’s Reference

ProgramStream Objects

The timeout is in seconds and should be an integer, not a floating-point number.
HISTORY: SEE ALSO:

Introduced in release 1.2.6. stop(), onpause()

play()
SYNOPSIS: DESCRIPTION:

boolean play(string timeRange, number speed) Begins playing the stream. The timeRange argument is two NPT-formatted time strings separated by a hyphen. The stream begins playing at the first time in the range and is scheduled to stop playing at the second. For example, if timeRange is “10.0–35.0”, the stream will begin playing at the 10th second and automatically stop at the 35th second. If the starting time is omitted (for example, “–35.0”), the current position of the stream (curTime) is assumed. If the ending time is omitted (“10.0–”), the end of the stream is assumed. A time that’s beyond the end of the stream is interpreted as the end. The play speed is set by the speed argument. The normal playing speed is 1; other speeds are fractions or multiples of this speed, as described in the “Playing Speeds” section earlier. For example, a speed of 2.5 is two and a half times as fast as normal and –0.75 rewinds at three-quarters the normal playing speed. This method can therefore fast forward and rewind the stream as well as play it for normal viewing. If the requested playing speed is not supported, play() uses the supported speed that’s closest to the one requested. For negative speeds, the timeRange must place the later time first (for example, “35.0–10.0”). Ranges specified in the opposite direction (such as “10.0–35.0” or “35.0–”) are not well formed. This method returns false if something obvious, such as a badly formed argument, indicates that it will fail. Otherwise, it returns true and an event handler will report whether it succeeded or failed. Either the onplay() handler will be called when the stream begins playing or the onerror() handler will be called to report failure. If the stream plays to the end of the specified time range before another action (such as fastForward()) intervenes, the stream stops playing but continues to display a last picture frame on-screen (as if pause() were called). However, if it reaches the very beginning or end of the stream, it stops without displaying a

Chapter 6: TV Information and Control

217

ProgramStream Objects

freeze frame (as if stop() were called). In either case, the ondone() handler is then called to report that the stream has played to completion. The implementation may define a timeout that applies when the stream is paused automatically at the end of the time range. If the user doesn’t act before the timeout expires, the onerror() handler will be called with “pauseTimedOut” as the error message.
HISTORY: SEE ALSO :

Introduced in release 1.2.6. onplay(), “Time Strings” in the “Overview” section

rewind() stop()
SYNOPSIS:

see fastForward()

boolean stop(void) boolean stop(string atTime) Stops the stream and removes the picture from the screen (unlike the pause() method, which continues to display the last frame). If the stream is playing, rewinding, or fast forwarding towards the atTime position passed as an argument, the stream will stop at that position (unless another action intervenes before it gets there). However, if the stream is moving away from the specified position or if atTime was not specified, it stops immediately. When the stream stops, the curSpeed is 0 and curTime remains at the current position. However, if the stream is already stopped when stop() is called, it remains stopped and atTime becomes the current position. This method returns false if it fails immediately. Otherwise, it returns true and one of three things happens: (1) onstop() is called when the stream has stopped, (2) onerror() is called to report that the stream could not be stopped or could not be scheduled to stop at the time requested, or (3) another action intervened before the stream could stop at the specified time, preventing either handler from being called.

DESCRIPTION:

HISTORY: SEE ALSO :

Introduced in release 1.2.6. pause(), onstop()

218

Content Developer’s Reference

ProgramStream Objects

Event Handlers
ondone()
SYNOPSIS:

void ondone(void) read/write handler Called when the stream stops playing, fast forwarding, or rewinding because a destination position in the stream (perhaps the beginning or end) was reached. Introduced in release 1.2.6. play(), fastForward()

DESCRIPTION:

HISTORY: SEE ALSO:

onerror()
SYNOPSIS:

void onerror(string message) read/write handler Called to report errors and failures of any of the ProgramStream methods. The message will be one of the following values:

DESCRIPTION:

Value
“playFailed” “pauseFailed” “pauseTimedOut” “stopFailed” “fastForwardFailed” “rewindFailed”
HISTORY:

Meaning
The play() method was unsuccessful; the stream didn’t begin playing. The pause() method was unsuccessful. A pause timeout has expired. The stream may have paused automatically or as the result of a pause() call. The stop() method was unsuccessful. The fastForward() method was unsuccessful. The rewind() method failed.

Introduced in release 1.2.6.

Chapter 6: TV Information and Control

219

ProgramStream Objects

onplay(), onfastforward(), onrewind(), onpause(), onstop()
SYNOPSIS:

void onplay(void) read/write handler void onfastforward(void) read/write handler void onrewind(void) read/write handler void onpause(void) read/write handler void onstop(void) read/write handler

DESCRIPTION:

These handlers are called to indicate that the corresponding methods have been successful and the requested actions have started or taken place. For example, when onplay() is called, the stream has begun playing; when onstop() is called, it has been stopped. The onpause() and onstop() handlers are called only as a consequence of pause() and stop() calls; they’re not called to report when the stream is automatically paused or stopped (for example, when it plays to the end of the stream). Instead, the ondone() handler reports when the stream automatically stops playing, fast forwarding, or rewinding.

HISTORY: SEE ALSO :

Introduced in release 1.2.6. play(), fastForward(), rewind(), pause(), stop()

220

Content Developer’s Reference

TvChannel Objects
Overview
A TvChannel object describes a television channel. It groups various information about the channel—its ID (channel number), frequency, network affiliation, and so on—into a single package. When the JavaScript API identifies a channel, it typically identifies it as a TvChannel object. TvChannels are obtained from a TvTuner object’s channels array:
var aChannel = navigator.tvTuners.primary.channels[index];

The array lists all the channels that the tuner can receive—so there’s no reason to construct a TvChannel object that’s not listed. Consequently, a constructor is not provided.

Tunable and Presentable Channels
People normally think of channels in two quite different ways: On the one hand, a channel is something that you can tune to—it’s a way of physically conveying a stream of data (video, audio, close captions, and possibly other information). Channel 5 is different from channel 6 because it has a different frequency and can carry a different data stream. On the other hand, a channel can also be thought of as the programming that a physical channel carries. If two people on different cable systems both say they’re tuned to CNN, they’re talking about the same channel in this sense, although one might be tuned to channel 12 and the other to channel 56. Because a channel in the programming sense is usually mapped directly to a channel in the physical sense, there’s no confusion in using the same term for both. However, sometimes the mapping is not one-to-one: • A physical channel might be split between two or more stations. For example, it might carry a fitness channel during the daytime and music videos at night. You can always tune to the channel (in the physical sense), but you get a different channel (in the programming sense) depending on the time of day. • Near video-on-demand (NVOD) carries the same program on a number of different channels, but staggers the starting time so that viewers can begin watching at their convenience and still see the whole program from the beginning. Two people on the same cable system may be watching the same channel (in the programming sense), but be tuned to different channels (in the physical sense).

Chapter 6: TV Information and Control

221

TvChannel Objects

TvChannel objects represent channels in both senses. A physical channel that you can tune to is tunable. A channel as programming content is said to be presentable, since an on-screen guide to upcoming programs would present only those channels to viewers. A programming guide would, for example, list more than one channel in the case of a split channel, but only one for NVOD. Each TvChannel object has corresponding tunable and presentable boolean flags. In ordinary circumstances, at least one of the two flags will be true for every TvChannel object. If both are true, there’s a one-to-one correspondence between the tunable channel and the presentable channel and a single object is being used for both. There can also be one-to-one mappings between different tunable and presentable TvChannels, since these two aspects of a channel are often split between objects. If the mapping is one-to-many or many-to-one, different tunable and presentable objects are always used. The mapping between tunable and presentable channels is accomplished by two other TvChannel properties: Each tunable channel keeps a presentables (note the plural) list of the programming channels it carries, and each presentable channel has a tunables (plural again) list of the physical channels that carry it. In addition, a splitTimes property reports how two or more presentable channels divide the time of a tunable channel.

Signal Type
Several factors affect the options available for a channel and the kinds of information needed to describe it. One of the most important factors is the type of signal that carries the channel to the set-top box. For example, a digital channel might offer a choice of language for the audio portion—say French or German—but analog channels can offer no such choice. A broadcast frequency is relevant for both analog and digital channels, but not for a channel carried over the Internet. On the other hand, an Internet channel has a URL, which analog and digital channels lack. These differences are reflected in the TvChannel API: If a property isn’t relevant for channels of a particular signal type, it won’t be defined for those channels. Since digital channels offer more options and carry more information than analog or Internet channels, more properties are defined for digital channels than for any other type. You can discover the signal type from the signal property, which is defined for all TvChannel objects.

222

Content Developer’s Reference

TvChannel Objects

Defined and Undefined Properties
The TvChannel properties documented here are those common to most systems. Under some circumstances, some of them may not be defined. Whether or not they’re defined chiefly depends on the following factors: • Whether or not the channel is the current channel. In some deployments, certain properties may be defined only for the current channel. That’s the case where the underlying system is unable to provide the required information for other channels. This manual notes the properties where this is most likely to be the case; however, depending on the deployment, it may be true for other properties as well. • The signal type. As noted in “Signal Type,” above, some properties are defined only for digital channels, some only for analog channels, and others only for Internet channels. These constraints are noted in the property descriptions. • The presentable/tunable distinction. Some properties (like a description of the channel’s programming content) are relevant only for presentable channels. Others (like the tuning frequency) apply only to tunable channels. • The deployment. The information that’s available about channels differs from deployment to deployment. It’s also likely that some TvChannel properties will be defined in addition to those documented here. Contact the service provider for information on deployment-specific TvChannel properties.

Properties
accessControlled
SYNOPSIS:

accessControlled read-only boolean Whether or not access to the channel is controlled by the conditional-access system on the set-top box—true if it is and false if not. The system controls premium channels that the user must sign up for and pay a fee to see, and possibly other channels that might be made available only to certain clients or clients in certain categories. If this property is undefined, it means either a conditional-access system is not present or the conditional-access provider doesn’t supply this information about individual channels. If it is defined, the provider may or may not use the

DESCRIPTION:

Chapter 6: TV Information and Control

223

TvChannel Objects

Liberate-specified ConditionalAccess object documented in this manual. A deployment-specific object could be used instead. If the ConditionalAccess object is used, you can pass a controlled channel to its getInfo() method to get the price of the channel and other information that viewers might need to know about it. For example:
var theTuner = navigator.tvTuners.primary; var channelList = theTuner.findChannel("Disney"); if ( channelList != null ) { if ( channelList[0].accessControlled == true ) { var info = theTuner.access.getInfo(channelList[0]); . . . } }

The format of the information that getInfo() returns varies from deployment to deployment. Besides the price, the returned object typically contains other information about the channel that only the conditional-access system would know about, such as whether the user is signed up, how long the subscription lasts, and so on.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. ConditionalAccess.getInfo() on page 195

availableComponents, selectedComponents
SYNOPSIS:

availableComponents controlled-read-only string selectedComponents controlled-read/controlled-write string

DESCRIPTION:

A “component” is a data stream carrying video, audio, or subtitle content for a channel. A digital channel may have a variety of alternative components that users can choose among—such as, audio in more than one language, video in both standard and wide-screen formats, more and less verbose subtitles, and so on. availableComponents is a list of comma-separated component descriptions. It lists all the currently available components for the channel—that is, all the current options for video, audio, and subtitles. selectedComponents is a similar list of component descriptions, but it picks out just the components that

224

Content Developer’s Reference

TvChannel Objects

determine what users are actually seeing and hearing on the channel at the present time (or what they would see and hear if they were to tune to the channel). These properties are defined only for presentable channels carried by a digital signal. They’re platform dependent, and are not defined for the set-top emulator in the current release. On some platforms, they may be defined only for the current channel (only for TvTuner.curChannel). Both properties may change from time to time as the programs and messages that the channel carries change. A component description has the following form,
streamType:[moreInfo][:componentTag]

where the square brackets ([ and ]) enclose optional elements. This description extracts a few pieces of information about the component from the MPEG program map table (PMT). It presents information that identifies the component and that might be helpful in deciding whether or not to select it. Each part of the description is explained below: streamType The streamType identifies the content carried by the stream—whether it’s video, audio, or subtitle data—and the type of encoding used. It (along with the colon that follows it) is the only obligatory part of the component description. For video and audio streams, streamType is the value of the 8-bit stream_type field from the PMT, expressed as hexadecimal digits. For example,
"01:"

indicates a video stream (as specified in the ISO/IEC 11172-2 standard), and
"04:"

indicates an audio stream (as specified by ISO/IEC 13818-3). These and other stream_type values are enumerated in the MPEG specification (ISO/IEC 13818–1, April 15, 1996); see, in particular, Table 2–29. For subtitles, the stream_type value would be 0x06. However, this value masks two different ways that the stream can carry subtitles. Therefore, for

Chapter 6: TV Information and Control

225

TvChannel Objects

subtitles, the streamType part of a component description is not “06:”, but a 16-bit value defined by Liberate:
"0100:" "0101:"

for EBU (European Broadcasting Union) teletext subtitles for DVB (Digital Video Broadcasting) subtitles

This distinction is important for interpreting the moreInfo part of the description. moreInfo Additional information about the component can optionally follow the first colon. It has the form:
languageCode[/typeCode]

This information is omitted if the component isn’t tied to a particular language (or languages). Since language information isn’t meaningful for video components, moreInfo is typically present only for audio and subtitles. For audio components (and for video if it’s specified), this additional information is taken from the PMT ISO_639_language_descriptor. The languageCode matches the ISO_639_language_code field of the descriptor; it’s a three-character sequence from the ISO 639-2/T standard—such as, “fra” for French, “jpn” for Japanese, and “hin” for Hindi. For example,
"04:deu"

specifies an audio stream in German. If more than one language code or audio type is associated with the stream, they’re separated by a dot. For example,
"04:fra.deu"

indicates an audio stream in both French and German. The typeCode is always omitted for a video stream. For an audio stream, it may or may not be omitted. If present, it matches the audio_type field of the ISO_639_language_descriptor (see Table 2–53 in the MPEG specification). For example,
"04:spa/02"

specifies an audio stream in Spanish for the hearing impaired.

226

Content Developer’s Reference

TvChannel Objects

For teletext subtitles (stream type “0100:”), moreInfo is taken from the teletext_descriptor detailed in the DVB Service Information (DVB–SI) specification. The languageCode matches the ISO_639_language_code field of the descriptor and the typeCode matches the teletext_type (see Table 70 in the DVB–SI specification for the typeCode values). For example,
"0100:eng/05"

would mean teletext subtitles in English for the hearing impaired. For DVB subtitles (stream type "0101:"), this information is taken from the DVB–SI subtitling_descriptor. The languageCode matches the ISO_639_language_code field of the descriptor and typeCode matches the subtitling_type field (see Table 16 in the DVB–SI specification for the typeCode values). For example,
"0101:eng/12"

would indicate English subtitles for display on a monitor with a 16:9 aspect ratio. componentTag DVB implementations of MPEG may optionally append a componentTag after a second colon. This hexadecimal string encodes the component_tag field of the PMT stream_identifier_descriptor for the stream. (Only DVB defines this descriptor.) The component tag can be used to find a component_descriptor with a matching component_tag field in the DVB event information tables (EIT). For example,
"01::2c"

indicates a video stream not associated with any particular language and described in an EIT by the component_descriptor having 0x2c as the component tag. The EIT component_descriptor holds various kinds of information about the component—such as whether an audio stream is monaural or stereo, what the aspect ratio of a video stream is, or what type of subtitles a stream carries. It also may also have a textual description of the component, suitable for displaying to users. You can get access to the EIT data through the TvProgram.raw property. The selectedComponents property identifies the active components in the availableComponents list—the components that currently provide video,

Chapter 6: TV Information and Control

227

TvChannel Objects

audio, and subtitle content for the channel. By setting this property, you can determine which components will provide the content users see and hear when they tune to the channel. You must set the entire property; there are no automatic defaults. For example, if a video component is not included when selectedComponents is set, the screen will be blank. If a subtitle component is not included, there will be no subtitles. Attempts to set inconsistent components (two video streams, for example, or subtitles for an aspect ratio that’s different than the video aspect ratio) will fail with indeterminate results. As long as the availableComponents property lists options for the channel, selectedComponents will record those that are currently selected. If it’s not set explicitly in JavaScript code, the underlying system will set it by default.
ACCESS:

Reading either property is controlled by the principal ACL; writing selectedComponents is controlled by the principal ACL and the minor ACL. Display.programDefaults on page 41, User.sysLanguagePreferences on page 362

SEE ALSO :

blackedOut, blocked
SYNOPSIS:

blackedOut read-only boolean blocked read/controlled-write boolean

DESCRIPTION:

These two properties indicate whether or not users are prevented from viewing the channel. If both are false, the channel can be viewed. But if either is true, users can tune to the channel (making it or its tunable counterpart the current channel) but cannot see or hear what’s on the channel. They may be faced with a black screen and no audio—or they may be presented with an on-screen notice saying that the channel is not available and, possibly, some alternative audio output. The decision to black out a channel is made at the broadcast source and affects a wide range of customers. The decision to block a channel is generally made by the user; it affects only a particular client machine, and often only particular users on that machine. For example, a parent may want to block channels with material deemed inappropriate for children. Someone who is tired of advertising may want to block the channels that carry the most commercials.

228

Content Developer’s Reference

TvChannel Objects

The blocked property can be used by an application that records and enforces these user preferences. Setting it to true effectively blocks the channel. The default value is false. These properties are defined only for presentable channels.
ACCESS:

Permission to write the blocked property is regulated by the principal ACL and the minor ACL.

category, description
SYNOPSIS:

category read-only string description read-only string

DESCRIPTION:

These two properties hold descriptions of the channel suitable for displaying to users. category is a short characterization of the general type of programming the channel carries (sports, news, movies, and so on). description is a longer description of the content to be found on the channel, possibly a few sentences or a short paragraph; the length of the description depends on the service provider. These properties are defined only for presentable channels. They’re empty strings if a category or description isn’t available for the channel, and undefined if the deployment can’t provide this kind of information for any channels.

curProgram, nextProgram
SYNOPSIS:

curProgram read-only TvProgram object nextProgram read-only TvProgram object

DESCRIPTION:

The program that’s currently being shown on the channel and the program that’s scheduled to be shown next. Information about the programs—such as their titles, durations, and when the next program is scheduled to start—can be taken from the TvProgram objects.

Chapter 6: TV Information and Control

229

TvChannel Objects

In some deployments, these properties may be valid only for the current channel of the primary tuner. If program information is not available, they’re not defined. Depending on the installation, the underlying data source for these TvProgram objects may differ from the data source for the objects obtained through TvInfo. For example, in systems based on Digital Video Broadcasting (DVB) Service Information (SI), curProgram and nextProgram are constructed from the Event Information Table (EIT) present/following tables. The objects that TvInfo returns are constructed from the EIT schedule tables. Despite this difference, the two sets of data generally match. However, the present/following tables are more likely to be kept up-to-date for last minute program changes—for example, when a sporting event runs past its scheduled time or when one movie is substituted for another. These two properties are initialized when TvInfo.setDataSource() is called. That method determines the source of all program information.
HISTORY: SEE ALSO :

These properties were added in the 1.2 release. “TvProgram Objects” on page 255, TvInfo.setDataSource() on page 245

description epgHidden frequency
SYNOPSIS:

see category renamed, see hidden

frequency read-only number The carrier frequency of the channel in hertz. This property is always defined for analog channels, and may or may not be defined for digital channels. This property is defined only for tunable channels.

DESCRIPTION:

fullName

see name

230

Content Developer’s Reference

TvChannel Objects

hidden
SYNOPSIS:

hidden read/controlled-write boolean Whether or not channel lists and programming guides that are displayed to the user should exclude the channel—true if they should exclude it, and false if not. This property is defined only for presentable channels.

DESCRIPTION:

ACCESS: HISTORY:

Writing is controlled by the minor ACL. Originally called epgHidden, this property was renamed in release 1.2. The longer name will be deprecated in a future release.

id
SYNOPSIS:

id read-only string The channel ID, typically a channel number. This variable is stored as a string to allow for IDs that are not simple numbers. The string captures the ID in a form that can be displayed to users. The TvChannel object describes the channel as it’s identified to the set-top box. For example, if broadcast channel 57 is mapped to channel 18 on a cable system, the TvChannel object will identify it as channel 18 to cable users. The channel ID for an external connector is set arbitrarily. For example, the single channel for an S-video port might be channel “998”.

DESCRIPTION:

SEE ALSO:

uniqueId

Chapter 6: TV Information and Control

231

TvChannel Objects

name, fullName, shortName
SYNOPSIS:

name read-only string fullName read-only string shortName read-only string

DESCRIPTION:

These properties supply names for the channel that can be displayed to the user. The first, name, is the most common name of the channel—typically a set of call letters (such as “KRON” or “WGN”), the abbreviated name of a specialized channel (such as “AMC” or “CNN”), or a single word (such as “Lifetime” or “Disney”). The other two properties hold alternatives to the common name: • fullName is the complete, unabbreviated name of the channel. For example, the full names of CNN and HBO are “Cable News Network” and “Home Box Office”. In some cases, the full name may be identical to the common name. • shortName is a short version of the name that can be displayed in a very small area, such as a channel grid. In general, the short name should be no wider than four uppercase letter Ws in the display font. If the common name is short enough (as it will be for call letters in North America), the short name and common name will be identical. All three properties are always defined. If the underlying data doesn’t supply a short name or a full name that contrasts with the common name, the shortName or fullName property will match the name string. Typically, at least one of these two properties will be the same as name. The exact spelling of the name strings (whether “Disney” or “DISN”, for example) depends on the spelling used in the underlying data. Comparisons should be case-insensitive. These properties are defined only for presentable channels.

HISTORY:

The shortName property was introduced in the 1.2.2 release.

232

Content Developer’s Reference

TvChannel Objects

network
SYNOPSIS:

network read-only string The network affiliation of the channel—such as “abc” or “Fox”—or an empty string if the channel is not affiliated with a network. This property is defined only for local channels that have a network affiliation, not for channels that are direct outlets of a network (such as CNN) and have no independent identity. The exact spelling of the network name depends on the spelling used in the underlying data. Comparisons should be case-insensitive. This property is defined only for presentable channels.

DESCRIPTION:

nextProgram ppv see price

see curProgram

presentable presentables

see tunable see tunable

price, purchased, ppv
HISTORY:

Deprecated in the 1.2 release. See the ConditionalAccess.getInfo() method instead.

rawData, rawInfo
HISTORY:

Deprecated in the 1.2 release.

Chapter 6: TV Information and Control

233

TvChannel Objects

relatedChannel
SYNOPSIS:

relatedChannel read-only TvChannel object A TV channel that bears some relationship to this channel. The nature of the relationship varies from deployment to deployment. If another channel is not related to this one or if the concept of a “related channel” is not supported in the deployment, this property will be undefined.

DESCRIPTION:

HISTORY:

Added in the 1.2.2 release.

selectedComponents serviceId see uniqueId

see availableComponents

serviceType
SYNOPSIS:

serviceType read-only string The type of service the channel delivers. The values may vary from deployment to deployment, but the basic set includes the following: “digitalTv” The channel carries regular TV programming. “digitalRadio” The channel is a digital sound service. It carries audio programming—such as continuous music—but no video. “fmRadio” The channel carries regular FM radio programming. “teletext” The channel carries a text stream for display on the TV screen. “nvodReference” “nvod” These channels deliver near-video-on-demand (NVOD) programming. An “nvodReference” channel carries the reference events that describe the

DESCRIPTION:

234

Content Developer’s Reference

TvChannel Objects

NVOD programs viewers can tune to. An “nvod” channel carries the actual time-shifted programs that viewers see. Typically, there are several “nvod” channels associated with a single “nvodReference” channel. The programs carried by these channels have matching “nvodReference” and “nvod” strings as values for their deliveryMode properties. “vod” The channel carries video-on-demand (VOD) programs. These programs have a matching “vod” deliveryMode. For more information on VOD, see the VodSession object. “data” The channel carries data, such as the data broadcast from the Mediacast server. This property is defined only for digital channels.
HISTORY: SEE ALSO:

Introduced in the 1.2 release. The “vod” value is new in the 1.2.6 release. TvProgram.deliveryMode on page 261

shortName signal
SYNOPSIS:

see name

signal read-only string The type of input signal that delivers the channel to the set-top box. The string will be one of the following values:

DESCRIPTION:

Value
“analog” “digital” “external” “internet”

Meaning
An analog signal A digital signal Input from the S-video, composite video, or SCART ports A TV channel carried over the Internet (TCP/IP)

The precise input port for an “external” signal can generally be determined from the initial name of the tuner.

Chapter 6: TV Information and Control

235

TvChannel Objects

split, splitTimes
SYNOPSIS:

split read-only boolean splitTimes read-only string

DESCRIPTION:

These properties help describe a split channel—a physical (tunable) channel that’s shared by two or more programming (presentable) channels. The split property is true for all participants in a split channel—in other words, for the tunable channel and for every presentable channel it carries. If split and presentable are both true, splitTimes is a list of comma-separated time spans that specify when the channel is broadcast. If either split or presentable is false, splitTimes is an empty string.

SEE ALSO :

tunable, “Tunable and Presentable Channels” on page 221 in the “Overview” section

transportStreamId

see uniqueId

tunable, presentable, tunables, presentables
SYNOPSIS:

tunable read-only boolean presentable read-only boolean tunables read-only string presentables read-only string

DESCRIPTION:

The tunable property reports whether or not it’s possible to tune to the channel—true if it is, and false if not. Similarly, presentable reports whether or not the channel represents a distinct stream of programming content—true if it does, and false if not. At least one of these two properties will always be true. It’s also possible for both properties to be true, in which case the TvChannel object represents both aspects of a channel—the physical carrier of data and the data that it carries.

236

Content Developer’s Reference

TvChannel Objects

However, it may be the case that only one of the properties will be true, making it necessary to map tunable channels to their presentable content and presentable channels to their tunable carriers. The tunables and presentables strings do just that. In both cases, the string is a list of comma-separated indexes into the TvTuner.channels array: • If presentable is true for a channel, each index in its tunables list picks a tunable channel that carries it. (Its presentables list will have just one entry, a self-reference to the presentable channel). • If tunable is true for a channel, each index in its presentables list identifies a presentable channel that it carries. (Its tunables list will have just one entry, a self-reference to the tunable channel). Further mapping for split channels is accomplished by the split and splitTimes properties. If you set TvTuner.curChannel to a channel that’s presentable but not tunable, the channel is automatically mapped to the corresponding tunable channel before being set.
SEE ALSO:

split, “Tunable and Presentable Channels” on page 221 in the “Overview” section

uniqueId, serviceId, transportStreamId
SYNOPSIS:

uniqueId read-only string serviceId read-only number transportStreamId read-only number

DESCRIPTION:

These properties hold identifiers associated with the channel. Unlike the unmodified id property, they are not commonly known to the nontechnical public. The uniqueId uniquely identifies the channel among all those the tuner can receive. It’s defined for all channel types; serviceId and transportStreamId are defined only for digital channels.

Chapter 6: TV Information and Control

237

TvChannel Objects

The transportStreamId identifies the multiplex (for example, the cable frequency or satellite transponder) that carries the channel. It’s unique within a delivery system. The serviceId uniquely identifies the channel within the transport stream. On digital systems, the uniqueId may be formed by combining the identifier for the delivery system (which is not exposed in JavaScript) with the transport stream ID and service ID.
HISTORY:

The uniqueId property was added in release 1.2. transportStreamId was previously named transportStream; the “Id” was added for clarification in release 1.2. The previous name will be deprecated in a future release.

url
SYNOPSIS:

url read-only string The URL for the TCP/IP stream that carries the video signal. This property is defined only for channels carried over the Internet.

DESCRIPTION:

238

Content Developer’s Reference

TvInfo Object
Overview
The TvInfo object provides a mechanism for getting broadcast information, particularly information about current and upcoming programs. A TvInfo object is a property of every TvTuner,
var systemInfo = navigator.tvTuners[index].info;

provided that the system can provide broadcast information for that tuner. If not, the TvTuner.info property won’t be defined. It’s best if your code checks before attempting to use the object:
if ( systemInfo ) . . .

There’s no TvInfo constructor.

Program Information
Information about television programs is presented as TvProgram objects. Each object represents one program. The properties that are defined for TvPrograms capture common information that’s available in most deployments—for example, the program title, the channel it’s on, the year it was produced, the time it starts, and how long it lasts. However, some deployments may not define all properties. TvProgram objects have a raw property that records all the available information about the program in its “raw” form. That typically includes information that’s not distilled into one of the standard properties. Deployment-specific information will show up under raw, not as a property of the TvProgram object itself. See “TvProgram Objects” on page 255 for more detailed information on these objects. TV Navigator is currently designed to work with systems that follow the Digital Video Broadcasting (DVB) Service Information (SI) specification for recording and delivering program information to the set-top box. Some properties of the TvInfo object are defined only for DVB– SI systems.

Chapter 6: TV Information and Control

239

TvInfo Object

Setting the Data Source
At the outset, a TvInfo object doesn’t hold any program data. To get program information, you must identify the source of the data and how much of it you want to examine. This is done with the setDataSource() method:
if ( systemInfo ) { systemInfo.setDataSource("mcast://progInfo", 3, callbackFunc); . . . }

This method takes arguments for: • The URL of the data source (“mcast://progInfo” in the example). • The number of hours of data that the object should retain (3). • A function that can be called to notify you when the data changes (callbackFunc). • A set of extensions to the main body of data being requested (not included in the example). In addition, setDataSource() relies on information recorded in the properties of the TvInfo object. You should set them to the desired values before calling the method.

Examining the Data
Once data tables are loaded and available, you can examine them in either of two ways: • By calling the search() method to look for specific groups of programs—for example, all movies in a particular time frame. This method returns an unordered array of TvProgram objects. • By stepping through an ordered index of all loaded broadcast events. The index is maintained by a TvInfoIndex object. The object must be set up with the addIndex() method before calling setDataSource():
if ( systemInfo ) { systemInfo.addIndex("name", "topics,startTime"); systemInfo.setDataSource("mcast://progInfo", 3, callbackFunc); . . . }

See the addIndex() method described here and “TvInfoIndex Objects” on page 251 for more information.

240

Content Developer’s Reference

TvInfo Object

Properties
indexes
SYNOPSIS:

indexes read-only array of TvInfoIndex objects indexes.length read-only number

DESCRIPTION:

The current set of TvInfoIndex objects. Objects are created and placed in the array by addIndex(); they’re removed from the array and deleted by deleteIndex(). The default length of the array is 0. Objects in the array can accessed with numerical indexes or by the name that addIndex() assigns to the object:
var lynneIx = theInfo.indexes[2]; var henryIx = theInfo.indexes["henry"];

HISTORY: SEE ALSO:

Introduced in the 1.2.2 release. addIndex(), “TvInfoIndex Objects” on page 251

pfEnabled, nvodEnabled
SYNOPSIS:

pfEnabled controlled-read/controlled-write boolean nvodEnabled controlled-read/controlled-write boolean

DESCRIPTION:

These properties inform setDataSource() what information to look for. They’re defined only for installations using Digital Video Broadcasting (DVB) Service Information (SI) and have an effect only when setDataSource() is called. If pfEnabled is true, setDataSource() will include the present/following tables from the DVB Event Information Table (EIT) as a source of program data. Present/following data is used to set the curProgram and nextProgram properties of the TvChannel object. If pfEnabled is false, these two properties will be undefined; they will be ignored even if the present/following tables are available.

Chapter 6: TV Information and Control

241

TvInfo Object

If nvodEnabled is true, the DVB descriptors for near-video-on-demand (NVOD) events will be used to set the NVOD-related TvProgram and TvChannel properties, which are: • TvProgram.nvodId • TvProgram.nvodReference • The “nvodId” and “nvodReference” settings for TvProgram.deliveryMode • The “nvodId” and “nvodReference” settings for TvChannel.serviceType If it’s false, these properties and settings will be undefined and unused. Even if NVOD descriptors are present in the data, they will be ignored. Consequently, NVOD programs will not be distinguished from other programs (unless deployment-specific descriptors are used to distinguish them). Both pfEnabled and nvodEnabled are true by default. They should be set to false if the present/following tables or the standard NVOD descriptors are not present in the data stream. Otherwise, setDataSource() will fail with undefined results. If pfEnabled is false, nvodEnabled should also be false. It’s an error to ask for NVOD data but not present/following data. In some cases, setDataSource() may be able to figure out that these properties are set incorrectly and “correct” them. However, your code should not count on that possibility, but set them to the proper values.
ACCESS:

Reading is controlled by the principal ACL; writing is controlled by the principal ACL and the minor ACL. These restrictions may be revised in a future release. Introduced in the 1.2.5 release.

HISTORY:

schemaUrl
SYNOPSIS:

schemaUrl controlled-read/controlled-write string The URL of a file defining the schema that TV Navigator should use when parsing DVB–SI program descriptors and making that information available on the client. This property has an effect only when SetDataSource() is called. The

DESCRIPTION:

242

Content Developer’s Reference

TvInfo Object

default value is null, which means the default schema—built into the TV Navigator application engine—will be used. The DVB–SI specification not only defines a number of standard descriptors for program information, it also permits other “private” descriptors to be defined as well. Consequently, deployments typically encode different sets of descriptors. For example, one might provide a list of the actors in movies and another might provide the country where the programs were produced. The schema file tells TV Navigator what the descriptors are and how they should be mapped to properties of the TvProgram.raw object, where JavaScript applications can look at them. It’s a binary file produced by the TV Info Schema Tool and may reside in nonvolatile memory on the set-top box, be loaded from a remote server, or be read from a Mediacast carousel. Typically, the schema changes only rarely. To switch schemas, you would need to unload current program data by passing an empty URL to setDataSource(), set this property to the new schema, and then call setDataSource() again with the correct URL.
ACCESS:

Reading is controlled by the principal ACL; writing is controlled by a combination of the principal and minor ACLs. These restrictions may be revised in a future release. Introduced in the 1.2.5 release. setDataSource(), the TV Info Schema Tool in the Customization Tools Guide

HISTORY: SEE ALSO:

Methods
addIndex(), deleteIndex()
SYNOPSIS:

void addIndex(string name, string sortOrder) void deleteIndex(object index)

DESCRIPTION:

These methods create and destroy TvInfoIndex objects, which maintain sorted indexes of all the programs described in the broadcast event tables that are currently loaded.

Chapter 6: TV Information and Control

243

TvInfo Object

In addition to creating the object, addIndex() places it in the indexes array. The first argument is the name of the index, which can be used to locate the object in the array:
var theIndex = systemInfo.indexes["name"];

The second argument, sortOrder, determines how programs will be arranged in the index. It’s a list of comma-separated TvProgram property names. Programs are sorted alphabetically by the first property that’s listed; any that have the same value for the first property are secondarily sorted by the second property that’s listed; and so on. If two programs match on all the properties listed in the sortOrder, they’re sorted on the channel ID. Currently, two sort orders are supported (along with the provisional variations mentioned in the VARIATIONS section below): “title,startTime” “topics,startTime” More will be added in future releases. The addIndex() method sets up the object, but the index is not prepared until program data is loaded after setDataSource() is called. Therefore, addIndex() must be called before setDataSource(). Use the callback function passed to setDataSource() to determine when the index is ready to use. The deleteIndex() method removes the index from the indexes array and deletes the object. This is the only way to free the memory allocated for the index.
VARIATIONS:

In some deployments, the “topics,startTime” sorting order has a provisional variant, “primaryTopics,startTime”, that looks only at the top level of the TvProgram.topics property. Although this functionality will be supported in future releases, the API is likely to change. Similarly, some deployments also support “topics,channel,startTime” and “primaryTopics,channel,startTime” sort orders. They sort programs by topic, but order programs within a topic by the channel ID before the starting time. The way these sorting orders are specified may change in a future release.

HISTORY: SEE ALSO :

Introduced in the 1.2.2 release. “TvInfoIndex Objects” on page 251

244

Content Developer’s Reference

TvInfo Object

search()
SYNOPSIS: DESCRIPTION:

object search(object params) Searches for program events that meet the requirements specified in the params TvProgram object passed as an argument, and returns an array of TvProgram objects with the results of the search. Objects in the return array have read-only properties. The setDataSource() method determines the data to be searched. If search() is called before the data is loaded, or if it can’t find any programs that match the params criteria, it returns null. A callback function passed to setDataSource() can notify you when the data is ready to be searched. If you don’t ask for the callback, the only way to know that the data has in fact been loaded is a search() return value other than null. All loaded tables from the specified data source are searched, unless they’re ruled out by the params search criteria. You don’t need to call this method to find out about the program being broadcast on the current channel, or the program scheduled to be broadcast next. You can get that information from the TvChannel object’s curProgram and nextProgram properties.

SEE ALSO:

“TvProgram Objects” on page 255, TvChannel.curProgram on page 229

setDataSource()
SYNOPSIS:

exclusive void setDataSource(string url, number hours [, function callback [, array extensions]]) Sets the source and scope of the program data that can be examined using the search() method and TvInfoIndex objects, and begins to acquire the data. The callback function can let you know when the data has been loaded. You can call this method any number of times. Existing data indexes are rebuilt each time it’s called. This method takes instructions from the current settings of the pfEnabled, nvodEnabled, and schemaUrl properties, and from the arguments it’s passed. The arguments determine where the data is to be found, how much of it the

DESCRIPTION:

Chapter 6: TV Information and Control

245

TvInfo Object

client should acquire, and how you should be notified when it has been acquired. They are: url The URL of the data source. The protocol name and exact URL depend on the service provider. Typically, the protocol can be http:, mcast:, or even mpeg:. For example, a deployment that gets program information from the Digital Video Broadcasting (DVB) Service Information (SI) tables might use mpeg://dvb as the URL that locates the data in the broadcast stream. This is the only context in which an mpeg: URL would be valid. hours The number of hours of program data that TvInfo should keep available. The number is a moving window of time extending from the present (whenever setDataSource() is called) into the future. All programs that fall within the window even in part—that is, even if they begin before the start of the window or end after it—are covered by the search. As time passes, programs that have finished airing are dropped from the data and new programs that begin within the hours window are added. However, the hours argument is just a hint. The TvInfo object will do its best to keep the requested amount of data loaded, but it may, from time to time, have somewhat more or less than that amount available—for example, as it’s dropping data for lapsed programs and acquiring new data for upcoming programs. Some systems may deliver the data in multi-hour chunks. Therefore, in order to cover the requested period, the TvInfo object may, at times, have to retain data for additional hours before and after the hours window. For example, suppose data is delivered in 3-hour chunks, starting at 3:00, 6:00, 9:00, and 12:00. If setDataSource() requests 5 hours of program data, at 8:00 p.m. TV Navigator would have to retain 9 actual hours of data (from 6:00 p.m. to 3:00 a.m.). The extensions argument can add fixed windows of time to the moving data window that hours requests. callback A function that takes a single argument and doesn’t have a meaningful return value: void callback(number status)

246

Content Developer’s Reference

TvInfo Object

The callback function is called whenever there’s a change in the data that’s available to be searched. It’s first called (with a status argument of 1) when information about available TV channels has been loaded—their names, descriptions, network affiliations, and so on. This indicates that the TvChannel objects in the TvTuner.channels array have been filled in with more than just channel numbers and frequencies. However, program data hasn’t yet been loaded. When program data for the full number of hours that were specified has been loaded, the function is called once more (this time with a status argument of 2). This indicates that the data is ready to examine. Thereafter, whenever loaded program data falls below the full amount—for example, when expired data has been thrown away, but data for new programs falling within the hours window hasn’t yet been loaded—the callback function is called with a status of 1, to indicate that only partial data is available. When the full amount of data is restored, the function is called again with a status of 2. If the page that calls setDataSource() (presumably the same page that defines the callback function) is unloaded, the data will still be available and will continue to be updated. However, the context for the callback function will no longer exist and notifications will cease. extensions An optional array that adds fixed windows of time to the moving data window established by the hours argument. The additional data covers specific periods of time, perhaps for specific channels. Each item in the array is an object that specifies a contiguous time range, and optionally a channel, for which data is to be acquired. The object has the following properties:

Property
object startTime number hours object channel

Purpose
A Date object that fixes the start of the period. The number of hours in the period. These hours are in addition to those specified by the hours argument. An optional TvChannel object.

The period begins at startTime and extends for the indicated number of hours. Like the window of time set by the hours argument, this period

Chapter 6: TV Information and Control

247

TvInfo Object

includes all programs that begin or end during it (even if they start before startTime or end after the period ends). If a channel is specified, only data for that channel is acquired. If a channel is not specified, data is acquired for all channels. Memory constraints may limit the amount of program data that can be acquired. If so, the hours argument is honored before the extensions request. There’s no specific constructor for the extensions array or for the objects in the array. However, the standard Array() and Object() constructors can be used. For example:
var theTuner = navigator.tvTuners.primary; var extensions = new Array(); extensions[0] = new Object(); extensions[0].startTime = new Date(2000, 9, 31, 19, 0, 0); extensions[0].hours = 8; var chans = theTuner.findChannel("PBS"); if ( chans ) { extensions[1] = new Object(); extensions[1].startTime = new Date(2000, 10, 1, 5, 0, 0); extensions[1].hours = 72; extensions[1].channel = chans[0]; } if ( typeof theTuner.info == "object" ) { theTuner.info.setDataSource(tvInfoUrl, 12, myCallback, extensions); }

This example asks the TvInfo object to: • Acquire 12 hours of program data starting from the present time, and maintain a 12-hour window going forward. • Acquire program data for an 8-hour period starting at 7:00 p.m on October 31, 2000. • Acquire program data for a 72-hour period starting at 5:00 a.m on November 1, 2000, but only for a PBS channel.

248

Content Developer’s Reference

TvInfo Object

Each time setDataSource() is called, it resets the data that should be acquired. Any data specified in an earlier call that’s not also specified in the subsequent call will be unloaded. To unload the current data tables without acquiring replacements, pass this method an empty string as the url:
theTuner.info.setDataSource("", 0);
ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. Previously, you could pass either the callback function itself to setDataSource() or just the name of the function. Given the following function definition,
function notifier(state) { . . . }

either of the following lines of code would work:
theTuner.info.setDataSource("mpeg://dvb", 3, notifier); theTuner.info.setDataSource("mpeg://dvb", 3, "notifier");

However, passing the function is more direct and efficient than passing just the name of the function. Therefore, the callback name argument was decremented in release 1.2.6.1.
SEE ALSO:

pfEnabled, schemaUrl, addIndex()

Chapter 6: TV Information and Control

249

TvInfo Object

250

Content Developer’s Reference

TvInfoIndex Objects
Overview
A TvInfoIndex object keeps an ordered index of all programs described in the broadcast event tables that are currently loaded. The order is determined when the object is created, by TvInfo.addIndex():
var progInfo = navigator.tvTuners.primary.info; progInfo.addIndex("topicsFirst", "topics,startTime");

This method produces a new TvInfoIndex object, assigns it a name (“topicsFirst” in the example above), establishes the ordering criteria (“topics,startTime”), and places the object in the TvInfo.indexes array. However, it doesn’t set up the index itself. That’s done when TvInfo.setDataSource() is called to begin loading the data. Therefore, the TvInfoIndex object must be created before calling setDataSource():
progInfo.addIndex("topicsFirst", "topics,startTime"); progInfo.addIndex("titleFirst", "title,startTime"); progInfo.setDataSource("mpeg://dvb", 7, doCallback);

In theory, any number of TvInfoIndex objects can be created, although, currently, only a handful of sorting orders (mainly the two illustrated above) are supported. Once setDataSource() is called, the index will be automatically updated each time old programs are dropped from the loaded data and new ones are added. To use a TvInfoIndex object to examine program data, you must first call search() to position a cursor in the index. Like TvInfo.search(), the TvInfoIndex search() method takes a TvProgram object as an argument. It searches through the index, from beginning to end, for the first program that matches the argument object. In the following example, it looks for a program titled “ER”:
var ix = navigator.tvTuners.primary.info.indexes["titleFirst"]; var target = new navigator.tvTuners.TvProgram(); if ( target ) { target.title = "ER"; ix.search(target); . . . }

The search() method places the cursor just before the program it finds, so that a subsequent getNext() call will return that program. If you pass an uninitialized TvProgram object to search(), it positions the cursor before the first program in the index. If you pass it a TvProgram

Chapter 6: TV Information and Control

251

TvInfoIndex Objects

object that doesn’t match any programs in the currently loaded event tables, it positions the cursor after the last program in the index. The getNext() and getPrev() methods walk through the index, returning one TvProgram object at a time and moving the cursor past the returned object. For example, the following code examines seven TvProgram objects in order:
for ( var i = 0; i < 7; i++ ) { var theProg = ix.getNext(); if ( theProg ) . . . else break; }

getNext() returns the program immediately following the cursor and steps forward through the index; getPrev() returns the program immediately preceding the cursor and steps backwards.

Properties
name
SYNOPSIS:

name read-only string The name of the TvInfoIndex object, set by TvInfo.addIndex() when the object was created. The name can be used to retrieve the object from the TvInfo.indexes array:
var theIndex = navigator.tvTuners[index].info.indexes["name"];

DESCRIPTION:

HISTORY: SEE ALSO :

Introduced in the 1.2.2 release. TvInfo.addIndex() on page 243

252

Content Developer’s Reference

TvInfoIndex Objects

Methods
getNext(), getPrev()
SYNOPSIS:

object getNext(void) object getPrev(void)

DESCRIPTION:

These methods each return a TvProgram object describing a broadcast event at the current position of the cursor in the index. The cursor is positioned between events; getNext() returns the program immediately following the cursor and getPrev() returns the program immediately preceding it. If the cursor is at the end of the index, getNext() returns null; if it’s at the beginning of the index, getPrev() returns null. They also return null if the cursor has not yet been positioned by the search() method. Both methods move the cursor past the program they return. Therefore, both can iterate through the index—getNext() stepping toward the end of the index and getPrev() stepping backwards towards the beginning. The loaded event tables are periodically updated to keep them current as time passes and the index is automatically updated to match. However, the cursor position remains the same. If these changes take place while iterating through the index, some programs may be missed or reported more than once.

HISTORY: SEE ALSO:

Introduced in the 1.2.2 release. search()

search()
SYNOPSIS: DESCRIPTION:

void search(object params) Positions the cursor in the index just before the first program that matches the TvProgram object passed as the params argument. The rules for a match are described in the introduction to the TvProgram object. If the params TvProgram object doesn’t have any defined properties, all programs match, so search() positions the cursor at the beginning of the index. If params has properties that don’t match any programs in the loaded event tables, it positions the cursor at the end of the index.

Chapter 6: TV Information and Control

253

TvInfoIndex Objects

There is no default cursor position; this method must be called after the index is built (after TvInfo.setDataSource() is called) and before calling getNext() or getPrev() to examine the data. It can be called any number of times. The cursor retains its position as the index is periodically updated because new program data is loaded or old program data is discarded. However, it may be invalidated if setDataSource() is again called. Therefore, you should reset the cursor with search() after every setDataSource() call.
HISTORY: SEE ALSO :

Introduced in the 1.2.2 release. TvInfo.setDataSource() on page 245, “TvProgram Objects” on page 255

254

Content Developer’s Reference

TvProgram Objects
Overview
TvProgram objects describe broadcast events—television programs. They appear in three contexts: • They’re passed to the TvInfo and TvInfoIndex search() methods to delimit the parameters that should be used when searching the database of current and upcoming programs. • They’re returned by the methods that get program descriptions from the database (by TvInfo.search() and TvInfoIndex getNext() and getPrev()). • They populate the curProgram and nextProgram properties of a TvChannel object. These TvProgram objects describe the program currently showing on the channel and the program scheduled to be shown next. The two TvChannel properties and the objects obtained from TvInfo and TvInfoIndex represent scheduled broadcast events that the system knows about. Each object has properties that describe a particular event—what channel it’s on, what time it starts, how long it lasts, whether captions or audio simulcasts are available, and so on. The TvProgram object that’s passed to TvInfo.search() and TvInfoIndex.search() lets those methods know what kinds of programs to look for. You can construct the object with the TvTuners.TvProgram() function:
var searchParams = new navigator.tvTuners.TvProgram();

However, if program information isn’t available to the system, it would be pointless to search for program data. For that reason, the TvInfo object, the TvChannel properties, and the TvProgram() constructor are defined only if program data can be found. Before trying to create a new TvProgram object, check the status of TvInfo:
if ( navigator.tvTuners.primary.info ) { var searchParams = new navigator.tvTuners.TvProgram(); . . . } else // stop

The properties of the TvProgram objects that the system defines—those you obtain from TvInfo, TvInfoIndex, or TvChannel—are read-only. The properties of the objects you construct are read/write.

Chapter 6: TV Information and Control

255

TvProgram Objects

Searching
A newly constructed TvProgram object has no defined properties. You must define those that you want to use as parameters in a search. For example:
if ( navigator.tvTuners.primary.info ) { var searchParams = new navigator.tvTuners.TvProgram(); var time = new Date(); time.setHours(19); time.setMinutes(30); searchParams.startTime = time; // start at 7:30 tonight searchParams.duration = 5 * 60; // cover a 5-hour period searchParams.topics = "*sports*"; // look for sports programs }

After initialization, the object is passed to TvInfo or TvInfoIndex search() to initiate a search of loaded system-information tables. TvInfo.search() returns an array of TvProgram objects describing all the broadcast events that meet the criteria encapsulated in the object passed as an argument:
var programs = navigator.tvTuners[0].info.search(searchParams);

TvInfoIndex.search() locates the first broadcast event that matches the argument object, so that a subsequent getNext() call will return a TvProgram object for that event:
var theIndex = navigator.tvTuners[0].info.indexes["indexName"]; theIndex.search(searchParams); var aProgram = theIndex.getNext();

In each case, search() finds objects that match all specified properties of the argument object, where the following rules define what constitutes a match: • The string properties of the TvProgram object passed to search() can contain wildcards for simple pattern matches. A question mark (?) matches any single character; an asterisk (*) matches any number of adjacent characters, including none. For example, each of the following search strings will match the word “cat”:
c* c?? *a** ?a? * ??? ca*t cat

The properties of objects the system defines won’t contain wildcards. • Only properties that you initialize in the object passed to search() constrain the search; properties that are left undefined are ignored. However, string properties that are set to “” (an empty string) are valid search parameters; they match program events that lack values for the property in question. For example, if the TvProgram.ageRating field is an empty

256

Content Developer’s Reference

TvProgram Objects

string, only unrated programs match the search criteria. But if ageRating is undefined, programs can match the criteria no matter whether they’re rated or not and without regard to what the rating may happen to be.

Defined and Undefined Properties
There’s no guarantee that all the properties described here will be present in the TvProgram objects that you obtain from TvInfo, TvInfoIndex, or TvChannel. It depends on what program information is available and may vary from deployment to deployment. Only those properties that can hold meaningful values will be defined. For example, if the television-information subsystem does not provide program descriptions, the description property will be undefined. By the same token, information may be available that’s not captured by the standard list of TvProgram properties documented here. That information will be contained in deploymentspecific properties of the TvProgram.raw object. For details of the program information that’s available for your deployment, contact the service provider.

Possible Values
Most properties of TvProgram objects are strings. The values that they can have—the text that’s meaningful to the search() methods and the values that you can find in the objects that the system returns—depend on the service that supplies the information. The best this documentation can do is give some illustrations of possible values. Contact the service provider for more specific information.

Constructor
TvProgram()
SYNOPSIS: DESCRIPTION:

void navigator.tvTuners.TvProgram(void) Constructs a TvProgram object that can be initialized and passed to TvInfo.search() or TvInfoIndex.search(). All of the properties of the object are read/write; none of them are defined on construction. This constructor is defined only if the TvInfo object is defined.

SEE ALSO:

TvInfo.search() on page 245, TvInfoIndex.search() on page 253

Chapter 6: TV Information and Control

257

TvProgram Objects

Properties
accessControlled
SYNOPSIS:

accessControlled for constructed objects, a read/write string for all other objects, a read-only string Whether or not access to the program is controlled by the conditional-access system on the set-top box—true if it is and false if not. For example, pay-perview programs come under the umbrella of the conditional-access system, as would other programs that the user must sign up for. If this property is not defined, either a conditional-access system is absent or the conditional-access provider doesn’t supply this information about individual programs. If it is defined, the provider may or may not use the Liberate-specified ConditionalAccess object documented in this manual. A deployment-specific object could be used instead. If the ConditionalAccess object is present, it can supply additional information about an access-controlled program—such as its price, whether it is already paid for, and so on. For example:
if ( thisProgram.accessControlled == true ) { var info = navigator.tvTuners[0].access.getInfo(thisProgram);

DESCRIPTION:

The format of the information that ConditionalAccess.getInfo() returns varies from deployment to deployment.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. ConditionalAccess.getInfo() on page 195

258

Content Developer’s Reference

TvProgram Objects

ageRating, qualityRating
SYNOPSIS:

ageRating for constructed objects, a read/write string for all other objects, a read-only string qualityRating for constructed objects, a read/write string for all other objects, a read-only string

DESCRIPTION:

Rating information for the broadcast event. This information may take different forms, depending on the type of event (regular TV show or movie, for example), the region (US or Europe), and the system used to do the ratings. The ageRating string generally categorizes the age appropriateness and content of the program. It generally can be displayed directly to users without modification. Here’s an illustrative (not exhaustive) list of possible values: “PG-13” “TV-G” “GBR-11” “Mild Violence, Adult Situations” The qualityRating string contains a judgment of how good the program is and depends on both the rating system and the conventions used for encoding it. It generally needs to be interpreted before being displayed to users. For a five-star rating system, the string typically is the number of half stars (“7” for 3 ½ stars, for instance), although other conventions could be used. Contact your service provider for the set of all possible ratings and the encoding conventions.

HISTORY:

The qualityRating property was added in the 1.2.2 release; at the same time, the former rating property was renamed ageRating.

audio
SYNOPSIS:

audio for constructed objects, a read/write string for all other objects, a read-only string A list of comma-separated audio choices for the broadcast event—for example, “stereo” and “surroundSound”. An empty string means that only standard, monaural audio is available.

DESCRIPTION:

Chapter 6: TV Information and Control

259

TvProgram Objects

Contact the service provider for the set of possible values.

blackedOut
SYNOPSIS:

blackedOut for constructed objects, a read/write boolean for all other objects, a read-only boolean Indicates whether or not the program is blacked out so that it can’t be viewed— true if it is blacked out, and false if not. For example, if all the tickets to a sporting event have not been sold, it might be blacked out in the area where the game is played. TvChannel.blackedOut on page 228

DESCRIPTION:

SEE ALSO :

captions
SYNOPSIS:

captions for constructed objects, a read/write string for all other objects, a read-only string A comma-separated list of available caption types for the broadcast event. Possible values are system-dependent, but will typically include information describing the caption language, aspect ratio, size, format, and so on.

DESCRIPTION:

channels
SYNOPSIS:

channels for constructed objects, a read/write array of TvChannel objects for all other objects, a read-only array of TvChannel objects The channel or channels on which the program is broadcast. If set as a search criteria, only events on the specified channels will match. Typically, the channels array of a returned object will contain just one TvChannel object. Even if the same program is broadcast over several channels at the same time, TvInfo and TvInfoIndex will generally return one TvProgram object for each channel.

DESCRIPTION:

SEE ALSO :

TvTuner.channels on page 271

260

Content Developer’s Reference

TvProgram Objects

deliveryMode
SYNOPSIS:

deliveryMode for constructed objects, a read/write string for all other objects, a read-only string The arrangement for delivering the program to the set-top box. The value is limited to one of the following strings: “basic” A typical program that is broadcast and received at a scheduled time. “vod” A video-on-demand (VOD) program that users can arrange to see at a time of their own choosing. Only TvChannels with a “vod” serviceType carry “vod” programs. “nvod” “nvodReference” A near-video-on-demand (NVOD) program that starts at staggered times. Each scheduled starting time is represented by a separate TvProgram object with “nvod” as its deliveryMode. Typically, the separate showings overlap—for example, a movie might begin every 15 minutes over a two-hour period. In this case, there would be eight “nvod” TvProgram objects; each object would have a different startTime property. In addition, another TvProgram object serves as a single reference for the program. This object has “nvodReference” as its delivery mode. It does not have a valid startTime property, but contains general information about the program, such as its title, duration, and rating. The “nvod” objects typically inherit this information from the “nvodReference” object, so they also fully describe the program. Although it doesn’t correspond to an actual showing of the program, the “nvodReference” object lists, in its channels property, the logical (presentable) channel associated with the program. In contrast, “nvod” objects list the physical (tunable) channels on which the program is actually shown. In each case, the serviceType property of the TvChannel object will have a corresponding “nvodReference” or “nvod” value. Since showings that overlap must be on different physical channels, different “nvod” objects are likely to have different channels lists. (Objects that represent repeat showings on the same channel would, of course, have the same channels list.)

DESCRIPTION:

Chapter 6: TV Information and Control

261

TvProgram Objects

The “nvod” and “nvodReference” objects are connected through a shared nvodId property. In addition, each “nvod” object has a nvodReference property that points to the associated “nvodReference” object for that program.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. nvodId, TvChannel.serviceType on page 234

description
SYNOPSIS:

description for constructed objects, a read/write string for all other objects, a read-only string A description of the program suitable for displaying to viewers.

DESCRIPTION:

duration
SYNOPSIS:

duration for constructed objects, a read/write number for all other objects, a read-only number The length of the program, in minutes. If included with startTime as part of a search criteria, duration specifies a particular period of time. Only programs that are broadcast—even in part— sometime within that period will match the criteria. If startTime is absent from the search criteria, only programs that are shorter than or equal to the stated duration will match.

DESCRIPTION:

SEE ALSO :

startTime

262

Content Developer’s Reference

TvProgram Objects

nvodId, nvodReference
SYNOPSIS:

nvodId for constructed objects, a read/write number for all other objects, a read-only number nvodReference read-only TvProgram object

DESCRIPTION:

These two properties connect the set of TvProgram objects that describe a nearvideo-on-demand (NVOD) program and all the times and channels on which it is broadcast. nvodId is a unique identifier for a single near-video-on-demand program. Its value will be the same for the reference TvProgram object that describes a particular program (the object with “nvodReference” as its deliveryMode) and all the objects that describe the starting times for the program (those with “nvod” as the deliveryMode). It’s not defined for other TvProgram objects. nvodReference is defined only for TvProgram objects with an “nvod” delivery mode. It refers to the reference object that describes the program, the one with a “nvodReference” delivery mode. This property is read-only, so it cannot be set as a search parameter; use the deliveryMode “nvodReference” value instead. These properties, along with deliveryMode, can be used to locate all the TvProgram objects that describe related NVOD events. For example, the following code first searches for the reference object for an NVOD program, then for all the objects that represent showings of the program. Related objects are identified by the nvodId property:
function findNvodEvents() { var p = new navigator.tvTuners.TvProgram(); p.deliveryMode = "nvodReference"; var refEvents = theTuner.tvinfo.search(p); if ( refEvents != null ) { for (var i = 0; i < refEvents.length; i++) { var timeShiftedEvent = new navigator.tvTuners.TvProgram(); timeShiftedEvent.deliveryMode = "nvod"; timeShiftedEvent.nvodId = refEvents[i].nvodId; var showings = theTuner.tvinfo.search(timeShiftedEvent);

Chapter 6: TV Information and Control

263

TvProgram Objects

if ( showings != null ) { var startingTimes = new Array(); for ( var j = 0; j < showings.length; j++ ) { startingTimes[j] = showings[j].startTime; } displayTheInfo(refEvents[i], startingTimes); } } } }

The displayTheInfo() function in this example is not part of the API.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. deliveryMode

price, purchased
HISTORY:

Deprecated in the 1.2 release. See the ConditionalAccess.getInfo() method instead.

qualityRating rating raw
SYNOPSIS:

see ageRating

renamed, see ageRating

raw read-only object The raw data from which this TvProgram object was built. The data is organized as a JavaScript object with properties that match the fields of the underlying event tables. The raw object has the same information about the event as the TvProgram object, but most likely organizes it differently. It typically also includes information about the event not reported by standard TvProgram properties. Depending on the schema used to convey program information, various properties of an event may be represented in the underlying data. The standard properties of TvProgram objects represent the most commonly used subset, cast

DESCRIPTION:

264

Content Developer’s Reference

TvProgram Objects

in a schema-neutral API. In addition to these properties, schema-specific properties that are not part of the common subset may also be present in the raw data. The raw object provides access to this information. To use it, you must be familiar with the schema and event tables used by the service provider. They vary from system to system and deployment to deployment.
SEE ALSO:

TvInfo.schemaUrl on page 242

shortTitle startTime
SYNOPSIS:

see title

startTime for constructed objects, a write-only string or a read/write Date object for all other objects, a read-only Date object The starting time for the broadcast event. If specified as part of a search criteria, startTime combines with duration to designate a specific period of time. (In other words, startTime for a search means the start of the period, not the start of the event.) Only events that occur sometime within that period or overlap with it—including events that begin before startTime or end after the period ends—will be found. If a specific duration isn’t specified as part of the search criteria, the period defaults to a minimal amount of time beginning at startTime. Only events that are on the air at startTime will be found. This property can be set as a JavaScript Date object or as a string in a format parsable by Date.parse(). When read, it returns a Date object.

DESCRIPTION:

SEE ALSO:

duration

Chapter 6: TV Information and Control

265

TvProgram Objects

title, shortTitle
SYNOPSIS:

title for constructed objects, a read/write string for all other objects, a read-only string shortTitle for constructed objects, a read/write string for all other objects, a read-only string

DESCRIPTION:

The full title of the program and a short version. The shortTitle condenses the title so that it can be displayed in a smaller area on-screen. For example, “What’s Eating Gilbert Grape?” might be shortened to “Gilbert Grape” and “The Red Violin” to “Red Violin.” If the title can’t be condensed, the two properties will match. There are no constraints on the length of the strings.

HISTORY:

The shortTitle property was introduced in the 1.2.2 release.

topics
SYNOPSIS:

topics for constructed objects, a read/write string for all other objects, a read-only string A list of comma-separated topics that categorize the program. An individual topic may contain a multilevel hierarchy, where the levels are separated by slashes—for example, “music/jazz/bebop”, “sports/team/basketball/college”, or “movie/romance”. For deployments based on DVB Service Information (SI), the topic levels are defined in the content_descriptor of the event information table (EIT). Each level is a 4-bit code that this property presents as a decimal string with values from “0” through “15”. The SI specification defines codes for the main topic and the first subtopic level. For example, “music/jazz” would be “6/4”, “sports/team” would be “4/5”, and “movie/romance” would be “1/6”. (See Table 18 in the DVB–SI specification for these codes.) Two further subtopic levels are also present, but their values are not standardized. The service provider should be able to inform you of the universe of all possible topics and their codes.

DESCRIPTION:

266

Content Developer’s Reference

TvProgram Objects

The usual * and ? wildcards can be used in defining the topics for a search. For example, you could use the string “1/*” to search for all movies or “1/?/*” to search for all movies with subtopics represented by a single decimal digit. In addition, another wildcard, +, stands for a single level in a topic hierarchy. For example, “+/2/*” would pick all programs that have “2” as the code for the first subtopic and “1/+/13/+” would look for all movies that have “13” as the second subtopic. This wildcard can be used only in the topics property. Unlike ?, it can stand for more than one character. But unlike *, it stands only for a single level in a topic description; it never includes the slash, /, that separates levels. Because it’s limited to a single level in the hierarchy, the + wildcard is somewhat more efficient than the other wildcards when skipping or omitting levels. For example, it would be more efficient to search for all movies as “1/+/+/+” than “1/*”. If more than one topic is listed as a search criteria—for example, “1/6/+/+,2/1/+/+,10/7/+/+”, which roughly translates to the unlikely combination of “movies/romance,” “news/weather,” and “leisure/gardening”— TvInfo.search() will return programs that match any of the topics listed; similarly, TvInfoIndex.search() will find the first program that matches any of the topics.
HISTORY:

The + wildcard was introduced in release 1.2.5.

year
SYNOPSIS:

year for constructed objects, a read/write string for all other objects, a read-only string A four-digit string for the year that the program (typically a movie) was released. Introduced in the 1.2.2 release.

DESCRIPTION:

HISTORY:

Chapter 6: TV Information and Control

267

TvProgram Objects

268

Content Developer’s Reference

TvTuner Objects
Overview
A TvTuner object represents a television tuner or some other source of video or audio input to the set-top box. It’s the place where the input signal is selected and controlled. All TvTuner objects are located in the tvTuners array of the Navigator object:
var firstTuner = navigator.tvTuners[0];

The objects in the array can also be accessed by name:
var mainTuner = navigator.tvTuners["tuner"]; var sameTuner = navigator.tvTuners.tuner;

The TvTuner that currently controls output to the screen is known as the primary tuner:
var primeTuner = navigator.tvTuners.primary;

There’s no TvTuner constructor and the Navigator.tvTuners array is read-only.

Types of TvTuner Objects
One object in the tvTuners array represents the television tuner built into the set-top box. If the box has more than one tuner, a separate object represents each one. In addition, there’s a separate TvTuner object for each S-video, composite video, or SCART input port on the box if (a) these ports could be connected to external tuners (for example, a VCR) and (b) the external tuner might be controlled by TV Navigator (for example, through infrared signals transmitted from the set-top box). Otherwise, the input port is represented by a TVChannel object associated with another TvTuner. Like a channel, it represents a single stream of program content.

Role of the TvTuner
The TvTuner object is the center for almost everything related to television: • It provides access to broadcast information, including the list of channels, the format of the incoming video signal, and program data. • It gives you a small amount of direct control over the TV. You can set the channel and turn input audio from the tuner on and off.

Chapter 6: TV Information and Control

269

TvTuner Objects

• It has methods for capturing images from the video stream. • It has a set of event handlers that are called to notify you when the channel changes, when the program on the current channel changes, and when the lineup of available channels changes. While TvTuner objects deal with video and audio input, there’s also a Display object that controls all output to the screen and a Speaker object for audio output. The Display object, for example, knows the size of the screen and has some properties that regulate how graphics are blended with the TV picture. The Speaker object holds the master volume controls. (These objects were described in Chapter 2, “TV Display.”) The illustration below imagines a set-top box with three video sources mapped to TvTuner objects. It shows that there can logically be many TvTuners for input, but just one Display object and one Speaker object for output.
set-top box video and audio input TvTuner object TvTuner object TvTuner object

Display object Speaker object

video output TV set audio output

TvTuner objects are supported by several other kinds of objects:
TvChannel Information about a particular TV channel—including the ID of the channel, its call letters, its network affiliation, and what kind of programs it carries. An object that provides access to broadcast information, including especially the schedule of TV programs. Information about a particular TV program, including what channel it’s on, when it starts, how long it lasts, what kind of program it is, how it’s rated, and so on. The video format—such as PAL, NTSC, or SECAM.

TvInfo TvProgram

TvFormat

270

Content Developer’s Reference

TvTuner Objects

ConditionalAccess ETv VodSession ProgramStream

The conditional-access system for purchasing premium channels and pay-per-view programs. An object containing controls and handlers for Web enhancements to 1.3 TV programs. An object that can set up and control a session with a video-on-demand server. A controller for a stream of program data that the user can start, stop, pause, rewind, and fast forward—such as a stream carrying a video-ondemand (VOD) program.

Properties
access
SYNOPSIS:

access controlled-read-only ConditionalAccess object An object with an interface for ordering premium channels and pay-per-view programs. This property is undefined if the set-top box doesn’t have a conditional-access system that permits users to purchase channels and programs online. Controlled by the principal ACL. “ConditionalAccess Object” on page 193

DESCRIPTION:

ACCESS: SEE ALSO:

channels
SYNOPSIS:

channels controlled-read-only array of TvChannel objects channels.length read-only number

DESCRIPTION:

The list of all possible channels that the user can tune to or watch. TV Navigator sets up the list by taking the information from the cable or satellite system or by enumerating all the possible channels broadcast by air, possibly including many that the tuner doesn’t receive or receives with an inadequate signal.

Chapter 6: TV Information and Control

271

TvTuner Objects

This is the full list of available channels, not necessarily the channel list that the user can configure and loop through. The length property records the number of objects in the array.
ACCESS: SEE ALSO :

Reading the channels array is regulated by the principal ACL. curChannel, onchannelsupdate(), “TvChannel Objects” on page 221

curChannel
SYNOPSIS:

curChannel controlled-read/controlled-write TvChannel object The channel that the tuner is currently tuned to. Most TvTuners tune to a default channel if curChannel has not been explicitly set. However, the TvTuner object that represents digital video input from the Internet and other nonbroadcast sources doesn’t pick a default; for it, curChannel is null by default. To set the channel, you must first get the TvChannel object for the desired channel. You can search for it in the channels array, or let findChannel() look for you. For example, the following snippet of code tunes to channel 14:
var theChannels = navigator.tvTuners.primary.findChannel("14"); if ( theChannels[0].id == "14" ) navigator.tvTuners.primary.curChannel = theChannels[0];

DESCRIPTION:

Of course, it’s generally foolish to choose a channel only by its ID; channel 14 carries different content in different locales. If you assign a channel that’s presentable but not tunable to curChannel, the TvTuner will figure out the corresponding tunable channel and tune to it. The channel can also be set in HTML using the tv: protocol specifier, which places the TV picture on the page. Unlike curChannel, tv: has no security restrictions on setting the channel. Two handlers—onbeforechannelchange() and onafterchannelchange()—are called each time the channel changes, whether curChannel is set directly or set through a tv: URL. You cannot be sure that the channel has actually changed until onafterchannelchange() is called.

272

Content Developer’s Reference

TvTuner Objects

ACCESS:

Reading this property is controlled by the principal ACL; writing it is controlled by a combination of the principal and minor ACLs. onbeforechannelchange(), channels, “TvChannel Objects” on page 221, “tv:” on page 383

SEE ALSO:

eTv
SYNOPSIS:

eTv

1.3

read-only object
DESCRIPTION:

An object that regulates and receives notifications that coordinate Web content with television content. Access to the object is not restricted, but all its properties and methods are reserved for a service that shares the Service Manager’s domain. Introduced in the 1.3 release. “ETv Object” on page 199

HISTORY: SEE ALSO:

format
SYNOPSIS:

format read-only TvFormat object A TvFormat object that contains information about the format of the video signal received by the set-top box. Currently, the object has just one property— system, a read-only string that reports the system used to encode the input signal. The standard video formats are: • “NTSC” (National Television Standards Committee), • “PAL” (Phase Alternation Line”), • “PAL 16:9”, the PAL variant that encodes the picture in a wide-screen 16:9 aspect ration (width to height), or • “SECAM” (Sequentiel Couleur Avec Mémoire). The Display object also has a format property, for the format of the signal sent from the set-top box to the display device (TV set).

DESCRIPTION:

Chapter 6: TV Information and Control

273

TvTuner Objects

HISTORY:

The TvFormat object had a variant property that was deprecated in release 1.2.1. Display.format on page 40

SEE ALSO :

frozen
SYNOPSIS:

1.3 frozen read/controlled-write boolean

DESCRIPTION:

Whether or not the television picture that has the TvTuner as its source is currently frozen on-screen—true if it is, and false if not. The default value is false. While this property is true, the input television signal continues to arrive at the set-top box, but its display (if it is displayed) is frozen, as if the current TV show was paused. However, unlike pausing a videotape, the viewer cannot recover any of the incoming signal that was not seen while the picture was frozen. You can use this property to freeze the TV picture long enough for the user to see what would be captured by the captureStill() method, and then decide whether to go ahead with the capture. However, you should keep it frozen only temporarily; if you set this property to true, be sure to reset it to false.

ACCESS: HISTORY: SEE ALSO :

Reading is unrestricted; writing is regulated by the principal and minor ACLs. Introduced in the 1.3 release. captureStill()

info
SYNOPSIS:

info read-only TvInfo object A global TvInfo object that provides access to broadcast system information for the tuner, particularly information about current and upcoming programs (broadcast events).

DESCRIPTION:

274

Content Developer’s Reference

TvTuner Objects

If program data isn’t available to the system, this property won’t be defined. Your code should check before delving into the wonderful world of broadcast information:
if ( typeof navigator.tvTuners[0].info == "object" ) // go ahead else // no data available
SEE ALSO:

“TvInfo Object” on page 239

mute
SYNOPSIS:

mute controlled-read/controlled-write boolean A control that can mute audio from the input source—it’s true if sound is turned off and false if it’s turned on. The Speaker object has a similar control for audio output. Reading this property is controlled by the principal ACL; writing it is controlled by both the principal and the minor ACLs. Speaker.mute on page 53

DESCRIPTION:

ACCESS:

SEE ALSO:

name
SYNOPSIS:

name controlled-read/controlled-write string The name that identifies the TvTuner object in the navigator.tvTuners array. The name can be assigned to match the function of the tuner—for example, “vcr” for the tuner representing an S-video connection to a VCR. Default names are platform-dependent, but generally reflect the video source that the object represents—for example, “broadcast” or “tuner” for the tuner in the set-top box, “svideo” for an S-video port, and so on. The name assigned to a TvTuner should never be “primary” or “secondary”, because a TvTuner with either of those names could not be distinguished from the tuner that currently functions as the primary or secondary tuner.

DESCRIPTION:

Chapter 6: TV Information and Control

275

TvTuner Objects

ACCESS:

Reading this property is controlled by the principal ACL; writing it is controlled by both the principal and the minor ACLs. TvTuners.primary on page 284

SEE ALSO :

Methods
captureStill()
SYNOPSIS:

1.3 controlled object captureStill(void) controlled object captureStill(string uploader [, number quality])

1.3

DESCRIPTION:

Captures and caches the current television picture as a still image (in JPEG format). If successful, this method returns an object that holds the image data and describes it. If for any reason it can’t capture the image, it returns null. This method works only if television is visible somewhere on the page that attempts the capture (if a tv: URL puts television on the page). The captured image is scaled as TV is scaled on the page. However, the full picture is captured, even if the visible image is cropped. The uploaderName argument is optional, and is ignored in the current release. In a future release, if it matches the name set for a file-upload field in a form,
<input type="file" name="uploader" . . .>

and the form is on the same page that calls captureStill(), this method will automatically insert the URL of the cached image in the form field. The user will then be able to use the form to send the captured image to the server. The quality argument sets the desired quality of the image, in the range 0 through 100. Higher numbers yield better quality images but also increase the size of the data. The default is 75. For JPEG images, the quality argument matches the quality settings used by the Independent JPEG Group’s compression software. However, the argument is just a hint; there’s no guarantee that the image will be captured at precisely that setting. To specify a quality without naming an uploader, set the uploader argument to an empty string:
var pic = navigator.tvTuners.primary.captureStill("", 50);

276

Content Developer’s Reference

TvTuner Objects

The object that captureStill() returns has the following properties: contentType A read-only string for the MIME media type of the captured image. Currently, the television picture is captured only as a JPEG image, so this property is always “image/jpeg”. src A read-only string, the URL of the image data in the cache. width and height Read-only numbers that report the width and height of the captured image in pixels. If either value is 0, the picture data has been discarded. binaryData A read/write object that holds the image data as an array of bytes. This object can be used in only one way: It can set the postData property of a NetRequest object:
var pic = navigator.tvTuners.primary.captureStill(); if ( pic ) { var myRequest = new navigator.net.NetRequest(); myRequest.post = true; myRequest.postData.set(pic.binaryData); . . . }

The binaryData object has a read-only length property that reports the number of bytes in the array. You can index the array to read particular bytes:
var numBytes = pic.binaryData.length; for ( i = 0; i < numBytes; i++ ) var value = pic.binaryData[i]; . . . }

The byte values that are read in this way are converted to the JavaScript number type. Setting binaryData to null discards the data and has the side effect of resetting width and height to 0. When you’re ready to get rid of the image,

Chapter 6: TV Information and Control

277

TvTuner Objects

it’s most efficient to first delete the data, then delete the object by also setting it to null:
var pic = navigator.tvTuners.primary.captureStill(); . . . pic.binaryData = null; pic = null;

It’s an error to set binaryData to anything but null. Attempting to set individual bytes in the array is also an error. Before calling this method, you may want to freeze the TV image so that the user can see the precise picture that will be captured.
ACCESS: HISTORY: SEE ALSO :

Controlled by the writing sublist of the principal ACL. Introduced in the 1.3 release. frozen, NetRequest.postData on page 179

findChannel()
SYNOPSIS: DESCRIPTION:

controlled object findChannel(string value [, string propertyName]) Searches the channels array for channels with the property value passed as an argument and returns an array of matching TvChannel objects. The second argument, propertyName, specifies the property that should be examined during the search. For example, the following code looks for channels with a name property matching the “Rugby” string:
var chanList = navigator.tvTuners.primary.findChannel("Rugby", "name"); if ( chanList ) var rugbyChannel = chanList[0];

Matches are case insensitive. Currently, this method can examine three TvChannel properties—id, name, and network. If a propertyName is not passed, id is assumed. If no matching channels are found, findChannel() returns null. If an invalid propertyName is passed, it generates a JavaScript error.
ACCESS: SEE ALSO :

Regulated by the reading sublist of the principal ACL. channels, “TvChannel Objects” on page 221

278

Content Developer’s Reference

TvTuner Objects

startMovieCapture() stopMovieCapture()

see captureStill() see captureStill()

Event Handlers
onbeforechannelchange(), onafterchannelchange()
SYNOPSIS:

void onbeforechannelchange(object targetChannel) controlled-read/controlled-write handler void onafterchannelchange(object targetChannel) controlled-read/controlled-write handler

DESCRIPTION:

Called when the channel changes for any reason—whether a tv: URL sets it or a new value is assigned to curChannel. The first of these handlers is called before the change takes effect; the second soon after the change is completed. If curChannel is read within the body of the onbeforechannelchange() handler, it will report the current channel before the change. The channel that will become the new current channel is passed as the targetChannel argument, a TvChannel object. When onafterchannelchange() is called, the change will have taken place and curChannel should match the targetChannel. If a body of code does something after setting the current channel,
navigator.tvTuners.primary.curChannel = someChannel; . . . // additional code

that code cannot assume that the channel has changed. The JavaScript interpreter will call the “before” handler at the point where the new value is assigned to curChannel (or the point where tv: sets a new channel). However, the change will likely not take place immediately. Moreover, the interpreter must finish executing the entire function or script that set the channel before it can call the “after” handler. Only when that handler is invoked can you be sure the channel has changed. Actions that depend on the change should be encoded in the onafterchannelchange() handler. If the channel can’t be changed for any reason, the “after” handler will not be called. Neither of these handlers can prevent the channel change from taking place. However, if the target channel is one that the user is not allowed to view, or it is

Chapter 6: TV Information and Control

279

TvTuner Objects

currently showing a program that the user is not permitted to see, the “before” handler can set the target channel’s blocked property to true. Although the target channel will become the current channel, the video and audio content carried by the channel will be blocked; the user will be presented with alternative content. Both handlers are undefined by default.
ACCESS:

Setting these handlers is controlled by a combination of the principal and minor ACLs; reading them is controlled by the principal ACL. Introduced in the 1.2.1 release. curChannel, TvChannel.blocked on page 228

HISTORY: SEE ALSO :

onchannelsupdate()
SYNOPSIS:

void onchannelsupdate(void) controlled-read/controlled-write handler Called when the lineup of channels in the channels array changes. Although it happens infrequently, cable and satellite operators may change the channel lineup at any time. This handler enables applications to take note of the change (and possibly inform the user) and to reset their state accordingly. It’s guaranteed that: • The change will not take place while JavaScript code is executing. If TV Navigator is informed of a change in the channel lineup while a script is being interpreted, it delays updating its data structures until the script terminates. Therefore, scripts that refer to the channels array can safely go about their business without concern that the array may change beneath them. • If onchannelsupdate() is defined, it will be the first JavaScript executed after the change is made. This handler is undefined by default.

DESCRIPTION:

ACCESS:

Setting this handler is controlled by the principal and minor ACLs; reading it is controlled by the principal ACL. channels

SEE ALSO :

280

Content Developer’s Reference

TvTuner Objects

onprogramchange()
SYNOPSIS:

void onprogramchange(void) controlled-read/controlled-write handler Called when the current program changes on the current channel. This handler is invoked immediately after the change takes effect and the new program is recorded in the TvChannel.curProgram property. If that property is not defined, onprogramchange() will not be called. The handler is called only when one program ends and another begins on the current channel; it’s not called when the current program changes because the channel was changed. Commercials do not count as “programs.”

DESCRIPTION:

ACCESS:

Setting this handler is controlled by a combination of the principal and minor ACLs; reading it is controlled by the principal ACL. Introduced in the 1.2.2 release. curChannel, TvChannel.curProgram on page 229

HISTORY: SEE ALSO:

Chapter 6: TV Information and Control

281

TvTuner Objects

282

Content Developer’s Reference

TvTuners Array
Overview
The TvTuners array holds one TvTuner object for each tunable source of video or audio input. It’s a read-only property of the Navigator object:
var tunersList = navigator.tvTuners;

If tvTuners is defined, the array will contain at least one object. That object corresponds to the television tuner in the set-top box and handles broadcast input. If the box has more than one tuner, there will be a TvTuner object for each one. In addition, each S-video, composite video, or SCART input port on the set-top box may be represented by its own TvTuner object. If the port could be connected to a remote tuner that TV Navigator could control (for example, through infrared transmissions), it’s mapped to a TvTuner object. If not, it’s mapped to a TvChannel object and treated like a channel in the main tuner. The tvTuners array can be accessed by a numerical index,
var thisTuner = navigator.tvTuners[0];

by the name of the TvTuner,
var thatTuner = navigator.tvTuners["tunerName"]; var thatTuner = navigator.tvTuners.tunerName;

or by the special name primary for the tuner that’s currently sending (or capable of sending) output to the screen:
var theTuner = navigator.tvTuners.primary;

In addition to the objects in the array, tvTuners holds the constructor for TvProgram objects and has other properties with information shared by all TvTuner objects.

Properties
defaultLanguage
HISTORY:

Deprecated in the 1.2 release. See User.sysLanguagePreferences on page 362 and Display.programDefaults on page 41 instead.

Chapter 6: TV Information and Control

283

TvTuners Array

length
SYNOPSIS:

length read-only number The number of TvTuner objects in the array.

DESCRIPTION:

musicText
SYNOPSIS:

musicText read-only MusicText object An object that provides text that can be displayed on-screen for radio channels (channels with no video component). The text accompanies the audio track being broadcast on the channel and describes the music being played. Currently, the musicText variable is not attached to the TvTuners array object, or to any other object. It will become a property of TvTuners in a future release. “MusicText Object” on page 207

DESCRIPTION:

VARIATIONS:

SEE ALSO :

primary, secondary
SYNOPSIS:

primary read/controlled-write object secondary read/controlled-write object

DESCRIPTION:

The TvTuner objects that are currently supplying the television picture seen onscreen—or that would supply the picture if any of the Web pages currently displayed asked for a tv: image. The first of these properties, primary, is always defined. It’s the tuner that supplies the picture if video from only one source is displayed or is requested. If video from two sources can be displayed (picture-in-picture, for example), secondary identifies the tuner that supplies the second picture. It’s defined only for systems that can display more than one television picture on-screen.

AVAILABILITY:

TV Navigator currently doesn’t support hardware that can display more than one television picture on-screen; therefore, secondary is not defined at the present time.

284

Content Developer’s Reference

TvTuners Array

ACCESS:

Writing is controlled by the minor ACL.

Methods
TvProgram()
SYNOPSIS: DESCRIPTION:

void TvProgram(void) The constructor for TvProgram objects. TvPrograms describe broadcast events and are used when querying the database of current and upcoming events. The constructor is defined only if the system has an event database to query. “TvProgram Objects” on page 255

SEE ALSO:

Chapter 6: TV Information and Control

285

TvTuners Array

286

Content Developer’s Reference

VodSession Objects
Overview
A VodSession object sets up a session between the set-top box and video-on-demand (VOD) servers. Video on demand puts programs under the user’s control—users can start the program when they want, pause, stop, rewind, and fast forward much as they would with a VCR or DVD player. A VOD implementation might use any standard protocol to arrange for and control the delivery of VOD content to the set-top box. It could be the Real Time Streaming Protocol (RTSP). It could also be the Digital Storage Media–Command Control (DSM-CC) protocol (typically in conjunction with another, lightweight protocol to actually control the data stream). The VodSession object defines an API that can work with any of them. The API is implemented by a TV Navigator module that understands the underlying system. The module is an extension, implemented using the Liberate TV Extender kit. Its sole purpose is to enable a JavaScript application—a service—to communicate with the VOD provider’s servers.

The VOD Service
The VodSession API is designed for a JavaScript service that implements a user interface for video on demand. The service would present the user with the list of available programs, help the user make a choice (possibly by showing program snippets), record the choice and arrange payment, set up the session and data stream that will carry the content, and give the user the tools to control the stream. However, the VodSession object is not concerned with all the tasks that fall to the VOD service. In particular, it’s not concerned with any of the preliminaries—how the service gets information about available VOD programs, displays them to the user, gets the user’s selections, determines the user’s eligibility, or arranges for payment. The service developer must have an independent way of getting information on these matters, generally by making HTTP requests to a deployment-specific source. Rather, the VodSession object is concerned with just two things: • Arranging and managing a session with VOD servers (the server that establishes and manages the session and the server that pumps program content to the set-top box). • Setting up the data stream that carries the content. The stream is managed by a ProgramStream object, which the VodSession creates.

Chapter 6: TV Information and Control

287

VodSession Objects

Usage
The VOD service constructs a VodSession object when it’s ready to obtain network resources and bandwidth for content delivery. However, constructing the object doesn’t start the session. The open() method opens the session and close() closes it. A VodSession object can open one session after another, but only one can be open at a time. After the session is open, the service calls createStream() to set up a data stream and produce the ProgramStream object that will control it. This method also identifies the channel where the program will be received (the channel that the service must tune to). VOD providers typically allocate a single physical channel per session for delivering content to a given set-top box. A stream is particular to a specific program. Because the VOD provider may allow users to preview programs as they browse through the available choices, a session can create multiple streams—as long as they are serialized to use just the one delivery channel. The destroyStream() method gets rid of a stream, after which another can be created. A VodSession can have only one ProgramStream object at a time. The current stream must be destroyed before a session can be closed. When the service no longer needs the VodSession object, it first calls destroyStream() and close(), then it simply makes sure that all references to the object are null.

Constructor
VodSession()
SYNOPSIS: DESCRIPTION:

void VodSession(void) Constructs a VodSession object:
var theSession = new VodSession();

Constructing the object doesn’t begin the session; for that, you need to call the open() method. The constructor initializes the configInfo property with a value determined by the underlying VOD extender. Other properties await the opening of the session and the creation of a ProgramStream object. You can have multiple VodSession objects at the same time.

288

Content Developer’s Reference

VodSession Objects

VARIATIONS:

Currently, the VodSession constructor is a top-level function, unassociated with a particular tuner. When multiple tuners are supported, it may become a method of a TvTuner object. Introduced in the 1.2.6 release. open()

HISTORY: SEE ALSO:

Properties
channelId
SYNOPSIS:

channelId read/write string The ID of the channel that carries the VOD program. This property matches the id property of a TvChannel object in the TvTuner.channels array. It can be used to tune to the channel:
var theTuner = navigator.tvTuners.primary; var theSession = new VodSession(); . . . var chans = theTuner.findChannel(theSession.channelId); if ( chans ) theTuner.curChannel = chans[0];

DESCRIPTION:

This property is not valid until the onstreamcreate() handler is called. Depending on the implementation of the VOD extender, the channel may not exist until the stream is created. It becomes invalid again when you call destroyStream().
HISTORY: SEE ALSO:

Introduced in the 1.2.6 release. createStream()

configInfo
SYNOPSIS:

configInfo read-only string Implementation-specific information that can be passed to a server to configure the session. The format and content of this string is determined by the VOD

DESCRIPTION:

Chapter 6: TV Information and Control

289

VodSession Objects

provider, as is its use. Contact the provider for information on the configuration mechanism and how to pass this information along.
HISTORY:

Introduced in the 1.2.6 release.

controlAddr
SYNOPSIS:

controlAddr read-only string An IP address used for setting up and controlling the session. The address is initially set by an argument to the open() method, but it may change if the client is redirected for server load-balancing. This property is invalid before the onopen() handler is called. It becomes invalid again when you call close().

DESCRIPTION:

HISTORY: SEE ALSO :

Introduced in the 1.2.6 release. open()

id
SYNOPSIS:

id read-only string A string used to identify this session to the server. This property is always valid when the onstreamcreate() handler is called; it may change each time a new stream is created. In some deployments, it becomes valid when onopen() is called. It becomes invalid again when the session is closed. Introduced in the 1.2.6 release. open()

DESCRIPTION:

HISTORY: SEE ALSO :

290

Content Developer’s Reference

VodSession Objects

stream
SYNOPSIS:

stream read-only object The ProgramStream object that createStream() produced. This property is invalid before the onstreamcreate() handler is called. Introduced in the 1.2.6 release. createStream()

DESCRIPTION:

HISTORY: SEE ALSO:

Methods
close() see open()

createStream(), destroyStream()
SYNOPSIS:

boolean createStream(string streamId, string title [, string ipAddr]) void destroyStream(void)

DESCRIPTION:

These methods create and destroy the stream that carries VOD program content from the server and the ProgramStream object that gives the client control over the stream. createStream() initializes the stream property with the ProgramStream object it creates and sets channelId to a valid value. In some deployments, it may also set or reset the session id. The streamId and title arguments identify the video-on-demand program that the user has selected. Once passed to createStream(), they initialize the ProgramStream.id and ProgramStream.title properties. This method also initializes the keyFrames and totalTime properties of the ProgramStream object, if those properties are supported. The optional ipAddr argument is the IP address of the server that will pump the stream of program data to the set-top box. Like the similar argument to the open() method, it should include a port number. The service provider uses this information as a hint and may actually use a different server. The hint may be required in some deployments, but not in others. createStream() fails if a ProgramStream object already exists. A session can have only one stream at a time. However, it can create any number of objects in

Chapter 6: TV Information and Control

291

VodSession Objects

series. After destroying one stream, it can create another—for example, to switch from one program to another. (In some implementations, you may be required to close the current session and open another one before creating a new stream.) If createStream() fails immediately (for example, because the arguments passed to it are not valid), it returns false. Otherwise, it returns true and a handler— either onstreamcreate() or onerror()—is called to report whether the operation succeeded or failed.
HISTORY: SEE ALSO :

Introduced in the 1.2.6 release. onstreamcreate(), “ProgramStream Objects” on page 287

open(), close()
SYNOPSIS:

boolean open(string ipAddr, number node [, number localPort]) void close(void)

DESCRIPTION:

These methods establish a session with the VOD server, and shut down a session previously opened. Establishing a session allocates network resources and obtains bandwidth for content delivery, but doesn’t set up the content stream or identify a delivery channel; you must call the createStream() method to do that. The ipAddr argument is the address of the server that sets up and manages the session. It should be an IP address, not a host name that needs to be resolved by a domain name server (DNS). It must specify a port on the server. For example:
"999.88.77.66:1234"

The node number helps the provider identify the particular server that should pump VOD content to the set-top box, the node it occupies in the provider’s constellation of VOD servers. The optional localPort argument specifies the port where the server managing the VOD session should direct its responses to the client. Generally, the client uses the same port number as the server; in that case, you don’t need to specify a port. The localPort argument permits you to specify a port number for the client if it differs from the number used on the server.

292

Content Developer’s Reference

VodSession Objects

The open() method sets the controlAddr property, possibly to the value passed in as ipAddr or possibly to another address supplied by the server. In some deployments, it also sets the VodSession’s id. If the open() method fails immediately, it returns false. Otherwise, it returns true and a handler—either onopen() or onerror()—is called to report whether or not a session was opened. A VodSession object can have only one session open at a time. However, after it closes a session, it can open another one. You must get rid of the stream (by calling destroyStream()) before closing the session.
HISTORY: SEE ALSO:

Introduced in the 1.2.6 release. id, controlAddr, onopen()

Event Handlers
onerror()
SYNOPSIS:

void onerror(string message) read/write handler Called when VodSession methods fail or system errors occur. The message will be one of the following values:

DESCRIPTION:

Value
“openFailed” “streamCreateFailed” “sessionFailed”

Meaning
The open() method wasn’t successful; the session was not started. The createStream() method was not successful; a ProgramStream object was not created. There was a general system failure that shut down the session.

HISTORY:

Introduced in the 1.2.6 release.

Chapter 6: TV Information and Control

293

VodSession Objects

onopen(), onstreamcreate()
SYNOPSIS:

void onopen(void) read/write handler void onstreamcreate(void) read/write handler

DESCRIPTION:

Called to report that a session has been opened by (the open() method) or that a ProgramStream object has been created (by the createStream() method). Introduced in the 1.2.6 release. open(), createStream()

HISTORY: SEE ALSO :

294

Content Developer’s Reference

System Capabilities

CHAPTERM

This chapter describes objects that give JavaScript some system-level capabilities. It includes: • The Input object for handling user input from a remote control device and keyboard. This object also maintains a stack for managing the window that is the focus of user attention and input. Later sections in this introduction have more detailed information on the focus stack and input handling. • An array of Indicator objects that correspond to the various lights, gadgets, and other indicators on the set-top box (such as the field that displays the channel number, the components of an LED clock, and the power light). • A System object with an assortment of systemwide handlers and controls. Almost everything in these objects is reserved for trusted Web sites or for the exclusive use of the Service Manager and the core services of the master application that share its domain. However, any Web page can define a page-specific input handler.

The Focus Stack
Because TV Navigator doesn’t put a cursor on-screen, users can’t point and click to choose a window. In the absence of a built-in interface for selecting windows, you must provide a means for users to transfer input focus from one window to another when needed. Sometimes switching windows requires an explicit user interface—for example, a button in one window that brings up another window; sometimes the switch is a by-product of another user action. In either case, the process must be managed from JavaScript. To keep track of the window that’s currently in focus and to regulate which window should receive the focus when the current window loses it, TV Navigator uses a stack of Window objects. The window that has focus is always at the top of the stack. Pushing a window on the stack gives it input focus. Popping a window from the stack removes the focus from that window and transfers it to the window that winds up at the top of the stack.

Chapter 7: System Capabilities

295

The Focus Stack

There are two methods that put a window on the stack and make it the focus window: • The Input object’s pushFocus() method adds a window to the top of the stack and assigns it focus; the depth of the stack increases by 1. Conversely, popFocus() removes the window at the top of the stack and assigns focus to the window that then rises to the top. • The Window.focus() method replaces the window currently at the top of the stack with the target window. The focus window changes, but the depth of the stack remains the same. When called for the window at the top of the stack, Window.blur() removes focus from the window, but does not remove the window from the stack. Another window is not automatically brought into focus. The focus() and blur() methods, therefore, have the standard behavior expected of them and are consistent with the stack, but do not modify the stack’s depth. In general, pushFocus() and popFocus() are used to move the user’s attention from one application to another. The focus() and blur() methods are used to move the user’s attention from window to window within an application. In other words, the Service Manager generally calls pushFocus() and popFocus(). An individual service should, to the extent possible, avoid increasing the depth of the stack and instead use focus() and blur() to manage the interaction between its windows.

Opening and Closing Windows
By default, opening a new, visible window pushes it to the top of the stack, as if pushFocus() was called. Closing the focus window pops it from the stack, as if popFocus() was called. Focus is pushed to an alert or soft keyboard automatically, then popped when the alert or soft keyboard is closed.

Showing and Hiding Windows
TV Navigator is able to create invisible windows that stay hidden off-screen until they are explicitly made visible (see the Window.visible property and the visible feature for Window.open()). An invisible window cannot become the focus window; it must be made visible first. If Input.pushFocus() or Window.focus() attempts to put an invisible window on the stack, a JavaScript error occurs. Opening an invisible window doesn’t affect the focus stack or the window currently in focus. However, when the window is made visible, it is pushed on the stack and becomes the focus window, as if pushFocus() was called. If the window at the top of the stack is made invisible, it’s popped from the stack, as if popFocus() was called.

296

Content Developer’s Reference

The Focus Stack

Making a window that’s not at the top of the stack invisible doesn’t affect either its position in the stack or the stack depth. If the window is made visible again, another reference to it is pushed on the stack; the window will then occupy two positions in the stack. However, if the window remains invisible and the windows above it are popped from the stack, it too will be popped. Input.popFocus() removes objects from the stack until there is a window that can take focus—that is, a visible window—at the top. The pop-up windows that the Service Manager creates for individual services are all initially invisible.

Autofocus Exception
The preceding sections describe the behavior of a normal window, whether visible or invisible. In some cases, an implicit pushFocus() is performed (when a visible window is opened or an invisible window is made visible). In others, an implicit popFocus() is performed (when the window is at the top of the stack and is either closed or made invisible). However, by setting the autofocus feature to “false” when calling Window.open(), you can create a window that must be explicitly managed. Such a window will not automatically be pushed on or popped from the focus stack; you must call pushFocus() and popFocus() (or focus() and blur()) yourself. When requesting a pop-up window from the Service Manager, a service can specify the autofocus setting.

The Focus within a Window
The focus stack does nothing more than manage the focus between windows; it doesn’t determine where input focus falls within a window (for example, which link or button is highlighted as the target of the user’s input). When a window is brought into focus, the input focus is handed to a specific element within the window. You can influence which element that will be by: • Setting the initialfocus attribute of the <meta> tag. • Calling a focus() function in an onload() handler. • Arranging the page. In the absence of other criteria, text fields are generally preferred over other focusable elements, and elements at the top and left of the page are preferred over those at the bottom and right. A window can become the focus window even if it doesn’t contain any focusable elements. However, you should avoid this situation, because it doesn’t leave the user a way to do anything—even to change the focusable window.

Chapter 7: System Capabilities

297

Input Handling

Input Handling
The Input object defines a mechanism for responding to the keys (or buttons) the user presses on a remote, a keyboard, or some other input device for the set-top box. Keys are identified by unique key codes, which are described in Appendix C. The input mechanism centers on two application-defined handlers, onkeyin() and onkeyout(), as shown in the following diagram:
input key onkeyin() handler returns true TV Navigator’s built-in HTML input handler can’t handle the key onkeyout() handler

s le n d ey ha e k th

When the user presses a key, its key code is exposed as the Input.curKey property and other Input properties reveal the time of the event and the device that was used. At the same time, the onkeyin() handler is called; onkeyin() can respond to the input key or not respond. If it returns false, it prevents any further handling of the key. If it returns true, it permits the usual handling to go forward. It may, if it chooses, change the curKey code, so that the input key will be handled as another key. Next, TV Navigator’s input handler looks at the key. This built-in handler responds when the user presses a key to move the focus rectangle, scroll, or make a selection. It also takes care of input to HTML forms. For example, if curKey corresponds to a character and a text field is in focus, it enters the character in the text field. If the key has an editorial function, like Delete, it makes the editing change. If the standard input handler responds to the key, nothing further is done. However, if the standard handler doesn’t know what to do with the key (for example, if nothing is in focus on the page or the key is one that the handler doesn’t recognize because it’s specific to the remote device), onkeyout() is called. Just as onkeyin() gives the application a first crack at a key, onkeyout() gives it a last chance to respond before the key is thrown away.

Window-Specific Handlers
Although onkeyin() is defined only for the Input object, there can be window-specific versions of onkeyout() in addition to the Input version. In general, the window-specific versions are given an opportunity to respond before Input.onkeyout() is called.

s rn tu e re als f
STOP

STOP

298

Content Developer’s Reference

Input Handling

The following diagram shows the chain of onkeyout() handlers that could be invoked:
unhandled key no

Can applications look at the key? yes

Input.onkeyout()

returns true Does something in the window have input focus? yes no top.onkeyout() returns false

STOP

returns true parent.onkeyout() returns false

STOP

returns true focus frame’s onkeyout() returns false

STOP

If the key that falls through the HTML input handler is not one that applications can legally look at (that is, if it has been hidden by the setExclusiveKeys() method), Input.onkeyout() is called directly, without first checking for similar functions associated with the window. However, if the unhandled key is one that all applications can view (if setExclusiveKeys() did not hide it), a search is made for a window-specific version of onkeyout() that will agree to respond to the key: • If an element within the window has input focus, the search begins with the frame where that element is located. If the Window object for that frame has an onkeyout() handler that returns false for the key, no further processing of the key takes place. However, if the frame doesn’t have an onkeyout() handler or its version of the handler returns true, the search continues in its parent frame—and so on up the frame hierarchy until it reaches the topmost level of the window. If the key isn’t handled anywhere within the window, the Input object version of onkeyout() is called as the final resort.

Chapter 7: System Capabilities

299

Input Handling

• If nothing within the window has input focus, the only window-specific version of onkeyout() that’s called is the version defined by the topmost Window object. If that version returns true or isn’t defined, the Input object version is called as the final step.

Defining the Handlers
Window-specific versions of onkeyout() can be defined in HTML as attributes of <frameset> or <body> elements:
<body onkeyout=". . ." >

Or they can be defined in JavaScript and assigned to the onkeyout property of a Window object:
function onKeyOut() { . . . } window.onkeyout = onKeyOut;

The Input object version of onkeyout() must be defined in JavaScript, since there’s no corresponding HTML element.

Input and the Service Manager
Because of their central importance to the user interface, the Input object’s versions of onkeyin() and onkeyout() should be defined only by the application that controls the overall look and feel of the client—that is, by the Service Manager, the first application that TV Navigator loads. The Service Manager that Liberate provides defines both handlers but permits individual services to register functions that the handlers will call. In this way, each service contributes a bit of the handler definition. A service can concentrate on just the keys it is interested in. It can bind itself to a particular key on the hand-held remote or keyboard by registering a function that will start running the service when the user presses that key. Services can also define window-specific onkeyout() handlers for their pages.

300

Content Developer’s Reference

Indicator Objects
Overview
An Indicator object represents something on the set-top box that conveys information to the user of the box. It might be an LED display for the channel number, a blinking light to show that something needs attention, a small light to indicate power status, or even a sound emitter of some sort; it could be anything. Each part of a digital clock—the hours, the minutes, the colon between them, and the AM/PM indicator—would probably be represented by separate Indicator objects. Every indicator has a name, an optional type, and a value that can be read and possibly set. Setting the value modifies the state of the indicator and what the user sees (or hears). The name, type, and value are all string properties of the Indicator object. Indicator objects reside in the Navigator.indicators array and can be accessed using either an index,
var first = navigator.indicators[0];

or the indicator name:
var alarm = navigator.indicators["buzzer"]; var alarm = navigator.indicators.buzzer;

Indicator objects and the indicators array provide a general mechanism for examining the indicators on the set-top box and, perhaps, modifying their values. However, because each settop box has its own peculiar set of indicators, nothing in this API can tell you what indicators are present, what their names or types are, what values are permitted, what values they have at start-up, or whether their values can be set as well as read. For that, you need additional information from the service provider. A platform might choose to export Indicator objects for things that are not, in fact, real indicators. Like other Indicators, these objects would allow JavaScript code to control some aspect of the set-top box, but they wouldn’t correspond to anything the user actually sees (or hears). For example, if the conditional-access system on a particular platform needs user input of a type not envisioned by the ConditionalAccess object, it could define a set of Indicators for that purpose. Setting the values of these objects would supply the conditional-access system with the information it needs. The application that governs the user interface for purchasing programs and channels might set them in response to events that the conditional-access system generates.

Chapter 7: System Capabilities

301

Indicator Objects

Properties
name
SYNOPSIS:

name controlled-read-only string The name of the indicator. Each object in the Navigator.indicators array has a unique name. The name follows the conventions for JavaScript identifiers, so it can always be used as a property name. For example:
var soundMaker = navigator.indicators.buzzer;

DESCRIPTION:

ACCESS:

Controlled by the principal ACL.

type
SYNOPSIS:

type controlled-read-only string The type of indicator. This property may be an empty string, or it may indicate the range of possible values for the object, if the indicator name is not sufficient for that purpose. For example, an “LED” type may indicate that the value can be “on” or “off”; a “percent” type might indicate permissible values ranging from “0” through “100”; an “rgb” type might indicate that “red”, “green” and “blue” are acceptable values; and so on. In other words, the type may serve to group indicators that take the same set of values. The conventions are up to the service provider.

DESCRIPTION:

ACCESS:

Controlled by the principal ACL.

value
SYNOPSIS:

value controlled-read/controlled-write string, controlled-read-only string, or controlled-write-only string The value of the indicator. This may be a string that you can both read and write, or it may be read-only. For some indicators, it may even be write-only. It

DESCRIPTION:

302

Content Developer’s Reference

Indicator Objects

depends on the indicator. In most cases, modifying the value should also modify what the indicator displays—for example, it could set the channel number or turn on a light. To know whether an attempt to set value succeeded, you can read the value back. However, there’s no guarantee that, even if successful, the value you read will exactly match the value you set. It depends upon the type of indicator and the semantics enforced by the service provider. For example, a value set for a digital clock may have been incremented because time advanced. A numeric indicator could accept both decimal strings (beginning with a digit) and hexadecimal strings (beginning with “0x”), convert the value to decimal before displaying it, and provide only the converted value when read. A number of possibilities can be imagined. It’s up to the service provider to explain the semantics of the indicators it exports.
ACCESS:

Reading is regulated by the principal ACL, writing by both the principal and the minor ACLs.

Chapter 7: System Capabilities

303

Indicator Objects

304

Content Developer’s Reference

Input Object
Overview
The Input object is concerned with user input from a handheld remote, a keyboard, the front panel of the set-top box, and other input devices. It currently plays two roles: • It manages a stack of Window objects that regulates which window is the focus for user input. Pushing a window on the stack makes it the focus window. Popping a window from the stack automatically transfers the focus to another window. See “The Focus Stack” in the chapter introduction for details. • It sets up a general mechanism that lets applications customize they way they respond to the user. An onkeyin() event handler looks at each key the user presses on an input device before the key is fed to the standard HTML input handler. One or more onkeyout() handlers can respond to keys that the standard input handler is unable to deal with. See “Input Handling” in the chapter introduction for a full explanation. This global object doesn’t correspond to an HTML element and has no constructor. It’s a readonly member of the navigator array:
var inputObj = navigator.input;

Properties
curKey, curChar
SYNOPSIS:

curKey read/controlled-write number, or exclusive-read/exclusive-write number curChar read-only string, or exclusive-read-only string

DESCRIPTION:

These properties report the current input key, the last key the user pressed. curKey holds the key code for the key and curChar holds the character the key represents, or an empty string if the key doesn’t correspond to a character. For example, if curKey is 109, the code for the M key (unmodified by Shift), curChar will be “m”. If curKey is 1026, the code for the volume-up key, curChar

Chapter 7: System Capabilities

305

Input Object

will be empty. Key codes and corresponding characters are discussed in Appendix C. The curChar string uses the standard ISO 8859-1 (Latin 1) character set, which is a superset of the ASCII character set. If curKey represents a character that falls outside the Latin 1 set, curChar will be empty. The onkeyin() and onkeyout() handlers look at these properties to discover which key the user pressed—which key they should respond to. A handler can reset the curKey value so that subsequent handlers will treat the input key as a different key. When curKey is modified, curChar is automatically updated to match.
ACCESS:

When the current key is one of those registered by setExclusiveKeys(), only pages permitted to access “exclusive” API elements can read these two properties—that is, only pages from the domain of the Service Manager. However, if the current key is not registered as an exclusive key, all pages can read both properties and pages trusted by both the principal ACL and the minor ACL can write curKey. onkeyin(), Appendix C, “Key Codes”

SEE ALSO :

deviceType, deviceNumber
SYNOPSIS:

deviceType read-only string, or exclusive-read-only string deviceNumber read-only number, or exclusive-read-only number

DESCRIPTION:

These properties identify the source of user input. deviceType names the type of input device—the device that holds the key the user pressed. It will be one of the following values:

Value
“remote” “frontPanel”

Meaning
The input is from a hand-held remote control for the set-top box. The input is from the front-panel of the set-top box.

306

Content Developer’s Reference

Input Object

Value
“keyboard” “gameController” “fake” “unknown”

Meaning
The input is from a keyboard, including a remote keyboard. The input is from a joystick or some other type of control device for games. The input isn’t from a device, but is inserted by insertKeys(). The source of the input is unknown.

deviceNumber is an index into a list of devices of the type reported by deviceType. For example, if there are two joysticks attached to the set-top box, it would identify one as device 0 and the other as device 1. If there’s only one device of a particular type, deviceNumber is 0.
ACCESS:

These properties have the same visibility as curKey and curChar: Unless the current key code matches a key hidden by setExclusiveKeys(), any application can read them. When it’s an exclusive key, only the Service Manager or pages from its domain can read them. curKey, timestamp

SEE ALSO:

timestamp
SYNOPSIS:

timestamp read-only Date object, or exclusive-read-only Date object The time when the input event occurred—when the user pressed the key or when insertKey() was called to add keys to the input queue. The microseconds field of the Date object is valid even though the Date.getMicroseconds() method, which was introduced in JavaScript 1.2, is not defined. However, you can use the Date.getTime() method to convert the object to an absolute number of microseconds, which can be compared to other timestamps similarly converted. Depending on the deployment, the resolution of the timestamp may not be microseconds, but 10’s or 100’s of microseconds. The timestamp is not affected by the actions of any handler. For example, it won’t change if onkeyin() resets the curKey value.

DESCRIPTION:

Chapter 7: System Capabilities

307

Input Object

This property is visible only when curKey and curChar are: If the current key is one that setExclusiveKeys() hid, only pages from the domain of the Service Manager can read the timestamp. Otherwise, any page can read it.
SEE ALSO :

curKey, deviceType

Methods
insertKeys()
SYNOPSIS:

controlled boolean insertKeys(number key) controlled boolean insertKeys(string chars) Puts a key code in the input queue, or all the key codes corresponding to the characters in a string. This method returns true if it succeeds in inserting the keys, and false if it fails. Controlled by the writing sublist of the principal ACL. curKey

DESCRIPTION:

ACCESS: SEE ALSO :

pushFocus(), popFocus()
SYNOPSIS:

controlled void pushFocus(object window) controlled void popFocus(void)

DESCRIPTION:

These methods operate a local stack of windows that determines which window is the focus for the user’s input. pushFocus() adds a Window object to the top of the stack and assigns the focus to that window. If the window argument it’s passed is a Window object that corresponds to a top-level window, it pushes that object on the stack. If the argument corresponds to a frame, it pushes the top-level Window that contains that frame on the stack. In this respect, pushFocus() behaves similarly to the Window.focus() method. popFocus() removes a Window object from the top of the stack, which removes input focus from that window and assigns it to the window that’s then at the top. It’s an error to push the focus to an invisible window (a Window object whose visible property is false), and popFocus() makes sure that an invisible window is never at the top of the stack. When it pops a window from the stack, it removes

308

Content Developer’s Reference

Input Object

as many Window objects as necessary until the one at the top corresponds to a visible window.
ACCESS: SEE ALSO:

Regulated by the writing sublist of the principal ACL. “The Focus Stack” on page 295 in the chapter introduction, Link.focus() on page 48

setAppKeys()

replaced, see setExclusiveKeys()

setExclusiveKeys()
SYNOPSIS: DESCRIPTION:

exclusive void setExclusiveKeys(object keysArray) Sets the keys that will be hidden from most applications and pages. The keysArray is an array of numbers, where each number is a key code. When one of those keys is the current input key, two restrictions apply: • The onkeyout() handlers attached to Window objects are not called. Only the Input object’s onkeyin() and onkeyout() handlers are given a chance to respond to the key. • The set of properties that describe the input event—curKey, curChar, deviceType, deviceNumber, and timestamp—are protected by the “exclusive” access privilege. Only the Service Manager and those essential services that share its domain can see them. If the current key was not listed in the keysArray argument, these properties are visible to any page. This method is not cumulative; if it is called more than once, TV Navigator wraps the “exclusive” protection around only the last set of keys it is passed. This method is also “exclusive”; the Service Manager should take responsibility for determining which keys other applications can see.

ACCESS: HISTORY:

Reserved for pages from the Service Manager’s domain. This method replaced setAppKeys() in the 1.2 release. It reverses the polarity of the former method. onkeyin(), curKey

SEE ALSO:

Chapter 7: System Capabilities

309

Input Object

Event Handlers
onkeyin(), onkeyout()
SYNOPSIS:

boolean onkeyin(void) exclusive-read/exclusive-write handler boolean onkeyout(void) exclusive-read/exclusive-write handler

DESCRIPTION:

These event handlers are called to look at and respond to user input. onkeyin() is called whenever the user presses a key, before the key is processed by the HTML input handler. onkeyout() is called if the HTML input handler can’t do anything with the key. Both handlers look at the curKey property to see which key the user pressed and at other Input properties to determine the device where the key is located and the time when it was pressed. The onkeyin() handler can change the curKey value so that the key will subsequently be handled as a different key. If it returns false, no further processing of the key will be attempted. If it returns true, the normal processing goes forward, as described under “Input Handling” in the chapter introduction. These handlers are for system-level customization only. onkeyin() might handle keys with a special purpose for Interactive TV—for example, the channel-up and channel-down keys. onkeyout() can handle keys that might either deliver standard HTML input or do something special for Interactive TV. For example, when the user presses a number key and a text field is in focus, the standard input handler will enter the number in the field. However, if there’s no text field, the key will fall through to onkeyout(), which could interpret the key as a channel number (or one digit of a channel number) and tune to the channel. The return value of onkeyout() is ignored. No matter what it returns, the key will not be processed further; this handler is the end of the line. However, window-specific implementations of onkeyout() may be called before the Input object version. Those handlers can prevent subsequent processing of the key by returning false, as described under “Window-Specific Handlers” in the chapter introduction. By default, neither handler is defined. They should be implemented just once, by the first application that’s loaded when the set-top box is turned on—in other words, by the Service Manager. Liberate’s Service Manager implements both handlers but permits services to define functions that the handlers will call. In effect, each service can implement a portion of each handler.

310

Content Developer’s Reference

Input Object

When onkeyin() and onkeyout() are called, the this property is not defined. They therefore cannot access curKey as this.curKey, but only as navigator.input.curKey.
VARIATIONS:

Currently, these handlers must be set as strings of JavaScript code, rather than as functions. setExclusiveKeys(), “Input Handling” on page 298 in the chapter introduction

SEE ALSO:

Chapter 7: System Capabilities

311

Input Object

312

Content Developer’s Reference

System Object
Overview
The System object is where systemwide handlers and controls that communicate with platform-dependent software are located. It’s a read-only property of the navigator array:
var sys = navigator.system;

Properties
uniqueId
SYNOPSIS:

uniqueId controlled-read-only string A string that uniquely identifies the set-top box among all boxes in the deployment. If there is no such identifier, this property is undefined or null. Controlled by the principal ACL. Introduced in the 1.2 release.

DESCRIPTION:

ACCESS: HISTORY:

Methods
control()
SYNOPSIS: DESCRIPTION:

exclusive void control(string request) Passes a control request to TV Navigator and the platform. Often the request is for TV Navigator to shut down, reboot, warm start, suspend, or otherwise right itself. For example, if the servers for some essential services are reconfigured and the master application is asked to restart in order to pick up the changes, it could comply by calling control() with a request to quit. This method is synchronous. It doesn’t return until the platform-independent part of TV Navigator (the application engine) has responded to the request string, passed the message on to platform-specific software, and received the platform’s response.

Chapter 7: System Capabilities

313

System Object

TV Navigator knows how to respond to two standard requests: • If the request string begins with “quit”, TV Navigator will exit—it will cease running on the set-top box. In this case, the control() method never returns. All platforms support this behavior. • If the request string begins with “suspend”, the application engine will become quiescent and suspend all activity to reduce the resources it uses. In particular, it will send modified cookie and user data to the server, and then cancel all networking activity, close open files, destroy any timers, and free as much allocated memory as it can. While suspended, it ignores user input. The control() method returns only when the platform causes TV Navigator to resume normal activity. Most platforms support this behavior. In these cases, the request string might simply be “quit” or “suspend”, or those words might be followed by more platform-specific elaborations—for example, “quit 9” or “quit_save_settings”. The application engine looks at just the beginning of the string, but hands the entire sequence to the platform. For example, suppose the request string is “quit:restart”. The application engine will respond to “quit” and shut down, and then pass the entire string to platform-dependent software, which will not only shut down but also act on the “restart” part of the request and immediately reboot, waking up TV Navigator again. In many cases, the application engine won’t recognize the request string, but will simply pass it on to the platform. This method is therefore a counterpart to the onexternalevent() handler. That handler passes a message from the platform to the master application; control() passes a message from the master application to the platform. Together, onexternalevent() and control() enable content developers and settop box providers to cooperate with little interference from TV Navigator itself. For example, the platform might deliver an external-event message to the master application, which would notify the user, get the user’s response, and then send an appropriate control request back to the platform. For the full set of requests that a platform supports, consult the service provider’s deployment-specific documentation.

314

Content Developer’s Reference

System Object

ACCESS: SEE ALSO:

Reserved for pages from the Service Manager’s domain. onexternalevent()

resetExecutionCount()
SYNOPSIS: DESCRIPTION:

controlled void resetExecutionCount(void) Resets the JavaScript execution counter to 0. The counter registers how much code is being executed in the current script, as figured either by the amount of time that has elapsed or by the number of instructions already executed. If the count becomes too high, the JavaScript interpreter aborts the script as a precaution against running out of memory, overloading the execution stack (through an overly deep recursion, for example), or doing other damage. The counter starts at 0 for each batch of JavaScript code that the interpreter encounters. Specifically, it starts at 0 when: • A script begins executing (the <script> tag). • An event handler is called. • Code is executed because a time delay set by Window.setTimout() has expired. • A javascript: URL is interpreted. • A JavaScript entity is interpreted. (Note, however, that JavaScript entities are not currently supported; see “JavaScript Entities” in Appendix B.) • Independent JavaScript is invoked—for example, the code that’s included as part of an enhanced TV trigger. Trusted pages that would otherwise run up against the limit can call this method to reset the counter to 0 as JavaScript is being executed. This should be done only rarely, and only when you’re certain that the script is absolutely safe.

ACCESS: HISTORY:

Controlled by the writing sublist of the principal ACL. Introduced in the 1.2.5 release.

Chapter 7: System Capabilities

315

System Object

Event Handlers
onerror()
SYNOPSIS:

void onerror(string type, string subtype, object victim, string problem, string badUrl) exclusive-read/exclusive-write handler Called when the system encounters various kinds of errors, before any other error handling occurs. If the system takes remedial action in face of the error— for example, if it displays a broken-image icon when it can’t find a requested image or it shows an error message to the user—it does so after this handler is called. Similarly, if another handler, such as Window.onerror(), is called for the same error, it’s called after System.onerror(). By notifying the master application of an error early, this handler gives it the opportunity to present appropriate information to the user, possibly get instructions from the user, and take corrective action. The type and subtype arguments categorize the error. The remaining arguments describe the error and identify the object that it victimizes. Each of the arguments is explained below: type subtype The type places the error in one of four categories—”http” for errors that occur during an HTTP fetch, “system” for errors that arise because of the inherent limitations of system software, “memory” for memory errors, and “mime” for errors that occur handling a MIME data type. The subtype explains the nature of the error in each category. The following type and subtype combinations are supported:

DESCRIPTION:

Type
“http”

Subtype
The HTTP error code—such as “404” when a requested document can’t be found or “501” when a server can’t respond to a request. “protocol”

Meaning
Error codes in the 400 range refer to apparent client errors and those in the 500 range refer to apparent server errors. Instead of a specific error code, the subtype may be “4xx” or “5xx” to indicate just the general nature of the error. TV Navigator doesn’t support the network protocol.

“system”

316

Content Developer’s Reference

System Object

Type
“memory”

Subtype
“javascript” “unknown” A MIME media type such as “text/plain” or “image/gif”

Meaning
The JavaScript context ran out of memory. The operating system ran out of memory. The browser didn’t have enough memory to handle some data of the specified MIME type. TV Navigator doesn’t support the MIME type. TV Navigator doesn’t support the specified version of the MIME type.

“mime”

“unsupported” “version”

victim problem The victim is the JavaScript object that suffers as a result of the error. It’s typically the object that owns the display that was altered because of the error—generally a Window object or an Image. The problem identifies, in general terms, what went wrong; it’s the location of the error. Each kind of problem is mapped to a particular type of victim. Therefore, you can tell the type of the victim object from the problem string, as shown in the following table:

Problem
“window” “background” “font” “image” “table background” “cell background”

Victim
a Window object a Window object a Window object an Image object a Table object a TableCell object

If the problem is a background of some sort, the window, table, or table cell will display a solid background instead of the one requested. If “image” is the problem, the image will display a broken-image icon instead of the requested image. However, these remedial actions are taken after onerror() returns.

Chapter 7: System Capabilities

317

System Object

badUrl The URL that caused the problem—for example, the URL of a document that couldn’t be parsed or of an image that couldn’t be decompressed and therefore caused a memory error. It’s possible for onerror() to try the URL again.
ACCESS:

Reserved for pages from the Service Manager’s domain.

onexternalevent()
SYNOPSIS:

void onexternalevent(string message) exclusive-read/exclusive-write handler Called to report an external event, an event whose source lies outside TV Navigator, the current application, or anything the user happens to be doing. External events arise from exterior conditions or communications. For example, an onexternalevent() call might inform the master application that the cable system wants it to present some information to its subscribers. Similarly, it might ask the master application to reboot so that it can get a clean start with corrected data. The handler allows the application to prepare for the impending shutdown and notify the user. External events can also serve platform-specific subsystems. For example, one might deliver a severe-weather warning, which would cause the master application to set off an alarm (through an Indicator object) and fetch specific information to display to users. The message argument categorizes the event and conveys information that may help the master application respond. Each platform defines its own set of events and its own messages. In a sense, this handler can be seen as a complement both to the control() method and to Indicator objects. Like them, it enables communication between a JavaScript application and the platform-dependent layers of the software. By calling control() or setting an Indicator, the application delivers output to the platform. By defining an onexternalevent() handler, it responds to input from the platform. In some cases, onexternalevent() may be implemented to simply pass the message string it receives to control() unchanged.

DESCRIPTION:

318

Content Developer’s Reference

System Object

Setting an Indicator is restricted to trusted applications, but onexternalevent() and control() are more exclusively reserved for the master application (the Service Manager and those closely associated services that share its domain).
ACCESS: SEE ALSO:

Reserved for pages from the Service Manager’s domain. control(), “Indicator Objects” on page 301

Chapter 7: System Capabilities

319

System Object

320

Content Developer’s Reference

Users and Services

CHAPTERM

A set-top box can host more than one user—each with distinctive properties, permissions, and preferences. For example, every member of a family could be registered as a separate user, so that they can all have their own e-mail accounts, young children can be blocked from watching certain shows, and everyone can customize the on-screen environment as they like. TV Navigator provides a mechanism and an API that permits the Service Manager (or a service with the same domain as the Service Manager) to manage users and the information associated with users. That information includes the lineup of services that are available in the deployment. Services are the modules that perform specific functions in the user interface. They’re associated with users so that individual users can customize the user experience. In some cases, the user might be able to choose among several alternative services that perform the same function—for example, two or more different e-mail applications. In other cases, users might be able to configure services as they prefer, so the same service would behave differently for different users.

Note: In some deployments, multiple users are not allowed. However, even then, a generic
“user” is installed on the set-top box and is able to customize services. It’s just that this user never varies (and probably is never revealed to the actual users of the box).

Object Overview
User and service data is kept on a server (in particular, the Datapoint server) and managed on the client through the following four objects: • The UserManager object handles all operations involving users. It can add and delete users, switch from one user to another, and allow guest users to be recognized on the set-top box. It keeps an array of User objects, one for each user it recognizes. • A User object records information about a particular user—the user’s name, password, permissions, and so on. Unlike the UserManager, it doesn’t manage anything; it’s simply a repository for user data. One of its properties is an array of Service objects.

Chapter 8: Users and Services

321

The User-Management Model

• A Service object represents an application or other service that’s available to the user. It records information about the service—such as its name, its URL, a description of what it does, and so on. It can be considered an extension of the User object. Like that object, it’s simply a collection of information. • An Authentication object permits the client to reestablish its authenticity to the server, when recoverable errors occur. The UserManager is a property of the Navigator object:
var um = navigator.userManager;

It provides access to User objects,
var firstUser = um.users[0];

and User objects, in turn, provide access to Service objects:
var firstService = firstUser.sysServices[0];

The Authentication object is a property of the UserManager:
var auth = um.authentication;

Any page can see if the UserManager is present, but only pages from the domain of the Service Manager can do anything with it or look at the other objects (although an exception is granted services so they can manage their own Service objects).

The User-Management Model
The user-management model that’s embodied in the UserManager, User, and Service objects has the features described in the following sections. Keep in mind that these features can be adapted to various types of user interface. They don’t all have to be presented to the user.

Current User
TV Navigator makes sure that there’s one and only one current user—the user who’s active and whose permissions and preferences are being enforced. The User object for the current user is located in the UserManager.users array, and is also recorded as the Navigator.curUser property:
var theUser = navigator.curUser;

This property may be null in the early stages of start-up and briefly when switching from one user to another, but otherwise there’s always a current user.

322

Content Developer’s Reference

The User-Management Model

Because a current user is required at all times, TV Navigator supplies one generic User object. If the UserManager doesn’t enroll any other users, this object will always be the current user, though it won’t appear to actual users of the machine that any particular user is identified as the current user.

Default User
TV Navigator automatically installs the default user as the current user when a session begins (when the set-top box is turned on). There’s no requirement for a user to log in. Currently, the User object that comes with the system is fixed as the default user.

User Identification
Individual users are identified by a name (unique among all users registered on the same settop box) and a password. The password is required to install a User as the current user and to do anything in the user’s name when the user isn’t the current user. Core services can require it for other operations. User objects verify passwords, but don’t reveal them (at least not to anyone who doesn’t already know the password). The password must be obtained from an independent source— typically, by asking the user for it. Passwords are encoded when they’re stored so that no one can illegally obtain them.

Administrative Privileges
User objects can be given (or be denied) administrative privileges—the right to manage other users. The current user must have administrative privileges for new users to be added or old ones removed. The current user must also have them to look at or modify most properties of other users.

Overriding the Current User
The UserManager permits you to perform JavaScript operations with the privileges and permissions of a user other than the current user—provided you know the user’s password. This feature enables an administrative user to take care of an administrative task without disturbing the current user. It’s not necessary to switch users to accomplish something the current user is barred from doing.

Chapter 8: Users and Services

323

User Interface

Roaming
Users can roam from their home machines and become guest users on other set-top boxes, using their passwords and a roaming name. Guest users cannot have administrative privileges and users with administrative privileges on the host machine can’t administer guest users—or even look at their properties. Other restrictions also apply: For example, it’s illegal to switch the current user from one guest user to another.

User Interface
The Service Manager or a designated service in the master application is responsible for providing a user interface for managing multiple users. In doing so, it can put whatever face it wants on the user-management model that TV Navigator provides. That model allows for various possibilities without mandating any particular form. For example, it doesn’t require user registration or a log-in procedure before the set-top box can be used. It would be possible to ask users to identify themselves only when they’re about to do something that’s userspecific. The master application can choose to expose or hide notions like the “current user,” “default user,” “password,” and “administrative privileges.” For example, it could automatically give all users the same password and never tell them about it or ask them for it. Similarly, instead of giving administrative privileges to individual users, it could confer those privileges temporarily when the user supplies a special password. This could be accomplished by reserving administrative privileges for a private User object. That object would never become the current user, but applications would require its password for certain operations and call UserManager.evalWithPrivileges() to perform them with the administrative privileges of the special user. The master application can also make whatever use it wants of the User object that comes with the system. It could, for example, give the object a more specific identity.

User and Service Properties
User information is stored in a database on a server (or servers). User and Service objects mirror this information and provide a means for the client to change it. Through the UserManager’s syncUserData() method, you can explicitly synchronize these objects with the database to ensure that they accurately represent the latest information and to have any changes you’ve made take immediate effect.

324

Content Developer’s Reference

User and Service Properties

System-Defined and Provider-Defined Properties
Every User object has a number of system-defined properties—for the user’s name, privileges, available services, language preferences, and so on. Similarly, every Service object has its own set of standard properties—for the name of the application, a logo, a set-up page, the language it currently displays, and so on. The standard properties of both objects are documented in this chapter. Typically, applications will need to record other service-specific and user-specific data—perhaps an address and phone number, credit information, the URL of a home page, a list of favorite Web sites, and so on. In some cases, cookies can be used to store this information. In others, the User or Service object is the appropriate place. (See “Cookies vs. User and Service Properties” later in this introduction.) Because User and Service properties merely reflect data stored in a server database, adding a new property requires configuration of the database, which must be done on the server. If you attempt to create a property on the client in the usual manner (by simply writing a script that uses the property), it won’t be recognized by the server and it won’t persist. When the current page is unloaded, the property will no longer exist. See the System Administration Guide for information on how to add properties to User and Service objects.

Disallowed Characters
In releases 1.1 and 1.2, string values for User and Service properties cannot contain three kinds of characters—semicolons (;), carriage returns (\r), and line feeds or new lines (\n). User passwords also bar tabs and spaces; they cannot contain semicolons or any white space characters. All other characters are permitted. Release 1.3 lifts all these restrictions. All characters are permitted.

Naming Convention
All system-defined properties (of both User and Service objects) begin with the prefix “sys”. This is because Liberate may define other properties in future releases. The prefix minimizes the possibility that our additions will clash with properties a service provider has already defined. If you choose another prefix for the properties you add (or at least refrain from using “sys”), there should be no conflict.

Chapter 8: Users and Services

325

Managing a Service

Passwords
One user property, the password, is not visible to anyone. There are methods to check it and change it, but no one can read it, not even users with administrative privileges.

Cookies vs. User and Service Properties
Not all user-specific data needs to be recorded as a User or Service property. In many situations, perhaps most situations, a cookie works perfectly well. Nevertheless, there are several differences between cookies and the properties of User and Service objects that you should keep in mind: • Cookies can be created by the client. User and Service properties cannot; they must be configured on a server. • Only the cookies of the current user are visible. However, the properties of all User and Service objects are visible when the current user has administrative privileges (as discussed in the next section). • Cookies are visible only to certain pages—typically, the pages that created them. User and Service properties are also visible only to certain pages, but a different set—pages with the right to access “exclusive” API. • There are no restrictions on modifying a cookie; any Web site that can look at a cookie can set it. However, User properties can be made read-only, and restrictions can be placed on who can view or modify the data, as described in the “Access Restrictions” section, next. • User and Service properties can participate in transactions on the server, so they can be managed in a way that keeps related properties consistent. It’s more difficult to manage a set of cookies on the server. Another apparent difference between a cookie and a User or Service property is that some browsers (but not TV Navigator) limits on the number of cookies that can be kept per machine and per user. When the limits are reached, some cookies are thrown away. Pages that create cookies are expected to regenerate them when they are destroyed; the cookie is a convenience.

Managing a Service
Each User object has a sysServices array with one Service object for each service in the deployment, whether or not the user has signed up for (or is even permitted to sign up for) the service. Each of the arrays presents the Service objects in the same order.

326

Content Developer’s Reference

Managing a Service

To make it easier to administer a service for all users on the set-top box, there’s also a sysServices array in the Navigator object, with objects for the same set of services as the User.sysServices arrays.
var machineLevelServices = navigator.sysServices;

The objects in Navigator.sysServices don’t belong to any particular user. Rather, they set values that apply to all users on the set-top box—except where a specific value has been set for a particular user. For example, suppose that a service has a winPosition property that determines where the service window will appear on-screen. It’s likely that a default value for this property is set for the entire deployment. By setting the winPosition property of the Service object taken from the Navigator.sysServices array, an administrative user can set a different default for all users on the set-top box. That default can, in turn, be overridden by individual users. The following section has more detailed information on managing Service object settings.

Setting and Getting Service Properties
Service properties can be set at any of three levels: • When a Service object is configured on the server, a default value is set for each of its properties. Those default values can be changed, but only on the server. • On the client machine, values can be set for the object in the Navigator.sysServices array. • Also on the client machine, values can be set for objects in the individual User.sysServices arrays. You normally look at Service properties only for individual users (through objects in the User.sysServices arrays). When you do, you see the value set for that particular user. If a value hasn’t been set for the user, you see the value set for all users on the set-top box (the value set in the Navigator.sysServices array). If a value hasn’t been set for the particular user or for all users on the machine, you see the default value set on the server. Consider what this means in a couple of cases: • Roaming. Users take their individual settings (settings in the User.sysServices arrays) with them when they roam to other machines. However, if they don’t have individual settings but rely on values set for all users on their home machines (settings in the Navigator.sysServices array) or on the deployment default, they may be faced with different values when they roam. As guests, they’re subject to the settings that apply locally on the host machine. • Changing the default. If a Service property is set for a particular user and later reset to the default value (the value set for the deployment or for all users on the machine), it remains

Chapter 8: Users and Services

327

Access Restrictions

a setting for that individual user. If the default value changes for the deployment or for the machine, it won’t change for the user. Currently there’s no way for the client to unset a Service property, at either the user or the machine level. Once a value has been set at the machine level (in Navigator.sysServices), the deployment value is forever blocked. Once a value is set at the user level (in User.sysServices), both the machine and deployments are blocked. They can be unblocked only on the server. When reading values of Service objects in the Navigator.sysServices array, you see only the values that were previously set at that level. If a value wasn’t set at machine level, the property will be null, not the deployment default.

Regulating User Access to a Service
The user’s access to a service is regulated from within the Service object itself. Three critical properties are involved: One, sysProviderConsent, records the service provider’s decision on the availability of the service—whether the user is blocked from using the service, required to have it, or allowed to decide whether or not to sign up for it. Another, sysAdminConsent, permits an administrative user to make a similar decision about the availability of the service for other users, in cases where the provider has left the decision open. The third, sysUserConsent, permits users to accept or reject services that the provider and administrative user have neither mandated or blocked.

Restricting Access to Service Objects
Access to Service objects is tightly restricted. The goal is to permit each service to access its own Service objects, but bar everyone else. This is accomplished through a Service property, sysTrustedUrl. The next section, “Access Restrictions,” explains how this property works.

Access Restrictions
Access to User and Service properties is regulated in three ways. Two are the same sorts of regulation that can apply to any JavaScript object; the third is specific to User and Service objects. They are: • Read/write restrictions. Some properties can be both read and written, while others are readonly. (In principle, some could also be write-only.) • Page restrictions. The JavaScript security mechanism may grant or deny access to certain properties depending on the origin of the page seeking access. This is the type of access control that this manual marks with the keywords “exclusive” and “controlled.” See “JavaScript Security” in Chapter 1 for a full explanation.

328

Content Developer’s Reference

Access Restrictions

• User restrictions. Access to User and Service properties may be further restricted depending on the identity and privileges of the current user. Access may be denied, for example, unless the current user has administrative privileges. These three types of restriction operate independently of each other. Any one of them can block access. For example, even if a page can access “exclusive” API, it cannot write a read-only variable. Even if the current user has administrative privileges, a page without “exclusive” rights cannot read User properties. The following sections describe how each type of restriction applies to User and Service objects.

Read/Write Restrictions
The writability of some User and Service properties can be contingent on other properties. For example, property P may be writable when property Q is false, but read-only when Q is true. These contingencies mainly affect the Service object and involve the properties that record whether the service is available to the user. In particular, when Service.sysProviderConsent is “blocked”, all the properties of the Service object are read-only; the service is not available to the user. When the client sets Service.sysAdminConsent to “blocked”, only that property can be written; all others are read-only. The administrative user has blocked the service, but can reverse that decision.

Page Restrictions
User and Service properties are protected by the “exclusive” access restriction, the most stringent limitation of this type possible. Normally, exclusive API elements can be accessed only by pages from the same server as the Service Manager. However, the rules are relaxed a bit so that services can manage their own Service objects and get necessary information about users. Every Service object has a sysTrustedUrl property. A page with a URL that matches that property is granted the right to access a limited subset of “exclusive” API. The subset includes: • The Service object itself—but not the Service objects of other services, unless the page also matches the sysTrustedUrl properties of those objects. • All the objects in the following paths:
navigator.userManager.users[index1].sysServices[index2].sysId navigator.curUser.sysServices[index].sysId navigator.sysServices[index].sysId

Chapter 8: Users and Services

329

Access Restrictions

In other words, any service can look at the sysId property of any Service object. Without this ability, a service could not find its own Service objects. • Certain properties of the User object. Different services may need different information about the user. Therefore, each service can be configured with permission to access a different set of User properties. In some cases, User properties are made available to all services. As noted previously, any service can read the sysServices array of any User. So that all services can discover the user’s language preferences, they can also read the User.sysLanguagePreferences property.

User Restrictions
Restrictions based on the current user apply only to User and Service objects. Access depends on the answers to two questions: Does the current user have administrative privileges? Does the target property you want to access belong to the current user? Depending on the property, access may be granted:

A. Only when the current user has administrative privileges. There are some things that
only an administrative user can do.

B. When either the current user has administrative privileges or the target user is the
current user. Current users are typically allowed to access their own properties.

C. When the current user has administrative privileges and the target user is not the
current user. The current user can be barred from accessing some properties.

D. At all times, no matter who the current user is.
These four possibilities can be diagrammed as follows: D B A C
Does the current user have administrative privileges? Does the target property belong to the current user? yes yes yes no no yes no no

330

Content Developer’s Reference

Access Restrictions

Access could be based on other combinations of answers—for example, only when the target property belongs to the current user—but these four are the restrictions that you’ll mainly see, in particular case B. Each property carries its own set of constraints. Getting a property value may be constrained differently than setting the value. The description of each User and Service property spells out these restrictions in the ACCESS section. When the required conditions are not met, setting the property fails and reading it yields a null value.

Note: Service objects in the Navigator.sysServices array aren’t associated with any particular
user; therefore, the answer to the second question (“Does the target property belong to the current user?”) is always “no” for properties of these objects. Typically, service properties fall under case B above—the target user must be the current user or the current user must have administrative privileges. Because there is no target user when the Service object is taken from Navigator.sysServices, the only relevant question is whether the current user has administrative privileges.

Chapter 8: Users and Services

331

Access Restrictions

332

Content Developer’s Reference

Authentication Object
Overview
Every time the server that stores user data (the Datapoint Server) communicates with a client machine, it makes sure that it is talking to an “authentic” client—and not, for example, to a pretender trying to steal services or gather information about the user.

Reauthentication
Only one detail of the authentication procedure is of concern here: When the client is first set up, the server supplies it with a machine password. The client stores the password in nonvolatile memory (NVRAM), but does not make it visible to users, Web pages, or applications. All communications from the client to the server must include the password, or the server will return an error and refuse to complete the transaction (except during periods when the server is not enforcing a strict security regime). The password is intended to prevent box cloning and identity theft. It’s possible for the machine password to be lost or corrupted, resulting in unintended communication failures. When this happens, someone can intervene and reset authentication parameters on the server so that a new machine password is generated. However, to minimize customer-service calls, the Authentication object provides a way to do it online in most cases. The procedure depends on setting up a key that reliably identifies a valid user of the set-top box. The Service Manager (or a closely allied service in the master application) can ask the user to supply a pair of strings—a key and a hint that will remind the user of the key. The hint could be a question and the key the answer known only to the user. Or the hint could be the first part of a phrase that the key completes. The hint could also be the URL for a reauthorization page that would derive the key by some more rigorous means. Anything is possible, as long as it yields a key that depends on the unique knowledge of the user. The master application doesn’t retain either the key or the hint; it passes both to the server (using the setKey() method). Then, when the client loses the machine password and transactions with the server fail, the server returns a special status code plus the hint. The master application can read the hint from an Authentication property and use it to obtain the key from the user. It sends the string it obtains to the server (through the reset() method). If the string matches the original key, the server issues a new machine password and re-authenticates the client. If you’re using the Emulator to develop content for TV Navigator, you should be aware that clearing NVRAM (for example, by deleting the NVRAM file) may result in the Datapoint Server

Chapter 8: Users and Services

333

Authentication Object

refusing to communicate with the client. One way to reestablish communication is to set up a re-authentication key, as described above.

Reconfiguration
Some authentication errors cannot be corrected by resetting the machine password. In some cases, it may be necessary to throw away all current user data and reset the client machine as if it just came out of the box. The Authentication object can initiate this type of reconfiguration when reset() is called without an argument.

Properties
hint
SYNOPSIS:

hint exclusive-read-only string The string that can be displayed to prompt the user for the key. This property is valid only when the status value is “reset needed”. In other words, it’s valid only when the client needs to be re-authenticated and the server has supplied the hint so that the user can be prompted for the key. The key would then be passed to the reset() method. Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. setKey(), reset()

DESCRIPTION:

ACCESS: HISTORY: SEE ALSO :

status
SYNOPSIS:

status exclusive-read-only string The authentication status of the client. Four values are possible: “waiting” The client has not yet communicated with the Datapoint server, or is currently in the process of contacting the server, or has already contacted the server, passed it authentication information, and is now waiting for a response.

DESCRIPTION:

334

Content Developer’s Reference

Authentication Object

“ok” The client and server have communicated, and the server determined that the client is authentic. “reset needed” The server cannot determine that the client is authentic, but the error is one that can be rectified through further communication. The hint property is valid and the reset() method can be called to reset the machine password and other authentication parameters. “failed” The server cannot determine that the client is authentic and the error cannot be corrected without reconfiguring the set-top box from scratch. It’s possible that the account has been disabled or that another machine is posing as this one. The master application should notify the cable or satellite service provider. Users can be given the option of trying reset() or contacting customer service. There is no notification when the status value changes. The master application must periodically check it. Typically, this needs to be done only when the client first contacts the Datapoint server at start-up after the set-top box has been turned on. When the status changes from “waiting” to “ok”, the master application can be sure of two things: (1) The data that was requested from the server has been loaded, processed, and is ready to use. (2) Authentication failures are unlikely for the duration of the session (so it’s not necessary to check status again).
ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. reset()

Methods
reset()
SYNOPSIS:

exclusive boolean reset(string key) exclusive boolean reset(void) Causes the set-top box to be reset to a previous safe state. The version of this method that takes an argument is the least intrusive. It passes the key string to

DESCRIPTION:

Chapter 8: Users and Services

335

Authentication Object

the server in an attempt to have it reset authentication parameters, including the machine password, without causing any other reconfiguration. When the status value is “reset needed”, the responsible service should get the previously set key from the user (prompting with the hint string). This version of the method should be called only for a status of “reset needed”; it won’t work when the status is “failed”. The version without an argument resets the set-top box back to factory defaults, before any users were registered and before anyone signed up for any services. The user will be asked to again set up the box from scratch. However, it doesn’t erase any data on the server, including the key and hint that were previously set. It may be appropriate to call this version of the method when the version that takes a key argument fails or when the status is “failed”. However, it may not work for some failures; in some cases, the user may need to contact the service provider. The process of reauthenticating or reconfiguring the client is asynchronous. If this method can successfully begin that process, it returns true and the onreset() handler will be called when the process is complete. If it returns false, the handler will not be called.
HISTORY:

Introduced in the 1.2 release. The version without an argument was added in the 1.2.5 release. Reserved for pages from the Service Manager’s domain. status

ACCESS: SEE ALSO :

setKey()
SYNOPSIS: DESCRIPTION:

exclusive boolean setKey(string key, string hint) Sets the key that can be used to re-authenticate the client and the hint that can be used to prompt the user for the key. The hint can be an empty string, but the key cannot. This method will be successful only if it’s called during a period when the client is able to authenticate itself to the server—that is, before communication fails.

336

Content Developer’s Reference

Authentication Object

Setting the key is an asynchronous process. If it can initiate the process, this method returns true and the onkeyset() handler will be called to report the result. If it can’t begin the process, it returns false and the handler is not called.
VARIATIONS:

In release 1.2, neither the key nor the hint can contain semicolons (;), carriage returns (\r), or line feeds (\n). The only allowed white space characters are tabs and spaces. In release 1.3, all characters are allowed, including semicolons, carriage returns, and line feeds.

ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. onkeyset()

Event Handlers
onkeyset()
SYNOPSIS:

void onkeyset(string status) exclusive-read/exclusive-write handler Called when the process initiated by setKey() is complete. If the status argument (not to be confused with the status property) is “ok”, the key and hint have successfully been set on the server. If status is “error”, the key and hint have not been set. Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. setKey()

DESCRIPTION:

ACCESS: HISTORY: SEE ALSO:

onreset()
SYNOPSIS:

void onreset(string status) exclusive-read/exclusive-write handler Called when the server has responded to the process begun by the reset() method. If the status argument is “ok” and reset() was called with a key

DESCRIPTION:

Chapter 8: Users and Services

337

Authentication Object

argument, the authenticity of the client has been reestablished. If status is “error”, the attempt has failed, perhaps because the key passed to reset() did not match the key last set by setKey(). If reset() was called without any arguments, an “ok” status indicates that the set-top box is ready to be reconfigured. If status is “error”, the box cannot be reconfigured without the intervention of humans. The user should be advised to contact the service provider.
ACCESS: HISTORY: SEE ALSO :

Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. reset()

338

Content Developer’s Reference

Service Objects
Overview
The first page that TV Navigator loads when the set-top box is turned on belongs to the Service Manager, an application that organizes the user interface for TV Navigator and makes other applications and modules available to the user. Those applications and modules are each represented by a Service object and are referred to as “services” in this manual. A service might be a full-fledged mail application, an interactive game, or an online programming guide. Or it might play a crucial but limited role in the user interface—such as changing the channel, adjusting the volume, adding new users, or displaying the list of recently visited Web sites. Service objects are primarily associated with users. Each User object keeps a sysServices array with one Service object for each service that’s part of the deployment:
var firstService = navigator.curUser.sysServices[0];

So that services can be easily managed for all users as a group, Service objects are also associated with the client machine, independent of any user:
var firstService = navigator.sysServices[0];

The two sysServices arrays contain objects representing the same set of services, arranged in the same order. Modifying the object for a particular user affects only that user, but modifying the machine-level object affects all users on the set-top box, except where a previous value was set for a particular user. Like other user data, Service objects are installed and configured on a server—through a Liberate Command wizard. They cannot be created in client-side JavaScript.

The Role of a Service Object
A Service object is not part of the service application itself. Rather, it describes the service, permits it to work with the Service Manager and other services, and gives it a place to store persistent, user-specific data. A Service object plays a number of interconnected roles: • It declares the availability of the service to the Service Manager. • It integrates the service into the user interface defined by the Service Manager. • It provides a script that the Service Manager can evaluate to set up the service for the user. The script informs the Service Manager what the service needs and how it should be treated. For example, a service can register a pop-up window for itself or claim a place for

Chapter 8: Users and Services

339

Service Objects

itself in the channels list. It can also register functions that the Service Manager should call and additional scripts it should evaluate at critical moments—for example, a key handler that would run the service when the user presses a particular key on the TV remote or a script that would clean up when the service is about to be unloaded. • It provides information that can be displayed to inform users about the service—for example, a name, logo, and a short description. • It lets users with administrative privileges block other users from a service, grant them permission to use it, or even mandate that they must use it. For example, a parent could block a child from a violent game. • It provides a mechanism for the service to sign up new users, in case an initial registration procedure is required. • It’s where the service can keep user-specific information that will persist even when the settop box is turned off (because it’s backed up by a server).

Standard Services
By itself, the Service Manager doesn’t have a user interface. It assigns all the user-interface work to specific services, which it organizes and coordinates. Each part of the interface is handled by a separate service. There are a number of standard services that Liberate supplies—one for the channel bar, another to control the volume, another to provide a menu and Web access, and so on. See the Service Developer’s Guide for a complete list. In addition, add-on applications like games, mail, chat, or a TV program guide are also treated as separate services, each with its own Service object.

Restrictions on Access
The properties of Service objects are subject to the same restrictions as User properties. The following paragraphs summarize how the various restrictions and exceptions discussed under “Access Restrictions” in the chapter introduction apply to Service objects. See that section for more detailed information.

Read/write restrictions. As documented here, all the properties of a Service object can be written as well as read, except for three groups:
• Properties that identify the service—sysId, sysInternalName, sysVersion, sysType, and sysTypeRequired. The values configured on the server cannot be overwritten by the client.

340

Content Developer’s Reference

Service Objects

• Properties that grant permission to use the service (except when a “superior” property authorizes them to be set). For example, if the administrative user mandates or blocks a service for a particular user, that user cannot override the administrative user’s decision. Similarly, an administrative user cannot override the service provider’s decision. See sysProviderConsent, sysAdminConsent, and sysUserConsent for a more complete explanation. • Properties that locate the service relative to other services and that, therefore, cannot be changed unilaterally. sysChannel is the prime example. All other properties are writable by default. However, when configuring a service, you can make these other properties of the object read-only—including properties you define for the service and those documented here as read/write.

Page restrictions. All Service properties are marked “exclusive,” indicating that they can be
accessed only from the Service Manager (or from pages sharing the Service Manager’s domain). However, this restriction is relaxed so that a service can manage its own Service object. Every Service object has a property, sysTrustedUrl, that determines which pages will be granted access to that object.

User restrictions. In general, a Service object can be seen or modified only if it is located in
the sysServices array of the current user (users can manage their own services) or the current user has administrative privileges (an administrative user can manage other users). Without administrative privileges, one user can’t look at the Service objects of another user or at the machine-level Service objects in Navigator.sysServices.

Access to User Properties
Pages that match the sysTrustedUrl of a Service object can access the properties of that object. So that they can find the Service object, they are also granted permission to read the sysServices arrays of User and Navigator objects. So that they can find out what language the user prefers, pages that match a sysTrustedUrl can also read the User.sysLanguagePreferences property. By default, sysServices and sysLanguagePreferences are the only two User properties that a service can see; pages that get “exclusive” rights through the sysTrustedUrl are generally barred from reading or writing any other User properties. However, some services may need to access certain other properties of the User object. For example, a mail application might record the user’s e-mail address as a User property, or the service that enables a parent to restrict the Web sites a child can visit may need to record data in the User.sysWebAccess property. Therefore, the configuration wizard lets you set up a service

Chapter 8: Users and Services

341

Service Objects

so that pages matching the sysTrustedUrl can read and write particular properties of User objects.

Default Values
When you configure a service (using a Liberate Command wizard), you can assign specific values to each Service property. These are the initial values that the client will see before it modifies the object. Because they may vary from deployment to deployment and from service to service, default values for Service properties are not documented here. For more on setting Service properties, see “Managing a Service” on page 326 in the introduction to this chapter.

Synchronization
Writing a Service property is just like modifying a property of the User object. The new value is not immediately delivered to the server unless you call UserManager.syncUserData().

Properties
sysAdminConsent sysBootUrl
SYNOPSIS:

see sysProviderConsent

sysBootUrl exclusive-read/exclusive-write string The URL of a page that the Service Manager can evaluate to discover needed information about the service—for example, which input keys it responds to, where it wants its overlay window to appear, and what it needs to do before and after switching to another user. The Service Manager evaluates the URL when the service application first becomes available—at startup and when switching to a new user brings a new or shut-down service into play. This mechanism allows services to register themselves and augment the Service Manager with their own code so that they can be seamlessly integrated into the

DESCRIPTION:

342

Content Developer’s Reference

Service Objects

user interface that the Service Manager defines. Among other things, the sysBootUrl page can: • Inform the Service Manager of its user-interface requirements. For the Liberate Service Manager, this means declaring whether it should be presented to the user as a channel (which the user could reach, for example, by pressing the channel-up and channel-down buttons on the TV remote), whether it will use a pop-up window, or whether it will simply load a page in the main window. • Register functions that the Service Manager should call and scripts it should evaluate at particular times. The functions typically respond to events and are called by the Service Manager’s event handlers. For example, a service might register a function that System.onerror() would call so that it could handle errors, or one that Net.onprogress() would call to let it respond to progress reports. Most services would need to register a key handler to respond to the key that launches the service. • Place its own code in the Service Manager so that it’s available to other services. For example, the channel bar service exports chanGoToChannel() for tuning to a specified channel.
ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. This property can be read and written only if the Service object belongs to the current user or the current user has administrative privileges.

HISTORY:

Introduced in the 1.2 release.

sysCancellationUrl sysChannel
SYNOPSIS:

see sysRegistrationUrl

sysChannel exclusive-read-only string The channel ID associated with the service—or null if the service will not be registered as a channel. The ID string must be short so that it will fit within the space allocated to the service in the channel grid.

DESCRIPTION:

Chapter 8: Users and Services

343

Service Objects

To register as a channel with the Liberate Service Manager, a service must call sRegisterChannel() within its sysBootUrl page. The “s” prefix identifies sRegisterChannel() as a function that the Service Manager defines.
ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. This property is readable only if the Service object belongs to the current user or the current user has administrative privileges.

HISTORY:

Introduced in the 1.2 release.

sysDescription
SYNOPSIS:

sysDescription exclusive-read/exclusive-write string A short description of the service, suitable for displaying to users. The description should be in ordinary text (the “text/plain” MIME media type), not HTML, and should be no longer than a single line. Typically, the page that presents the user with information about available services will use this description to briefly explain the service. If the user asks for more information, it can be obtained from the sysInfoUrl. The description string can be localized by the sysLocalizationUrl.

DESCRIPTION:

ACCESS:

SEE ALSO :

sysDisplayName, sysInfoUrl

344

Content Developer’s Reference

Service Objects

sysDisplayLanguage, sysLocalizationUrl
SYNOPSIS:

sysDisplayLanguage exclusive-read/exclusive-write string sysLocalizationUrl exclusive-read/exclusive-write string

DESCRIPTION:

sysDisplayLanguage records the current operating language of the service and of the Service properties that can be displayed to users—for example, whether sysDisplayName holds the French or the English name of the service. The value has the form specified by RFC 1766—typically a language code optionally followed by a hyphen and a two-letter country code or other suffix. However, the language is indicated by a three-letter code, rather than the earlier two-letter codes that RFC 1766 mentions. For example:
eng eng-AU eng-cockney tam fra nav

English Australian English Cockney English Tamil French Navajo

The three-letter codes are defined by ISO 639–2/T. At startup and when the user changes, the service that manages users compares sysDisplayLanguage to the preferred language of the user. If there’s a mismatch, it loads the service’s sysLocalizationUrl page, which should check the user’s preferences and do three things: • Adjust the service so that it conforms to the user’s language preference. • Reset localizable Service properties—such as sysDisplayName and sysLogoUrl—to reflect the new language. • Reset sysDisplayLanguage to inform the Service Manager of the language it is now using. The user’s language preferences are recorded in the sysLanguagePreferences property of the User object (Navigator.curUser). That property is a list of comma-separated strings, as described above, arranged in the order of the user’s

Chapter 8: Users and Services

345

Service Objects

preference. When comparing sysDisplayLanguage to sysLanguagePreferences, the following principles apply: • A specific display language can match a general preference—for example, displayed “eng-AU” will match preferred “eng”. • A specific preference must be matched exactly—for example, displayed “eng” will not match preferred “eng-AU”. • If a service can conform to more than one of the user’s language preferences, it should choose the one the user ranked highest. The sysLocalizationUrl will be able to reset Service properties only if it matches the sysTrustedUrl.
ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. These properties can be read and written only if the Service object belongs to the current user or the current user has administrative privileges.

HISTORY: SEE ALSO :

Introduced in the 1.2 release. sysDisplayName, sysLogoUrl, sysDescription, sysInfoUrl

sysDisplayName
SYNOPSIS:

sysDisplayName exclusive-read/exclusive-write string The name of the service as it should be displayed to users. The name should not include any HTML tags and should be short. If the service is registered as a channel with the Liberate Service Manager, it should be no longer than five characters so that it will fit in the limited space the channel grid provides for channel names. The name can be localized by the sysLocalizationUrl.

DESCRIPTION:

ACCESS:

346

Content Developer’s Reference

Service Objects

HISTORY: SEE ALSO:

This property replaced sysName in the 1.2 release. sysDescription

sysHeaderValue, sysHeaderUrl
SYNOPSIS:

sysHeaderValue exclusive-read/exclusive-write string sysHeaderUrl exclusive-read/exclusive-write string

DESCRIPTION:

sysHeaderValue is a string that supplies the value for an HTTP request header when requests are made for URLs matching the sysHeaderUrl. The name of the header is “x-sys-service”, so the full header will have the following form:
"x-sys-service: sysHeaderValue"

The header is included whenever the URL of an HTTP request contains the sysHeaderUrl—in other words, whenever the requested domain and pages with URLs matching the sysTrustedUrl matches or is a subdomain of the sysHeaderUrl domain and the requested path matches or is an extension of the sysHeaderUrl path. If the sysHeaderUrl protocol is https:, the header will be included only in secure requests. If it’s generic http:, it will be included in both secure and insecure requests. The same rules are used when comparing a URL to the domain and path of a cookie, or a candidate URL to the sysTrustedUrl. See that property for an example. If sysHeaderValue is null or sysHeaderUrl is an empty string, the header will not be sent.
ACCESS:

HISTORY: SEE ALSO:

These properties replaced sysHttpHeader and sysUseUrl in the 1.2 release. sysTrustedUrl

Chapter 8: Users and Services

347

Service Objects

sysHttpHeader

replaced, see sysHeaderValue

sysId, sysInternalName, sysVersion
SYNOPSIS:

sysId exclusive-read-only string sysInternalName exclusive-read-only string sysVersion exclusive-read-only string

DESCRIPTION:

These read-only properties identify the service. sysId uniquely identifies it across all implementations of all services in the deployment; no other service or version of a service can have the same ID. This string is typically not displayed to users. sysInternalName identifies the service without regard to version. No other service in the deployment can have the same internal name, but all versions of the same service must have the same name. The wizard that configures a service permits the string to contain only alphanumeric characters and the underscore (_). Unlike the display name, this name is not localized and is typically not displayed to users. sysVersion is the version number. It’s unique within the scope of sysInternalName. The wizard that configures a service permits only alphanumeric characters and a period (.) in the version string. The version may be displayed to users. The wizard that configures a service creates a suggested sysId from the other two properties when those properties are set, but it’s possible to choose another ID string—provided that it’s unique. Liberate reserves all IDs and internal names that begin with the characters “std” for itself. Developers should register with the Liberate PopTV program to reserve a portion of the namespace for themselves.

ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. The sysId property can also be read by any page that matches the sysTrustedUrl of any service (so that services can find their own Service objects).

348

Content Developer’s Reference

Service Objects

These properties are readable only if the Service object belongs to the current user or the current user has administrative privileges.
HISTORY: SEE ALSO:

sysVersion and sysInternalName were introduced in the 1.2 release. sysType

sysInfoUrl
SYNOPSIS:

sysInfoUrl exclusive-read/exclusive-write string The location of a page giving information about the service. This property can be localized by the sysLocalizationUrl. The sysDescription property has a shorter description of the service that can be included in other pages.

DESCRIPTION:

ACCESS:

SEE ALSO:

sysDescription

sysInternalName

see sysId see sysStatus

sysLastStatusChange sysLastUsed
HISTORY:

Deprecated in the 1.2 release.

Chapter 8: Users and Services

349

Service Objects

sysLocalizationUrl

see sysDisplayLanguage

sysLogoUrl, sysSmallLogoUrl
SYNOPSIS:

sysLogoUrl exclusive-read-only string sysSmallLogoUrl exclusive-read-only string

DESCRIPTION:

The location of logo images for the service. Like the service name and description (sysName and sysDescription), the logos are typically used by the application that presents service information to the user, not by the service itself. sysSmallLogoUrl is a small image suitable for displaying with the name in a list of services; sysLogoUrl is a larger image suitable for displaying in a more extensive layout, possibly with the service description or with the more detailed information obtained from the sysInfoUrl. These URLs can be localized by the sysLocalizationUrl.

ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. These properties are readable only if the Service object belongs to the current user or the current user has administrative privileges.

SEE ALSO :

sysDescription, sysDisplayName

sysName

replaced, see sysDisplayName

350

Content Developer’s Reference

Service Objects

sysProviderConsent, sysAdminConsent, sysUserConsent
SYNOPSIS:

sysProviderConsent exclusive-read-only string sysAdminConsent exclusive-read-only string, or exclusive-read/exclusive-write string sysUserConsent exclusive-read-only boolean, or exclusive-read/exclusive-write boolean (see the VARIATIONS section after the DESCRIPTION)

DESCRIPTION:

These three properties form a tiered system of consents that regulate the availability of the service to the user. Decisions at one tier cascade down to the tiers beneath. In the end, the Service Manager looks only at sysUserConsent; it will not run the service unless that property is true. Starting at the top, the three tiers are as follows: sysProviderConsent The first property records the approval of the service provider and is therefore always read-only. It has three possible values: “required” “blocked” “optional” If the value is “required”, sysAdminConsent also is “required” and sysUserConsent is true. In this case, neither of these other two properties is writable. The provider has decreed that the user must have the service. If sysProviderConsent is “blocked”, sysAdminConsent also is “blocked” and sysUserConsent is false. In this case, none of the properties of the Service object are writable. The provider has decreed that the user cannot have the service. Consequently, the Service object cannot be altered. If sysProviderConsent is “optional”, the decision falls through to the next tier, sysAdminConsent. sysAdminConsent This property records the administrative user’s decision about the availability of the service to the user, employing the same three values listed for sysProviderConsent. It’s writable only when the current user has

Chapter 8: Users and Services

351

Service Objects

administrative privileges and sysProviderConsent is “optional”. If sysProviderConsent is “blocked” or “required”, sysAdminConsent echoes those values. When sysAdminConsent is “blocked” because sysProviderConsent is “blocked”, none of the properties of the Service object are writable. When it’s “blocked” because a user with administrative privileges set it to “blocked”, no other properties of the Service object can be written, but this property remains writable. If sysAdminConsent is set to “required”, sysUserConsent will be true and read-only; the user must have the service. If it’s “blocked”, sysUserConsent will be false and everything in the object will be read-only (except sysAdminConsent); the user cannot run the service. However, if sysAdminConsent is “optional”, the decision is left to the user. sysUserConsent This property records the user’s decision whether to accept the service. It’s writable only if sysAdminConsent is “optional”. It’s read-only and true if sysAdminConsent is “required” and read-only and false if sysAdminConsent is “blocked”. The Service Manager loads the sysBootUrl only for services where sysUserConsent is true; it ignores services where this property is false.
VARIATIONS:

At the present time, all three properties are strings; sysUserConsent can be “true” or “false”. Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. These three properties are readable only if the Service object belongs to the current user or the current user has administrative privileges. However, they differ in the conditions that permit them to be written: • sysProviderConsent can never be written. • sysAdminConsent can be written only if the current user has administrative privileges and sysProviderConsent is “optional”. • sysUserConsent can be written only if (a) the Service object belongs to the current user or the current user has administrative privileges and (b) the other two properties are both “optional”.

ACCESS:

352

Content Developer’s Reference

Service Objects

HISTORY: SEE ALSO:

Introduced in the 1.2 release. sysBootUrl

sysRegistrationUrl, sysCancellationUrl, sysRegistered
SYNOPSIS:

sysRegistrationUrl exclusive-read/exclusive-write string sysCancellationUrl exclusive-read/exclusive-write string sysRegistered exclusive-read/exclusive-write boolean (see VARIATIONS )

DESCRIPTION:

These properties aid a service in signing up new users and getting rid of old users when they cancel. sysRegistered records whether the user is already registered for the service— true if the user is signed up, and false if not. sysRegistrationUrl is the URL of a page that the Service Manager will evaluate in two circumstances: • When the sysRegistered property is false and the value of sysUserConsent changes from false to true because of a user action. The change in value indicates that the user is signing up for the service (or an administrative user is signing up on the user’s behalf). • When a new user is created (through UserManager.addUser()) and the Service object for that user indicates that the user should be signed up (sysUserConsent is true) but is not yet registered (sysRegistered is false). Through its sysRegistrationUrl, a service can set user preferences and ask for any other user-specific information that it needs. Once it has registered the user, it should set sysRegistered to true. Alternatively, a service could not define a registration page (sysRegistrationUrl is null) and ask for the information when the user first begins running the service. sysCancellationUrl is a page that the Service Manager will evaluate in the opposite situation—when sysRegistered is true and sysUserConsent changes

Chapter 8: Users and Services

353

Service Objects

from true to false. It enables the service to get rid of any data it no longer needs for a user who has cancelled. The page should reset sysRegistered to false. Changes to sysUserConsent that are initiated on the server do not cause the sysRegistrationUrl or sysCancellationUrl to be evaluated.
VARIATIONS:

At the present time, sysRegistered is not a boolean, but a string with a value of “true” or “false”. Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. This property can be read and written only if the Service object belongs to the current user or the current user has administrative privileges.

ACCESS:

HISTORY:

Introduced in the 1.2 release. sysRegistrationUrl replaced sysSignupUrl.

sysRoot
SYNOPSIS:

sysRoot exclusive-read/exclusive-write string A string that extracts the common portion of various URLs stored as Service properties, permitting those properties to contain shorter strings. To obtain a fully qualified URL, you must concatenate the . . .Url property to sysRoot:
var qualifiedUrl = sysRoot + sysInfoUrl;

DESCRIPTION:

The Liberate Service Manager assumes that any . . .Url property without a colon (:) is relative to sysRoot. However, if the URL contains a colon, the Service Manager assumes it to be absolute and will not concatenate it.
ACCESS:

HISTORY:

Introduced in the 1.2 release.

354

Content Developer’s Reference

Service Objects

sysSignupUrl
HISTORY:

Deprecated in the 1.2 release. See sysRegistrationUrl for similar functionality.

sysSmallLogoUrl

see sysLogoUrl

sysStatus, sysLastStatusChange
SYNOPSIS:

sysStatus exclusive-read/exclusive-write string sysLastStatusChange exclusive-read/exclusive-write Date object

DESCRIPTION:

The current status of the service vis-à-vis the user, and the time when that status last changed. The values for sysStatus are not mandated and might vary from installation to installation. Possibilities include: “blocked” “required” “available” “offered” “declined” “on trial” “signed up” “canceled” Although some of these strings match the values that sysProviderConsent and sysAdminConsent can have, there are no formal dependencies between those properties and this one. TV Navigator does not automatically update sysStatus. However, it updates sysLastStatusChange whenever a value is assigned to sysStatus.

ACCESS:

Chapter 8: Users and Services

355

Service Objects

sysTrustedUrl
SYNOPSIS:

sysTrustedUrl exclusive-read/exclusive-write string The URL that a page must match to be granted access to the Service object as if it enjoyed “exclusive” rights, like pages from the domain of the Service Manager. This puts the management of the Service object in the hands of the service it describes. The match is calculated by the same rules used for cookies: • Only pages with URLs that contain the domain and path of the sysTrustedUrl will match. For example, if the value of this property is the string “http://acme.com/updater”, the following URL would be trusted because its domain includes the domain and its path includes the path of the sysTrustedUrl: http://talker.acme.com/updater/reconfig.html • In addition, if the sysTrustedUrl protocol is https:, only URLs with the same protocol will match. Pages that are trusted through this rule must be able to find the Service object. That means that they have to be able to read User objects from the UserManager.users array and get Service objects from the User.sysServices array. So that they can find the right Service object in the sysServices array, they are also permitted to read any Service object’s sysId property. In addition, trusted pages can access some User properties, as outlined under “Page Restrictions” in the chapter introduction. However, pages that get “exclusive” rights through the sysTrustedUrl are barred from other “exclusive” operations. For example, they can’t open a new window or define a System.onerror() handler.

DESCRIPTION:

ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs that match this property. This property can be read and written only if the Service object belongs to the current user or the current user has administrative privileges.

SEE ALSO :

sysId, “Page Restrictions” on page 329 in the chapter introduction, “Cookie Objects” on page 65

356

Content Developer’s Reference

Service Objects

sysType
SYNOPSIS:

sysType exclusive-read-only string The type of service—“mail”, “chat”, “chan” (for the channel bar), “hist” (for the history list), “vol” (for volume controls), and so on. Liberate’s Service Manager allows users to run only one service of a given type. For example, different users can have different “mail” services, but each user can be signed up for only one “mail” application at any given time. Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl. This property is readable only if the Service object belongs to the current user or the current user has administrative privileges.

DESCRIPTION:

ACCESS:

HISTORY: SEE ALSO:

Introduced in the 1.2 release. sysTypeRequired

sysTypeRequired
SYNOPSIS:

sysTypeRequired exclusive-read-only boolean (see the VARIATIONS section after the DESCRIPTION) Whether or not the user must have at least one service of the Service object’s sysType—true if such a service is required, and false if not. (For Liberate’s Service Manager, true means the user must have one and only one sysType service, since multiple services of the same type are not permitted.) When services are configured, the wizard enforces consistency in the sysTypeRequired property for all services of the same sysType. If the user can choose among two or more services of a required type, one of the services should be turned on by default (see sysUserConsent). (For the Liberate Service Manager to function properly, all other services of the same type must be off.)

DESCRIPTION:

VARIATIONS:

At the present time, this property is not a boolean, but a string with a value of “true” or “false”. Reserved for pages from the Service Manager’s domain and pages with URLs matching the service’s sysTrustedUrl.

ACCESS:

Chapter 8: Users and Services

357

Service Objects

This property is readable only if the Service object belongs to the current user or the current user has administrative privileges.
HISTORY: SEE ALSO :

Introduced in the 1.2 release. sysType

sysUserConsent sysUseUrl sysVersion

see sysProviderConsent

replaced, see sysHeaderValue see sysId

358

Content Developer’s Reference

User Objects
Overview
User objects represent identifiable users of the set-top box. Each object is a collection of persistent properties that describe a particular user. The object does nothing except hold information; all actions that affect users are performed by the UserManager. TV Navigator supplies just a single User object, a generic object for the default user. All other Users must be created by the UserManager, which can also delete users and change the current user. When it sets up a new User, the UserManager puts the object in its users array:
var userList = navigator.userManager.users; var ultimateUser = userList[userList.length - 1];

The Navigator object keeps track of the current user:
var who = navigator.curUser; if ( who.sysAdminEnabled == true ) { . . . }

For security reasons, User objects can be seen only by pages from the domain of the Service Manager, the first application that TV Navigator loads (although all services can read some User properties and individual services can be configured with permission to access others).

Properties
sysAdminEnabled
SYNOPSIS:

sysAdminEnabled exclusive-read/exclusive-write boolean (see the VARIATIONS section after the DESCRIPTION) Records whether the user has administrative privileges—the right to administer other user accounts. The current user must have administrative privileges for the UserManager to add or delete users and for most properties of other users to be examined or modified. By default, this property is true for the user that comes with TV Navigator (the default user), and false for all new users. Only the default user automatically has administrative privileges. However, if there are multiple users on the set-top

DESCRIPTION:

Chapter 8: Users and Services

359

User Objects

box, some with administrative privileges and some without, you should probably remove those privileges from the default user. If you don’t, anyone who turns on the box can do anything an administrator can. Administrative privileges can’t be granted to guest users (users roaming away from their home machines). Only users registered on the set-top box are eligible.
VARIATIONS:

At the present time, this property is not a boolean, but a string with a value of “true” or “false”. Reserved for pages from the Service Manager’s domain. This property is readable only when the User is the current user or the current user has administrative privileges. It can be written only if the current user has administrative privileges. It takes a user with administrative privileges to confer them on (or remove them from) another user.

ACCESS:

sysDefault
SYNOPSIS:

sysDefault exclusive-read-only boolean (see the VARIATIONS section after the DESCRIPTION) Marks the default user, the user that TV Navigator makes the current user when the set-top box is turned on. Currently, the user that comes with TV Navigator is fixed as the default user, so this property is true for that user and false for all others. These assignments cannot be changed. Nevertheless, the master application can override the default by immediately switching to another user at start-up. For example, it could automatically switch to the user that was the current user when the previous session ended (although it’s not a good idea for the initial user to have administrative privileges, unless all users have them). It could also ask for a user to log in at start-up, or let an administrative user on the set-top box pick the user who would customarily be the initial user.

DESCRIPTION:

VARIATIONS:

Currently, this property is not a boolean, but a string with a value of “true” or “false”. Reserved for pages from the Service Manager’s domain.

ACCESS:

360

Content Developer’s Reference

User Objects

This property is readable only when the User is the current user or the current user has administrative privileges.

sysFirstScreen
SYNOPSIS:

sysFirstScreen exclusive-read/exclusive-write string The first channel, service, or Web page that TV Navigator should display when the User becomes the current user. The default value for a new User object is an empty string. This property makes it possible to customize the starting point for each user— for example, a favorite channel or Web page—or to record what users were last doing before logging off, so they can begin again at the same place when logging in again. Liberate’s Service Manager interprets this property as follows: • If the string contains only digits, it is assumed to be a channel ID and the Service Manager attempts to tune to the channel. • If the string contains a colon (:), it is assumed to be a URL and the Service Manager attempts to load the page. The URL must be fully qualified; that is, it must begin with a protocol name followed by a colon. • If the string matches a service type (the Service.sysType property of any service the user is authorized to use), the Service Manager loads the service. • If the string is an empty string, the Service Manager displays a default channel or Web page.

DESCRIPTION:

ACCESS:

Reserved for pages from the Service Manager’s domain. This property can be read and written only if the User object is the current user or the current user has administrative privileges.

HISTORY:

Introduced in version 1.2.6.

Chapter 8: Users and Services

361

User Objects

sysLanguagePreferences
SYNOPSIS:

sysLanguagePreferences exclusive-read/exclusive-write string A list of comma-separated language identifiers indicating the languages that the user would prefer to see (and hear) in the user interface. The list is arranged in decreasing order of the user’s preference. The default value for a new user is an empty string. Individual language identifiers begin with a 3-character language code as specified by the ISO 639–2/T standard—for example, “eng” for English, “deu” for German, and “tam” for Tamil. The codes are case-sensitive. The language code can be followed by one or more optional tags specifying regional or dialectal variants of the language. Each tag begins with a hyphen. For example:
eng eng-UK eng-UK-cockney eng-AU

DESCRIPTION:

Languages not covered by ISO 639–2/T can be described using an “x-” or “i-” prefix:
i-navajo x-pig-latin

This should be rare. As outlined above, language identifiers have the form mandated by RFC 1766, except that the actual language codes are the 3-character strings specified in the more recent version of ISO 639, rather than the 2-character strings of the older version. When a service parses sysLanguagePreferences and compares the user’s preferences to its capabilities, it should register a match whenever the user’s specification is identical to or more general than its own. The user’s specification is more general than the services’s when it differs from the service’s only by the absence of one or more subtags. For example, if sysLanguagePreferences is,
"eng-UK,eng,esp-SP"

362

Content Developer’s Reference

User Objects

“eng-US” would match “eng” and “eng-UK” would match both “eng-UK” and “eng”. However, “esp” and “esp-PT” would not match. Users may want to include increasingly general specifications of their favorite languages—for example:
"eng-UK-cockney,eng-UK,eng" "eng-US,eng-AU,eng-UK,eng,fra-FR,fra,deu,ita"

In the first example, the user would prefer Cockney English if the service by some chance can provide it; if not, then some variety of the English spoken in the United Kingdom will do; and if not that, the user would settle for any form of English.
ACCESS:

Reserved for pages from the Service Manager’s domain and pages with URLs that match the sysTrustedUrl of any Service object. Because services must be able to discover the user’s language preferences, trusted pages of all services are able to read this property as if it was a property of the Service object. This property can be read and written only if the User object is the current user or the current user has administrative privileges.

HISTORY: SEE ALSO:

Introduced in the 1.2 release. Service.sysDisplayLanguage on page 345, Service.sysTrustedUrl on page 356, Display.programDefaults on page 41

sysMasterAppId
SYNOPSIS:

1.3 sysMasterAppId exclusive-read/exclusive-write string

DESCRIPTION:

A string that lets the Service Manager know the minimum set of services it should load for the user. Liberate’s Service Manager reads this property only at start-up, before TV Navigator contacts the Datapoint server to get user information and service data. It, therefore, reads it only for the “family” user, the initial user when the set-top box is turned on. This property is not meaningful for other users. Because they’re loaded before any network connections are verified, the services that this property identifies should be resident on the set-top box.

Chapter 8: Users and Services

363

User Objects

The Service Developer’s Guide has more information on how the master application ID is used.
HISTORY:

Introduced in the 1.3 release.

sysName, sysRoamingName
SYNOPSIS:

sysName exclusive-read/exclusive-write string sysRoamingName exclusive-read-only string

DESCRIPTION:

The names that identify the user. sysName is the local name used for most purposes—such as, for e-mail or switching users—and is initially set when the User object is created. Each user must have a sysName that’s unique within the set of users registered on the set-top box. The default name for the user that comes with TV Navigator is “family”. sysRoamingName has a wider scope. It’s unique to all users known to the service provider, or all users of a particular system or within a particular area. By using this name, users can “roam” and be recognized as guests on machines other than the home machines where they’re registered. Some systems will automatically choose a roaming name for users—for example, they might use the user’s e-mail address, which must be a unique string. Others will require it to be set by customer service personnel. Some may give users a way to try out names until, through trial and error, they find one that’s unique. Names and roaming names can be up to 512 characters long.

ACCESS:

Reserved for pages from the Service Manager’s domain. sysName can be read by anyone; any user can find out who the other registered users are. However, it can be changed only if the User is the current user or the current user has administrative privileges. sysRoamingName cannot be read (or written) unless the User is the current user or the current user has administrative privileges.

SEE ALSO :

UserManager.addUser() on page 370, UserManager.switchToUser() on page 372

sysRoamingName

see sysName

364

Content Developer’s Reference

User Objects

sysServices
SYNOPSIS:

sysServices exclusive-read-only array of Service objects sysServices.length read-only number

DESCRIPTION:

An array of Service objects. Each object in the array describes a service that’s part of the deployment and visible to the master application—whether or not the service is actually available to the user, or to any user on the set-top box. Services are defined in the “Overview” section for the Service object. Reserved for pages from the Service Manager’s domain and pages with URLs that match the sysTrustedUrl of any Service object. Because services must be able to find their own Service objects, trusted pages of all services are able to read this property as if it was a property of the Service object. This property is readable only if the User object is the current user or the current user has administrative privileges.

ACCESS:

SEE ALSO:

Service.sysTrustedUrl on page 356, “Service Objects” on page 339

sysSetupDone
SYNOPSIS:

sysSetupDone exclusive-read/exclusive-write boolean (see the VARIATIONS section after the DESCRIPTION) Records whether the user has run a set-up procedure defined by the master application—true if the procedure has been successfully completed and false otherwise. The default for a new user is false. It’s up to the master application to update this property and determine how it should be used—or whether it should be used at all.

DESCRIPTION:

VARIATIONS:

At the present time, this property is not a boolean, but a string with a value of “true” or “false”. Reserved for pages from the Service Manager’s domain. This property can be read and written only if the User object is the current user or the current user has administrative privileges.

ACCESS:

Chapter 8: Users and Services

365

User Objects

sysUniqueId
SYNOPSIS:

sysUniqueId exclusive-read-only string A string that uniquely identifies the user in the universe of all users in a deployment. The system assigns this identifier when the User object is created. The algorithm that generates the string makes it next to impossible for the same identifier ever to be assigned to more than one user. The ID is therefore universally unique. TV Navigator uses this property to make sure that no one else is masquerading as the user. It identifies the user in the user database, it might be recorded on the user’s smart card, and it could be employed by services that the user subscribes to. Unlike the password and roaming name, it’s not something that users are required to remember.

DESCRIPTION:

ACCESS:

Reserved for pages from the Service Manager’s domain. This property is readable only if the User object is the current user or the current user has administrative privileges.

sysWebAccess
SYNOPSIS:

sysWebAccess exclusive-read/exclusive-write string A string that records constraints on the user’s freedom to access Web sites—for example, constraints that would prevent a child from viewing “adult” sites. The string holds information needed to impose the appropriate limitations on the user. It might name a category of user (such as, “child under 8”), a level of protection, or a set of permissions and constraints (“adult, no violence”). The precise format of the string depends on the service provider. The default value for all new users is an empty string.

DESCRIPTION:

VARIATIONS: ACCESS:

Currently, the default value is “default”. Reserved for pages from the Service Manager’s domain. This property is readable only if the User object is the current user or the current user has administrative privileges. It can be written only if the current user has administrative privileges.

366

Content Developer’s Reference

User Objects

Methods
changePassword()
SYNOPSIS: DESCRIPTION:

exclusive boolean changePassword(string newPassword, string oldPassword) Changes the user’s password from oldPassword to newPassword. Passwords don’t have to be unique. If the user doesn’t have a password, oldPassword should be an empty string (“”). If newPassword is an empty string, this method gets rid of the user’s password. The generic user provided with TV Navigator doesn’t have a password. The oldPassword argument is not always required. The rules are as follows: • If the User object is the current user, the oldPassword must exactly match the user’s current password. You can set the password of the current user, but only if you know the current password. • If the User object is not the current user but the current user has administrative privileges, the oldPassword is ignored and can be omitted. A user with administrative privileges can arbitrarily change the password of any other user. • If the User object is not the current user and the current user does not have administrative privileges, this method fails. Passwords are limited to 512 characters. The service that enables users to set a password can, of course, impose its own limit. If successful in installing a new password, changePassword() returns true. If not, it returns false.

VARIATIONS:

In releases 1.1 and 1.2, passwords cannot contain semicolons or any white space characters, including carriage returns, line feeds, spaces, or tabs. Nevertheless, the Service Manager (or its user-management service) can allow users to put these characters in their passwords, if it translates them to permitted characters before passing the string to User and UserManager functions. In release 1.3, all characters are permitted.

ACCESS:

Reserved for pages from the Service Manager’s domain.

Chapter 8: Users and Services

367

User Objects

The password can be changed only if the User object is the current user or the current user has administrative privileges.
SEE ALSO :

checkPassword(), String.encrypt() on page 95

checkPassword()
SYNOPSIS: DESCRIPTION:

exclusive boolean checkPassword(string password) Returns true if the password string passed as an argument exactly matches the user’s current password, and false otherwise. If passed an empty string, this method reports whether the user has a password. It returns false if the user has one, and true if not.

ACCESS:

Reserved for pages from the Service Manager’s domain. There are no user-based restrictions on checking a user’s password. Any user can check another user’s password, even without administrative privileges.

SEE ALSO :

changePassword(), String.encrypt() on page 95

368

Content Developer’s Reference

UserManager Object
Overview
As its name indicates, the UserManager object manages a group of users on a set-top box. It can: • Add users to the machine—give them an identity so that they can receive e-mail, keep track of favorite Web sites, and so on—and delete users previously added. • Switch from one user to another. • Enable a user to perform particular operations without switching to that user. • Synchronize user data on the set-top box with the data stored in the server database. Each user is represented by a User object. The UserManager keeps a list of these objects and is the only agent that can modify the list. However, it doesn’t manage the information associated with particular users. It leaves that task to the individual User objects. The UserManager is a read-only property of the Navigator array:
var theManager = navigator.userManager;

Although anyone can get the UserManager object as shown above, for security reasons only pages with “exclusive” access privileges can call its methods or look at its properties.

Properties
authentication
SYNOPSIS:

authentication read-only Authentication object An object that enables the client machine to reestablish itself as “authentic” in the eyes of the server that holds user data (the Datapoint Server). Reserved for pages from the Service Manager’s domain. Introduced in the 1.2 release. “Authentication Object” on page 333

DESCRIPTION:

ACCESS: HISTORY: SEE ALSO:

Chapter 8: Users and Services

369

UserManager Object

users
SYNOPSIS:

users exclusive-read-only array of User objects users.length exclusive-read-only number

DESCRIPTION:

An array of User objects. Each object represents one identifiable user of the machine. The addUser() method creates User objects and adds them to the array; deleteUser() removes them. The array can be accessed using either numerical indexes,
var firstUser = navigator.userManager.users[0];

or a user name (the User.sysName property):
var tommy = navigator.userManager.users["tomj"]; var tommy = navigator.userManager.users.tomj;

Each user must have a name that’s unique among all the users registered on the set-top box. Guest users (roaming users) are not added to the array and are therefore exempt from this requirement. Before addUser() puts any users in the array, the array has just one User object, for the default user named “family” that comes with TV Navigator. The length property records the number of User objects currently in the array, the number of registered users on the machine.
ACCESS: SEE ALSO :

Reserved for pages from the Service Manager’s domain. “User Objects” on page 359

Methods
addUser(), deleteUser()
SYNOPSIS:

exclusive boolean addUser(string name, string password) exclusive boolean deleteUser(object user)

DESCRIPTION:

These methods register users for the set-top box and remove users previously registered. addUser() begins the registration process that will place a new User

370

Content Developer’s Reference

UserManager Object

object with a specified name and password at the end of the users array. The name must not match the name of any other user already in the array. Unlike the name, the password doesn’t have to be unique and can be an empty string. User names and passwords can be up to 512 bytes long. deleteUser() removes the user object from the users array. It’s illegal to delete the current user, a guest user, or the default user provided with TV Navigator. These methods fail if the current user does not have administrative privileges. If all goes well—if the name is unique, the current user has administrative privileges, the user targeted for deletion isn’t the default user, and so on— addUser() and deleteUser() initiate the process of adding or deleting a user and return true. They return before the entire process, which may involve communication with a server, can be completed. The onadd() and ondelete() handlers are then called when the operation is done. If you’re adding a new user, you have to wait until the onadd() call before setting any User attributes (other than the initial name and password). You can’t be sure that the new User object has appeared in the users array until the handler is called. If they cannot initiate the addition or deletion of a user, addUser() and deleteUser() return false. The operation fails and the handlers aren’t called.
VARIATIONS:

In releases 1.1 and 1.2, user names and passwords can’t include semicolons, carriage returns, or line feeds. In addition, passwords can’t contain tabs or spaces, although names can. In release 1.3, all characters are allowed.

ACCESS: SEE ALSO:

Reserved for pages from the Service Manager’s domain. onadd(), User.sysName on page 364, User.changePassword() on page 367

evalWithPrivileges()
SYNOPSIS: DESCRIPTION:

exclusive boolean evalWithPrivileges(object user, string password, string javascript) Executes a string of javascript code in the current context, but with the privileges of the specified user object rather than the current user. The user must be an object registered on the set-top box and the password must match that object’s password—or be an empty string if the user doesn’t have a password.

Chapter 8: Users and Services

371

UserManager Object

This method doesn’t switch users; instead it allows some JavaScript to be interpreted as if another object was the current user. For example, the master application could permit a user to briefly check e-mail messages while leaving the current user in place. Typically, evalWithPrivileges() allows a user with administrative privileges to accomplish something without becoming the current user. For example, a parent could enable a child to watch a blocked TV program—then leave the room knowing that all the normal restrictions on the child are still in place. In most respects, this method is similar to the standard Object.eval() function. However, it doesn’t return a value from the JavaScript it evaluates. It returns true if the user and password are correctly specified and it can interpret the javascript string, and false otherwise.
ACCESS: SEE ALSO :

Reserved for pages from the Service Manager’s domain. “User Objects” on page 359

switchToUser()
SYNOPSIS:

exclusive boolean switchToUser(object user, string password) exclusive boolean switchToUser(string roamingName, string password) Installs a user as the current user (as Navigator.curUser), provided that the second argument is the correct password for that user. If the user doesn’t have a password, the argument should be an empty string. The user can be identified either by a User object (user) or by a name that’s unique among all users known to the service provider (roamingName). The version of this method that takes a user argument is the more efficient of the two, but is limited to users registered on the set-top box. The User object is taken from the users array:
var desiredUser = navigator.userManager.users.sidney; if ( navigator.userManager.switchToUser(desiredUser, "z2xW*!v") ) . . .

DESCRIPTION:

The version that takes a roamingName argument allows a user registered elsewhere to be recognized and become the current user (that is, to roam). In this case, the UserManager creates a temporary User object for the guest and assigns it to Navigator.curUser, but doesn’t put the temporary object in the users array.

372

Content Developer’s Reference

UserManager Object

If TV Navigator has a two-way Internet connection, this method contacts the server (much as syncUserData() would) to make sure that all data for the new current user is up-to-date. If it doesn’t have a two-way connection or can’t communicate with the server, it nevertheless will switch to a known user. However, switching to a guest user always requires server communication. switchToUser() is asynchronous. If it can begin the process of changing users, it returns true and a subsequent onswitch() call will let you know whether or not the switch could be completed. If it can’t begin changing users—for example, if the arguments it’s passed are not well formed or the target user is already the current user—it returns false. In this case, the current user remains the same and onswitch() won’t be called.
ACCESS: SEE ALSO:

Reserved for pages from the Service Manager’s domain. onswitch(), Navigator.curUser on page 86

syncUserData(), writeUserData()
SYNOPSIS:

exclusive boolean syncUserData(void) exclusive boolean syncUserData(object user) exclusive boolean writeUserData(void) exclusive boolean writeUserData(object user)

DESCRIPTION:

These methods write user data to the server database—and, in the case of syncUserData(), read user data back from the server. They affect just one user at a time—the particular user indicated by the User object passed as an argument, or the current user if called without an argument. If changes have been made to the User object in question, or to any Service objects in its sysServices array, writeUserData() makes sure the server picks up those changes. syncUserData() goes a step further: After writing the client’s changes, it reads the server’s settings for all the user’s data. Therefore, the client will pick up changes that have been made on the server. For example, imagine three items of user data, X, Y, and X as illustrated in the following diagram. On the client, X and Y have been modified to XC and YC. On the server, Y and Z have been modified to YS and ZS. writeUserData() makes the server values match the client; syncUserData() also makes the client values match the server. Note that the server change to Y is lost; the change on the client takes precedence.

Chapter 8: Users and Services

373

UserManager Object

client X→X Y → YC Z client XC YC Z client X YC ZS
C C

server X Y → YS Z → ZS server writeUserData() XC YC ZS server syncUserData() XC YC ZS

Since much less time is consumed sending data to the server than receiving it, writeUserData() is the more efficient of the two methods. You would call one of these methods if you’ve made a change to user data and want the change to take effect immediately. By default, changes are conveyed to the server lazily—when it’s convenient to do so. You may not be able to wait for an automatic update if an impending action depends on the change you’re making. For example, if a user subscribes to a service, you may call writeUserData() to complete the subscription so the user can begin using the service right away. In addition, there are two situations in which it’s advisable to call syncUserData() rather than the lighter-weight writeUserData(): • Before examining data for a user other than the current user. (The switchToUser() method automatically synchronizes data for the user it installs as the current user, but the data for other users may not be up-todate. By calling syncUserData() you can make sure you get the latest information.) • Before changing any data for a user, if the change you’re about to make depends on the current value. These methods return true if they can begin writing data to the server, and false if not. They might return false, for example, if TV Navigator doesn’t have a

374

Content Developer’s Reference

UserManager Object

two-way Internet connection that allows the UserManager to communicate with the server, or if the user argument isn’t a User object. If syncUserData() returns true, the onsync() handler will be called when the synchronization process is complete. If writeUserData() returns true, onwrite() will be called when the server acknowledges receiving the data. If either method returns false, the handlers won’t be called.
ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. writeUserData() was introduced in the 1.2.6.1 release. onsync()

Event Handlers
onadd(), ondelete()
SYNOPSIS:

void onadd(object user, string status) exclusive-read/exclusive-write handler void ondelete(string status) exclusive-read/exclusive-write handler

DESCRIPTION:

These handlers are counterparts to the addUser() and deleteUser() methods. Those methods begin the process of adding a new user or deleting an existing one. Their respective handlers are called to notify you when the process is complete and to inform you whether or not it was successful. If the status argument is “ok”, the operation was a success; if it’s “error”, the operation failed. When a user is successfully added, a new User object is created, initialized, appended to the users array, and passed to onadd() as the user argument. If the user couldn’t be added, a new object will not have been created and the user argument is null. If ondelete() is called with a status of “error”, the User object that deleteUser() got rid of will reappear in the users array. The handlers are not called if their counterpart methods return false.

ACCESS: SEE ALSO:

Reserved for pages from the Service Manager’s domain. addUser()

Chapter 8: Users and Services

375

UserManager Object

onswitch()
SYNOPSIS:

void onswitch(object user, string status) exclusive-read/exclusive-write handler Called when switching from one user to another. If the status argument is “ok”, the switch was successful. If status is “error”, it failed. Switching users is initiated by the switchToUser() method; onswitch() is called to report the outcome if that method returns true, but not if it returns false. Depending on the platform, onswitch() may also be called when a smart card for a guest user is inserted or ejected. When the switch is successful (status is “ok”), one User object may simply replace another as the current user (as Navigator.curUser). In that case, onswitch() is called just once, with the new current user as the user argument. However, there may be a brief interval between the instant when one User object loses its status as the current user and the moment when another object gains that status. During that interval, there is no current user (curUser is null). At the beginning of the interval, onswitch() is called with a null user argument to indicate that the current user has been dethroned. It’s called again at the end of the interval with the newly installed current user as the user argument. If the switch fails (status is “error”), the user argument is invalid. It will fail, for example, if switchToUser() is passed an incorrect roaming name. On failure, there’s likely to be just one onswitch() call, rather than two. To be sure that the switch has taken place, check both arguments—that status is “ok” and that the target User object shows up as the user argument.

DESCRIPTION:

ACCESS: SEE ALSO :

Reserved for pages from the Service Manager’s domain. switchToUser()

376

Content Developer’s Reference

UserManager Object

onsync(), onwrite()
SYNOPSIS:

void onsync(object user, string status) exclusive-read/exclusive-write handler void onwrite(object user, string status) exclusive-read/exclusive-write handler

DESCRIPTION:

Called to report that the actions begun by syncUserData() and writeUserData() are complete. The user argument is the User object whose data is being written to or synchronized with the user database. If status is “ok”, the database accurately reflects the properties set for the user object (including all Service objects in its sysServices array)—and, in the case of onsync(), the User and Service objects accurately reflect the attributes recorded in the server database. If status is “error”, the data could not be written or synchronized for some reason—possibly because the two-way network is down, making it impossible to contact the server. These handlers are not called if the corresponding method (syncUserData() or writeUserData()) returns false.

ACCESS: HISTORY: SEE ALSO:

Reserved for pages from the Service Manager’s domain. onwrite() was introduced in the 1.2.6.1 release. syncUserData()

onwrite()

see onsync()

Chapter 8: Users and Services

377

UserManager Object

378

Content Developer’s Reference

Content Data Types

CHAPTERM

TV Navigator has the built-in ability to handle various types of data retrieved over the Internet. This chapter lists the types it handles without any help—the audio types it can play, the text and image types it can display, and so on. It shows the content-type string (the MIME media type) along with the file extensions that typically identify the type—for example, “audio/wav” and something.wav for a file with data in the Waveform Audio File Format. Because TV Navigator is a thin client, some of the work of interpreting incoming data may be taken over by a server, particularly the Liberate Transcode server. The server processes incoming data and translates it to another, private type for more efficient handling by the client software. For example, the TV Navigator client can display JPEG and GIF images although it never sees the JPEG and GIF data formats. The server converts these formats to a third type before sending the data to the client. This chapter documents the MIME media types that the server and client, working together, can handle. It doesn’t document the private types used internally between client and server.

Text Formats
text/plain
EXTENSIONS: DESCRIPTION:

.txt etc. Plain text not formatted with HTML tags.

text/html
EXTENSIONS: DESCRIPTION:

.html, .htm HTML documents. The HTML tags and attributes that TV Navigator supports are listed in Appendix A, “HTML Catalog.”

Chapter 9: Content Data Types

379

Audio Formats

Audio Formats
Beginning with release 1.3, TV Navigator supports sampled audio data in the WAV, AIFF, and AU formats. It accepts both monaural and stereo data sampled at all standard rates, namely:
8.000 kHz 11.025 kHz 12.000 kHz 16.000 kHz 22.050 kHz 24.000 kHz 32.000 kHz 44.100 kHz 48.000 kHz

However, the three formats differ in which compression schemes and sample sizes are supported. Those differences are described in the list of types that follows. Although a range of sampled audio data is understood—including all common encodings—the Transcode server simplifies the variety for the client. It currently translates all audio data to a single format at one encoding, sample rate, and sample size before delivering it to the set-top box. In the 1.1 and 1.2 releases, all sound data must be in the WAV format, uncompressed, monaural, and sampled at 8 bits per second.

audio/aiff, audio/x-aiff
EXTENSIONS: DESCRIPTION:

1.3

.aiff, .aif Audio Interchange File Format (AIFF), developed by Apple Computer and used mainly on their computers. TV Navigator supports only uncompressed, linear PCM (Pulse Code Modulation) encodings at either 8 or 16 bits per sample. Support for this format was introduced in release 1.3.

HISTORY:

audio/basic
EXTENSIONS: DESCRIPTION:

1.3

.au Audio (AU) format, developed by Sun Microsystems and originally used on UNIX machines. Several encodings are supported, primarily the following: • Uncompressed, linear PCM encoding, either integer or floating point, at 8, 16, or 32 bits per sample. • Conventional A-law and µ-law compression (the CCITT G711 standard).

380

Content Developer’s Reference

Image and Video Formats

In addition, two versions of ADPCM (Adaptive Differential Pulse Code Modulation) encoding are supported on an experimental basis: • G721 compression at 4 bits per sample. • G723 compression at 3 or 5 bits per sample.
HISTORY:

Support for this format was introduced in release 1.3.

audio/wav, audio/x-wav
EXTENSIONS: DESCRIPTION:

.wav Waveform Audio File Format (WAV), first defined by Microsoft for multimedia extensions to Windows and now an Internet standard. The supported encodings are: • Uncompressed, linear PCM encoding at 8 or 16 bits per sample. Floating point is not supported. • A-law and µ-law compression (the G711 standard). • Microsoft ADPCM compression. • IMA (Interactive Multimedia Association) ADPCM compression. • G721 ADPCM compression.

HISTORY:

Prior to release 1.3, only linearly encoded (uncompressed) WAV files sampled at 11.025 kHz and 8 bits per sample were supported.

Image and Video Formats
image/gif
EXTENSIONS: DESCRIPTION:

.gif The GIF format (Graphic Interchange Format) for representing image data.

Chapter 9: Content Data Types

381

Other Formats

image/jpeg
EXTENSIONS: DESCRIPTION:

.jpeg, .jpg, .jpe, etc. The JPEG (Joint Photographic Experts Group) format for compressed image data.

image/png
EXTENSIONS: DESCRIPTION:

.png The Portable Network Graphics (PNG) format, for animation.

Other Formats
application/x-javascript
EXTENSIONS: DESCRIPTION: VARIATIONS:

.js, .mocha JavaScript code. TV Navigator currently identifies JavaScript code in files with the extension .wnj as the “application/x-dtv-script” type. In practice, there is no difference between this type and “application/x-javascript”. This redundancy simply lets you distinguish one sort of JavaScript file from another. For example, you could mark files that use the Liberate extensions with the .wnj extension and reserve .js for more generic files (or use .js for files with the extensions and .wnj for the others).

application/x-shockwave-flash
EXTENSIONS: DESCRIPTION: HISTORY: SEE ALSO :

1.3

.swf The data format for Macromedia Flash movies. Introduced in the 1.3 release. Appendix E, “Playing Flash Movies”

382

Content Developer’s Reference

Protocols

CHAPTERM

This chapter lists the protocol names that can appear in URLs understood by TV Navigator. Standard protocols are listed here, but are not described in any detail. The protocols that are peculiar to the TV environment—tv: and mcast:—are discussed more fully.

Protocols for TV and Broadcast
tv:
SYNOPSIS: DESCRIPTION:

tv:[channel][#src=(left,top,width,height)] Places television in a Web page and optionally specifies two things: the source of video input (the channel) and the part of the television picture to be displayed (a rectangle defined by the left, top, width, and height parameters). In general, the tv: protocol can be used anywhere that a URL can specify image data. Specifically, it can set the src attribute of an <img> or <frame> element and the background attribute of a handful of other elements:
<img src="tv:" . . .> <frame src="tv:" . . .> <body background="tv:" . . .> <frameset background="tv:" . . .> <td background="tv:" . . .>

It can also be the destination of a link:
<a href="tv:">

In JavaScript, it can be used in comparable places:
document.myImage.src = "tv:"; window.location = "tv:";

Chapter 10: Protocols

383

Protocols for TV and Broadcast

window.open(“tv:”, . . .); document.myTable.rows[0].cells[0].background = "tv:";

Tuning. If a channel ID immediately follows the protocol name, TV Navigator
will, if possible, tune to the specified channel. For example:
<img src="tv:12" . . .> window.location = "tv:5";

Channel IDs are strings, so “12” is not the same as “0x0C” and “5” is not the same as “05” or “005”. The string that follows tv: must exactly match the id property of a TvChannel object. In theory, you can also specify the video source by channel name,
"tv:cnn", "tv:kron"

or by a network name,
"tv:abc", "tv:fox"

provided that information is available that would permit the system to map those names to channel IDs. Channel and network names are case insensitive. If an ID or name is omitted, tv: adds video to the page, but retains the current tuning.

Note: In the current release, channel IDs are supported, but channel and
network names are not.

Scaling the picture. By default, a tv: URL places the full television picture on
the page and scales it to fit the container (the window, frame, image, or table cell to which it’s assigned). In the following example, the TV picture would be scaled to fit the width and height specified for the image. Viewers would see a miniature, 180 × 135 version of full-screen TV:
<img src="tv:" width="180" height="135">

Some set-top boxes are capable of scaling the picture only to certain sizes—such as 1/4, 1/3, 1/2, 2/3, and 3/4 full size.

Selecting part of the picture. It’s not necessary to display the entire television picture contained in the incoming video signal. The tv: URL can select just a section of it to display. The section is defined by a rectangle using a coordinate system that has coordinate units equal to pixels and the origin at

384

Content Developer’s Reference

Protocols for TV and Broadcast

the upper left corner of the full picture. The rectangle is measured against the dimensions of the full picture as defined for the video format. It’s located by its left and top sides and its width and height, in the following format: #src=(left,top,width,height) For example, the following code selects a central section of the picture to display. Assuming the incoming television signal carries video that’s 640 pixels wide and 480 pixels high (the NTSC format), it trims 90 pixels from the top and bottom of the picture and 70 pixels from the left and right sides:
<img src="tv:#src=(70,90,500,300)" . . .>

The specified 500 × 300 section of the TV picture is scaled to fit the container where it’s placed. If, in this example, the image container was the same size as the source rectangle, scaling would not be necessary:
<img src="tv:#src=(70,90,500,300)" width="500" height="300">

However, if the container is smaller, the 500 × 300 source picture would be scaled smaller. In the following code, its dimensions are cut in half, to 250 × 150:
<img src="tv:#src=(70,90,500,300)" width="250" height="150">

Similarly, if the container is bigger than the source rectangle, the picture is scaled larger:
<img src="tv:#src=(70,90,500,300)" width="600" height="360">

Just as some set-top boxes are limited to certain sizes or fractions when scaling smaller, they may also be limited when scaling larger. In the examples just shown, the dimensions of the source rectangle are stated in pixel units. They can also be defined as percentages of the screen size for the video format:
<img src="tv:#src=(20%,30%,50%,50%)" . . .>

If the screen is 720 pixels wide and 576 pixels high (typical of the PAL format), these percentages would translate to pixels as follows:
<img src="tv:#src=(144,172,360,288)" . . .>

If the screen is 640 × 480 (typical of NTSC), they would translate to different pixel values:
<img src="tv:#src=(128,144,320,240)" . . .>

Chapter 10: Protocols

385

Protocols for TV and Broadcast

Only integers should be used as percentages (no floating-point numbers). It’s best not to mix percentages with pixels in the same specification.

Picking a container. The tv: protocol is the only way to put TV in a document. If there’s just one source of TV input (one TvTuner object), there’s just one TV resource to allocate. It can therefore be specified only once for all documents, frames, and windows. If two or more URLs compete for the TV picture, TV Navigator uses the following ordered rules to determine which one prevails:

1. It prefers to put television in a visible window, rather than in one that’s
currently invisible. See the Window.visible property for more information. (Visibility is measured only by that property; if a window is on-screen but covered by other windows, it is still considered visible.)

2. If the competing windows are all equally visible, it prefers the window
that’s closest to the front of the screen—the one with the greatest Window.layer value. See that property for more information.

3. If the URLs are in the same window or the competing windows have the
same visibility and are assigned to the same layer, TV Navigator picks the URL that would put television in the largest container. Size is calculated by multiplying the container’s width by its height. If these three rules are not decisive, the container that draws first prevails. In this case, it’s not guaranteed that the same container would always draw first. For example, if a page had two equal tv: images, as in the following example,
<img width="360" height"288" name="telepic" src="tv:"> . . . <img width="360" height"288" name="teleimg" src="tv:">

one of the images might grab the TV picture when the page is displayed one time, and the other image another time. Note that as the visibility of windows changes dynamically, the TV picture might jump from one container to another. Containers that don’t get the TV picture, or lose it, are drawn in a solid color.
AVAILABILITY: HISTORY: SEE ALSO :

Channel and network names are not currently supported. The source rectangle was introduced in the 1.2.6.1 release. “Transparent and Opaque Backgrounds” on page 22, Chapter 3 of the Content Developer’s Guide

386

Content Developer’s Reference

Standard Protocols

mcast:
SYNOPSIS:S DESCRIPTION:

mcast://. . . A protocol for listening to Mediacast channels—data received through a oneway broadcast mechanism, including: • A stream of in-band MPEG data from a cable or satellite • Data encoded in the vertical blanking interval (VBI) of analog broadcasts • IP Multicast (IPM) data over an IP network An mcast: URL addresses all the data in a particular Mediacast channel— everything in a data carousel, for example, or in a stream of ticker data. Individual items in the stream may be addressed by their own URLs, possibly URLs with http: or another protocol name (but not mcast:). The mcast: URL maps logical names to particular data categories and sources. For example:

Example URL
mcast://news/headlines

Data
Yields a series of Web pages (a data carousel). Yields a single well-known page (also a data carousel). Yields a stream of data.

mcast://favorites/contents.html

mcast://ticker/stock mcast://tvinfo

Standard Protocols
The TV Navigator application engine supports the standard protocols listed in this section. As noted in the next section, some other protocols are supported by specific Liberate applications.

http:
DESCRIPTION:

Hypertext Transfer Protocol, the customary protocol for most Internet activity.

Chapter 10: Protocols

387

Unsupported Protocols

https:
DESCRIPTION:

The secure version of the customary protocol.

javascript:
DESCRIPTION:

The protocol name that’s prefixed to embedded JavaScript code. When TV Navigator parses a javascript: URL, it executes the code, but does nothing with the resulting value. Typically, on computer-oriented browsers, if the last expression in the code inside a javascript: URL evaluates to a string (or to a type that can be converted to a string), the browser treats the string as if it was the document referred to by the URL. When the user follows the link in the following somewhat silly example, it would display the user agent string (since the last expression evaluates to what’s at the right of the assignment operator):
<a href="javascript:ua = navigator.userAgent;”>get user agent</a>

Currently, TV Navigator doesn’t look at the value a javascript: URL produces. In this example, it would execute the code but not alter the display. This limitation is imposed because the client requires content that has passed through the Transcode server. However, this restriction will not apply in some future versions of TV Navigator. To avoid future problems, make the javascript: URLs you now use with TV Navigator compatible with the standard behavior. In other words, make sure the last expression in the URL evaluates to nothing. The simplest and safest way to do this is with the void operator. For example:
<a href="javascript:void doSomething(); . . .">

Unsupported Protocols
A special word needs to be said about three standard protocols that are not supported, at least not directly, and don’t appear in the preceding lists: file: The protocol for specifying the path name of a file or other locally stored entity. Because TV Navigator is not currently available on set-top boxes that have hard disks and file systems, it does not support this protocol at the present time. Future versions will implement the file: protocol if the hardware supports a client file system.

388

Content Developer’s Reference

Unsupported Protocols

mailto: The protocol name for opening an e-mail application so the user can send mail to the specified recipient. Although the application engine for TV Navigator doesn’t recognize this protocol, the Liberate TV Mail™ application does. If TV Mail is installed for a user who selects a mailto: link, it will bring up a window where the user can compose a mail message. irc: The IRC (Internet Relay Chat) protocol for chat sessions. Although TV Navigator doesn’t support this protocol, Liberate TV Chat™ does. If TV Chat is installed for the current user and the user selects an irc: link, it attempts to contact the specified chat server and start the chat session.

Chapter 10: Protocols

389

Unsupported Protocols

390

Content Developer’s Reference

HTML Catalog

APPENDIXM

The tables in this appendix list every HTML element and attribute that TV Navigator–S supports. Because its support is based on HTML version 3.2, the tables include: • All tags, attributes, and values that are defined in the 3.2 specification—including the few that TV Navigator–S doesn’t implement. • Other HTML elements that are commonly recognized by browsers that implement the 3.2 standard—again, whether or not TV Navigator–S currently supports them. • All the Liberate additions to HTML, including additions for other versions of TV Navigator. The tables mark (with a check, √) every tag and attribute that TV Navigator–S supports. You can look up any item and see clearly whether or not it will work with TV Navigator Standard. Like most browsers, TV Navigator simply ignores HTML codes that it doesn’t recognize. Unsupported tags and attributes therefore don’t “break” a document; they just have no effect.

Tags and Attributes
The catalog consists of eight tables that divide the HTML universe as follows: “Top-Level Tags” “Head-Level Tags” “Body-Structuring Tags” “Table Tags” “List Tags” “Form Tags” “Text-Formatting Tags” “Other Inline Tags” <html>, <body>, <frameset>, <frame>, and others <meta>, <link>, <script>, <title>, and so on <p>, <h1>, <h2>, <pre>, <hr>, <div>, <scrollstop>, and others <table>, <tr>, <td>, <th>, and <caption> <ul>, <ol>, <li>, <dl>, <dt>, <dd>, <menu>, and <dir> <form>, <input>, <textarea>, <select>, <option>, and so on <b>, <em>, <font>, <i>, <strike>, <sub>, <tt>, <u>, and so on <a>, <br>, <embed>, <img>, <map>, <spacer>, and others

Appendix A: HTML Catalog

391

Tags and Attributes

Top-Level Tags
Tag, attributes, and values
<html> version="string" <head> <body> background="URL" bgcolor="color" overscan=["left" | "top" | "right" | "bottom" | "all" | "none"] link="color" alink="color" vlink="color" text="color" onfocus="JavaScript" onblur="JavaScript" onerror="JavaScript" onload="JavaScript" onunload="JavaScript" onkeyout="JavaScript" onvisible="JavaScript" <frameset> background="tv:. . ." √ √ √ √ √ √ √ √ √ √ A Liberate addition, for TV images only. See “Frameset Background” on page 21. See “Image and Frame Borders” on page 33. A Liberate addition. See the “Input Object” section on page 305. A Liberate addition. See “Window Object Additions” on page 103.

Supported Comments
√ √ √ √ √ √ √ √ A Liberate addition. See “Backgrounds beyond Window Borders” on page 23. The version doesn’t make a difference.

border="pixels" bordercolor="color" frameborder=["yes" | "no"]

√

392

Content Developer’s Reference

Tags and Attributes

Top-Level Tags (continued)
Tag, attributes, and values
<frameset> (continued) cols="list" rows="list" overscan=["left" | "top" | "right" | "bottom" | "all" | "none"] onfocus="JavaScript" onblur="JavaScript" onload="JavaScript" onunload="JavaScript" onkeyout="JavaScript" onvisible="JavaScript" <frame> bordercolor="color" frameborder=["yes" | "no"] marginheight="pixels" marginwidth="pixels" name="string" noresize scrolling=["yes" | "no" | "auto"] src="URL" <noframes> √ √ √ √ √ Ignored, because frames are supported. Frames are never resizable. Scrolling is always “auto”. √ √ √ √ √ √ √ √ √ √ A Liberate addition. See the “Input Object” section on page 305. A Liberate addition. See “Window Object Additions” on page 103. A Liberate addition. See “Backgrounds beyond Window Borders” on page 23.

Supported Comments

Appendix A: HTML Catalog

393

Tags and Attributes

Head-Level Tags
Tag, attributes, and values
<base> href="URL" target="frameName" <isindex> prompt="text" <link> rel="next"

Supported Comments
√ √ √ √ √ √ √ Values other than “next” are not supported. See “Prefetching” on page 63 for more information. See Note 1 on page 405.

href="URL" rev title <meta> initialfocus=["name" | "notme"] history="transient" http-equiv="fieldName" content="fieldValue" name="name" <script> language="javascript" src="URL" <noscript> <style> <title>

√

√ √ √ √ √ √ √ √ √ √ Ignored, since all Liberate products support JavaScript. A placeholder for HTML 4.0. √ A Liberate addition. See “Setting the Initial Focus” on page 27. A Liberate addition. See “Transient History” on page 57. See “HTTP Header Equivalents” on page 57.

394

Content Developer’s Reference

Tags and Attributes

Supported Comments
√ √ √ √ √ √ √ √ √ The default font size of headings is increased for display on the TV screen. See “Headings” on page 32. The sound source. The number of times to play the sound.

√ √ √ √ √ √ √ Deprecated in HTML 3.2. TV Navigator–S always renders a horizontal rule in noshade mode. The minimum is 2 pixels. See “Horizontal Rules” on page 34.

Appendix A: HTML Catalog

395

Tags and Attributes

Body-Structuring Tags (continued)
Tag, attributes, and values
<pre> cols="maxCharacters" width="pixels" wrap <scrollstop> √ Lines always wrap if necessary. See “Preventing Line Breaks” on page 34. A Liberate addition for TV Navigator Analog; not supported by TV Navigator Standard. √ Deprecated in HTML 3.2.

Supported Comments
√

<xmp>

Table Tags
Tag, attributes, and values
<table> align=["left" | "center" | "right"] bgcolor="color" border="pixelThickness"

Supported Comments
√ √ √ √ See “Transparent and Opaque Backgrounds” on page 22. A pixelThickness of 0 means no border. All other values yield a 2-pixel thick border. See “Table Borders, Cell Separation, and Cell Margins” on page 35. See “Table Borders, Cell Separation, and Cell Margins” on page 35. See the dynamiccols attribute instead.

cellpadding="pixels" cellspacing="pixels" cols="number"

√ √

396

Content Developer’s Reference

Tags and Attributes

Table Tags (continued)
Tag, attributes, and values
<table> (continued) dynamiccols="number" √ The minimum number of TableCell objects per row. See “Minimum Number of Cells” on page 120 in Chapter 4, “Dynamic Tables.” A Liberate addition. See “Highlighting the Cell in Focus” on page 122. See “Table Width and Height” on page 36.

Supported Comments

highlightable=["true" | "false"] height=["pixels" | "percent"] width=["pixels" | "percent"] hspace="pixels" vspace="pixels" name="string"

√ √ √ √ √ √

A Liberate addition. See “Table Objects” on page 125 in Chapter 4, “Dynamic Tables.” Liberate extensions for dynamic tables. See “Table Objects” on page 125 for details.

√ √ √ √ √ √ √ √ √ √

See “Transparent and Opaque Backgrounds” on page 22.

Appendix A: HTML Catalog

397

Tags and Attributes

Supported Comments
√ √ √ √ √ √ √ √ A Liberate addition. See Chapter 4, “Dynamic Tables,” especially “Focusable Cells” on page 121. A Liberate addition. See “Highlighting the Cell in Focus” on page 122. A Liberate addition. See “Cell Background” on page 122. See “Transparent and Opaque Backgrounds” on page 22.

√ √ √ √ √ √ √ √ √

See “Preventing Line Breaks” on page 34. Liberate additions. These attributes animate the text within a cell. See “Animated Text in Cells” on page 123.

398

Content Developer’s Reference

Tags and Attributes

List Tags
Tag, attributes, and values
<ul> type=["circle" | "disc" | "square"] compact <ol> type=[ "1" | "a" | "A" | "i" | "I" ] start="number" compact <li> type=["circle" | "disc"| "square"] type=[ "1" | "a" | "A" | "i" | "I" ] value="number" <dl> compact <dt> <dd> <menu> compact <dir> compact √ √ √ √ √ √ √ √ √ (for <ul>) See Note 2 on page 405. (for <ol>) See Note 2 on page 405. (for <ol> only) √ √ √ See Note 2 for TV Navigator–S restrictions.

Supported Comments
√

Appendix A: HTML Catalog

399

Tags and Attributes

Supported Comments
√ √ √ √ √ √ √ √ √ √ The “file” type is not supported. See Note 1 on page 405. See Note 3 on page 405.

√ √ √ √ √ √ √ √ √ √ √ √ √ See Note 4 on page 405. A Liberate addition; see “Preventing Image Cursors” on page 28. A Liberate addition for the “text” and “password” input types.

400

Content Developer’s Reference

Tags and Attributes

Form Tags (continued)
Tag, attributes, and values
<select> multiple name="string" size="numItems" background="URL" popupbg="URL" bgcolor="color" text="color" selbgcolor="color" seltext="color" onfocus="JavaScript" onblur="JavaScript" onchange="JavaScript" <option> selected value="optionValue" <textarea> bgcolor="color" cols="numChars" rows="numLines" focusable=["true" | "false"] name="string" wrap=["off" | "hard" | "soft"] onfocus="JavaScript" onblur="JavaScript" onselect="JavaScript" onchange="JavaScript" √

Supported Comments
√ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See Note 4 on page 405. The default is “soft”. A Liberate addition. See “Preventing Focus on a Text Area” on page 30. A Liberate addition. Liberate additions. See “Images and Colors in Selection Lists” on page 61.

Appendix A: HTML Catalog

401

Tags and Attributes

Text-Formatting Tags
Tag, attributes, and values
<b> <baseFont> size=["1"–"7" | "small" | "medium" | "large"] <big> <blink> <cite> <code> <dfn> <em> <font> color="color" face="fontList" size=["1"–"7" | "+number" | "–number"] <i> <kbd> <s> <samp> <small> <strike> <strong> <sub> <sup> <tt> <u> <var> √ √ √ √ √ A larger font size is required to display text on a TV screen. See “Font Size” on page 31 for details. √ √

Supported Comments
√ √ √ See “Font Size” on page 31 for the meaning of “small”, “medium”, and “large”.

√

√ √ √ √ √ √ √ √ √ √ √ √

402

Content Developer’s Reference

Tags and Attributes

Other Inline Tags
Tag, attributes, and values
<a> highlightable=["true" | "false"] href="URL" target="frameName" name="string" rel="relationship" rev="relationship" title="text" onclick="JavaScript" onmouseover="JavaScript" onmouseout="JavaScript" <applet> <area> coords="coordinates" shape=["default" | "circle" | "poly" | "polygon" | "rect"] href="URL" nohref name="string" target="frameName" alt="text" onclick="JavaScript" onmouseover="JavaScript" onmouseout="JavaScript" <br> clear=["left" | "right" | "all"] √ √ √ √ √ √ See Note 1 on page 405. √ √ √ √ √ √ √ √

Supported Comments
√ √ √ √ √ See Note 1 on page 405. A Liberate addition. See “Highlighting Links” on page 29.

Appendix A: HTML Catalog

403

Tags and Attributes

Other Inline Tags (continued)
Tag, attributes, and values
<embed> <noembed> <img> src="URL" lowsrc="URL" alt="text" name="string" align=["left" | "right" | "top" | "texttop" | "baseline" | "absmiddle" | "middle" | "absbottom" | "bottom"] border height=["pixels" | "percent"] width=["pixels" | "percent"] hspace="pixels" vspace="pixels" ismap usemap="name" onabort="JavaScript" onerror="JavaScript" onload="JavaScript" <map> name="string" <nobr> √ √ √ √ √ √ √ √ √ √ √ √ See “Preventing Line Breaks” on page 34 for a discussion of how this element may be reinterpreted. See “Image Width” on page 33. See “Image Spacing” on page 32. √ √

Supported Comments
√ √ √ √

See “Image and Frame Borders” on page 33.

<param>

404

Content Developer’s Reference

Notes

Supported Comments
√ √ √

√ √ Spacers can be scaled in some circumstances. See “Preventing Line Breaks” on page 34 and “Table Cell Width” on page 37.

size="pixels" <wbr>

√ √

Notes
1. TV Navigator never creates a new window for the destination document of a link. If the
target attribute of the <a> tag is “_blank”, the document is loaded in the top-level window (as if the target was “_top”). This rule applies equally to the target attributes of the <area>, <base>, and <form> tags. See Window.open() for other restrictions on the creation of new windows.

2. For reasons of efficiency and compactness, TV Navigator–S currently does not support the
full range of list options. For unordered lists (<ul>), the bullet is always a solid dot— equivalent to a type value of “disc”. For ordered lists (<ol>), the marker is always numeric— equivalent to a type value of “1”.

3. The supported encoding types are:
"application/x-www-form-urlencoded" "multipart/form-data" "text/plain"

4. TV Navigator–S doesn’t support the multicharacter selection of text.

Appendix A: HTML Catalog

405

Notes

406

Content Developer’s Reference

APPENDIXM

JavaScript Catalog

This appendix catalogs everything in client-side JavaScript that TV Navigator–S currently supports. It includes both standard JavaScript features (those that other browsers recognize) and the Liberate Technologies additions. Liberate’s additions are more thoroughly documented in the previous chapters of this Reference. TV Navigator–S is currently based on JavaScript 1.1, as Netscape Communications Corporation defines that version. However, it also implements some features of JavaScript 1.2. Therefore, the catalog lists all of JavaScript 1.1 and 1.2. It also lists all of the Liberate extensions, including the few that TV Navigator–S does not support at present but that are implemented by other versions of TV Navigator. Supported items are marked with a check, √. You can see at a glance which elements of the core language and which objects, methods, and properties in the clientside API are supported, and which are not. The most common reason why a feature would not be supported is that it is not part of JavaScript 1.1, but was introduced in version 1.2. Currently, TV Navigator–S does not attempt full compatibility with JavaScript 1.2; only a few of its features are implemented. Almost all of JavaScript 1.1 is supported. However, a few 1.1 features are not defined or behave differently than you might expect if you’re familiar with them on a computer-based browser. The reason usually lies in the TV Navigator architecture and product design. For example, TV Navigator windows don’t have a status bar, so setting Window.status doesn’t automatically display anything. In most cases, these differences and omissions are explained by a note. “Notes” begin on page 450, following the lists.

Core Language
The JavaScript language is in many ways a work in progress. From time to time, it acquires new constructions and conventions—and alters the meanings of old ones. In particular, some operators and statements were added to the core language in version 1.2 and later, and a few other changes were made, particularly regarding event handlers and regular expressions.

Appendix B: JavaScript Catalog

407

Core Language

Because TV Navigator is currently based on version 1.1 of the language, these additions are not yet supported. The following tables indicate which expressions and statements TV Navigator understands and which it does not. Subsequent sections discuss event handlers, regular expressions, and JavaScript entities.

Operators
Symbol
. [ ] ( ) ++ -– ~ !

Description
Member of Array index Function call or definition Increment Decrement Minus Bitwise complement Logical complement Mark property as undefined Create a new object Return data type of Return undefined value Multiplication, division, and remainder (modulo) Addition and subtraction String concatenation Shift left and right with sign extension Shift right with zero extension Equality and inequality (with implicit type conversion) Identity and non-identity (equality and inequality without type conversion)

Supported Comments
√ √ √ √ √ √ √ √ Added in version 1.2. √ √ √ √ √ √ √ √ √ Added in version 1.2

delete new typeof void
*, /, % +, – + <<, >> >>> ==, != ===, !==

408

Content Developer’s Reference

Core Language

Symbol
<, <= >, >= &, |, ^ &&, || ? : = +=, –=, *=, /=, %=, <<=, >>=, >>>=, &=, |=, ^=

Description
Less than, less than or equal to Greater than, greater than or equal to Bitwise AND, OR, and exclusive OR Logical AND and OR Ternary conditional operator Assignment Assignment with operation

Supported Comments
√ √ √ √ √ √ √

Multiple evaluation

√

Statements
Keywords if, else Example
if ( str == "all" ) . . . else if ( str == "none" ) . . . else . . . switch ( str ) { case "all": . . . case "none”: . . . default: . . . } while ( i > 0) { . . . i--; }

Supported Comments
√

switch, case, default

Added in version 1.2.

while

√

Appendix B: JavaScript Catalog

409

Core Language

Keywords do while

Example
do { . . . i--; } while ( i >= 0 ); for ( i=0; i < 10; i++ ) { . . . } for ( prop in someObject ) { . . . } for ( i=0; i < 10; i++ ) { . . . break; } outer: for ( i=0; i < 10; i++ ) { . . . while ( j > 0 ) { . . . break outer; } } with ( someObject ) { . . . } var aVariableName; function doSomething(arg) { . . . } function doSomething(arg) { . . . return(false); } function doSomething(arg) { . . . } export doSomething;

Supported Comments
Added in version 1.2.

for

√

for in

√

break, continue

√

labels with break and continue

Added in version 1.2.

with

√

var function

√ √

return

√

import, export

Added in version 1.2.

410

Content Developer’s Reference

Core Language

Event Handlers
Two recent changes affect event handlers. One concerns their syntax and the other the way they’re spelled.

Syntax. Beginning with version 1.2, all event handlers are passed a single argument—an object that contains properties describing the event. They take no other arguments; all information the handler requires is bundled into the object.
TV Navigator continues to support the version 1.1 syntax. Most standard handlers don’t take any arguments. Where information is passed to the handler, it’s typically passed as one or more individual arguments, rather than as properties of an object.

Spelling. For ease of reading, event handlers are often documented with mixed-case names
(for example, onMouseOver()). However, in JavaScript code, the properties that hold eventhandler functions traditionally had to have names that were all lowercase (for example, onmouseover()). Some browsers are now beginning to accept mixed-case names in addition to the all-lowercase ones. However, TV Navigator accepts only the lowercase version. To avoid confusion, this manual lists handlers as they must be spelled in JavaScript.

Regular Expressions
TV Navigator does not currently support regular expressions, whether constructed as a literal string bracketed by a pair of slashes (/),
var thisFormat = /*\smis[ls]ed\x20you/;

or created by the RegExp constructor:
var thatPattern = new RegExp("*\smis[ls]ed\x20you");

Regular expressions were added to the language in version 1.2.

JavaScript Entities
TV Navigator–S currently does not support JavaScript entities—JavaScript code bracketed by &{ and };—for any purpose. Generally, the purpose is to assign a value to an HTML attribute. For example:
<body bgcolor="&{curPrefs.mainColor};" link="&{curPrefs.linkColor};">

However, TV Navigator–S does support character entities—such as   (for a nonbreaking space) or > (for a greater-than symbol).

Appendix B: JavaScript Catalog

411

Client-Side API

Client-Side API
The catalog of client-side JavaScript begins below. Objects are presented in alphabetical order. Within each object, properties are listed first, followed by methods, and then by event handlers. Items within each of these groups are also alphabetized. The catalog does not include two kinds of API extension: • JavaScript extensions for specific types of data placed on a page (with the HTML <embed> and <object> tags) are not covered. For information on the JavaScript used to play embedded sounds, see Appendix D, “Playing Sounds,” on page 465. For information on the JavaScript you can use with embedded Macromedia Flash (.swf) files, see Appendix E, “Playing Flash Movies,” on page 467. • Platform-specific and deployment-specific extensions are excluded from the catalog. For example, a particular deployment might have information about the episode titles or cast members of TV programs and expose that information as properties of the TvProgram.raw object. Or it might have additional TvChannel properties, such as one for the primary broadcast language of the channel. For these kinds of API additions, contact the network operator that’s deploying TV Navigator.

Object and properties
Anchor name text x y Applet Area Array constructor index input length

Introduced in Supported Comments version
JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.2 JS 1.2 JS 1.1 √ √ √ √ See Note 1 on page 450. A variety of Link object. See “Link” on page 423. √ √

412

Content Developer’s Reference

Client-Side API

Object and properties
Array (continued) prototype concat() join() pop() push() reverse() shift() slice() sort() splice() toString() unshift() valueOf() Authentication hint status reset() setKey() onkeyset() onreset() Boolean constructor prototype toString() valueOf()

Introduced in Supported Comments version
JS 1.1 JS 1.2 JS 1.1 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.1 JS 1.2 JS 1.1 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ See “Authentication Object” on page 333. √ √ √ √ √

Appendix B: JavaScript Catalog

413

Client-Side API

Object and properties
Button form name type value blur() click() focus() handleEvent() onblur() onclick() onfocus() onmousedown() onmouseup() Cache remove() Checkbox checked defaultChecked form name type value blur() click() focus() handleEvent()

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.2 JS 1.1 JS 1.0 JS 1.1 JS 1.2 JS 1.2 TVN–S 1.0 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.2 √ √ √ √ √ √ √ √ √ √ √ √ See “Cache Object” on page 147. √ √ √ √ √ √ √ √ √ √ √

414

Content Developer’s Reference

Client-Side API

Object and properties
Checkbox (continued) onblur() onclick() onfocus() ConditionalAccess credit cancelPurchase() changePin() checkPin() getInfo() purchase() onalarm() oncommand() Cookie domain expiration name path secure transmitted value load() remove() store() Cron CronEvent

Introduced in Supported Comments version
JS 1.1 JS 1.0 JS 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2 TVN–S 1.0 TVN–S 1.1 TVN–S 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–A TVN–A √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “Cookie Objects” beginning on page 65. See “ConditionalAccess Object” beginning on page 193.

Appendix B: JavaScript Catalog

415

Client-Side API

Object and properties
Date constructor prototype getDate() getDay() getHours() getMinutes() getMonth() getSeconds() getTime() getTimezoneOffset() getYear() parse() setDate() setHours() setMinutes() setMonth() setSeconds() setTime() setYear() toGMTString() toLocaleString() toString() UTC() valueOf()

Introduced in Supported Comments version
JS 1.0 JS 1.1 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See Note 2 on page 450. See Note 2 on page 450. Deprecated in JS 1.3.

416

Content Developer’s Reference

Client-Side API

Object and properties
Display alpha flickerFilterEnabled format format.system preferredFormat programDefaults programDefaults.language safeArea screenArea settingsAlwaysRetained tvVisible videoOn wideScreenStyle retainSettings() Document alinkColor anchors anchors.length applets applets.length bgColor classes cookie cookies cookies.length domain

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.0 TVN–A TVN–S 1.0 TVN–S 1.0 TVN–S 1.1 TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2.6 TVN–S 1.0 TVN–S 1.1 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.1 JS 1.0 JS 1.2 JS 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.1 √ √ √ √ See “Cookie Objects” on page 65. √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See Note 1 on page 450. Supported, but currently ineffective. √ √ See “Display Object” beginning on page 39.

Appendix B: JavaScript Catalog

417

Client-Side API

Object and properties
Document (continued) embeds embeds.length fgColor forms forms.length height ids images images.length lastModified layers linkColor links links.length location

Introduced in Supported Comments version
JS 1.1 JS 1.1 JS 1.0 JS 1.1 JS 1.1 JS 1.2 JS 1.2 JS 1.1 JS 1.1 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ Deprecated in JS 1.1; use the location property of the Window object instead. √ √ A synonym for embeds. See Note 3 on page 451. √ √ √ √ √ √ √ √ See Note 3 on page 451.

plugins plugins.length referrer tags title URL vlinkColor width name of image name of embed

JS 1.1 JS 1.1 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.1 JS 1.1

√ √ √ √ √ Present, but ineffective.

418

Content Developer’s Reference

Client-Side API

Object and properties
Document (continued) name of form name of table

Introduced in Supported Comments version
JS 1.1 TVN–S 1.0 √ √ See “Named Tables and JavaScript Objects” on page 113.

captureEvents() clear() close() contextual() getSelection() handleEvent() open() releaseEvents() routeEvent() write() writeln() onclick() ondblclick() onkeydown() onkeypress() onkeyup() onmousedown() onmouseup() ETv enabled triggerUrl unmatchedUrlsAccepted addToUrlFilter()

JS 1.2 √ JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.0 JS 1.2 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.2 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 √ √ √ √ √ See “ETv Object” beginning on page 199. See Note 4 on page 451. See Note 4 on page 451. √ √

Appendix B: JavaScript Catalog

419

Client-Side API

Object and properties
ETv (continued) resetUrlFilter() setChannelFilter() ontrigger() Event FileUpload Form action elements elements.length encoding length method name target name of form element handleEvent() reset() submit() onreset() onsubmit() Frame Function arguments arguments.callee arguments.caller arguments.length

Introduced in Supported Comments version
TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ √ √ √ √ √ √ √ JS 1.2 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.1 JS 1.1 JS 1.2 JS 1.1 JS 1.1 √ Deprecated in JS 1.3. See Function.caller instead. √ √ √ √ √ √ √ See the Window object. See Note 6 on page 451 and Note 7 on page 451. √ √ √

420

Content Developer’s Reference

Client-Side API

Object and properties
Function (continued) arity caller constructor length prototype toString() valueOf() Hidden form name type value History curIndex current length next previous add() back() forward() fullGo() go() remove() toString()

Introduced in Supported Comments version
JS 1.2 JS 1.0 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.0 TVN–S 1.2 JS 1.1 JS 1.0 JS 1.1 JS 1.1 TVN–S 1.0 JS 1.0 JS 1.0 TVN–S 1.2.3 JS 1.0 TVN–S 1.0 TVN–S 1.2 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See remove() on page 80. See fullGo() on page 81. See add() on page 80. See curIndex on page 80.

Appendix B: JavaScript Catalog

421

Client-Side API

Object and properties
HistoryEntry appData title go() toString() Image border

Introduced in Supported Comments version
TVN–S 1.2 TVN–S 1.2.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 JS 1.1 JS 1.1 √ √ √ √ √ √ √ Present, but ineffective. See “Image and Frame Borders” on page 33. See “History and HistoryEntry Objects” beginning on page 79.

complete height hspace lowsrc name src vspace width handleEvent() onabort() onerror() onkeydown() onkeypress() onkeyup() onload() Indicator name type value

JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.2 JS 1.1 JS 1.1 JS 1.2 JS 1.2 JS 1.2 JS 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0

√ √ √ √ √ √ √ √ √ √ Nonfunctional for the “A” version of TV Navigator. See Note 8 on page 452. See Note 7 on page 451.

√ √ √ √ √ See “Indicator Objects” beginning on page 301.

422

Content Developer’s Reference

Client-Side API

Object and properties
Input curChar curKey deviceNumber deviceType timestamp insertKeys() popFocus() pushFocus() setExclusiveKeys() onkeyin() onkeyout() Java JavaArray JavaClass JavaObject JavaPackage Layer Link hash highlightable host hostname href name pathname port

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.2 JS 1.0 JS 1.0 TVN–S 1.2 JS 1.0 JS 1.0 JS 1.0 TVN–S 1.1 JS 1.0 JS 1.0 √ √ √ √ √ √ √ √ √ Defined if the link is assigned a name in HTML. See highlightable on page 47. √ √ √ √ √ √ √ √ √ √ √ √ See Note 1 on page 450. See Note 1 on page 450. See Note 1 on page 450. See Note 1 on page 450. See Note 1 on page 450. See “Input Object” beginning on page 305.

Appendix B: JavaScript Catalog

423

Client-Side API

Object and properties
Link (continued) protocol search target text x y blur() focus() handleEvent() onclick() ondblclick() onkeydown() onkeypress() onkeyup() onmousedown() onmouseout() onmouseover() onmouseup() Location hash host hostname href pathname port protocol search

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.2 TVN–S 1.2 TVN–S 1.0 JS 1.2 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.1 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ Not supported Not supported See the description on page 48. √ √ √

424

Content Developer’s Reference

Client-Side API

Object and properties
Location (continued) reload() replace() toString() Math E LN10 LN2 LOG10E LOG2E PI SQRT1_2 SQRT2 abs() acos() asin() atan() atan2() ceil() cos() exp() floor() log() max() min() pow() random() round()

Introduced in Supported Comments version
JS 1.1 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √

Appendix B: JavaScript Catalog

425

Client-Side API

Object and properties
Math (continued) sin() sqrt() tan() MimeType description enabledPlugin suffixes type MusicText start() stop() onreceive() Navigator appCodeName appName appVersion cache cron curUser display extensions extensions.length indicators input ir language

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 JS 1.0 JS 1.0 JS 1.0 JS 1.0 TVN–S 1.0 TVN–A TVN–S 1.1 TVN–S 1.0 TVN–S 1.2.5 TVN–S 1.2.5 TVN–S 1.0 TVN–S 1.0 TVN–A JS 1.2 √ √ √ √ √ √ See indicators on page 88. See input on page 88. See curUser on page 86. See display on page 87. See extensions on page 87. √ √ √ √ √ √ √ √ √ √ √ See userAgent on page 92 for the TV Navigator–S values. See cache on page 86. See “MusicText Object” on page 207. √ √ √ √ √

426

Content Developer’s Reference

Client-Side API

Object and properties
Navigator (continued) length mimeTypes mimeTypes.length net platform plugins plugins.length plugins.refresh() serviceManager smartCardSlots smartCardSlots.length speaker sysServices sysServices.length system tvTuners userAgent userManager javaEnabled() preference() savePreferences() taintEnabled()

Introduced in Supported Comments version
TVN–S 1.0 JS 1.1 JS 1.1 TVN–S 1.0 JS 1.2 JS 1.1 JS 1.1 JS 1.1 TVN–S 1.2.6.1 TVN–A TVN–A TVN–S 1.0 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.0 TVN–S 1.0 JS 1.0 TVN–S 1.0 JS 1.1 JS 1.2 JS 1.2 JS 1.1 √ Always returns false. See Note 9 on page 452. √ √ √ √ √ √ √ √ See systemsystem on page 91. See tvTuners on page 91. See userAgent on page 92. See userManager on page 94. Currently returns false. See Note 1 on page 450. See speaker on page 90. √ √ √ See Note 3 on page 451. √ √ √ √ See net on page 89. See length on page 88.

Appendix B: JavaScript Catalog

427

Client-Side API

Object and properties
Net connected connectionSpeed ensureConnection() NetEvent() NetRequest() NetSession() onprogress() NetEvent binaryData binaryData.length contentType headers headers.getValue() headers.length textData type url NetMsgSession appId nodeId nodeType sessionId attach() detach() register() send() unregister()

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.0 TVN–A TVN–S 1.0 TVN–S 1.1 TVN–S 1.0 TVN–S 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “NetMsgSession Objects” beginning on page 165. See “NetEvent Objects” beginning on page 157. √ √ See “Net Object” beginning on page 151.

428

Content Developer’s Reference

Client-Side API

Object and properties
NetMsgSession (continued) onerror() onreceive() NetRequest cache direct headers headers.getValue() headers.length post postData postData.length postData.set() postData.toString() url cancel() fetch() oncancel() ondone() onerror() onload() onstart() Netscape NetSession headers headers.getValue() headers.length url

Introduced in Supported Comments version
TVN–S 1.3 TVN–S 1.3 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.3 TVN–S 1.3 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See Note 1 on page 450. See “NetSession Objects” beginning on page 185. See “NetRequest Objects” beginning on page 175.

Appendix B: JavaScript Catalog

429

Client-Side API

Object and properties
NetSession (continued) send() start() stop() onerror() onreceive() onstart() onstop() Number constructor MAX_VALUE MIN_VALUE NaN NEGATIVE_INFINITY POSITIVE_INFINITY prototype toString() valueOf() Object constructor prototype eval()

Introduced in Supported Comments version
TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.1 JS 1.0 JS 1.1 JS 1.1 JS 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See the global version of eval() and Note 10 on page 452. √ √

toString() unwatch() valueOf() watch()

JS 1.0 JS 1.2 JS 1.1 JS 1.2

430

Content Developer’s Reference

Client-Side API

Object and properties
Option defaultSelected index length selected text

Introduced in Supported Comments version
JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ √ √ √ Can be both read and written (to change the option text, as per 1.1). See Note 1 on page 450. √ √ √ √ √ √ √ √ √ √ √ √ See Note 3 on page 451. √ √ √ √ See “ProgramStream Objects” beginning on page 211. Not effective. See Note 5 on page 451.

value Packages Password defaultValue form name type value blur() focus() handleEvent() select() onblur() onchange() onfocus() Plugin ProgramStream curSpeed curTime fastForwardSpeed

JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.1 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6

√

Appendix B: JavaScript Catalog

431

Client-Side API

Object and properties
ProgramStream (continued) id keyFrames mute rewindSpeed title totalTime fastForward() pause() play() rewind() stop() ondone() onerror() onfastforward() onpause() onplay() onrewind() onstop() Radio checked defaultChecked form name type value blur() click() focus()

Introduced in Supported Comments version
TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √

432

Content Developer’s Reference

Client-Side API

Object and properties
Radio (continued) handleEvent() onblur() onclick() onfocus() RegExp Reset form name type value blur() click() focus() handleEvent() onblur() onclick() onfocus() SafeArea height left top width Screen ScreenArea height width

Introduced in Supported Comments version
JS 1.2 JS 1.1 JS 1.0 JS 1.1 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.2 JS 1.1 JS 1.0 JS 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 √ √ √ See “ScreenArea and SafeArea Objects” beginning on page 49. √ √ √ √ √ √ √ √ See “ScreenArea and SafeArea Objects” beginning on page 49. √ √ √ √ √ √ √ √ √ √ √ See “Regular Expressions” earlier in this appendix.

Appendix B: JavaScript Catalog

433

Client-Side API

Object and properties
Select form length name options options.length options.selectedIndex selectedIndex type blur() focus() handleEvent() onblur() onchange() onfocus() Service sysAdminConsent sysBootUrl sysCancellationUrl sysChannel sysDescription sysDisplayLanguage sysDisplayName sysHeaderValue sysHeaderUrl sysId sysInfoUrl sysInternalName

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 TVN–S 1.1 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.1 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.1 TVN–S 1.1 TVN–S 1.2 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “Service Objects” beginning on page 339. √ √ √ √ √ √ √ √ √ √

434

Content Developer’s Reference

Client-Side API

Object and properties
Service (continued) sysLastStatusChange sysLocalizationUrl sysLogoUrl sysProviderConsent sysRegistered sysRegistrationUrl sysRoot sysSmallLogoUrl sysStatus sysTrustedUrl sysType sysTypeRequired sysUserConsent sysVersion SmartCard SmartCardPackage SmartCardSlot Speaker mute volume String constructor length prototype anchor() big() blink() bold()

Introduced in Supported Comments version
TVN–S 1.1 TVN–S 1.2 TVN–S 1.1 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.1 TVN–S 1.1 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–A TVN–A TVN–A TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.0 √ √ √ √ √ √ √ √ √ √ √ See Note 11 on page 452. See Note 11 on page 452. See Note 11 on page 452. See Note 11 on page 452. See “Speaker Object” on page 53. √ √ √ √ √ √ √ √ √ √ √ √ √ √

Appendix B: JavaScript Catalog

435

Client-Side API

Object and properties
String (continued) charAt() charCodeAt() concat() encrypt() fixed() fontcolor() fontsize() fromCharCode() indexOf() italics() lastIndexOf() link() match() replace() search() slice() small() split() strike() sub() substr() substring() sup() toLowerCase() toString() toUppperCase() valueOf() Style

Introduced in Supported Comments version
JS 1.0 JS 1.2 JS 1.2 TVN–S 1.3 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.2 √ √ √ √ √ √ See Note 11 on page 452. √ √ √ √ See Note 11 on page 452. See Note 11 on page 452. See Note 11 on page 452. √ √ √ √ See Note 11 on page 452. √ √ √ √ See encrypt() on page 95. See Note 11 on page 452. See Note 11 on page 452. See Note 11 on page 452. √ √

436

Content Developer’s Reference

Client-Side API

Object and properties
Submit form name type value blur() click() focus() handleEvent() onblur() onclick() onfocus() Sun System uniqueId control() resetExecutionCount() onerror() onexternalevent() Table drawingDisabled name rows rows.length blur() clear() focus() scrollRows()

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.2 JS 1.1 JS 1.0 JS 1.1 JS 1.1 TVN–S 1.0 TVN–S 1.2 TVN–S 1.1 TVN–S 1.2.6 TVN–S 1.0 TVN–S 1.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “Table Objects” beginning on page 125. √ √ √ See Note 1 on page 450. See “System Object” beginning on page 313. √ √ √ √ √ √ √ √

Appendix B: JavaScript Catalog

437

Client-Side API

Object and properties
Table (continued) onblur() onclick() onfocus() onnavigate() TableCell align background behavior bgColor colSpan direction elisionString fgColor focusable highlightable loop scrollAmount scrollDelay valign wrappingEnabled findColsNeeded() findFit() read() write() TableRow cells cells.length

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.2 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “TableRow Objects” on page 143. See “TableCell Objects” beginning on page 133.

438

Content Developer’s Reference

Client-Side API

Object and properties
Text bgColor defaultValue form name type value blur() focus() handleEvent() select() onblur() onchange() onfocus() onselect() Textarea bgColor bottomLine curLineCount defaultValue focusable form maxLineCount name topLine type

Introduced in Supported Comments version
JS 1.0 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.0 TVN–S 1.2 JS 1.0 TVN–S 1.0 JS 1.0 TVN–S 1.0 JS 1.1 √ √ √ √ √ √ √ √ √ √ √ See topLine on page 99. See maxLineCount on page 98. See bgColor on page 98. See bottomLine on page 99. See curLineCount on page 98. √ √ √ √ See Note 5 on page 451. Does nothing. See Note 5 on page 451. √ √ √ √ √ √ √ √ √ See bgColor on page 97.

Appendix B: JavaScript Catalog

439

Client-Side API

Object and properties
Textarea (continued) value wrap append() blur() focus() handleEvent() select() onblur() onchange() onfocus() onkeydown onkeypress() onkeyup() onselect() Transmitter Trigger channel expiration name script url TvChannel accessControlled availableComponents blackedOut blocked

Introduced in Supported Comments version
JS 1.0 TVN–S 1.0 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.0 TVN–A TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.3 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 √ √ √ √ √ √ √ √ √ √ √ See “TvChannel Objects” beginning on page 221. See the ontrigger() event handler of the ETv object on page 204. See Note 5 on page 451. √ √ √ √ Does nothing. See Note 5 on page 451. √ √ √ √ √ See wrap on page 100. See append() on page 100.

440

Content Developer’s Reference

Client-Side API

Object and properties
TvChannel (continued) category curProgram description frequency fullName hidden id name network nextProgram presentable presentables relatedChannel selectedComponents serviceId serviceType shortName signal split splitTimes transportStreamId tunable tunables uniqueId url TvFormat system

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See Display.format and TvTuner.format.

Appendix B: JavaScript Catalog

441

Client-Side API

Object and properties
TvInfo nvodEnabled indexes pfEnabled schemaUrl addIndex() deleteIndex() search() setDataSource() update() TvInfoIndex name getNext() getPrev() search() TvProgram accessControlled ageRating audio blackedOut captions channels deliveryMode description duration nvodId nvodReference qualityRating

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.2.5 TVN–S 1.2.2 TVN–S 1.2.5 TVN–S 1.2.5 TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–A TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.2 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2 TVN–S 1.2 TVN–S 1.0 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “TvProgram Objects” beginning on page 255. See “TvInfoIndex Objects” beginning on page 251. √ √ √ √ √ √ √ √ √ See “TvInfo Object” beginning on page 239.

442

Content Developer’s Reference

Client-Side API

Object and properties
TvProgram (continued) raw shortTitle startTime title topics year TvTuner access channels channels.length curChannel eTv format format.system frozen info infoEnabled mute name transmitter captureStill() startMovieCapture() stopMovieCapture() findChannel() onafterchannelchange() onbeforechannelchange() onchannelsupdate() onprogramchange()

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.2.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.3 TVN–S 1.0 TVN–S 1.0 TVN–S 1.3 TVN–S 1.0 TVN–A TVN–S 1.0 TVN–S 1.0 TVN–A TVN–S 1.3 TVN–A TVN–A TVN–S 1.0 TVN–S 1.2.1 TVN–S 1.2.1 TVN–S 1.1 TVN–S 1.2.2 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “TvTuner Objects” beginning on page 269.

Appendix B: JavaScript Catalog

443

Client-Side API

Object and properties
TvTuners array length musicText primary secondary TvProgram() User sysAdminEnabled sysDefault sysFirstScreen sysLanguagePreferences sysMasterAppId sysName sysRoamingName sysServices sysServices.length sysSetupDone sysUniqueId sysWebAccess changePassword() checkPassword() UserManager authentication users users.length addUser() deleteUser() evalWithPrivileges()

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.0 TVN–S 1.2.6 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.1 TVN–S 1.1 TVN–S 1.2.6 TVN–S 1.2 TVN–S 1.3 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.1 TVN–S 1.0 TVN–S 1.2 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.1 √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “UserManager Object” beginning on page 369. See “User Objects” beginning on page 359. √ √ √ √ See “TvTuners Array” on page 283. See Note 12 on page 452.

444

Content Developer’s Reference

Client-Side API

Object and properties
UserManager (continued) switchToUser() syncUserData() writeUserData() onadd() ondelete() onswitch() onsync() onwrite() VodSession channelId configInfo controlAddr id stream close() createStream() destroyStream() open() onerror() onopen() onstreamcreate() Window closed crypto crypto.random() crypto.signText() defaultStatus

Introduced in Supported Comments version
TVN–S 1.0 TVN–S 1.1 TVN–S 1.2.6.1 TVN–S 1.0 TVN–S 1.0 TVN–S 1.0 TVN–S 1.1 TVN–S 1.2.6.1 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 TVN–S 1.2.6 JS 1.0 JS 1.1 JS 1.2 JS 1.2 JS 1.2 JS 1.0 √ See Note 13 on page 452. √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ √ See “VodSession Objects” beginning on page 287..

Appendix B: JavaScript Catalog

445

Client-Side API

Object and properties
Window (continued) document frames frames.length history innerHeight innerWidth layer length location locationbar menubar name navigator navigator.length offscreenBuffering opener outerHeight outerWidth overscan pageXOffset pageYOffset parent personalbar screenX screenY scrollbars self

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.0 JS 1.1 JS 1.2 JS 1.2 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.0 JS 1.0 TVN–S 1.0 JS 1.2 JS 1.1 JS 1.2 JS 1.2 TVN–S 1.0 JS 1.2 JS 1.2 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.0 √ √ √ See overscan on page 103. √ See Note 14 on page 452. √ √ √ √ √ √ See layer on page 103. √ √ √ √

446

Content Developer’s Reference

Client-Side API

Object and properties
Window (continued) status statusbar toolbar top visible window alert() atob() back() blur() btoa() captureEvents() clearInterval() clearTimeout() close() confirm() disableExternalCapture() enableExternalCapture() find() focus() forward() handleEvent() home() moveBy() moveTo()

Introduced in Supported Comments version
JS 1.0 JS 1.2 JS 1.2 JS 1.0 TVN–S 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.2 JS 1.2 JS 1.0 JS 1.0 JS 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.2 √ See Note 14 on page 452. Not supported, but see History.forward. √ √ See Note 14 on page 452. √ Not supported, but see History.back(). See Note 14 on page 452. √ √ √ √ See visible on page 104. √ See Note 13 on page 452.

Appendix B: JavaScript Catalog

447

Client-Side API

Object and properties
Window (continued) open() passwordPrompt() print() prompt() releaseContext() releaseEvents() resizeBy() resizeTo() routeEvent() scroll() scrollBy() scrollTo() setHotKeys() setInterval() setResizable() setTimeout() setZOptions() stop() onblur() ondragdrop() onerror() onfirstdraw() onfocus() onkeyout()

Introduced in Supported Comments version
JS 1.0 TVN–A JS 1.2 JS 1.0 TVN–S 1.0 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.2 JS 1.0 JS 1.2 JS 1.2 JS 1.1 JS 1.2 JS 1.1 TVN–A JS 1.1 TVN–S 1.0 √ See onkeyout() on page 110 √ √ See Note 16 on page 452. See Note 15 on page 452. Deprecated in 1.2. √ See releaseContext() on page 109. √ See open() on page 105 and Note 14 on page 452.

448

Content Developer’s Reference

Client-Side API

Object and properties
Window (continued) onload() onmove() onresize() onunload() onvisible()

Introduced in Supported Comments version
JS 1.0 JS 1.2 JS 1.2 JS 1.0 TVN–S 1.0 √ √ See Note 17 on page 453. See onvisible() on page 110. √

Top-level functions
Constructors Array() Boolean() Cookie() Date() Function() Image() Number() Object() Option() String() VodSession()

Introduced in Supported Comments version
JS 1.1 JS 1.0 TVN–S 1.0 JS 1.0 JS 1.1 JS 1.0 JS 1.1 JS 1.0 JS 1.0 JS 1.0 TVN–S 1.2.6 √ √ √ √ √ √ √ √ √ √ √ See “VodSession Objects” on page 287. See Note 18 on page 453. See “Cookie Objects” on page 65. See Note 2 on page 450.

Appendix B: JavaScript Catalog

449

Notes

Top-level functions
Core functions escape() eval() isFinite() isNaN() Number() parseFloat() parseInt() String() taint() unescape() untaint()

Introduced in Supported Comments version
JS 1.0 JS 1.0 JS 1.2 JS 1.1 JS 1.2 JS 1.0 JS 1.0 JS 1.2 JS 1.1 JS 1.0 JS 1.1 √ See Note 9 on page 452. See Note 9 on page 452. √ √ √ √ √

Notes
1. Currently, TV Navigator doesn’t support applets or the part of JavaScript that
communicates with Java. Therefore, objects like Sun, Packages, JavaObject, and JavaClass are not defined at the present time. Because HTML <applet> tags are parsed, the Document.applets array is present, but the array is empty.

2. When called without any arguments, the Date constructor produces an object that records
the current date and time. On most set-top boxes, it captures the current time accurately down to milliseconds. Similarly, the Date.getTime() and Date.UTC() methods return the time as measured in milliseconds since 00:00:00 on January 1, 1970 (local time for getTime() and universal time for UTC()). However, on some platforms, it’s accurate only to seconds; 0 is recorded for the milliseconds. Other Date methods that refer to milliseconds are not supported, including the getMilliseconds() and setMilliseconds() methods, which were added in JavaScript version 1.3, and the milliseconds arguments to the following two versions of the constructor:
var obj = new Date(milliseconds); var obj = new Date(year, month, day, hour, minute, seconds, milliseconds);

450

Content Developer’s Reference

Notes

3. TV Navigator doesn’t support plug-ins—in the sense of independent modules that can be
dynamically loaded to handle particular types of data. However, it has built-in modules to handle embedded sounds, Macromedia Flash movies (release 1.3), and other data commonly associated with plug-ins. The Navigator.plugins array is present, but it’s empty. The Document.embeds array is also present. For some types of embedded data—notably sound files and Flash movies—objects in the array are well-defined and fully functional. However, for most types of data, the object is absent.

4. TV Navigator–S currently doesn’t support Document.write(), Document.writeln(), and
associated methods. It’s an especially thin client and is able to stay that way because the Transcoding Translator server preprocesses documents and does some of the layout work for it. At present, this deprives it of the ability to modify a document arbitrarily. Modifications can be made only in restricted realms—to table cells, options lists, and images, for example.

5. The selection of text is not under JavaScript control; it’s handled in the user interface by
other means. Therefore, the select() methods for Text, Textarea, Password, and FileUpload objects, though defined, are inoperative. The corresponding onselect() handlers for Text and Textarea are not defined. At the present time, TV Navigator–S doesn’t support the selection of text within a text field as a distinct event in the user interface. When a field is brought into focus, an insertion point appears and the user is able to begin entering (or editing) text at that point. Therefore, there is currently no conceptual difference between focusing on a text field and selecting the field.

6. The name assigned to a form element in HTML becomes a property of the Form object; the
property refers to the element (for example, to a Button, Checkbox, Textarea, or other object). This is standard JavaScript. TV Navigator differs from some other platforms in how it treats elements that share the same name: Generally, if a form contains two or more elements with the same name, the name will refer to just one of the elements. However, if the form contains a group of radio buttons all with the same name, the name will be an array of the radio buttons (an array of Radio objects). TV Navigator–S treats checkboxes like radio buttons; if more than one checkbox has the same name, the name refers to an array of Checkbox objects.

7. If a form contains an <img> tag, the image will be available by name as a property of the
Document object, but not of the Form object.

Appendix B: JavaScript Catalog

451

Notes

8. TV Navigator–S supports Image.lowsrc only as a read-only property. It lets you read the
value set in HTML, but you can’t modify it.

9. The data-tainting security model is not supported. (Data tainting has been replaced by
signed scripts in JavaScript 1.2.) TV Navigator uses a different security mechanism. See “JavaScript Security” on page 6 in Chapter 1 for details.

10. TV Navigator–S supports the top-level eval() function, but not the Object version (which is
deprecated in JavaScript 1.2).

11. The String methods that format a string with HTML tags—for example, String.bold() and
String.small()—are implemented, but they have limited utility for TV Navigator–S since it cannot display the formatted strings. Document.write() is disabled (see Note 4, above), form elements (like Option.text or Textarea.value) accept only plain text, and TableCell.write() likewise requires plain text.

12. In release 1.2.6 of TV Navigator–S, the musicText property is not attached to the TvTuners
array object, or to any other object; it’s a top-level variable.

13. Some Window properties—such as defaultStatus (1.0), scroll (1.1), menubar (1.2), scrollbar
(1.2), and toolbar (1.2)—refer to parts of the browser window. However, the windows that TV Navigator–S provides are blank rectangles; it’s up to applications (particularly the set of standard services) to provide the user interface. Therefore, although it may be possible to set a property like Window.status, the client doesn’t provide a place where the text can be automatically displayed.

14. TV Navigator–S supports Window.open() and can place multiple windows on-screen,
although with certain restrictions and extensions. The features that currently can be set are “width”, “height”, “left”, “top”, layer”, “visible”, “progressReported”, “autofocus”, and “history”—all but the first two being Liberate additions. See the discussion of the open() method on page 105.

15. TV Navigator adjusts all Web content so that it fits within the width of the TV screen.
Therefore, horizontal scrolling is not needed and not supported. Window.scroll() is not implemented by TV Navigator–S. For details on how TV Navigator lays out content for the TV screen, see “Automatic Adjustments” in the Content Developer’s Guide and Chapter 2, “TV Display,” in this manual.

16. Window.setTimeout() is compatible with JavaScript 1.1. It can evaluate an expression, but
cannot call a function, a variation introduced in JavaScript 1.2.

452

Content Developer’s Reference

Notes

17. The Window.onunload() handler is prevented from taking actions that risk referring to
freed objects. Most notably, it cannot look at objects corresponding to parts of the unloaded page (for example, Document, Image, and Form objects) and it cannot call the Window.alert() method.

18. Image objects are sometimes constructed as part of a strategy to prefetch image data before
the image is displayed. For example, the following code would fetch the requested image and cache it on the client:
var readyImg = new Image(width, height); readyImg.src = "artwork/img0041.gif";

The cached image can then be placed on-screen when it’s needed—typically when an event occurs—without any delay:
function invokeHandler() { document.images.target.src = readyImg.src; }

This strategy works for TV Navigator—on one condition: The width and height of the constructed Image object must exactly match the width and height of the target container for the image. If the target image was set up as follows,
<img name="target" width="320" height="240" src="originalImage.gif">

the Image object would have to be constructed with the same dimensions:
var readyImg = new Image(320, 240);

In addition to the specific points covered by these notes, the “Differences from Standard JavaScript” section on page 4 in Chapter 1 describes some other conditions and practices that may more broadly affect the way JavaScript is written for TV Navigator.

Appendix B: JavaScript Catalog

453

Notes

454

Content Developer’s Reference

Key Codes

APPENDIXM

The JavaScript Input object, described in Chapter 7, lets applications respond directly to users. When the user presses a key on a handheld remote (or on a keyboard, the front panel of the set-top box, or another input device), the key is recorded in a property of the Input object and one or more event handlers are called. The handler identifies the key by a numerical key code. This appendix explains how key codes are mapped to keys and it lists the codes that are assigned arbitrarily.

Character Keys
If a key can generate a character, its key code is the Unicode value for the character—the number that represents the character in the Unicode character set. Unicode encompasses the commonly used ISO 8859-1 (Latin 1) character set, and Latin 1 includes ASCII. Therefore, if a key produces a Latin 1 character, its key code matches the Latin 1 encoding for the character. If the key produces an ASCII character, its key code matches the ASCII value. This rule applies to all types of characters, including: • Visible characters (like the letter b and the symbol +), • Invisible characters that can be part of a text string (like a space or a new line), • Characters that affect the display of text (like the Backspace character), and • Other control characters (like Control-B or Control-F). For example, the key code for the key labeled G is 103 (hexadecimal 0x0067), the Unicode encoding for lowercase letter g. Similarly, the code for the 8 key is 56 (0x0038), the encoding for the digit 8. For Enter or an OK key, it’s 13 (0x000D), the code for a carriage return.

Appendix C: Key Codes

455

Character Keys

Modifiers
If modifier keys (such as Shift, Control, or Alt) can affect the character that’s produced, the key code may vary depending on which modifiers the user holds down. For example, Shift-G would be reported as 71 (0x0047), the code for uppercase G, and Control-G as 7 (0x0007). Currently, there’s no independent way to determine which modifier keys the user pressed; the key code is the only clue. An application can choose to turn character keys (particularly those modified by Control) into shortcuts for various purposes. For example, Control-Q could cancel an operation and ControlA could activate something.

The Enter Key
The Enter key—the key mapped to character value 13 (0x000D)—plays a central role in the TV Navigator user interface. Its principal function is to select the element currently in focus. For example, when the focus rectangle highlights a button, pressing the Enter key will “click” the button. If the focus is on a link, pressing Enter activates the link. This key also plays two other roles: • In a text area that accepts multiple lines, it starts a new line. • When the user is entering a channel number, it indicates that the last digit has been entered. On a handheld remote, this key might be label Select or OK, instead of Enter.

Exceptions for the Emulator
With few exceptions, all the keys that you’d expect to generate characters and have character values as their key codes follow the rules described at the beginning of the “Character Keys” section. However, there are some exceptions when you’re using a computer keyboard with the set-top emulator: • One exception is the Esc key. Its key code is not 27 (0x001D), the ASCII value normally associated with this key, but 769 (0x0300) for the key that turns the power on and off. In other words, Esc emulates the Power key. • Another exception is the Tab key. Instead of 0 (0x0009), the ASCII value for a tab character, its key code is 1293 (0x050D). It’s a navigation key that moves the focus from one element to another.

456

Content Developer’s Reference

Other Keys

• The keys on the numerical keypad are also exceptions. For the set-top emulator, they may be mapped to keys normally found on a remote control device. For example, the key labeled with an asterisk (*) on the keypad doesn’t have 42 (0x002A) as its key code, as the asterisk key on the main keyboard does. Instead, its code is 1038 (0x0403) for the key that returns to the previous channel. See the tables in the next section for information on other keypad keys. All other keys that normally produce characters have character values as their key codes.

Control-Enter
The Control-Enter combination is also an exception for the set-top emulator. This combination produces the same key code as Enter alone, 13 (0x000D), but the set-top emulator marks the input as coming from a handheld remote, not a keyboard. When an empty text field is in focus and the user presses the Enter (or Select or OK) key on a remote, TV Navigator assumes that the user wants to enter text but doesn’t have a keyboard at hand. It therefore places a software keyboard on-screen for the user to “type” with. The Control-Enter combination simply emulates the Enter key on a remote in order to support this user interface.

Other Keys
Keys that don’t generate characters have arbitrarily assigned key codes. There are four groups of these keys: Keys 0x0300 through 0x0311 Keys 0x0400 through 0x0415 Keys 0x0500 through 0x050F Platform-Defined Keys (keys 0x800 through 0x0807) Most keys for controlling television fall in the second group and most navigation keys fall in the third group. The following tables describe the keys in each group. Not all platforms will generate all the key codes listed. For example, the remotes for some settop boxes might not have a Print (781) or a Jump (1041) key. Similarly, the Service Manager and the set of installed services may not respond to all the key codes that are generated.

Appendix C: Key Codes

457

Other Keys

Keys 0x0300 through 0x0311
Key code (decimal, hexadecimal)
768, 0x0300 769, 0x0301 770, 0x0302 771, 0x0303 772, 0x0304 773, 0x0305 774, 0x0306 775, 0x0307 776, 0x0308 777, 0x0309

Likely key cap for a handheld remote
, Power Home Mail Guide Search Fav, Favorites Menu, Home, Interactive Info,

Key cap for the Function set-top emulator
Esc Toggles the power on and off.

Control-Home Goes to the user’s “home” page or the principal page of the user interface. F2 F3 Brings up an e-mail application, like Liberate TV Mail. Brings up a guide to the channels and the Web. Goes to a Web search engine. The / key on the keypad Alt (either left or right) Insert Goes to the next channel in the list of the user’s favorite channels. Shows and hides the menu bar or otherwise gives the user access to Web sites on the Internet. Presents information about the program showing on TV or the current Web site. Brings up a marquee or ticker service. Brings up the panel for ordering pay-perview (PPV) programs, particularly video-ondemand (VOD) or near video-on-demand (NVOD) programs. Shows and hides the history list of recently visited Web sites. F1 F4 Brings up online help information. Displays the current settings.

i
Ticker VOD, NVOD, PPV Recent, History ?, Help Settings

778, 0x030A 779, 0x030B 780, 0x030C

458

Content Developer’s Reference

Other Keys

Keys 0x0300 through 0x0311 (continued)
Key code (decimal, hexadecimal)
781, 0x030D 782, 0x030E 783, 0x030F 784, 0x0310 785, 0x0311

Likely key cap for a handheld remote
Print TV + Chat Messenger Go

Key cap for the Function set-top emulator
Prints the current page. Reserved for the service facilitating Web enhancements for TV programs. Brings up a chat application, like Liberate TV Chat. Brings up a messaging service, like Liberate TV Messenger™. Brings up a panel where the user can enter a URL to browse the Web.

Keys 0x0400 through 0x0415
Key code (decimal, hexadecimal)
1024, 0x0400 1025, 0x0401 1026, 0x0402 1027, 0x0403 1028, 0x0404 1029, 0x0405

Likely key cap for a handheld remote
Chan +, Chan ↑ Chan –, Chan ↓ Vol +, Vol ↑ Vol –, Vol ↓ , Fast Rewind , Rewind

Key cap for the Function set-top emulator
The + key on the keypad The – key on the keypad F11 F10 F6 Goes to the next higher channel. Goes to the next lower channel. Increases the volume, undoing mute if necessary. Decreases the volume. Rewinds quickly. Rewinds slowly.

Appendix C: Key Codes

459

Other Keys

Keys 0x0400 through 0x0415 (continued)
Key code (decimal, hexadecimal)
1030, 0x0406 1031, 0x0407 1032, 0x0408 1033, 0x0409 1034, 0x040A 1035, 0x040B 1036, 0x040C 1037, 0x040D , Fast Forward , Pause , Play Rec, Record , Stop Mute Zoom, TV/Net F7 F12 Pause F9 F5 F8

Likely key cap for a handheld remote

Key cap for the Function set-top emulator
Moves forward slowly. Moves forward quickly. Pauses. Begins playing. Begins recording. Stops recording. Toggles audio output on and off. Toggles between showing Web content (including any overlay windows the content uses) and a full-screen display of the current channel (without overlay windows). Goes to the previous channel. Removes any overlay windows from the screen, exits Web content, and displays only the current channel. Turns the picture-in-picture (or TV-in-Web) feature on and off. Jumps back to a targeted Web site or channel.

1038, 0x040E 1039, 0x040F 1040, 0x0410 1041, 0x0411

Prev, Last Exit

The * key on the keypad Scroll Lock

PIP Jump

460

Content Developer’s Reference

Other Keys

Keys 0x0400 through 0x0415 (continued)
Key code (decimal, hexadecimal)
1042, 0x0412 1043, 0x0413 1044, 0x0414 1045, 0x0415

Likely key cap for a handheld remote
A, red key cap B, green key cap C, yellow key cap D, blue key cap

Key cap for the Function set-top emulator
Control-F1 Control-F2 Control-F3 Control-F4 The first shortcut or “fast-text” key. The second shortcut or “fast-text” key. The third shortcut or “fast-text” key. The fourth shortcut or “fast-text” key.

Keys 0x0500 through 0x050F
Key Code (decimal, hexadecimal)
1280, 0x0500 1281, 0x0501 1282, 0x0502 1283, 0x0503 1284, 0x0504 1285, 0x0505 1286, 0x0506

Likely key cap for a handheld remote
↑, ∧ ↓, ∨ ←, < →, > ∧ ∧ ∨ ∨ <<

Key cap for the Function set-top emulator
↑ ↓ ← → Page Up Page Down Moves up to the nearest focusable element. Moves down to the nearest focusable element. Moves left to the nearest focusable element. Moves right to the nearest focusable element. Scrolls up one screenful. Scrolls down one screenful. Undefined.

Appendix C: Key Codes

461

Other Keys

Keys 0x0500 through 0x050F (continued)
Key Code (decimal, hexadecimal)
1287, 0x0507 1288, 0x0508 1289, 0x0509 1290, 0x050A 1291, 0x050B 1292, 0x050C 1293, 0x050D 1294, 0x050E 1295, 0x050F Hop Hop Back

Likely key cap for a handheld remote
>> Back Forward, Fwd Clear, Delete Reload, Refresh

Key cap for the Function set-top emulator
Undefined. Home End Delete Control-End Shift-Tab Goes to the previous Web site or channel in the history list. Goes to the next Web site or channel in the history list. Erases all text from the text field that’s currently in focus. Reloads the current page. Moves the focus to the left, as key 0x0500 would, but wraps up and to the right when it can go no farther left. Moves the focus to the right, as key 0x0501 would, but wraps down and to the left when it can go no farther right. Moves the focus to the next frame down or to the right. Moves the focus to the next frame up or to the left.

Tab

ControlShift-Tab Control-Tab

Platform-Defined Keys
Service providers can define additional key codes for unique or platform-specific keys—such as a key dedicated to a special application. The codes for those keys begin at 2048 (0x0800). To make development with platform-defined keys easier, the set-top emulator maps keys on a standard computer keyboard to the first eight key codes (0x0800 through 0x0807).

462

Content Developer’s Reference

Key Handling

The following table shows the mapping:

Key Code (decimal, hexadecimal)
2048, 0x0800 2049, 0x0801 2050, 0x0802 2051, 0x0803 2052, 0x0804 2053, 0x0805 2054, 0x0806 2055, 0x0807

Key cap for the set-top emulator
Control-F5 Control-F6 Control-F7 Control-F8 Control-F9 Control-F10 Control-F11 Control-F12

Key Handling
As discussed under the Input object (see the “Input Handling” section in Chapter 7, “System Capabilities”), input keys are handled in three steps:

1. An Input.onkeyin() event handler is given the first chance to respond to the key. 2. If the onkeyin() handler doesn’t consume the key, TV Navigator’s built-in handler tries to
respond.

3. If the built-in handler can’t do anything with the key, a series of one or more onkeyout()
event handlers are called.

Appendix C: Key Codes

463

Key Handling

The built-in handler (Step 2) takes care of navigation within a page and standard HTML tasks, such as input to forms. In particular, it knows what to do with the following kinds of keys: • It handles keys that navigate within a page by scrolling and moving the focus rectangle. • If the focus is on a text area or text field, it handles all key codes with Unicode values—that is, all keys mapped to characters, including keys (like Backspace) that edit the text. • If the focus is on a link, a scroll arrow, a button, or another element, it responds to the Enter key—key code 13 (0x000D)—by following the link, scrolling, initiating the action of the button, and so on. It’s up to the Service Manager, acting on behalf of the services it manages, to handle (or purposefully ignore) every other key code that the platform generates. Services can register functions that the Service Manager will call. See the Service Developer’s Guide for details.

464

Content Developer’s Reference

Playing Sounds

APPENDIXM

Content created for TV Navigator can associate sounds with a Web page in three ways: • As background sounds—played with the standard <bgsound> tag. You can loop through the sound a specified number of times or have it played repeatedly. For example:
<bgsound src="http://www.yourdomain.com/kaboom.wav" loop="3">

• As linked sounds—played when the user follows a link to the sound file. The sound is played only once, when the file is loaded. For example:
<a href="http://www.yourdomain.com/kaboom.wav">Kaboom!!</a>

• As embedded sounds—placed on the page with the standard <embed> tag. For example:
<embed src="http://www.yourdomain.com/kaboom.wav" . . .>

In all cases, sound data must be in one of the supported audio formats listed in Chapter 9, “Content Data Types.” Currently, TV Navigator can play embedded sounds only if they are declared to be user interface (UI) sounds—the various clicks, beeps, and shwooshes that accompany user actions, such as when the user selects a radio button or presses a key. A Liberate–defined attribute, uiSound, notifies TV Navigator that the sound is to be used in the user interface. Embedded sounds without this attribute are ignored. User-interface sounds are always hidden; they don’t have a visual presence on-screen and are not subject to user control. They’re played by calling the Embed object’s play() method, usually from a JavaScript event handler, as illustrated in the example on the next page. The example shows a user-interface sound that’s played when the user selects a button, from the button object’s onclick() handler.

Appendix D: Playing Sounds

465

Playing Sounds

<html> <head> <title>UI sound demonstration</title> <script language="JavaScript"> function playClick() { document.sound1.play(); } </script> </head> <body bgcolor="#EEFFFF"> . . . <form> <input type="button" value="Click This!" name="b1" onclick="playClick();"> </form> . . . </body> <embed src="click.wav" name="sound1" width="0" height="0" loop="4" uiSound> </html>

This example shows the <embed> tag with six attributes: • The src attribute specifies the sound file (“click.wav”) and name gives it a name (“sound1”). The script then uses the name to identify the embedded sound as a property of the Document object. It defines a playClick() function that calls the sound’s play() method; the onclick() handler calls playClick() when the user invokes the button. • The height and width attributes are required for compatibility with other browsers, but their values are ignored. • The loop attribute specifies that the sound will be played an annoying four times when play() is called. • The uiSound attribute is required for TV Navigator to recognize the sound. The standard hidden attribute is not specified, but is assumed. Other attributes of the <embed> tag are not supported. Because UI sounds are played immediately in response to a user action, there’s not enough time to stream them in over the network. This means that they stay resident in RAM, taking up valuable resources. Be aware of the space that UI sounds consume, and keep them small.

466

Content Developer’s Reference

Playing Flash Movies

APPENDIXM

TV Navigator can play Macromedia Flash™ movies created in the Flash 4.0 SWF format. This support was added in the 1.3 release; it’s not available in the 1.1 and 1.2 versions of TV Navigator and may be present only in some deployments of 1.3. You can load a Flash movie into a window or frame by making it the subject of a link,
<a href="demoMovie.swf">See a demonstration.</a>

or by assigning it as the source document of a frame:
<frame src="demoMovie.swf">

However, movies are typically placed on a page using the <embed> tag. For example, the following HTML fragment places a Flash movie (skiing.swf) in a container that’s 200 pixels wide and 100 pixels high:
<embed src="skiing.swf" width="200" height="100" name=”skiingMovie”></embed>

This fragment shows the <embed> tag with a set of commonly used attributes. A source file (the src attribute) must be specified. The width and height of the display area, while not required, are recommended for efficient page translation. The name attribute is required only if the movie will be manipulated in JavaScript (see “Using JavaScript” on page 472).

Attributes of the <embed> Tag
This section describes how TV Navigator treats common attributes of the <embed> tag when it’s used to embed a Flash movie. If attributes other than those listed are included in the tag, TV Navigator ignores them. If you don’t specify a value for an optional attribute, TV Navigator uses the default value.

Appendix E: Playing Flash Movies

467

Attributes of the <embed> Tag

base
SYNOPSIS: DESCRIPTION:

1.3

The base URL used to resolve relative path statements in the Flash movie. For example:
<embed src="skiing.swf" base="http://www.liberate.com/" . . .>

bgcolor
SYNOPSIS: DESCRIPTION:

1.3

The background color of the movie. This attribute overrides the background color setting in the Flash file. It takes a hexadecimal red-green-blue color specification (#RRGGBB) or the special color name “transparent” for a transparent background. Other color names are not supported. For example, an indigo background would be specified as follows:
<embed src="skiing.swf" bgcolor="#4B0082" . . .>

height

see width

highlightable
SYNOPSIS: DESCRIPTION:

1.3

Determines whether or not the user can select elements within the movie— “true” if it’s possible and “false” if not. The default is “true”.

loop
SYNOPSIS: DESCRIPTION:

1.3

Whether or not to repeat the movie indefinitely—“true” if it should begin playing again at the first frame whenever it reaches the final frame, and “false” if it should stop on the final frame. The default value is “true”.

468

Content Developer’s Reference

Attributes of the <embed> Tag

name
SYNOPSIS: DESCRIPTION:

1.3

A name that can be used to refer to the movie in JavaScript. For example, the following assignment,
<embed src="skiing.swf" name="crash" . . .>

would allow a script to find the corresponding Embed object as follows:
<script> var theMovie = window.document.crash; theMovie.Play(); . . . </script>

If there’s more than one <embed> tag on the page, be sure to use a unique name for each one.

play
SYNOPSIS: DESCRIPTION:

1.3

Whether or not the movie will play automatically when it’s loaded—“true” if it should play automatically and “false” if not. The default is “true”. If you set this attribute to “false” to prevent the movie from playing automatically, you must use a JavaScript method to begin the movie animation.

pluginspage
SYNOPSIS:

DESCRIPTION:

The pluginspage attribute tells the browser where to find the Flash plugin if it is not detected. TV Navigator ignores this attribute because Flash capability is built into the TV Navigator application engine. However, if your movie will be shown on other browsers, you should use this attribute.

Appendix E: Playing Flash Movies

469

Attributes of the <embed> Tag

quality
SYNOPSIS: DESCRIPTION:

1.3

salign
SYNOPSIS: DESCRIPTION:

1.3

Specifies how the movie is to be aligned when it’s resized using the scale attribute. The default behavior centers the movie in the specified area, and crops the edges if the movie does not fit. The salign attribute is ignored if it is used without a corresponding scale attribute. The values position the movie along one edge or two adjacent edges of the containing rectangle, and crop it if necessary: The values are “L” (left), “R” (right), “T” (top), “B” (bottom), “TL” (top and left), “TR” (top and right), “BL” (bottom and left), and “BR” (bottom and right).

scale
SYNOPSIS: DESCRIPTION:

1.3

Specifies how the movie should be scaled to its container. This attribute applies only when the width and height specified are different from the movie’s original size. The values behave as follows: • “showall” makes the entire movie visible in the available area, while maintaining the aspect ratio. Borders may appear on two sides of the movie. This is the default setting. The effect is similar to a wide-screen film shown on a TV screen in “letterbox” format; a black border is shown above and below the film. • “noborder” shows as much of the movie as possible in the available area, while maintaining the aspect ratio. Parts of the movie that do not fit in the available area are cropped. The effect is similar to watching a wide-screen film that has been cropped on the sides (“panned and scanned”) to fit the narrower width of a TV screen. • “exactfit” forces the movie to fit the entire visible area. Aspect ratio will not be maintained, and distortion will occur.

470

Content Developer’s Reference

Attributes of the <embed> Tag

src
SYNOPSIS: DESCRIPTION:

1.3

The source file for the movie. The URL can be relative or absolute. For example:
<embed src="skiing.swf" . . .> <embed src="http://www.downhilldisasters.com/x/skiing.swf" . . .>

Although most of the other attributes are optional, this one is obligatory. Your must specify a source.

ui
SYNOPSIS: DESCRIPTION:

1.3

This attribute has no value. It’s either present or absent. Its presence indicates that the movie plays a role in the user interface. TV Navigator takes this fact into account when it needs to reclaim memory to make room for new data. It tries to free other things, including other Flash movies, before getting rid of a movie marked with this attribute.

width, height
SYNOPSIS:

1.3 1.3

DESCRIPTION:

These attributes specify a size for the movie; they override the size set in the Flash file. When set as a percent, they define the size of the movie in relation to the available screen area. When set as pixels, they define an absolute width and height. As such, they’re interpreted similarly to the width and height attributes of the <table> tag. For example:
<embed src="skiing.swf" width="80%" height="60%" . . .> <embed src="snowboarding.swf" width="150" height="300" . . .>

If only one of these attributes is specified, TV Navigator will attempt to maintain the aspect ratio of the movie.

Appendix E: Playing Flash Movies

471

Using JavaScript

Although width and height are optional, these attributes should be used whenever possible to improve transcoding performance.
SEE ALSO :

scale, salign

Using JavaScript
The JavaScript object for an embedded Flash movie has a number of methods that you can use to manipulate the movie dynamically. This API is defined by Macromedia. It’s described here as a convenience. You should also see the Macromedia documentation. Descriptions of some of the methods can be found at the following URL: http://www.macromedia.com/software/flash/open/licensing/sourcecode/index_javascriptAPI.fhtml

Getting the Embed Object
The Embed object for an embedded Flash movie can be located using the name assigned in HTML. That name becomes the name of a property of the Document object:
<script> var mm = window.document.myMovie; . . . </script> . . . <embed src="movies/animation34.swf" name="myMovie" . . .>

The Embed object can also be located in the Document object’s embeds array:
var mm = window.document.embeds[index];

Timing Considerations
When using JavaScript on a Flash movie, you must ensure that the movie is loaded before executing your scripts. The following code fragment lets the user know when interaction is possible. You can adapt this fragment to suit your needs.
<script> function WaitForFlash() { if ( document.myMovie.PercentLoaded() < 100 ) { setTimeout("WaitForFlash();", 100); }

472

Content Developer’s Reference

Properties of the Embed Object

else { alert("Flash is ready to interact with now."); } } </script> . . . <body onload="WaitForFlash();" . . .>

Note that this function is not recursive—it doesn’t call itself, directly or indirectly. Rather, it calls setTimeout() and returns. When the timeout (100 milliseconds in the example) expires, the function is called again, resulting in a series of independent invocations until the Flash file is 100% loaded. If this function was recursive, it could consume great amounts of memory, causing a JavaScript error.

Targeted Methods
Flash 4 introduced a number of methods that begin with the letter T and take a target string as the first argument. These methods act on a sprite or layer defined within the movie, the sprite or layer named by the target argument. If the target is an empty string, “”, they act on the base movie just like methods without an initial T. In some cases, a T method has a counterpart without the T or target argument—for example, TPlay() and Play(), or TGotoFrame() and GotoFrame(). These paired methods work alike, except that one can target a particular sprite or layer. and the other cannot

Properties of the Embed Object
name
SYNOPSIS:

name 1.3 read-only string The name assigned in HTML. the name attribute on page 469

DESCRIPTION: SEE ALSO:

Appendix E: Playing Flash Movies

473

Methods of the Embed Object

src
SYNOPSIS:

src

1.3

read/write string
DESCRIPTION:

The URL of the source file set in HTML. Setting this property to a different URL changes the movie that is displayed. You must call a method to begin playing the new movie; it won’t play automatically. LoadMovie(), the src attribute on page 471

SEE ALSO :

Methods of the Embed Object
CurrentFrame() FlashVersion()
SYNOPSIS: DESCRIPTION:

see TotalFrames()

number FlashVersion(void)

1.3

Returns 0x4001c in the current version of TV Navigator Standard. This is a compound value: The major version is 4, and the minor version is 0x1c. It is similar in function, but not syntax, to the Flash internal variable $VERSION.

FrameLoaded()
SYNOPSIS: DESCRIPTION:

boolean FrameLoaded(number frame)

1.3

Returns true if the Frame number specified by frame is loaded, and false if not.

GetVariable(), SetVariable()
SYNOPSIS:

1.3 string GetVariable(string varName) string GetVariable(string timeline:varName)

1.3 1.3

1.3 void SetVariable(string varName, string value) void SetVariable(string timeline:varName, string value)
DESCRIPTION:

These methods get and set variables in the Flash movie. Variables are attached to a single timeline, so in a movie with more than one timeline you must

474

Content Developer’s Reference

Methods of the Embed Object

specify the timeline. Refer to Macromedia’s Flash documentation for more information about working with variables. GetVariable() returns the value in the Flash movie of the variable specified by the argument varName. It returns null if the variable does not exist. In a movie with a single timeline, this is a simple task:
var firstName = movie.GetVariable(“FirstName”);

In the following example of a movie with more than one timeline, GetVariable() returns the value of the text field “FirstName” inside the movie clip “Register”
firstName = movie.GetVariable(“/Register/TextField:FirstName”);

SetVariable() sets the value of the Flash movie variable specified by varName to the value specified by value. It uses the same syntax for indentifying the timeline of the variable as GetVariable().

GotoFrame()
SYNOPSIS: DESCRIPTION:

void GotoFrame(number frame)

1.3

Activates the frame number specified by frame in the current movie. If the data for a requested frame is not yet available, the player goes to the last frame available and stops, causing unexpected results during playback. Use the PercentLoaded() method to determine if enough of the movie is available to execute the GotoFrame() method. The argument frame is zero-based; that is, frame is 0 in the first frame of the movie, 1 for the second frame, and so on. This differs from the Goto action within Flash, which begins at 1.

IsPlaying()

see Play()

LoadMovie()
SYNOPSIS: DESCRIPTION:

void LoadMovie(number layer, string url)

1.3

Loads a new Flash movie into the specified layer. Specifying a layer of 0 will replace the currently displayed movie. The url argument is the URL of the source SWF file.

Appendix E: Playing Flash Movies

475

Methods of the Embed Object

Pan()
SYNOPSIS: DESCRIPTION:

void Pan(number x, number y, number mode)

1.3

Pans a zoomed-in movie to the coordinates specified by x and y. Use mode to specify whether the values for x and y are pixels or a percent of the window. When mode is 0, the coordinates are pixels; when mode is 1, the coordinates are a percent of the window width and height. Pan() does not pan beyond the boundaries of the zoomed-in movie.

PercentLoaded()
SYNOPSIS: DESCRIPTION:

number PercentLoaded(void)

1.3

Returns the percent of the Flash movie that has streamed into the browser. Possible values are from 0 to 100.

Play(), StopPlay(), IsPlaying(), TPlay(), TStopPlay()
SYNOPSIS:

void Play(void)

1.3 1.3 1.3 1.3 1.3

void StopPlay(void)

boolean IsPlaying(void) void TPlay(string target)

void TStopPlay(string target)
DESCRIPTION:

The Play() and StopPlay() methods start and stop the movie, respectively. IsPlaying() returns the current status of the movie—true if it’s playing, false if not. These TPlay() and TStopPlay() methods start or stop playing the specified target (a named sprite or layer). Refer to the Flash documentation for the syntax of the target parameter.

Rewind()
SYNOPSIS: DESCRIPTION:

void Rewind(void) Rewinds the movie to the first frame.

476

Content Developer’s Reference

Methods of the Embed Object

SetVariable()

see GetVariable() see Zoom()

SetZoomRect() StopPlay()

see Play()

TCallFrame(), TCallLabel()
SYNOPSIS:

void TCallFrame(string target, number frameNumber) void TCallLabel(string target, number frameLabel)
1.3

1.3

DESCRIPTION:

These two methods execute the action(s) specified in the frame identified by frameNumber for TCallFrame() or frameLabel for TCallLabel(). The target parameter refers to a sprite or layer name. If the target is an empty string, the global movie in layer 0 is used. Refer to the Flash documentation for the syntax of the target parameter. Note that these methods are different from GoToFrame(), which plays the movie from the specified frame. These methods return after executing the action(s).

TCurrentFrame() TCurrentLabel() TGetProperty()

see TotalFrames() see TotalFrames() see TSetProperty() see TSetProperty()

TGetPropertyAsNumber() TCurrentFrame()

see TotalFrames()

TGotoFrame(), TGotoLabel()
SYNOPSIS:

void TGotoFrame(string target, number frame) void TGotoLabel(string target, string label)
1.3

1.3

DESCRIPTION:

These two methods advance the timeline of the target (named sprite or layer) to the frame specified by frame or label. Refer to the Flash documentation for the syntax of the target parameter.

Appendix E: Playing Flash Movies

477

Methods of the Embed Object

If the data for a requested frame is not yet available, the player goes to the last frame available and stops, causing unexpected results during playback. Use the PercentLoaded() method to determine if enough of the movie is available to execute these methods. The argument frame is zero-based; that is, frame is 0 in the first frame of the timeline, 1 for the second frame, and so on. This differs from the Goto action within Flash, which begins at 1.

TotalFrames(), CurrentFrame(), TCurrentFrame(), TCurrentLabel()
SYNOPSIS:

number TotalFrames(void) number CurrentFrame(void)

1.3 1.3 1.3

number TCurrentFrame(string target) stringTCurrentLabel(string label)
DESCRIPTION:

1.3

TotalFrames() returns the total number of frames in the movie, while CurrentFrame() returns the number of the currently displayed frame. TCurrentFrame() returns the currently playing frame number of the specified object (named sprite or layer). It returns –1 if the object does not exist. TCurrentLabel() returns the currently playing frame label of the specified object. It returns null if the object does not exist. Refer to the Flash documentation for the syntax of the target parameter.

TPlay()

see Play() see Play()

TStopPlay()

TSetProperty(), TGetProperty(), TGetPropertyAsNumber()
SYNOPSIS:

void TSetProperty(string target, number property, string value) string TGetProperty(string target, number property)
1.3

1.3

number TGetPropertyAsNumber(string target, number property)
DESCRIPTION:

1.3

Use these three property methods to get and set properties of objects in Flash movies. Individual properties of objects in Flash movies are identified by an

478

Content Developer’s Reference

Methods of the Embed Object

index number. For these three property methods, use the following table to identify the integer to use for the property parameter:

Description
X Position Y Position X Scale Y Scale Current Frame Total Frames Alpha Visibility Width Height Rotation Target Path Frames Loaded Instance Name Drop Target Path URL High Quality Focus Rectangle Sound Buffer Time

Property Constant
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 X_POS Y_POS X_SCALE Y_SCALE CURRENT_FRAME TOTAL_FRAMES ALPHA VISIBLE WIDTH HEIGHT ROTATE TARGET FRAMES_LOADED NAME DROP_TARGET URL HIGH_QUALITY FOCUS_RECT SOUND_BUF_TIME

Getable Setable
yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes yes no no yes yes no no yes no no yes no no yes yes yes

The property methods operate on the timeline indicated by target. Refer to the Flash documentation for the syntax of the target parameter. The TGetProperty() method and the TGetPropertyAsNumber() method both perform the same function, but differ in the way they return data.

Appendix E: Playing Flash Movies

479

Methods of the Embed Object

In the following example, the var statement substitutes a name for the property parameter. This makes the code easier to read.
var visibilityIndex = 7; var nameIndex = 13; movie.TSetProperty("/MovieClip", visibilityIndex, 1); movie.TSetProperty("/MovieClip", nameIndex, "NewName");

TStopPlay()

see Play()

Zoom(), SetZoomRect()
SYNOPSIS:

void Zoom(number percent)

1.3

void SetZoomRect(number left, number top, number right, number bottom, 1.3 number percent)
DESCRIPTION:

The Zoom() method zooms the view in the current movie by a relative scale factor specified by the percent argument. If percent is 50, it doubles the size of the objects in the view. If percent is 200, it reduces the size of objects in the view by one half. Passing 0 as the percent resets the view to 100%. You cannot specify a reduction in the size of objects in the view when the current view is already 100%. SetZoomRect() zooms in on a rectangular area of the movie. Note that the units of the coordinates are in twips (1440 units per inch). To calculate a rectangle in Flash, set the ruler units to points and mulitply the coordinates by 20 to get twips. Distances are measured from the upper-left corner of the movie.

480

Content Developer’s Reference

INDEX
A
<a> highlightable 29 access control lists (ACLs) 7 accessControlled property TvChannel object 223 TvProgram object 258 ACLs (access control lists) 7 add(), History object 80 addIndex() 243 addToUrlFilter() 202 addUser() 370 administrative privileges 323, 359 Advanced Television Enhancement Forum (ATVEF) 200 ageRating property 259 align property 133 alpha property 39 appData property 83 append() 100 appId property 168 application/x-dtv-script 382 application/x-javascript 382 application/x-shockwave-flash 382 attach() 169 ATVEF (Advanced Television Enhancement Forum) 200 audio property 259 audio/aiff 380 audio/basic 380 audio/wav 381 audio/x-aiff 380 audio/x-wav 381 Authentication object hint 334 onkeyset() 337 onreset() 337 reset() 335 setKey() 336 status 334 authentication property 369 availableComponents property

224

B
back() 81 background attribute <frameset> 21 <select> 61 <td> 122 background property, TableCell object background sounds 465 base attribute, for Flash movies 468 <basefont> size 31 behavior property 136 bgColor 97, 98 bgcolor attribute <body> 22 Flash movies 468 <input> 22 <select> 61 table tags 22 <textearea> 22 bgColor property TableCell object 134 Text object 97 Textarea object 98 <bgsound> tag 465 binaryData property 159 blackedOut property TvChannel object 228 TvProgram object 260 blocked property 228 blur() Link object 48 Table object 127 <body> overscan 23

134

Index

481

border attribute 33, 35 bottomLine property 99 broadcast streams 185, 387

C
Cache object 86, 147 remove() 147 cache property Navigator object 86 NetRequest object 177 cancel() 182 cancelPurchase() 194 captions property 260 captureStill() 276 category property 229 cellpadding attribute 35 cells property 143 cellspacing attribute 35 changePassword() 367 changePin() 194 channel property, Trigger object 204 channelId property, VodSession object channels property TvProgram object 260 TvTuner object 271 checkPassword() 368 checkPin() 194 clear() 127 close() VodSession object 292 Window object 105 colSpan property 137 ConditionalAccess object 193 cancelPurchase() 194 changePin() 194 checkPin() 194 credit 193 getInfo() 195 onalarm() 196 oncommand() 196 purchase() 196 configInfo property 289 connected property 151

289

contentType property 160 control() 313 controlAddr property 290 controlled 15 controlled API 7 Cookie object 65 constructor 69 domain 70 expiration 71 load() 73 name 71 path 70 remove() 73 secure 72 store() 74 transmitted 72 value 72 cookies property 66, 77 createStream() 291 credit property 193 curChannel property 272 curChar property 305 curIndex property 80 curKey property 305 curLineCount property 98 curProgram property 229 current user 86, 322 curSpeed property 212 curTime property 213 curUser property 86

D
deleteIndex() 243 deleteUser() 370 deliveryMode property 261 description property TvChannel object 229 TvProgram object 262 destroyStream() 291 detach() 169 deviceNumber property 306 deviceType property 306 direct property 177

482

Content Developer’s Reference

direction property 136 Display object 39, 87, 270 alpha 39 format 40 preferredFormat 41 programDefaults 41 retainSettings() 45 safeArea 42 screenArea 42 settingsAlwaysRetained 42 tvVisible 43 videoOn 44 wideScreenStyle 44 display property 87 Document object 77 cookies 77 write() not supported 4, 451 domain property 70 drawingDisabled property 126 duration property 262 dynamicCols attribute 120

E
elisionString property 137 Embed object (for Flash movies) FlashVersion() 474 FrameLoaded() 474 GetVariable() 474 GotoFrame() 475 IsPlaying() 476 LoadMovie() 475 name 473 Pan() 476 PercentLoaded() 476 Play() 476 Rewind() 476 SetVariable() 474 SetZoomRect() 480 src 474 StopPlay() 476 TCallFrame() 477 TCallLabel() 477 TGetProperty() 478 472

TGetPropertyAsNumber() 478 TGotoFrame() 477 TGotoLabel() 477 TPlay() 476 TSetProperty() 478 TStopPlay() 476 Zoom() 480 Embed object (for sounds) 465 play() 465 Embed object (in general) 451 enabled property 200 encrypt() 95 ensureConnection() 151 ETv object addToUrlFilter() 202 enable 200 ontrigger() 204 resetUrlFilter() 202 setChannelFilter() 203 triggerUrl 201 unmatchedUrlsAccepted 201 eTv property 273 evalWithPrivileges() 371 event handlers arguments to 411 capitalization of 411 defining 10 event handlers, defined 16 exclusive 15 exclusive API 10 expiration property Cookie object 71 Trigger object 204 extensions property 87

F
fastForward() 215 fastForwardSpeed property fetch() 182 fgColor property 138 findChannel() 278 findColsNeeded() 140 findFit() 141 213

Index

483

Flash <embed> attributes base 468 bgcolor 468 height 471 highlightable 468 loop 468 name 469 play 469 pluginspage 469 quality 470 salign 470 scale 470 src 471 ui 471 width 471 Flash movies 467 Embed object for 472 timing considerations 472 using JavaScript with 472 focus stack (of Windows) 295 focus() Link object 48 Table object 127 focusable attribute <td> 121 <textarea> 30 focusable property TableCell object 139 Textarea object 99 <font> size 31 format property Display object 40 TvTuner object 273 formats NTSC 40, 50, 273 PAL 40, 50, 273 forward() 81 <frameset> background 21 border 33 overscan 23 frequency property 230

frozen property 274 fullGo() 81 fullName property 232

G
getInfo() 195 getNext() 253 getPref() 253 getValue() 149 go() History object 81 HistoryEntry object 84 guest user 324, 364

H
<h1> through <h6> 32 headers property NetEvent object 161 NetRequest object 178 NetSession object 187 height attribute Flash movies 471 <table> 36 height property SafeArea object 51 ScreenArea object 50 hidden property 231 highlightable attribute <a> 29 Flash movies 468 <table> 122 <td> 122 highlightable property Link object 47 TableCell object 139 hint property 334 history attribute 57 History object 79 add() 80 back() 81 curIndex 80 forward() 81

484

Content Developer’s Reference

fullGo() 81 go() 81 remove() 80 HistoryEntry object 79 appData 83 go() 84 title 83 toString() 84 <hr> 34 href attribute 63 hspace attribute 32 http-equiv attribute 57

popFocus() 308 pushFocus() 308 setExclusiveKeys() 309 timestamp 307 input property 88 insertKeys() 308

J
Java 4, 450 JavaScript entities 411

K
key codes 455 key handling 298, 463 keyFrames property 214

I
id property 231 ProgramStream object 214 VodSession object 290 image/gif 381 image/jpeg 382 image/png 382 <img> border 33 hspace 32 width 33 indexes property 241 Indicator object 88, 301 name 302 type 302 value 302 indicators property 88 info property 274 initialfocus attribute 27 <input> bgcolor 22 <input> nocursor 28 Input object 88, 305 curChar 305 curKey 305 deviceNumber 306 deviceType 306 insertKeys() 308 onkeyin() 310 onkeyout() 310

L
layer property 103 left property 51 <link> 63 Link object 47 blur() 48 focus() 48 highlightable 47 name 47 linked sounds 465 load() 73 loop attribute Flash movies 468 for embedded sounds loop property 136

466

M
Macromedia Flash 467 master application 1 maxLineCount property mcast: protocol 387 Mediacast 185, 387 mediacast 235 <meta> history 57 http-equiv 57 initialfocus 27 98

Index

485

multiple images in tables 34 MusicText object onreceive() 209 start() 208 stop() 208 musicText property 284 mute property ProgramStream object 214 Speaker object 53 TvTuner object 275

N
name attribute Flash movies 469 <table> 119 name property Cookie object 71 Embed object for Flash movies 473 Indicator object 302 Link object 47 Table object 126 Trigger object 204 TvChannel object 232 TvInfoIndex object 252 TvTuner object 275 Navigator object 85 cache 86 curUser 86 display 87 extensions 87 indicators 88 input 88 length 88 net 89 serviceManager 89 speaker 90 sysServices 90 system 91 tvTuners 91 userManager 94   34 near video on demand (NVOD) 221, 234, 261

Net object 89, 151 connected 151 ensureConnection() 151 NetEvent() 152 NetMsgSession() 152 NetRequest() 152 NetSession() 152 onprogress() 153 net property 89 NetEvent object 157 binaryData 159 constructor 152, 159 contentType 160 headers 161 textData 162 type 162 url 162 NetMsgSession object appId 168 attach() 169 constructor 152, 168 detach() 169 nodeId 168 nodeType 168 onerror() 173 onreceive() 173 register() 170 send() 171 sessionId 169 unregister() 170 NetRequest object 175 cache 177 cancel() 182 constructor 152, 176 direct 177 fetch() 182 headers 178 oncancel() 183 ondone() 183 onerror() 183 onload() 183 onstart() 183

486

Content Developer’s Reference

post 179 postData 179 url 181 NetSession object 185 constructor 152, 186 headers 187 onerror() 189 onreceive() 189 onstart() 189 onstop() 189 send() 187 start() 188 stop() 188 url 187 network property 233 nextProgram property 229 <nobr> 34 nocursor attribute 28 nodeId property 168 nodeType property 168 normal play time 212 NPT (normal play time) 212 NTSC 40, 50, 273 NVOD (near video on demand) nvodEnabled property 241 nvodId property 263 nvodReference property 263

221, 234, 261

O
onadd() 375 onafterchannelchange() 279 onalarm() 196 onbeforechannelchange() 279 onblur() <table> 121 Table object 130 oncancel() 183 onchannelsupdate() 280 onclick() <table> 121 Table object 130 oncommand() 196 ondelete() 375

ondone NetRequest object 183 ProgramStream object 219 onerror() NetMsgSession object 173 NetRequest object 183 NetSession object 189 ProgramStream object 219 System object 316 VodSession object 293 onexternalevent() 318 onfastforward() 220 onfocus() <table> 121 Table object 130 onkeyin() 310 onkeyout() Input object 310 Window object 110 onkeyset() 337 onload() 183 onnavigate() 121, 130 onopen() 294 onpause() 220 onplay() 220 onprogramchange() 281 onprogress() 153 onreceive() MusicText object 209 NetMsgSession object 173 NetSession object 189 onreset() 337 onrewind() 220 onstart() NetRequest object 183 NetSession object 189 onstop() 189, 220 onstreamcreate() 294 onswitch() 376 onsync() 377 ontrigger() 204 onvisible() 110

Index

487

onwrite(), UserManager object open() VodSession object 292 Window object 105 overscan property 103

377

P
PAL 40, 50, 273 path property 70 pause() 216 pfEnabled property 241 play attribute, for Flash movies 469 play() for embedded sounds 465 ProgramStream object 217 plug-ins 4, 451 pluginspage attribute, for Flash movies popFocus() 308 popupbg attribute 61 post property 179 postData property 179 <pre> 34 preferredFormat property 41 presentable property 222, 236 presentables property 236 primary property 284 programDefaults property 41 ProgramStream object 211 curSpeed 212 curTime 213 fastForward() 215 fastForwardSpeed 213 id 214 keyFrames 214 mute 214 ondone() 219 onerror() 219 onfastforward() 220 onpause() 220 onplay() 220 onrewind() 220 onstop() 220 pause() 216

play() 217 rewind() 215 rewindSpeed 213 stop() 218 title 215 totalTime 213 protocols http: 387 HTTPS 65, 72 https: 388 javascript: 388 mcast: 387 tv: 383 purchase() 196 pushFocus() 308 469

Q
quality attribute, for Flash movies 470 qualityRating property 259

R
raw property 264 read() 141 register() 170 regular expressions 411 rel attribute 63 relatedChannel property 234 releaseContext() 109 remove() Cache object 147 Cookie object 73 History object 80 reset() 335 resetExecutionCount() 315 resetUrlFilter() 202 restricted API 7 retainSettings() 45 rewind() 215 rewindSpeed property 213 right property 51 roaming 324, 364 rows property 127

488

Content Developer’s Reference

S
safe area 49 SafeArea object 42, 49 height 51 left 51 right 51 width 51 salign attribute, for Flash movies 470 same-origin principle 6 scale attribute, for Flash movies 470 schemaUrl property 242 ScreenArea object 42, 49 height 50 width 50 script property 204 scrollAmount property 136 scrollDelay property 136 scrolling 30 scrollRows() 128 search() TvInfo object 245 TvInfoIndex object 253 secondary property 284 secure property 72 selbgcolor attribute 61 <select> 61 selectedComponents property 224 seltext attribute 61 send() 187 NetMsgSession object 171 Service Manager 2, 10 Service object 90, 322, 339 sysAdminConsent 351 sysBootUrl 342 sysCancellationUrl 353 sysChannel 343 sysDescription 344 sysDisplayLanguage 345 sysDisplayName 346 sysHeaderUrl 347 sysHeaderValue 347

sysId 348 sysInfoUrl 349 sysInternalName 348 sysLastStatusChange 355 sysLocalizationUrl 345 sysLogoUrl 350 sysProviderConsent 351 sysRegistered 353 sysRegistrationUrl 353 sysRoot 354 sysSmallLogoUrl 350 sysStatus 355 sysTrustedUrl 356 sysType 357 sysTypeRequired 357 sysUserConsent 351 sysVersion 348 serviceId property 237 serviceManager property 89 services 2, 322, 339 serviceType property 234 sessionId property 169 setChannelFilter() 203 setDataSource() 245 setExclusiveKeys() 309 setKey() 336 setting the channel 272 settingsAlwaysRetained property 42 shared objects 5, 8, 9 shortName property 232 shortTitle property 266 signal property 235 size attribute 31 Speaker object 53, 90, 270 mute 53 volume 53 speaker property 90 split property 236 splitTimes property 236 src attribute, for Flash movies 471 src property, for Flash movies 474

Index

489

standard services 2 start() MusicText object 208 NetSession object 188 startTime property 265 status property 334 stop() MusicText object 208 NetSession object 188 ProgramStream object 218 store() 74 stream property 291 String object encrypt() 95 switchToUser() 372 syncUserData() 373 sysAdminConsent property 351 sysAdminEnabled property 359 sysBootUrl property 342 sysCancellationUrl property 353 sysChannel property 343 sysDefault property 360, 361 sysDescription property 344 sysDisplayLanguage property 345 sysDisplayName property 346 sysHeaderUrl property 347 sysHeaderValue property 347 sysId property 348 sysInfoUrl property 349 sysInternalName property 348 sysLanguagePreferences property 362 sysLastStatusChange property 355 sysLocalizationUrl property 345 sysLogoUrl property 350 sysMasterAppId property 363 sysName property 364 sysProviderConsent property 351 sysRegistered property 353 sysRegistrationUrl property 353 sysRoamingName property 364 sysRoot property 354

sysServices property Navigator object 90 User object 365 sysSetupDone property 365 sysSmallLogoUrl property 350 sysStatus property 355 System object 91, 313 control() 313 onerror() 316 onexternalevent() 318 resetExecutionCount() 315 uniqueId 313 system property Navigator object 91 TvFormat object 40, 273 sysTrustedUrl property 356 sysType property 357 sysTypeRequired property 357 sysUniqueId property 366 sysUserConsent property 351 sysVersion property 348 sysWebAccess property 366

T
<table> bgcolor 22 border 35 cellpadding 35 cellspacing 35 dynamicCols 120 event handlers 121 height 36 highlightable 122 name 119 width 36 Table object 125 blur() 127 clear() 127 drawingDisabled 126 focus() 127 name 126 onblur() 130

490

Content Developer’s Reference

onclick() 130 onfocus() 130 onnavigate() 130 rows 127 scrollRows() 128 TableCell object 133 align 133 background 134 behavior 136 bgColor 134 colSpan 137 direction 136 elisionString 137 fgColor 138 findColsNeeded() 140 findFit() 141 focusable 139 highlightable 139 loop 136 read() 141 scrollAmount 136 scrollDelay 136 valign 133 wrappingEnabled 140 write() 141 TableRow object 143 cells 143 tables resizing images 34 wrapping text 34 <td> background 122 behavior 123 bgcolor 22 direction 123 focusable 121 highlightable 122 loop 123 nowrap 34 scrollamount 123 scrolldelay 123 width 37

text attribute 61 Text object 97 text/html 379 text/plain 379 <textarea> bgcolor 22 focusable 30 Textarea object 97, 98 append() 100 bottomLine 99 curLineCount 98 focusable 99 maxLineCount 98 topLine 99 wrap 100 textData property 162 timestamp property 307 title property HistoryEntry object 83 ProgramStream object 215 TvProgram object 266 topics property 266 topLine property 99 toString() 84 totalTime property 213 <tr> bgcolor 22 transmitted property 72 transparency 22 transportStreamId property 237 Trigger object channel 204 expiration 204 name 204 script 204 url 205 triggerUrl property 201 tunable property 222, 236 tunables property 236 tv: protocol 383 TvChannel object 221 accessControlled 223 availableComponents 224

Index

491

blackedOut 228 blocked 228 category 229 curProgram 229 description 229 frequency 230 fullName 232 hidden 231 id 231 name 232 network 233 nextProgram 229 presentable 222, 236 presentables 236 relatedChannel 234 selectedComponents 224 serviceId 237 serviceType 234 shortName 232 signal 235 split 236 splitTimes 236 transportStreamId 237 tunable 222, 236 tunables 236 uniqueId 237 url 238 TvFormat object system 40, 273 TvInfo object 239, 274 addIndex() 243 deleteIndex() 243 indexes 241 nvodEnabled 241 pfEnabled 241 schemaUrl 242 search() 245 setDataSource() 245 TvInfoIndex object 251 getNext() 253 getPrev() 253

name 252 search() 253 TvProgram object 255 accessControlled 258 ageRating 259 audio 259 blackedOut 260 captions 260 channels 260 constructor 257, 285 deliveryMode 261 description 262 duration 262 nvodId 263 nvodReference 263 qualityRating 259 raw 264 shortTitle 266 startTime 265 title 266 topics 266 year 267 TvTuner object 91, 269 access 271 captureStill() 276 channels 271 curChannel 272 eTv 273 findChannel() 278 format 273 frozen 274 info 274 mute 275 name 275 onafterchannelchange() 279 onbeforechannelchange() 279 onchannelsupdate() 280 onprogramchange() 281 TvTuners array 91, 283 musicText 284 primary 284

492

Content Developer’s Reference

secondary 284 TvProgram() 285 tvTuners property 91 tvVisible property 43 type property Indicator object 302 NetEvent object 162

U
ui attribute, for Flash movies 471 UI sound 465 uiSound attribute 465 uniqueId property System object 313 TvChannel object 237 unmatchedUrlsAccepted property 201 unregister() 170 url property NetEvent object 162 NetRequest object 181 NetSession object 187 Trigger object 205 TvChannel object 238 user administrative privileges 323, 359 current 86, 322 default 323 guest (roaming) 324, 364 identification 323 name 323, 364 password 323, 367, 368 user interface sound 465 User object 321, 359 changePassword() 367 checkPassword() 368 sysAdminEnabled 359 sysDefault 360, 361 sysLanguagePreferences 362 sysMasterAppId 363 sysName 364 sysRoamingName 364 sysServices 365

sysSetupDone 365 sysUniqueId 366 sysWebAccess 366 UserManager object 94, 321, 369 addUser() 370 authentication 369 deleteUser() 370 evalWithPrivileges() 371 onadd() 375 ondelete() 375 onswitch() 376 onsync() 377 onwrite() 377 switchToUser() 372 syncUserData() 373 users 370 writeUserData() 373 userManager property 94 users property 370

V
valign property 133 value property Cookie object 72 Indicator object 302 video on demand (VOD) 235, 261, 287 videoOn property 44 visible property 104 VOD (video on demand) 235, 261, 287 VodSession object channelId 289 close() 292 configInfo 289 constuctor 288 controlAddr 290 createStream() 291 destroyStream() 291 id 290 onerror() 293 onopen() 294 onstreamcreate() 294 open() 292 stream 291

Index

493

VodSession() 288 volume property 53

W
wide screen 40, 44 wideScreenStyle property 44 width attribute 37 Flash movies 471 <img> 33 <table> 36 width property SafeArea object 51 ScreenArea object 50 Window object 8, 103 close() 105 layer 103 onkeyout() 110 onvisible() 110 open() 105 overscan 103 releaseContext() 109 visible 104 windows extending background 23, 103 focus stack 295 front-to-back order 103 hiding and showing 104, 110, 296 opening 105 TV background 21 wrap property 100 wrappingEnabled property 140 write(), TableCell object 141 writeUserData() 373

Y
year property 267

494

Content Developer’s Reference

</div><br />

<script type='text/javascript'>
  aster_cloud_id = '2422251';
  aster_cloud_format = '728x90';
</script>
<script type='text/javascript'>
  document.write(unescape("%3Cscript src='http://web.asterpix.com/media/js/searchlight.js' type='text/javascript'%3E%3C/script%3E"));
</script>

</div>
            </div>
        </div>
    </div>

</div>

<div class="docs-box-header">Other docs by <a href="/profile/azcameron">Alex Cameron</a></div><div class="docs-box">
<div class="doc">
<a href="/docs/939276/Using-Eq" class="thumb" title="939276"></a>
<div class="titleStats"><a class="title" href="/docs/939276/Using-Eq">Using Eq</a>
<div class="stats">
Views: 118  |  Downloads: 6</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939275/The-Sectret-of-the-mastering-engineer" class="thumb" title="939275"></a>
<div class="titleStats"><a class="title" href="/docs/939275/The-Sectret-of-the-mastering-engineer">The Sectret of the mastering engineer</a>
<div class="stats">
Views: 122  |  Downloads: 7</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939274/Recording-Real-Drums" class="thumb" title="939274"></a>
<div class="titleStats"><a class="title" href="/docs/939274/Recording-Real-Drums">Recording Real Drums</a>
<div class="stats">
Views: 112  |  Downloads: 9</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939273/Recording-Lead-Vocals" class="thumb" title="939273"></a>
<div class="titleStats"><a class="title" href="/docs/939273/Recording-Lead-Vocals">Recording Lead Vocals</a>
<div class="stats">
Views: 140  |  Downloads: 6</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939272/Recording-in-One-Room" class="thumb" title="939272"></a>
<div class="titleStats"><a class="title" href="/docs/939272/Recording-in-One-Room">Recording in One Room</a>
<div class="stats">
Views: 105  |  Downloads: 9</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939271/Recording-Bass-Guitar" class="thumb" title="939271"></a>
<div class="titleStats"><a class="title" href="/docs/939271/Recording-Bass-Guitar">Recording Bass Guitar</a>
<div class="stats">
Views: 133  |  Downloads: 8</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939270/Recording-Acoustic-Guitar" class="thumb" title="939270"></a>
<div class="titleStats"><a class="title" href="/docs/939270/Recording-Acoustic-Guitar">Recording Acoustic Guitar</a>
<div class="stats">
Views: 113  |  Downloads: 5</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939269/Practical-Mixing" class="thumb" title="939269"></a>
<div class="titleStats"><a class="title" href="/docs/939269/Practical-Mixing">Practical Mixing</a>
<div class="stats">
Views: 79  |  Downloads: 1</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939266/MediaFinance94" class="thumb" title="939266"></a>
<div class="titleStats"><a class="title" href="/docs/939266/MediaFinance94">MediaFinance94</a>
<div class="stats">
Views: 165  |  Downloads: 2</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939263/iTV-is-dead_-Long-live-IPTV---Broadcast-Engineering-Digital-TX-Limited-_wwwdigitaltxtv_" class="thumb" title="939263"></a>
<div class="titleStats"><a class="title" href="/docs/939263/iTV-is-dead_-Long-live-IPTV---Broadcast-Engineering-Digital-TX-Limited-_wwwdigitaltxtv_">iTV is dead_ Long live IPTV - Broadcast Engineering-Digital TX Limited _www.digitaltx.tv_</a>
<div class="stats">
Views: 77  |  Downloads: 1</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939258/IPTV-VoDTheWorldThatsOnItsWay-DigitalTXLimited_wwwdigitaltxtv_" class="thumb" title="939258"></a>
<div class="titleStats"><a class="title" href="/docs/939258/IPTV-VoDTheWorldThatsOnItsWay-DigitalTXLimited_wwwdigitaltxtv_">IPTV-VoD.The.World.Thats.On.Its.Way-Digital.TX.Limited._www.digitaltx.tv_</a>
<div class="stats">
Views: 62  |  Downloads: 1</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939256/IPTV-VoDTheHareAndTheTortoise-DigitalTXLimited_wwwiptvworkshopcouk_" class="thumb" title="939256"></a>
<div class="titleStats"><a class="title" href="/docs/939256/IPTV-VoDTheHareAndTheTortoise-DigitalTXLimited_wwwiptvworkshopcouk_">IPTV-VoD.The.Hare.And.The.Tortoise-Digital.TX.Limited._www.iptvworkshop.co.uk_</a>
<div class="stats">
Views: 78  |  Downloads: 0</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939255/IPTV-VoDTheFallOfContentsKingdom-DigitalTXLimited_wwwdigitaltxtv_" class="thumb" title="939255"></a>
<div class="titleStats"><a class="title" href="/docs/939255/IPTV-VoDTheFallOfContentsKingdom-DigitalTXLimited_wwwdigitaltxtv_">IPTV-VoD.The.Fall.Of.Contents.Kingdom-Digital.TX.Limited._www.digitaltx.tv_</a>
<div class="stats">
Views: 47  |  Downloads: 0</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939254/IPTV-VoDFastForwardToChristmasFuture-DigitalTXLimited_wwwiptvworkshopcouk_" class="thumb" title="939254"></a>
<div class="titleStats"><a class="title" href="/docs/939254/IPTV-VoDFastForwardToChristmasFuture-DigitalTXLimited_wwwiptvworkshopcouk_">IPTV-VoD.Fast.Forward.To.Christmas.Future-Digital.TX.Limited._www.iptvworkshop.co.uk_</a>
<div class="stats">
Views: 57  |  Downloads: 1</div></div>
<div class="clr"></div>
</div>
<div class="doc">
<a href="/docs/939252/IPTV-VoDBurstingThePPVBubble-DigitalTXLimited_wwwiptvworkshopcouk_" class="thumb" title="939252"></a>
<div class="titleStats"><a class="title" href="/docs/939252/IPTV-VoDBurstingThePPVBubble-DigitalTXLimited_wwwiptvworkshopcouk_">IPTV-VoD.Bursting.The.PPV.Bubble-Digital.TX.Limited._www.iptvworkshop.co.uk_</a>
<div class="stats">
Views: 62  |  Downloads: 1</div></div>
<div class="clr"></div>
</div>
</div>

</div>

</div>
		</div>
		<div class="cls"></div><br />
	
	
		
		<div id="footer-wrap">
			<div id="footer">
				<div class="l-cap"></div>
				<div class="inner">
					<dl>
							<dt>About:</dt>
							<dd><a href="/about/" rel="nofollow">What is Docstoc?</a> | <a href="javascript:void window.open('/popterm.aspx?page_id=15','TC','width=800,height=500,menubar=0,location=0,resizable=1,scrollbars=1,status=0')" rel="nofollow">Docstoc Terms of Service</a> | <a href="javascript:void window.open('/popterm.aspx?page_id=102','TC','width=800,height=500,menubar=0,location=0,resizable=1,scrollbars=1,status=0')" rel="nofollow">DocStore Terms of Service</a> | <a href="javascript:void window.open('/popterm.aspx?page_id=22','TC','width=800,height=500,menubar=0,location=0,resizable=1,scrollbars=1,status=0')" rel="nofollow">Privacy Policy</a> | <a href="/FAQ/" rel="nofollow">FAQs</a></dd>
					</dl>
					<dl>
							<dt>Links:</dt>
							<dd><a href="http://blog.docstoc.com/" onclick="outbound('blog.docstoc.com')">Docstoc Blog</a> | <a href="/pro/" rel="nofollow">Join Pro</a> | <a href="/requests/" rel="nofollow">Requests</a> | <a href="/docsters/">Docsters</a> | <a href="/upload/" rel="nofollow">Upload</a> | <a href="/User/cmsstatic.aspx?page_id=100" rel="nofollow">DMCA Guidelines</a> | <a href="/DMCA/" rel="nofollow">DMCA Notification</a> | <a href="http://platform.docstoc.com/" rel="nofollow">Docstoc API</a> | <a href="/feeds/rssfeed.aspx" rel="nofollow">RSS Feeds</a> <a href="/feeds/rssfeed.aspx" rel="nofollow"><img src="/i/ico/rss-sm.gif" alt="RSS Feeds" /></a></dd>
					</dl>
					<dl>
							<dt>Contact:</dt>
							<dd><a href="/contact/" rel="nofollow">Contact Us</a> | <a href="http://docstoc.suggestionbox.com/" rel="nofollow">Suggest Features</a> | <a href="/jobs/" rel="nofollow">Join Our Team</a></dd>
					</dl>
					<dl>
							<dt>Share:</dt>
							<dd><a href="/Embed-Documents/">Embed Documents</a> | <a href="/OneClick/">Docstoc OneClick</a> | <a href="/Sync/">Docstoc Sync</a> </dd>
					</dl>
					</div>
					<div class="r-cap"></div>
					<div class="copyright">© Docstoc 2009. All rights reserved.</div>
			</div>
		</div>
		
	<br />
</div>
<script type="text/javascript">
google_spot_id = 'ad-spot6'
google_ad_client = 'pub-7343870454215956';
google_ad_output = 'js';
google_max_num_ads = '3';
google_ad_type = 'text';
google_ad_channel ="2191561729+5544646509"
google_feedback = 'on';
googleAdStyle = 'v';
</script>
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>
<script type="text/javascript">
google_spot_id = 'ad-spot1'
google_ad_client = 'pub-7343870454215956';
google_ad_output = 'js';
google_max_num_ads = '3';
google_ad_type = 'text';
google_ad_channel ="5056562550+3509764174+5544646509"
google_feedback = 'on';
googleAdStyle = 'h';
</script>
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>
<script type="text/javascript">
google_spot_id = 'ad-spot3'
google_ad_client = 'pub-7343870454215956';
google_ad_output = 'js';
google_max_num_ads = '5';
google_ad_type = 'text';
google_ad_channel ="7385883220+5544646509+0390437055"
google_feedback = 'on';
googleAdStyle = 'v';
</script>
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>
<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script>
<script type="text/javascript">
var pageTracker ='';
if (_gat && _gat!=null && _gat!=undefined){
pageTracker = _gat._getTracker("UA-1289929-1");
pageTracker._trackPageview();
}
</script>

</body>
</html>