Indy 9 | Content | Index | Reference

TIdEntityHeaderInfo
Hierarchy, Properties, Methods, See Also, Unit: IdHTTPHeaderInfo
Specifies entity and general headers used in the HTTP protocol.

    TIdEntityHeaderInfo = class(TPersistent)

Unit
IdHTTPHeaderInfo
Description
TIdEntityHeaderInfo is a TPersistent descendant that represents message headers from a HTTP request or response, as described in the Internet Standards document:

- RFC 2616 - Hypertext Transfer Protocol version 1.1 [HTTP/1.1] (http://www.rfc-editor.org/rfc/rfc2616.txt)

TIdEntityHeaderInfo is the ancestor class that defines the common headers used in TIdRequestHeaderInfo and TIdResponseHeaderInfo, and represents header fields that define metainformation about the entity body or, if no body is present, about a resource associated with a request. Some of this metainformation is optional; some headers might be required dependent on the HTTP protocol specification.

Applications will normally create instances of TIdRequestHeaderInfo or TIdResponseHeaderInfo, which implement the contextual semantic requirements for the HTTP protocol.

TIdEntityHeaderInfo.CacheControl
TIdEntityHeaderInfo, See Also
Specifies the HTTP Cache-Control general message header directives.

    property CacheControl: String;

Description
CacheControl is a String property that contains HTTP Cache-Control general message header directives in an HTTP request or response. CacheControl indicates the behavior that prevents a cache from adversely interfering with the request or response, and generally override the default caching algorithms. Cache directives are unidirectional, and the presence of a directive in a HTTP request does not imply that the same directive will appear in a HTTP response.

Some common values for CacheControl in a HTTP request include the following:

- "no-cache"

- "no-store"

- "max-age=" [delta-seconds]

- "max-stale=" [delta-seconds]

- "min-fresh=" [delta-seconds]

- "no-transform"

- "only-if-cached"

Some common values for CacheControl in a HTTP response include the following:

- "public"

- "private"

- "no-cache"

- "no-store"

- "no-transform"

- "must-revalidate"

- "proxy-revalidate"

- "max-age=" [delta-seconds]

- "s-maxage=" [delta-seconds]

Note: CacheControl might not be implemented for HTTP/1.0, which might contain a header value for storage in the the Pragma property that contains the value "no-cache".

TIdEntityHeaderInfo.Connection
TIdEntityHeaderInfo, See Also
Indicates that the connection will be closed after a response.

    property Connection: string;

Description
Connection is a String property that contains the value for the HTTP general message header that indicates the options desired for a particular connection. The Connection header value must not be forwarded by a proxy over further connections.

For HTTP/1.1 applications, Connection may contain the value "close" to indicate that the connection will be closed after completion of the response. HTTP/1.1 applications that do not support persistent connections must include the "close" connection option in every message.

TIdEntityHeaderInfo.ContentEncoding
TIdEntityHeaderInfo, See Also
Indicates transformations applied to the content of an entity.

    property ContentEncoding: string;

Description
ContentEncoding is a String property used as an optional modifier to the ContentType for an entity body. ContentEncoding indicates the additional content encoding performed on the entity body, and the decoding mechanisms needed to obtain the media-type referenced by ContentType.

ContentEncoding must contain a value that is registered with the Internet Assigned Numbers Authority (IANA), and initially permitted the following values:

- gzip - An encoding format produced by the file compression program "gzip" (GNU zip) as described in RFC 1952. This format is a Lempel-Ziv coding (LZ77) with a 32 bit CRC.

- compress - The encoding format produced by the common UNIX file compression program "compress". This format is an adaptive Lempel-Ziv-Welch coding (LZW).

- deflate - The "zlib" format defined in RFC 1950 in combination with the "deflate" compression mechanism described in RFC 1951.

- identity - The default (identity) encoding; the use of no transformation whatsoever. This content encoding is used only in the AcceptEncoding header in TIdRequestHeaderInfo, and should not be used in the ContentEncoding header.

If multiple encodings have been applied to an entity, then ContentEncoding will list the encodings in the order in which they were applied. Additional information about encoding parameters may be provided by other entity header properties, or in ExtraHeaders.

TIdEntityHeaderInfo.ContentLanguage
TIdEntityHeaderInfo
Identifies the preferred language for the contents of an entity.

    property ContentLanguage: string;

Description
ContentLanguage is a String property that identifies the preferred language for the contents of an entity. If ContentLanguage not specified, then the content is intended for all language audiences or the default alnguage is unknown. Multiple languages may be listed for content that is intended for multiple audiences by using a comma-delimited list of language values.

The syntax for values in ContentLanguage is defined in the Internet Standards document:

- RFC 1766, Tags for the Identification of Languages

TIdEntityHeaderInfo.ContentLength
TIdEntityHeaderInfo, See Also
Indicates the size of an entity body.

    property ContentLength: Integer;

Description
ContentLength is an Integer property that indicates the size of an entity body, as a number of octets. ContentLength reflects the transfer length of the content after any encodings specified in ContentEncoding.

When ContentLength is given in a message where a message body is allowed, its field value must exactly match the number of octets in the message body. ContentLength should be avaiable whenever the message length can be determined prior to being transferred, unless this is prohibited by the HTTP protocol specification.

For compatibility with HTTP/1.0 applications, HTTP/1.1 requests containing a message body must include a valid ContentLength header field unless the server is known to be HTTP/1.1 compliant. If a request contains a message body and ContentLength is not given, the server should respond with 400 (bad request) if it cannot determine the length of the message, or with 411 (length required) if it wishes to insist on receiving a valid ContentLength.

All HTTP/1.1 applications that receive entities must accept "chunked" transfers that allow retrieval of HTP entities when the message length cannot be determined in advance.

TIdEntityHeaderInfo.ContentRangeEnd
TIdEntityHeaderInfo, See Also
Identifies the upper byte range in a partial request.

    property ContentRangeEnd: Cardinal;

Description
ContentRangeEnd is a Cardinal property that identifies the upper byte range requested for a partial entity resource. ContentRangeEnd is used with ContentRangeStart to reveal the "Content-Range" message header value.

All ContentRangeEnd values are expressed in bytes.

Note: clients cannot depend on servers to send a "416 Requested range not satisfiable" response instead of a "200 (OK)" response for an unsatisfiable request with ContentRangeStart and ContentRangeEnd values, since not all servers implement this request-header.

TIdEntityHeaderInfo.ContentRangeStart
TIdEntityHeaderInfo, See Also
Identifies the beginning byte range in a partial request.

    property ContentRangeStart: Cardinal;

Description
ContentRangeStart is a Cardinal property that identifies the beginning byte range requested for a partial entity resource. ContentRangeStart is used with ContentRangeEnd to reveal the "Content-Range" message header value.

All ContentRangeStart values are expressed in bytes.

Note: clients cannot depend on servers to send a "416 Requested range not satisfiable" response instead of a "200 (OK)" response for an unsatisfiable request with ContentRangeStart and ContentRangeEnd values, since not all servers implement this request-header.

TIdEntityHeaderInfo.ContentType
TIdEntityHeaderInfo
Indicates the type, subtype, and attribute parameters for data in an entity body.

    property ContentType: string;

Description
ContentType is a String property that indicates the media type used to represent an entity body, and contains a registered Internet Assigned Number Authority (IANA) media type. HTTP uses ContentType to provide open and extensible data typing and type negotiation. ContentType contains type, subtype, and parameter attribute name components significant to the processing of a media-type.

Note: Any HTTP/1.1 message containing an entity body should include a ContentType value defining the media type of that body. The default value for media type should be "application/octet-stream".

TIdEntityHeaderInfo.ContentVersion
TIdEntityHeaderInfo, See Also
Identifies the version tag associated with a server resource.

    property ContentVersion: string;

Description
ContentVersion is a String property that represents the version tag associated with a rendition of an entity. ContentVersion can be used with the "Derived-From" message header in RawHeaders to allow access to multiple versions of the same server resource.

TIdEntityHeaderInfo.CustomHeaders
TIdEntityHeaderInfo, See Also
Represents custom headers names and values for the HTTP message.

    property CustomHeaders: TIdHeaderList;

Description
CustomHeaders is a TIdHeaderList property that contains header names and values that have been added to an HTTP message by the client application. CustomHeaders is used to stored header names and values that are not represented as properties in TIdEntityHeaderInfo and descendant classes.

CustomHeaders is initialized in the Create constructor, and freed in Destroy.

CustomHeaders is used when TIdEntityHeaderInfo builds the textual representation of header names and value for an HTTP message prior to transmission. When building the textual header values, headers represented as properties in TIdEntityHeaderInfo are added to RawHeaders. Any values in CustomHeaders are appended to the text without any additional processsing.

Use CustomHeaders to create HTTP headers that are not represented as properties, since RawHeaders is cleared when generating headers for the HTTP message from properties and CustomHeaders.

TIdEntityHeaderInfo.Date
TIdEntityHeaderInfo
Indicates the origin date and time for an HTTP message.

    property Date: TDateTime;

Description
Date is a TDateTime property that indicates the origin date and time for an HTTP message. Origin servers must include a Date value in all responses, except in the following cases:

- Response status code is 100 (Continue) or 101 (Switching Protocols); Date is an optional header field.

- Response status code is a server error, e.g. 500 (Internal Server Error) or 503 (Service Unavailable), and it is inconvenient or impossible to generate a valid Date.

- Server does not have a clock that can provide a reasonable approximation of the current time, its responses must not include a Date header field.

A received message without a Date header must have a Date header value constructed on the client after receipt.

A message sent by a client can contain an optional Date header value if the message has an entity body, as in HTTP PUT and POST requests.

TIdEntityHeaderInfo.Expires
TIdEntityHeaderInfo, See Also
Represents the timestamp when an entity is considered stale.

    property Expires: TDateTime;

Description
Expires is a TDateTime property that represents the date and time after which the content of an entity is considered stale. A stale cache entry may not normally be returned by a cache unless it is first validated with the origin server. The presence of an Expires field does not imply that the original resource will change or cease to exist at, before, or after the indicated timestamp value.

Expires is read from the headers in an HTTP response, and may originally contain either an integer number of seconds for the expiration value or an actual date and time. When the header is expressed as an integer value, the Expires property will be given a value that corresponds to the current date and time plus the number of seconds in the header.

Note: A response that includes a CacheControl header with the max-age directive will override the Expires property.

TIdEntityHeaderInfo.HasContentLength
TIdEntityHeaderInfo, See Also
Indicates if a value has been assigned to ContentLength in the entity headers.

    property HasContentLength: Boolean;

Description
HasContentLength is a read-only Boolean property that indicates if a value has been assigned to ContentLength in the entity headers. HasContentLength is updated when ProcessHeaders is called to set property values from the corresponding header values. HasContentLength is True when ContentLength contains a non-zero positive integer value. Assigning a value to ContentLength will insure that HasContentLength is also updated.

TIdEntityHeaderInfo.LastModified
TIdEntityHeaderInfo, See Also
Indicates the date and time a server resource was modified.

    property LastModified: TDateTime;

Description
LastModified is a TDateTime property that indicates the date and time when the origin server believes the most recent version of a resource was modified. An origin server must not send a LastModified date which is later than the server time of message origination in Date. An origin server should send LastModified whenever possible.

TIdEntityHeaderInfo.Pragma
TIdEntityHeaderInfo, See Also
Represents HTTP server directives in a client request.

    property Pragma: string;

Description
Pragma is a string property that contains HTTP server directives, and represent optional behavior for the HTTP protocol. Pragma normally contains the value "no-cache" and indicates that the HTTP request should be forwarded to the server even when the request can be satisfied from the server cache.

Pragma is used in an HTTP client request, and has the same meaning as the CacheControl property used in HTTP/1.1. Pragma is defined to provide backward compatibility with HTTP/1.0.

Pragma may also contain implementation-specific extension values which are defined in the HTTP protocol. Pragma directives must be passed by a proxy or gateway application, regardless of their significance to that application, since the directives might be applicable to all recipients along the request/response chain. It is not possible to specify Pragma for a specific client. Any Pragma directive not relevant to the client should be ignored.

Notes
Use of Pragma in a HTTP response is not defined by the HTTP protocol, and does not provide a reliable replacement for CacheControl in the response.

TIdEntityHeaderInfo.RawHeaders
TIdEntityHeaderInfo, See Also
Contains message header names and values in their original form.

    property RawHeaders: TIdHeaderList;

Description
RawHeaders is a read-only TIdHeaderList property that contains the message header names and values in their original form, as received in an HTTP request or response. RawHeaders are used as the origin for header values during processing and storage in their property representation. RawHeaders are used as the destination for property values when generating the headers for an HTTP protocol response.

Use CustomHeaders to create new header values that cannot be expressed as a property in the TIdEntityHeaderInfo instance.

TIdEntityHeaderInfo.Clear
TIdEntityHeaderInfo, See Also
Resets properties to their default empty values.

    procedure Clear; virtual;

Description
Clear is procedure that resets properties in the object instance to their default empty values, including:

- Connection

- ContentVersion

- ContentEncoding

- ContentLanguage

- ContentType

- ContentLength

- ContentRangeStart

- ContentRangeEnd

- Date

- LastModified

- Expires

Clears sets the default value for the ContentType property to the MIME type and subtype '[text/html'. Clear also removes all values in the RawHeaders property.

TIdEntityHeaderInfo.Create
TIdEntityHeaderInfo, See Also
Constructor for the object instance.

    constructor Create; virtual;

Description
Create is the constructor for the object instance. Create relies on the inherited constructor, and initializes the object properties CustomHeaders and RawHeaders prior to calling Clear.

TIdEntityHeaderInfo.Destroy
TIdEntityHeaderInfo, See Also
Frees the object instance.

    destructor Destroy; override;

Description
Destroy is the destructor for the object instance. Destroy frees the object properties CustomHeaders and RawHeaders prior to calling the inherited Destroy method.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.