HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:43:20 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Tue, 17 Mar 1998 16:34:00 GMT ETag: "2e79ec-3b78-350ea5f8" Accept-Ranges: bytes Content-Length: 15224 Connection: close Content-Type: text/plain Network Working Group J. De Winter Internet Draft: ACAP-DISCOVER Wildbear Consulting Document: draft-ietf-acap-dewinter-dtype-00.txt April 25, 1997 Expires: Oceober 31, 1997 ACAP Datatyping and Datatyping Discovery Status of this Memo This document is an Internet Draft. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its Areas, and its Working Groups. Note that other groups may also distribute working documents as Internet Drafts. Internet Drafts are draft documents valid for a maximum of six months. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a ``working draft'' or ``work in progress``. To learn the current status of any Internet-Draft, please check the 1id-abstracts.txt listing contained in the Internet-Drafts Shadow Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or munnari.oz.au. This document suggests a proposed protocol for the Internet community, and requests discussion and suggestions for improvements. Distribution of this draft is unlimited. The protocol discussed in this document is experimental and subject to change. Persons planning on either implementing or using this protocol are STRONGLY URGED to get in touch with the author before embarking on such a project. 1.0 Abstract The Application Configuration Access Protocol (ACAP) is designed to support remote storage and access of program option, configuration and preference information. In certain circumstances, it is desirable or necessary to deal with information that has a limit imposed on it. While the general ACAP specification does provide for a (SYNTAX) alert to inform the submittor that the stored information was not in a valid syntax for that field, there is no generic method to discover that syntax. There is strong feeling in the ACAP working group that variable length strings should be used for data where possible, but there is also the knowledge that ACAP will be used to configure and access existing systems where the use of such variable length strings may be difficult or impossible. 2.0 Specification The DISCOVER extension may be used with any ACAP server which returns "DISCOVER" as one of the supported capabilities in the initial untagged ACAP response. The decision on whether or not to preload certain information for datasets is left to the client implementation. It should be noted however that most of the discvoery information in a large number of the datasets is consistant accross all instances of that dataset, and caching could provide a substantial savings. 2.1 Referencing Each of the datasets contain a given set of entries. The Discover extension extends each of these entries to provide an in-situ method of discovering their type information. This information is only provided if asked for, so a client implementation that does not support the DISCOVER extension will not be affected. Every entry in every dataset will include all of the mandatory elements described below, and may include the optional elements. Please note that a given type of field may also mandate one of the optional elements to provide more information on that field. Each of the accesses within the datasets to this extended information will be prefixed by "Extension.Type". For example, to find the type of a given addressbook item "EMail", a client would request information about "EMail.Extension.Type." where is the desired piece of type information. If all of the type information is desired, the "Extension.Type" can be used by itself to return all of the type information for that item. For the purpose of quota information, none of this dataset discovery information should be accounted for towards any quota count, as it is server supplied information the client does not have any control over. 2.2 Mandatory Elements 2.2.1 Extension.Type.Cache This field is assigned a value of 'yes' or 'no' and specifies if the discovery information for this field is for the dataset or for this specific instance of the dataset. Caching of disocvery information over a dataset is encouraged, but it is understood that certain enties may mandate dynamic information. 2.2.2 Extension.Type.Description This field is assigned a string of no more that 512 characters that describes the field itself. This description should take into account any character sets selected and offer a base description in English. 2.2.3 Extension.Type.Type This field is assigned a value that denotes what kind of data it will contain. This list shall be considered to be set unless ammended by a standards track document. If ammended, an addition extension tag should be used to advertise the additional dataset ability. Additional elements to be used with the typing are provided as elements that occur after the type declaration itself. In the case of a type that does not have any additional elements, the type is returned as is. Otherwise, the type is followed by a SPACE character and a SPACE separated list of elements. 2.2.3.1 Extension.Type.Type = "vstring" The variable length string (hence referred to as vstring) is used to store an arbitrarily long string of information. This information should be stored as per the instructions in the [ACAP] document. There is no additional information that needs to be provided with this type. 2.2.3.2 Extension.Type.Type = "bstring" The bounded length string (hence referred to as bstring) is used to store a fixed number of characters. This type is primarily for fields where there are strong constraints on the number of characters needed to fulfil this item. The minimum and maximum elements define the lower and upper bounds on the string. The default values for those elements are 0 and 254, effectively making them the same as the string type defined below. 2.2.3.3 Extension.Type.Type = "string" The string is defined as a short string containing from 0 to 254 characters, not including any implementation specific terminating characters. This is a subset of the 'bstring' type described above, where the minimum is 0 and the maximum is 254. 2.2.3.4 Extension.Type.Type = "whole" The string is defined to consist of a sequence of numeric characters that comprise an unsigned 32 bit value. The optional base element denotes the numeric base of the whole number, and defaults to base 10 if not present. The grammar in section 3.0 provides a BNF description of how the whole number can be expressed. 2.2.3.5 Extension.Type.Type = "bwhole" The string represents a bounded whole number (hence refered to as bwhole). This is a number that falls within the same constraints as the whole type, but with the upper and lower bound of the number specified by the optional minimum and maximum elements. If not present, the default values for the minimum and maximum elements are 0 and 100 respectively. 2.2.3.6 Extension.Type.Type = "integer" The string is defined to consist of a sequence of numeric characters plus the prefix unary minus character, and is used to comprise a signed 32 bit value in base 10. 2.2.3.7 Extension.Type.Type = "binteger" The string represents a bounded integer number (hence refered to as binteger). This is a number that falls within the same constraints as the integer type, but with the upper and lower bound of the number specified by the optional minimum and maximum elements. If not present, the default values for the minimum and maximum elements are 0 and 100 respectively. 2.2.3.8 Extension.Type.Type = "boolean" The string represents a true or false value. The true value may be represented by the strings "1", "yes", or "true". The false value may be represented by the strings "0", "no", or "false". The server should be consistant in its setting of the given field to a given pair of these values. 2.2.3.9 Extension.Type.Type = "date" The string represents a time in "yyyy/mm/dd" format. 2.2.3.10 Extension.Type.Type = "time" The string repsents a time in "hh:mm:ss" format, assuming GMT. 2.2.3.11 Extension.Type.Type = "datetime" The string represents a combined date and time, assuming GMT, of "yyyy/mm/dd hh:mm:ss". 2.2.3.12 Extension.Type.Type = "fstring" The string represents a formatted string (hence referred to as fstring). If the first character is a '[', then the format in the Dataset.Format element is an ABNF construct, with the rules for the ABNF contained within [ABNF]. See section XXXX for a listing of the built-in constructs that the ABNF parser can assume unless otherwise specified. If the format string is empty, then the fstring is assumed to behave like a vstring. Otherwise, the format is assumed to be a simple format string, using the '*' and '?' characters to replace one or more characters and a single character. The '*' and '?' characters can be used by escaping them with a '\' character before them, and the '\' character must be escaped itself as well. 2.2.3.13 Extension.Type.Type = "select" The string represents a given entry from a list of acceptable entries. The list of acceptible entries is denoted by the list element, and by default contains a single element consisting of the empty string. 2.2.3.14 Extension.Type.Type = "mime" The string represents a mime object. The constrains on the type of MIME object allowed for this field are specified with the optional MimeDataType element. The default for the mime_list element is "(*/*)". [Open Issue: Need to talk to RobE regarding storing of mime information and make sure that things sync up.] 2.2.3.15 Extension.Type.Type = "complex" The string represents a complex data type, as it may be desirable in some cases to pass the string to a backend process for validation or compilation. In this case, if a (SYNTAX) response is generated, then the human readable section of the response will reflect the error that occured during submission. Example: storing a [SIEVE] script using ACAP with a server implementation that compiles the script and validates the script before it accepts it. [Open Issue: Is is possible to return more than one error string?] 2.3 Optional Elements 2.3.1 Dataset.Hint This string represents a hint of no more that 512 character than can assist a client program in providing the user with a hint on what type of data is expected for this field. 2.3.7 Dataset.Hide This element may be used with any of the given types to ask the client program to try and hide the value from the user. This is primarily for fields such as passwords and password validation where displaying of the password itself is not desired. Note that with some fields, operating system constraints may not allow the given display to hide the value in question. (e.g. multiple select list box) 2.3.8 Dataset.ForceUpper and Dataset.ForceLower These elements are used with the string types to provide a way to force an entry to be in upper or lower case. [Open Issue: How would this apply to other charsets?] 2.4 Error detection If the dataset in question supports any of the data types other than the vstring data type, it is possible to return an error to the client, indicating the unsuitability of the data. In this case, the server will return an extended response code of "SYNTAX" with the human readable text possibly giving more information on the nature of the syntactical error reported. For the datatype "complex", it is highly recommended that the human readable text reflect as much information as possible to the client. 3.0 Syntax This syntax is expressed using BNF, except that the # constructor for list uses a SPACE character as a separator, rather than a comma. Any text provided as part of the grammar should be considered case-insensitive. digit_nz ::= "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" digit ::= "0" / digit_nz number ::= digit_nz *digit / digit ; 32 bit unsigned number with no leading zeros ; 0 <= n < 4,294,967,296 minimum ::= number maximum ::= number whole ::= number integer ::= [ "-" ] digit_nz *digit / digit ; 32 bit signed number with no leading zeros ; -2,147,483,647 <= n < 2,147,483,648 boolean_true ::= "true" / "yes" / "1" boolean_false ::= "false" / "no" / "0" boolean ::= boolean_true / boolean_false base ::= "2" / "8" / "10" / "16" date_year ::= 4digit date_month ::= 2digit date_day ::= 2digit ; Note: day of the month date ::= date_year "/" date_month "/" date_day time_hour ::= 2digit ; 0 <= n <= 23 time_minute ::= 2digit ; 0 <= n <= 59 time_second ::= 2digit ; 0 <= n <= 59 time_zone ::= ( "+" / "-" ) 4digit time ::= time_hour ":" time_minute ":" time_second SPACE time_zone datetime ::= date SPACE time abnf_build ::= to be added glob_char ::= CHAR8 except "*", "?", and "\\" glob_build ::= *( "*" / "?" / "\*" / "\?" / "\\" / glob_char ) quoted_char ::= CHAR8 except "\" and <"> quoted-string ::= <"> *( <\"> / "\\" / quoted-char ) <"> list ::= "(" #quoted-string ")" mime_item ::= "*" / CHAR8 mime_subtype ::= mime_item mime_type ::= mime_item mime_list ::= "(" #( mime_type "/" mime_subtype ) ")" ; note that if the mime_type is "*", the mime_subtype must be "*" type ::= "vstring" / "bstring" [ SPACE minimum SPACE maximum ] / "fstring" [ SPACE ( abnf_build / glob_build )] / "string" / "whole" [ SPACE base ] / "bwhole" [ SPACE minimum SPACE maximum [ SPACE base ]] / "integer" / "binteger" [ SPACE minimum SPACE maximum ] / "boolean" / "date" / "time" / "datetime" / "select" [ SPACE list ] / "mime" [ SPACE mime_list ] / "complex" 3.0 References [ACAP] Myers, J., and Newman, C., "Application Configuration Access Protocol (ACAP)", Work in Progress of the IETF ACAP WG, draft-ietf-acap-spec-??.txt. Check Internet Drafts listing for latest version. [MIME-1] Borenstein, N., and Freed, N., "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies", RFC 1521. 4.0 Security Considerations There are no known security issues with this extension. 5.0 Author's Addresses Jack De Winter Wildbear Consulting, Inc. 17 Brock Street Kitchener, Ontario N2M 1X2 Canada Email: jack@wildbear.on.ca