HTVCP: Hypertext Version Control Protocol Version 1.0 - 15 January 1999 by Toby W. Rush 0.0 Introduction 0.1 Description Hypertext Version Control Protocol (HTVCP) is a system with which software can automatically connect to a remote server and check to see if a more current version is available. It is intended to be invoked automatically at periodic intervals or at the user's discretion. HTVCP is based on HTTP and requires a web server. Version information is stored in an HTTP file which is loaded and checked for current information. This method is advantageous because it does not require a dedicated server or specialized software. 0.2 Table of Contents 0.0 Introduction 0.1 Description 0.2 Table of Contents 1.0 Specification 1.1 Overview 1.2 The HTVCP File 1.2.1 HTVCP Tags 1.2.2 The Object Description Tag 1.2.2.1 X-HTVCP-OBJECT 1.2.2.2 X-HTVCP-AUTHOR 1.2.2.3 X-HTVCP-VERSION 1.2.2.4 X-HTVCP-LINK 1.2.3 The Redirection Tag 1.2.3.1 X-HTVCP-REDIRECT 1.3 Parsing the HTVCP File 2.0 Example HTVCP File 1.0 Specification 1.1 Overview HTVCP communication is conducted between an HTVCP-compliant software program and a web server. Upon connection with the web server, the software program requests a specially created HTVCP file which may contain version information for one or more software programs, or the address of a new HTVCP file. 1.2 The HTVCP File The HTVCP file is a text file which can contain any printable characters in the range of ASCII 32-127. The file must contain one or more tags as specified in the following sections. The file may also contain HTML code in any format. There are two types of HTVCP tags which may be included in an HTVCP file: the object description tag and the redirection tag. 1.2.1 HTVCP Tags An HTVCP tag consists of one or more object/value pairs within greater-than and less-than signs as follows: Object/value pairs may be in any order and are separated by a single space character (ASCII 32). Values are enclosed in quotation marks (ASCII 34). Values may not contain quotation marks or spaces; plus characters in a value will be converted to a space character by the software program. 1.2.2 The Object Description Tag The first type of tag that may be included in an HTVCP file is the object description tag. The purpose of this tag is to provide version information about a specific software program. The object description tag consists of three required object/value pairs and one optional object/value pair. 1.2.2.1 X-HTVCP-OBJECT The first required object/value pair is X-HTVCP-OBJECT. This pair specifies the name of the software program whose version information is described by the tag. 1.2.2.2 X-HTVCP-AUTHOR The second required object/value pair is X-HTVCP-AUTHOR. This pair specifies the name of the software programmer or company who created or administers the software program whose version information is described by the tag. 1.2.2.3 X-HTVCP-VERSION The third required object/value pair is X-HTVCP-VERSION. This pair specifies the current version of the software program whose version information is described by the tag. The value is encoded in the following format: MMMmm.aasrrr MMM: The major version of the software, specified as a three-digit decimal number. If the software version is 1.2.7, this number would be 001. mm: The minor version of the software, specified as a two-digit decimal number. If the software version is 1.2.7, this number would be 02. aa: The maintenance version of the software, specified as a two-digit decimal number. If the software version is 1.2.7, this number would be 07. s: The current status of the software, specified as a one-digit number between 6 and 9. Each number represents a certain state of development, as follows: 6: development 7: alpha 8: beta 9: final rrr: The release number of the software, specified as a three-digit number. If ths software version is 1.3.1b4, this number would be 004. If a portion of the version is unspecified, as the maintenance version number in 1.5, a zero value is implied. 1.2.2.4 X-HTVCP-LINK The optional object/value pair in the object description tag is X-HTVCP-LINK. This tag specifies the URL at which the user can download the new version of the software. This URL can be used by the HTVP-capable software program to provide an automatic way for the user to download the new version. 1.2.3 The Redirection Tag The second type of tag that may be included in an HTVCP file is the redirection tag. This tag specifies a new URL at which to find the current HTVCP file. If this tag is included in a file, all other HTVCP tags will be ignored. Upon retrieving this file, the HTVCP-capable software program should load the current file from the indicated URL. 1.2.3.1 X-HTVCP-REDIRECT The redirection tag has only one object/value pair: X-HTVCP-REDIRECT. The value in this pair consists of two parts, separated by a backslash as follows: "Remote_Machine\New_URL" Remote_Machine: The address of the remote machine at which the new HTVCP file is located. If the port number is specified, it is separated by the machine address by a colon (e.g., "www.example.com:80"). If the port is not specified, the colon is not used, and port 80 is assumed. New_URL: The URL at which the new HTVCP file is located. This is included separate from the machine name in order to make HTVCP backward-compatible with HTTP/1.0 servers. For these servers, some of which may not recognize absolute pathnames, New_URL may be a relative pathname (i.e., a pathname without the machine name). See RFC 2068, Section 5.1.2 for more information about absolute pathnames used in the request line. 1.3 Parsing the HTVCP File An HTVCP version check consists of the following steps: a. The software program downloads the HTVCP file from the URL hardwired into the program. If the HTVCP file does not exist at the specified URL, the program should report an error. b. If an X-HTVCP-REDIRECT tag is found, the program should return to step (a) and load the HTVCP file at the new URL. c. The program should step through the tags in the file until it finds one with the X-HTVCP-OBJECT and X-HTVCP-AUTHOR values that match those of the program. If matching values are not found, the program should report an error. d. The program should compare the current version and the version specified by the X-HTVCP-VERSION value. This can be done by converting the coded version number (as specified in version 1.2.2.3) into a number and determining which is higher. d1. If the version specified by X-HTVCP-VERSION is higher than the current software version, the program should report to the user that a new version is available, and optionally offer to download the new version from the URL indicated by the X-HTVCP-LINK value. 2.0 Example HTVCP File An example file including several object description tags: An example file showing the redirect tag: Another example file showing the redirect tag: