TellyScript

From WebTV Wiki
Jump to navigation Jump to search

TellyScript is a scripting language used by WebTV/MSN TV clients that specifies access numbers and dialing instructions that should be used to connect to the WebTV/MSN TV network. It was designed by Andy Rubin and was based off a scripting language he had previously written in college. The name is a pun on "Telescript", a scripting language developed by General Magic, a company Rubin and many other early WebTV Networks employees worked for prior to joining WebTV.

Overview

At its core, TellyScript is designed to operate as a dialing script for WebTV/MSN TV clients, while having the flexibility of a general programming language, like C. It contains both general C-like functions and dedicated, WebTV-specific functions that can be taken advantage of to have better control over the connection process. This allows TellyScripts to do things like directly initialize the modem, update the progress bar on the connecting screen at specific events when connecting, work around modem-related bugs, use one of up to eight different sets of POPs (Point of Presence) to connect to based on the day of the week, time, and month a user is connecting on, and handling different kinds of failures. On the service side, TellyScripts sent to WebTV/MSN TV clients are generated from C-like script fragments, which include common TellyScript functions, locale-specific code, code to support logging in to supported WebTV/MSN TV ISPs, and code generated on the fly, which contain the actual access numbers and if applicable, toll call warnings. These fragments are selectively combined as the service sees fit for each WebTV/MSN TV client depending on factors like what type of box or client a user is connecting with and their location. The combined fragments are then tokenized and compressed before being sent to the WebTV/MSN TV client. The service also had the ability to track the last two TellyScripts sent for each WebTV/MSN TV client in the event the script computed on the service is different and has to be updated (the last two are tracked to accomodate the quirk of WebTV/MSN TV clients not saving TellyScripts to NVRAM unless they're powered off).

On the client side, a TellyScript is obtained by first being downloaded off the pre-registration (scriptless) servers after the WebTV/MSN TV service has detected that the user's location is supported (this is based off the phone number they've dialed in from, or a number the user specified directly on the service if their phone line doesn't support ANI). The box will store this script in NVRAM and use it for all future connections unless it's cleared or replaced.

The scripting language used by TellyScript is based off a C-like language that utilized byte-sized tokens for keywords, data types, and general script flow. It also utilized two types of compression: a simple "minification" algorithm that involves turning variable and function names into 1 or 2-letter names, and LZSS compression of the TellyScript code using a WebTV-specific variation of the algorithm.

Structure

The structure of a TellyScript consists of a 36-byte header and the actual script, the latter of which is compressed and minified. The header starts with the magic string "ANDY" (0x414e4459 in hexadecimal). This is in reference to Andy Rubin, who designed the scripting language. The rest of the header contains two version fields with no known purpose, a field that possibly stores a 4-byte hash (possibly CRC32), which is used by the service to track if the client needs their script to be updated, fields for the lengths of the decompressed and compressed script data, a UNIX timestamp of when the script was generated, and an unknown field that has no discernable purpose right now. All integers in the header are packed as big endian 32-bit values.

The following table will be provided to document the header:

Field Name Type Offset Description
Magic bytes uint32 0x00 Magic bytes identifying TellyScript header. Value always should be 0x414e4459 (ANDY in ASCII)
"version1" uint32 (possibly) 0x04 Use unknown. Value is usually 1
"version2" uint32 (possibly) 0x08 Use unknown. Value is usually 1, but has been reported to have a different value in at least one TellyScript
"hash1" uint32 0x0c Possibly a CRC32 hash. Sent in WTVP request messages in the wtv-script-id header if a client has a valid TellyScript. This hash value was read by the WebTV/MSN TV service to track if clients needed their scripts to be updated
Time created uint32 0x10 UNIX timestamp of the exact date and time a TellyScript was generated from the WebTV/MSN TV servers. Sent in WTVP request messages in the wtv-script-mod header if a client has a valid TellyScript
Compressed script length uint32 0x14 Length of LZSS compressed script
Decompressed script length uint32 0x18 Length of decompressed script
Decompressed script hash uint32 0x1c CRC32 hash of decompressed script
"unknown1" uint32 (possibly) 0x20 Unknown value. Always has value 0x0101ffff from looking at archived TellyScripts


Information on the tokenized scripting language is too extensive for us to simply write up here at the moment, and will possibly be added in the future when the opportunity allows us. Andy McFadden, however, has since made source code available that decompresses and decompiles tokenized TellyScript into readable C-like code, and is known to at least work with almost all TellyScript samples in our content archive.

DialScript

DialScript is a revision of TellyScript, primarily designed for use with Windows CE-based WebTV/MSN TV clients (see UltimateTV). It's confirmed to have been used since the Microsoft TV iteration of WebTV technology, but its inception seems to go back as far as 1999, as it was mentioned in a revision of the "Greater Scroll of Dialing Wisdom" document published in the same year. It's believed that it was used well into the MSNTV 2's lifespan as well.

The only known differences between DialScript and TellyScript is that DialScripts appears to use a different magic string - VKAT, most likely in reference to Venkatesh Krishnamurthy, the person who is credited in the "Greater Scroll of Dialing Wisdom" for being "in charge" of DialScript. The script data itself, when decompressed, also has 8 extra bytes at the beginning that don't appear to be part of the script itself and are currently undocumented. Outside of that, the core scripting language used by DialScript appears to have been unchanged from the original TellyScript incarnation. The script contents, however, make more use of system calls for modem stuff. This was likely to take advantage of Windows CE APIs to manage the modem as opposed to doing it at the low level in the script.

Availability

Thankfully, with the releases of eMac's "server emulator" over the years, alongside other sources, some TellyScripts and DialScripts have been preserved. For our own curiosity's sake, though, we would be interested in more versions of these TellyScripts and DialScripts for any version of WebTV/MSN TV. If you got any of them or other WebTV/MSN TV stuff we're looking for, don't hesitate to send them over to us!

External Links