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";