SWI-Prolog 8.3.18
AllApplicationManualNameSummaryHelp

All predicatesShow sourcehttp_header.pl -- Handling HTTP headers

The library library(http/http_header) provides primitives for parsing and composing HTTP headers. Its functionality is normally hidden by the other parts of the HTTP server and client libraries.

Source http_read_request(+FdIn:stream, -Request) is det
Read an HTTP request-header from FdIn and return the broken-down request fields as +Name(+Value) pairs in a list. Request is unified to end_of_file if FdIn is at the end of input.
Source http_read_reply_header(+FdIn, -Reply)
Read the HTTP reply header. Throws an exception if the current input does not contain a valid reply header.
Source http_reply(+Data, +Out:stream) is det
Source http_reply(+Data, +Out:stream, +HdrExtra) is det
Source http_reply(+Data, +Out:stream, +HdrExtra, -Code) is det
Source http_reply(+Data, +Out:stream, +HdrExtra, +Context, -Code) is det
Source http_reply(+Data, +Out:stream, +HdrExtra, +Context, +Request, -Code) is det
Compose a complete HTTP reply from the term Data using additional headers from HdrExtra to the output stream Out. ExtraHeader is a list of Field(Value). Data is one of:
html(HTML)
HTML tokens as produced by html//1 from html_write.pl
file(+MimeType, +FileName)
Reply content of FileName using MimeType
file(+MimeType, +FileName, +Range)
Reply partial content of FileName with given MimeType
tmp_file(+MimeType, +FileName)
Same as file, but do not include modification time
bytes(+MimeType, +Bytes)
Send a sequence of Bytes with the indicated MimeType. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
stream(+In, +Len)
Reply content of stream.
cgi_stream(+In, +Len)
Reply content of stream, which should start with an HTTP header, followed by a blank line. This is the typical output from a CGI script.
Status
HTTP status report as defined by http_status_reply/4.
Arguments:
HdrExtra- provides additional reply-header fields, encoded as Name(Value). It can also contain a field content_length(-Len) to retrieve the value of the Content-length header that is replied.
Code- is the numeric HTTP status code sent
To be done
- Complete documentation
Source http_reply_data(+Data, +Out, +HdrExtra, +Method, -Code) is semidet[private]
Fails if Data is not a defined reply-data format, but a status term. See http_reply/3 and http_status_reply/6.
Errors
- Various I/O errors.
Source http_status_reply(+Status, +Out, +HdrExtra, -Code) is det
Source http_status_reply(+Status, +Out, +HdrExtra, +Context, -Code) is det
Source http_status_reply(+Status, +Out, +HdrExtra, +Context, +Request, -Code) is det
Emit HTML non-200 status reports. Such requests are always sent as UTF-8 documents.

Status can be one of the following:

authorise(Method)
Challenge authorization. Method is one of
  • basic(Realm)
  • digest(Digest)
authorise(basic, Realm)
Same as authorise(basic(Realm)). Deprecated.
bad_request(ErrorTerm)
busy
created(Location)
forbidden(Url)
moved(To)
moved_temporary(To)
no_content
not_acceptable(WhyHtml)
not_found(Path)
method_not_allowed(Method, Path)
not_modified
resource_error(ErrorTerm)
see_other(To)
switching_protocols(Goal, Options)
server_error(ErrorTerm)
unavailable(WhyHtml)
Source status_reply(+Status, +Out, +Options:Dict)[private]
Formulate a non-200 reply and send it to the stream Out. Options is a dict containing:
  • header
  • context
  • method
  • code
  • accept
 status_has_content(+StatusTerm, -HTTPCode)[private]
True when StatusTerm is a status that usually comes with an expanatory content message.
Source serialize_body(+Reply, -Body) is det[private]
Serialize the reply as returned by status_page_hook/3 into a term:
body(Type, Encoding, Content)
In this term, Type is the media type, Encoding is the required wire encoding and Content a string representing the content.
Source http:serialize_reply(+Reply, -Body) is semidet[multifile]
Multifile hook to serialize the result of status_reply/3 into a term
body(Type, Encoding, Content)
In this term, Type is the media type, Encoding is the required wire encoding and Content a string representing the content.
Source status_page_hook(+Term, -Reply, +Options) is det[private]
Calls the following two hooks to generate an HTML page from a status reply.
http:status_reply(+Term, -Reply, +Options)
Provide non-HTML description of the (non-200) reply. The term Reply is handed to serialize_body/2, calling the hook http:serialize_reply/2.
http:status_page(+Term, +Context, -HTML)
http:status_page(+Code, +Context, -HTML)
Arguments:
Term- is the status term, e.g., not_found(URL)
See also
- http:status_page/3
Source http_join_headers(+Default, +Header, -Out)
Append headers from Default to Header if they are not already part of it.
Source http_update_encoding(+HeaderIn, -Encoding, -HeaderOut)
Allow for rewrite of the header, adjusting the encoding. We distinguish three options. If the user announces `text', we always use UTF-8 encoding. If the user announces charset=utf-8 we use UTF-8 and otherwise we use octet (raw) encoding. Alternatively we could dynamically choose for ASCII, ISO-Latin-1 or UTF-8.
Source mime_type_encoding(+MimeType, -Encoding) is semidet[private]
Encoding is the (default) character encoding for MimeType. Hooked by http:mime_type_encoding/2.
 http:mime_type_encoding(+MimeType, -Encoding) is semidet[multifile]
Encoding is the (default) character encoding for MimeType. This is used for setting the encoding for HTTP replies after the user calls format('Content-type: <MIME type>~n'). This hook is called before mime_type_encoding/2. This default defines utf8 for JSON and Turtle derived application/ MIME types.
Source http_update_connection(+CGIHeader, +Request, -Connection, -Header)
Merge keep-alive information from Request and CGIHeader into Header.
Source connection(+Header, -Connection)[private]
Extract the desired connection from a header.
Source http_update_transfer(+Request, +CGIHeader, -Transfer, -Header)
Decide on the transfer encoding from the Request and the CGI header. The behaviour depends on the setting http:chunked_transfer. If never, even explitic requests are ignored. If on_request, chunked encoding is used if requested through the CGI header and allowed by the client. If if_possible, chunked encoding is used whenever the client allows for it, which is interpreted as the client supporting HTTP 1.1 or higher.

Chunked encoding is more space efficient and allows the client to start processing partial results. The drawback is that errors lead to incomplete pages instead of a nicely formatted complete page.

Source transfer(+Header, -Connection)[private]
Extract the desired connection from a header.
Source content_length_in_encoding(+Encoding, +In, -Bytes)[private]
Determine hom many bytes are required to represent the data from stream In using the given encoding. Fails if the data cannot be represented with the given encoding.
Source http_post_data(+Data, +Out:stream, +HdrExtra) is det
Send data on behalf on an HTTP POST request. This predicate is normally called by http_post/4 from http_client.pl to send the POST data to the server. Data is one of:
  • html(+Tokens) Result of html//1 from html_write.pl
  • xml(+Term) Post the result of xml_write/3 using the Mime-type text/xml
  • xml(+Type, +Term) Post the result of xml_write/3 using the given Mime-type and an empty option list to xml_write/3.
  • xml(+Type, +Term, +Options) Post the result of xml_write/3 using the given Mime-type and option list for xml_write/3.
  • file(+File) Send contents of a file. Mime-type is determined by file_mime_type/2.
  • file(+Type, +File) Send file with content of indicated mime-type.
  • memory_file(+Type, +Handle) Similar to file(+Type, +File), but using a memory file instead of a real file. See new_memory_file/1.
  • codes(+Codes) As codes(text/plain, Codes).
  • codes(+Type, +Codes) Send Codes using the indicated MIME-type.
  • bytes(+Type, +Bytes) Send Bytes using the indicated MIME-type. Bytes is either a string of character codes 0..255 or list of integers in the range 0..255. Out-of-bound codes result in a representation error exception.
  • atom(+Atom) As atom(text/plain, Atom).
  • atom(+Type, +Atom) Send Atom using the indicated MIME-type.
  • cgi_stream(+Stream, +Len) Read the input from Stream which, like CGI data starts with a partial HTTP header. The fields of this header are merged with the provided HdrExtra fields. The first Len characters of Stream are used.
  • form(+ListOfParameter) Send data of the MIME type application/x-www-form-urlencoded as produced by browsers issuing a POST request from an HTML form. ListOfParameter is a list of Name=Value or Name(Value).
  • form_data(+ListOfData) Send data of the MIME type multipart/form-data as produced by browsers issuing a POST request from an HTML form using enctype multipart/form-data. ListOfData is the same as for the List alternative described below. Below is an example. Repository, etc. are atoms providing the value, while the last argument provides a value from a file. 
    ...,
http_post([ protocol(http),
            host(Host),
            port(Port),
            path(ActionPath)
          ],
          form_data([ repository = Repository,
                      dataFormat = DataFormat,
                      baseURI    = BaseURI,
                      verifyData = Verify,
                      data       = file(File)
                    ]),
          _Reply,
          []),
...,
  • List If the argument is a plain list, it is sent using the MIME type multipart/mixed and packed using mime_pack/3. See mime_pack/3 for details on the argument format.
Source post_header(+Data, +HeaderExtra)//[private]
Generate the POST header, emitting HeaderExtra, followed by the HTTP Content-length and Content-type fields.
Source http_reply_header(+Out:stream, +What, +HdrExtra) is det
Create a reply header using reply_header//3 and send it to Stream.
Source reply_header(+Data, +HdrExtra, -Code)// is det[private]
Grammar that realises the HTTP handler for sending Data. Data is a real data object as described with http_reply/2 or a not-200-ok HTTP status reply. The following status replies are defined.
  • created(+URL, +HTMLTokens)
  • moved(+URL, +HTMLTokens)
  • moved_temporary(+URL, +HTMLTokens)
  • see_other(+URL, +HTMLTokens)
  • status(+Status)
  • status(+Status, +HTMLTokens)
  • authorise(+Method, +Realm, +Tokens)
  • authorise(+Method, +Tokens)
  • not_found(+URL, +HTMLTokens)
  • server_error(+Error, +Tokens)
  • resource_error(+Error, +Tokens)
  • service_unavailable(+Why, +Tokens)
See also
- http_status_reply/4 formulates the not-200-ok HTTP replies.
Source vstatus(+Status, -Code)// is det[private]
Source vstatus(+Status, -Code, +HdrExtra)// is det[private]
Emit the HTTP header for Status
Source status_number(?Status, ?Code)// is semidet[private]
Parse/generate the HTTP status numbers and map them to the proper name.
See also
- See the source code for supported status names and codes.
Source status_number(+Status:atom, -Code:nonneg) is det[private]
status_number(-Status:atom, +Code:nonneg) is det[private]
Relates a symbolic HTTP status names to their integer Code. Each code also needs a rule for status_comment//1.
throws
- type_error If Code is instantiated with something other than an integer.
- domain_error If Code is instantiated with an integer outside of the range [100-599] of defined HTTP status codes.
Source status_comment(+Code:atom)// is det[private]
Emit standard HTTP human-readable comment on the reply-status.
Source content_length(+Object, ?Len)// is det[private]
Emit the content-length field and (optionally) the content-range field.
Arguments:
Len- Number of bytes specified
Source content_range(+Unit:atom, +From:int, +RangeEnd:int, +Size:int)// is det[private]
Emit the Content-Range header for partial content (206) replies.
Source header_field(-Name, -Value)// is det[private]
 header_field(+Name, +Value) is det[private]
Process an HTTP request property. Request properties appear as a single line in an HTTP header.
Source read_field_value(-Codes)//[private]
Read a field eagerly upto the next whitespace
Source http_parse_header_value(+Field, +Value, -Prolog) is semidet
Translate Value in a meaningful Prolog term. Field denotes the HTTP request field for which we do the translation. Supported fields are:
content_length
Converted into an integer
status
Converted into an integer
cookie
Converted into a list with Name=Value by cookies//1.
set_cookie
Converted into a term set_cookie(Name, Value, Options). Options is a list consisting of Name=Value or a single atom (e.g., secure)
host
Converted to HostName:Port if applicable.
range
Converted into bytes(From, To), where From is an integer and To is either an integer or the atom end.
accept
Parsed to a list of media descriptions. Each media is a term media(Type, TypeParams, Quality, AcceptExts). The list is sorted according to preference.
content_disposition
Parsed into disposition(Name, Attributes), where Attributes is a list of Name=Value pairs.
content_type
Parsed into media(Type/SubType, Attributes), where Attributes is a list of Name=Value pairs.

As some fields are already parsed in the Request, this predicate is a no-op when called on an already parsed field.

Arguments:
Value- is either an atom, a list of codes or an already parsed header value.
Source known_field(?FieldName, ?AutoConvert, -Type)[private]
True if the value of FieldName is by default translated into a Prolog data structure.
Source field_to_prolog(+Field, +ValueCodes, -Prolog) is semidet[private]
Translate the value string into a sensible Prolog term. For known_fields(_,true), this must succeed. For maybe, we just return the atom if the translation fails.
Source parse_header_value(+Field, +ValueCodes, -Value) is semidet[private]
Parse the value text of an HTTP field into a meaningful Prolog representation.
Source field_value(+Name, +Value)//[private]
Source auth_field_value(+AuthValue)//[private]
Emit the authentication requirements (WWW-Authenticate field).
Source value_options(+List, +Field)//[private]
Emit field parameters such as ; charset=UTF-8. There are three versions: a plain key (secure), token values and quoted string values. Seems we cannot deduce that from the actual value.
Source accept(-Media)// is semidet[private]
Parse an HTTP Accept: header
Source content_disposition(-Disposition)//[private]
Parse Content-Disposition value
Source parse_content_type(-Type)//[private]
Parse Content-Type value into a term media(Type/SubType, Parameters).
Source rank_specialised(+Type, +TypeParam, -Key) is det[private]
Although the specification linked above is unclear, it seems that more specialised types must be preferred over less specialized ones.
To be done
- Is there an official specification of this?
 value_parameters(-Params:list) is det[private]
Accept (";" <parameter>)*, returning a list of Name=Value, where both Name and Value are atoms.
Source token(-Name)// is semidet[private]
Process an HTTP header token from the input.
Source quoted_string(-Text)// is semidet[private]
True if input starts with a quoted string representing Text.
Source header_fields(+Fields, ?ContentLength)// is det[private]
Process a sequence of [Name(Value), ...] attributes for the header. A term content_length(Len) is special. If instantiated it emits the header. If not it just unifies ContentLength with the argument of the content_length(Len) term. This allows for both sending and retrieving the content-length.
 field_name(?PrologName)[private]
Convert between prolog_name and HttpName. Field names are, according to RFC 2616, considered tokens and covered by the following definition: 
token          = 1*<any CHAR except CTLs or separators>
separators     = "(" | ")" | "<" | ">" | "@"
               | "," | ";" | ":" | "\" | <">
               | "/" | "[" | "]" | "?" | "="
               | "{" | "}" | SP | HT
Source separators(-CharCodes) is det[private]
CharCodes is a list of separators according to RFC2616
Source now//[private]
Current time using rfc_date//1.
Source rfc_date(+Time)// is det[private]
Write time according to RFC1123 specification as required by the RFC2616 HTTP protocol specs.
Source http_timestamp(+Time:timestamp, -Text:atom) is det
Generate a description of a Time in HTTP format (RFC1123)
Source request_uri_parts(+RequestURI, -Parts, ?Tail) is det[private]
Process the request-uri, producing the following parts:
path(-Path)
Decode path information (always present)
search(-QueryParams)
Present if there is a ?name=value&... part of the request uri. QueryParams is a Name=Value list.
fragment(-Fragment)
Present if there is a #Fragment.
 request_header(+In:stream, -Header:list) is det[private]
Read the remainder (after the request-uri) of the HTTP header and return it as a Name(Value) list.
Source cookies(-List)// is semidet[private]
Translate a cookie description into a list Name=Value.
Source cookie_option(-Option)// is semidet[private]
True if input represents a valid Cookie option. Officially, all cookie options use the syntax <name>=<value>, except for Secure and HttpOnly.
Arguments:
Option- Term of the form Name=Value
bug
- Incorrectly accepts options without = for M$ compatibility.
Source range(-Range)// is semidet[private]
Process the range header value. Range is currently defined as:
bytes(From, To)
Where From is an integer and To is either an integer or the atom end.
Source reply(+In, -Reply:list)// is semidet[private]
Process the first line of an HTTP reply. After that, read the remainder of the header and parse it. After successful completion, Reply contains the following fields, followed by the fields produced by http_read_header/2.
http_version(Major-Minor)
status(Code, Status, Comment)
Code is an integer between 100 and 599. Status is a Prolog internal name. Comment is the comment following the code as it appears in the reply's HTTP status line. @see status_number//2.
Source http_read_header(+Fd, -Header) is det
Read Name: Value lines from FD until an empty line is encountered. Field-name are converted to Prolog conventions (all lower, _ instead of -): Content-Type: text/html --> content_type(text/html)
Source http_parse_header(+Text:codes, -Header:list) is det
Header is a list of Name(Value)-terms representing the structure of the HTTP header in Text.
Errors
- domain_error(http_request_line, Line)
Source address//[private]
Emit the HTML for the server address on behalve of error and status messages (non-200 replies). Default is 
SWI-Prolog httpd at <hostname>

The address can be modified by providing a definition for the multifile predicate http:http_address//0.

 http:http_address// is det[multifile]
HTML-rule that emits the location of the HTTP server. This hook is called from address//0 to customise the server address. The server address is emitted on non-200-ok replies.
 http:status_page(+Status, +Context, -HTMLTokens) is semidet[multifile]
Hook called by http_status_reply/4 and http_status_reply/5 that allows for emitting custom error pages for the following HTTP page types:
  • 201 - created(Location)
  • 301 - moved(To)
  • 302 - moved_temporary(To)
  • 303 - see_other(To)
  • 400 - bad_request(ErrorTerm)
  • 401 - authorise(AuthMethod)
  • 403 - forbidden(URL)
  • 404 - not_found(URL)
  • 405 - method_not_allowed(Method,URL)
  • 406 - not_acceptable(Why)
  • 500 - server_error(ErrorTerm)
  • 503 - unavailable(Why)

The hook is tried twice, first using the status term, e.g., not_found(URL) and than with the code, e.g. 404. The second call is deprecated and only exists for compatibility.

Arguments:
Context- is the 4th argument of http_status_reply/5, which is invoked after raising an exception of the format http_reply(Status, HeaderExtra, Context). The default context is [] (the empty list).
HTMLTokens- is a list of tokens as produced by html//1. It is passed to print_html/2.
ClioPatria (version V3.1.1-40-g9d9e003)