HttpHeaders abstract interface

abstract interface class HttpHeaders

Headers for HTTP requests and responses.

In some situations, headers are immutable:

• HttpRequest and HttpClientResponse always have immutable headers.

• HttpResponse and HttpClientRequest have immutable headers from the moment the body is written to.

In these situations, the mutating methods throw exceptions.

For all operations on HTTP headers the header name is case-insensitive.

To set the value of a header use the set() method:

request.headers.set(HttpHeaders.cacheControlHeader,
                    'max-age=3600, must-revalidate');

To retrieve the value of a header use the value() method:

print(request.headers.value(HttpHeaders.userAgentHeader));

An HttpHeaders object holds a list of values for each name as the standard allows. In most cases a name holds only a single value, The most common mode of operation is to use set() for setting a value, and value() for retrieving a value.

Properties

chunkedTransferEncoding read / write

bool chunkedTransferEncoding

getter:

Whether the connection uses chunked transfer encoding.

Reflects and modifies the value of the transferEncodingHeader header.

setter:

Whether the connection uses chunked transfer encoding.

Reflects and modifies the value of the transferEncodingHeader header.

Implementation

late bool chunkedTransferEncoding;

contentLength read / write

int contentLength

getter:

The value of the contentLengthHeader header, if any.

The value is negative if there is no content length set.

setter:

The value of the contentLengthHeader header, if any.

The value is negative if there is no content length set.

Implementation

int contentLength = -1;

contentType read / write

ContentType? contentType

getter:

The ContentType of the contentTypeHeader header, if any.

setter:

The ContentType of the contentTypeHeader header, if any.

Implementation

ContentType? contentType;

date read / write

DateTime? date

getter:

The date specified by the dateHeader header, if any.

setter:

The date specified by the dateHeader header, if any.

Implementation

DateTime? date;

expires read / write

DateTime? expires

getter:

The date and time specified by the expiresHeader header, if any.

setter:

The date and time specified by the expiresHeader header, if any.

Implementation

DateTime? expires;

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

host read / write

String? host

getter:

The value of the hostHeader header, if any.

setter:

The value of the hostHeader header, if any.

Implementation

String? host;

ifModifiedSince read / write

DateTime? ifModifiedSince

getter:

The date and time specified by the ifModifiedSinceHeader header, if any.

setter:

The date and time specified by the ifModifiedSinceHeader header, if any.

Implementation

DateTime? ifModifiedSince;

persistentConnection read / write

bool persistentConnection

getter:

Whether the connection is persistent (keep-alive).

setter:

Whether the connection is persistent (keep-alive).

Implementation

late bool persistentConnection;

port read / write

int? port

getter:

The value of the port part of the hostHeader header, if any.

setter:

The value of the port part of the hostHeader header, if any.

Implementation

int? port;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

add()

void add(String name, Object value, {bool preserveHeaderCase = false})

Adds a header value.

The header named name will have a string value derived from value added to its list of values.

Some headers are single valued, and for these, adding a value will replace a previous value. If the value is a DateTime, an HTTP date format will be applied. If the value is an Iterable, each element will be added separately. For all other types the default Object.toString method will be used.

Header names are converted to lower-case unless preserveHeaderCase is set to true. If two header names are the same when converted to lower-case, they are considered to be the same header, with one set of values.

The current case of the a header name is that of the name used by the last set or add call for that header.

Implementation

void add(String name, Object value, {bool preserveHeaderCase = false});

clear()

void clear()

Removes all headers.

Some headers have system supplied values which cannot be removed. All other header values are removed, and header names with not remaining values are no longer considered present.

Implementation

void clear();

forEach()

void forEach(void Function(String name, List<String> values) action)

Performs the action on each header.

The action function is called with each header's name and a list of the header's values. The casing of the name string is determined by the last add or set operation for that particular header, which defaults to lower-casing the header name unless explicitly set to preserve the case.

Implementation

void forEach(void Function(String name, List<String> values) action);

noFolding()

void noFolding(String name)

Disables folding for the header named name when sending the HTTP header.

By default, multiple header values are folded into a single header line by separating the values with commas.

The 'set-cookie' header has folding disabled by default.

Implementation

void noFolding(String name);

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

remove()

void remove(String name, Object value)

Removes a specific value for a header name.

Some headers have system supplied values which cannot be removed. For all other headers and values, the value is converted to a string in the same way as for add, then that string value is removed from the current values of name. If there are no remaining values for name, the header is no longer considered present.

Implementation

void remove(String name, Object value);

removeAll()

void removeAll(String name)

Removes all values for the specified header name.

Some headers have system supplied values which cannot be removed. All other values for name are removed. If there are no remaining values for name, the header is no longer considered present.

Implementation

void removeAll(String name);

set()

void set(String name, Object value, {bool preserveHeaderCase = false})

Sets the header name to value.

Removes all existing values for the header named name and then adds value to it.

Implementation

void set(String name, Object value, {bool preserveHeaderCase = false});

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

value()

String? value(String name)

Convenience method for the value for a single valued header.

The value must not have more than one value.

Returns null if there is no header with the provided name.

Implementation

String? value(String name);

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);

operator

List<String>? operator [](String name)

The values for the header named name.

Returns null if there is no header with the provided name, otherwise returns a new list containing the current values. Not that modifying the list does not change the header.

Implementation

List<String>? operator [](String name);

Constants

acceptCharsetHeader

const String acceptCharsetHeader

Implementation

static const acceptCharsetHeader = "accept-charset";

acceptEncodingHeader

const String acceptEncodingHeader

Implementation

static const acceptEncodingHeader = "accept-encoding";

acceptHeader

const String acceptHeader

Implementation

static const acceptHeader = "accept";

acceptLanguageHeader

const String acceptLanguageHeader

Implementation

static const acceptLanguageHeader = "accept-language";

acceptRangesHeader

const String acceptRangesHeader

Implementation

static const acceptRangesHeader = "accept-ranges";

accessControlAllowCredentialsHeader

const String accessControlAllowCredentialsHeader

Implementation

@Since("2.14")
static const accessControlAllowCredentialsHeader =
    'access-control-allow-credentials';

accessControlAllowHeadersHeader

const String accessControlAllowHeadersHeader

Implementation

@Since("2.14")
static const accessControlAllowHeadersHeader = 'access-control-allow-headers';

accessControlAllowMethodsHeader

const String accessControlAllowMethodsHeader

Implementation

@Since("2.14")
static const accessControlAllowMethodsHeader = 'access-control-allow-methods';

accessControlAllowOriginHeader

const String accessControlAllowOriginHeader

Implementation

@Since("2.14")
static const accessControlAllowOriginHeader = 'access-control-allow-origin';

accessControlExposeHeadersHeader

const String accessControlExposeHeadersHeader

Implementation

@Since("2.14")
static const accessControlExposeHeadersHeader =
    'access-control-expose-headers';

accessControlMaxAgeHeader

const String accessControlMaxAgeHeader

Implementation

@Since("2.14")
static const accessControlMaxAgeHeader = 'access-control-max-age';

accessControlRequestHeadersHeader

const String accessControlRequestHeadersHeader

Implementation

@Since("2.14")
static const accessControlRequestHeadersHeader =
    'access-control-request-headers';

accessControlRequestMethodHeader

const String accessControlRequestMethodHeader

Implementation

@Since("2.14")
static const accessControlRequestMethodHeader =
    'access-control-request-method';

ageHeader

const String ageHeader

Implementation

static const ageHeader = "age";

allowHeader

const String allowHeader

Implementation

static const allowHeader = "allow";

authorizationHeader

const String authorizationHeader

Implementation

static const authorizationHeader = "authorization";

cacheControlHeader

const String cacheControlHeader

Implementation

static const cacheControlHeader = "cache-control";

connectionHeader

const String connectionHeader

Implementation

static const connectionHeader = "connection";

contentDisposition

const String contentDisposition

Implementation

static const contentDisposition = "content-disposition";

contentEncodingHeader

const String contentEncodingHeader

Implementation

static const contentEncodingHeader = "content-encoding";

contentLanguageHeader

const String contentLanguageHeader

Implementation

static const contentLanguageHeader = "content-language";

contentLengthHeader

const String contentLengthHeader

Implementation

static const contentLengthHeader = "content-length";

contentLocationHeader

const String contentLocationHeader

Implementation

static const contentLocationHeader = "content-location";

contentMD5Header

const String contentMD5Header

Implementation

static const contentMD5Header = "content-md5";

contentRangeHeader

const String contentRangeHeader

Implementation

static const contentRangeHeader = "content-range";

contentTypeHeader

const String contentTypeHeader

Implementation

static const contentTypeHeader = "content-type";

cookieHeader

const String cookieHeader

Implementation

static const cookieHeader = "cookie";

dateHeader

const String dateHeader

Implementation

static const dateHeader = "date";

entityHeaders

const List<String> entityHeaders

Implementation

static const entityHeaders = [
  allowHeader,
  contentEncodingHeader,
  contentLanguageHeader,
  contentLengthHeader,
  contentLocationHeader,
  contentMD5Header,
  contentRangeHeader,
  contentTypeHeader,
  expiresHeader,
  lastModifiedHeader,
];

etagHeader

const String etagHeader

Implementation

static const etagHeader = "etag";

expectHeader

const String expectHeader

Implementation

static const expectHeader = "expect";

expiresHeader

const String expiresHeader

Implementation

static const expiresHeader = "expires";

fromHeader

const String fromHeader

Implementation

static const fromHeader = "from";

generalHeaders

const List<String> generalHeaders

Implementation

static const generalHeaders = [
  cacheControlHeader,
  connectionHeader,
  dateHeader,
  pragmaHeader,
  trailerHeader,
  transferEncodingHeader,
  upgradeHeader,
  viaHeader,
  warningHeader,
];

hostHeader

const String hostHeader

Implementation

static const hostHeader = "host";

ifMatchHeader

const String ifMatchHeader

Implementation

static const ifMatchHeader = "if-match";

ifModifiedSinceHeader

const String ifModifiedSinceHeader

Implementation

static const ifModifiedSinceHeader = "if-modified-since";

ifNoneMatchHeader

const String ifNoneMatchHeader

Implementation

static const ifNoneMatchHeader = "if-none-match";

ifRangeHeader

const String ifRangeHeader

Implementation

static const ifRangeHeader = "if-range";

ifUnmodifiedSinceHeader

const String ifUnmodifiedSinceHeader

Implementation

static const ifUnmodifiedSinceHeader = "if-unmodified-since";

lastModifiedHeader

const String lastModifiedHeader

Implementation

static const lastModifiedHeader = "last-modified";

locationHeader

const String locationHeader

Implementation

static const locationHeader = "location";

maxForwardsHeader

const String maxForwardsHeader

Implementation

static const maxForwardsHeader = "max-forwards";

pragmaHeader

const String pragmaHeader

Implementation

static const pragmaHeader = "pragma";

proxyAuthenticateHeader

const String proxyAuthenticateHeader

Implementation

static const proxyAuthenticateHeader = "proxy-authenticate";

proxyAuthorizationHeader

const String proxyAuthorizationHeader

Implementation

static const proxyAuthorizationHeader = "proxy-authorization";

rangeHeader

const String rangeHeader

Implementation

static const rangeHeader = "range";

refererHeader

const String refererHeader

Implementation

static const refererHeader = "referer";

requestHeaders

const List<String> requestHeaders

Implementation

static const requestHeaders = [
  acceptHeader,
  acceptCharsetHeader,
  acceptEncodingHeader,
  acceptLanguageHeader,
  authorizationHeader,
  expectHeader,
  fromHeader,
  hostHeader,
  ifMatchHeader,
  ifModifiedSinceHeader,
  ifNoneMatchHeader,
  ifRangeHeader,
  ifUnmodifiedSinceHeader,
  maxForwardsHeader,
  proxyAuthorizationHeader,
  rangeHeader,
  refererHeader,
  teHeader,
  userAgentHeader,
];

responseHeaders

const List<String> responseHeaders

Implementation

static const responseHeaders = [
  acceptRangesHeader,
  ageHeader,
  etagHeader,
  locationHeader,
  proxyAuthenticateHeader,
  retryAfterHeader,
  serverHeader,
  varyHeader,
  wwwAuthenticateHeader,
  contentDisposition,
];

retryAfterHeader

const String retryAfterHeader

Implementation

static const retryAfterHeader = "retry-after";

serverHeader

const String serverHeader

Implementation

static const serverHeader = "server";

setCookieHeader

const String setCookieHeader

Implementation

static const setCookieHeader = "set-cookie";

teHeader

const String teHeader

Implementation

static const teHeader = "te";

trailerHeader

const String trailerHeader

Implementation

static const trailerHeader = "trailer";

transferEncodingHeader

const String transferEncodingHeader

Implementation

static const transferEncodingHeader = "transfer-encoding";

upgradeHeader

const String upgradeHeader

Implementation

static const upgradeHeader = "upgrade";

userAgentHeader

const String userAgentHeader

Implementation

static const userAgentHeader = "user-agent";

varyHeader

const String varyHeader

Implementation

static const varyHeader = "vary";

viaHeader

const String viaHeader

Implementation

static const viaHeader = "via";

warningHeader

const String warningHeader

Implementation

static const warningHeader = "warning";

wwwAuthenticateHeader

const String wwwAuthenticateHeader

Implementation

static const wwwAuthenticateHeader = "www-authenticate";