Struct soup::MessageHeaders

pub struct MessageHeaders { /* private fields */ }

The HTTP message headers associated with a request or response.

Implementations

impl MessageHeaders

pub fn as_ptr(&self) -> *mut SoupMessageHeaders

Return the inner pointer to the underlying C value.

pub unsafe fn from_glib_ptr_borrow<'a>( ptr: *const *const SoupMessageHeaders ) -> &'a Self

Borrows the underlying C value.

impl MessageHeaders

pub fn new(type_: MessageHeadersType) -> MessageHeaders

Creates a #SoupMessageHeaders.

(Message does this automatically for its own headers. You would only need to use this method if you are manually parsing or generating message headers.)

type_

the type of headers

Returns

a new #SoupMessageHeaders

pub fn append(&self, name: &str, value: &str)

Appends a new header with name @name and value @value to @self.

(If there is an existing header with name @name, then this creates a second one, which is only allowed for list-valued headers; see also replace().)

The caller is expected to make sure that @name and @value are syntactically correct.

name

the header name to add

value

the new value of @name

pub fn clean_connection_headers(&self)

Removes all the headers listed in the Connection header.

pub fn clear(&self)

Clears @self.

pub fn foreach<P: FnMut(&str, &str)>(&self, func: P)

Calls @func once for each header value in @self.

Beware that unlike list(), this processes the headers in exactly the way they were added, rather than concatenating multiple same-named headers into a single value. (This is intentional; it ensures that if you call append() multiple times with the same name, then the I/O code will output multiple copies of the header when sending the message to the remote implementation, which may be required for interoperability in some cases.)

You may not modify the headers from @func.

func

callback function to run for each header

pub fn content_length(&self) -> i64

Gets the message body length that @self declare.

This will only be non-0 if encoding() returns Encoding::ContentLength.

Returns

the message body length declared by @self.

pub fn content_range(&self) -> Option<(i64, i64, i64)>

Parses @self’s Content-Range header and returns it in @start, @end, and @total_length. If the total length field in the header was specified as “*”, then @total_length will be set to -1.

Returns

true if @self contained a “Content-Range” header containing a byte range which could be parsed, false otherwise.

start

return value for the start of the range

end

return value for the end of the range

total_length

return value for the total length of the resource, or None if you don’t care.

pub fn encoding(&self) -> Encoding

Gets the message body encoding that @self declare.

This may not always correspond to the encoding used on the wire; eg, a HEAD response may declare a Content-Length or Transfer-Encoding, but it will never actually include a body.

Returns

the encoding declared by @self.

pub fn expectations(&self) -> Expectation

Gets the expectations declared by @self’s “Expect” header.

Currently this will either be Expectation::CONTINUE or Expectation::UNRECOGNIZED.

Returns

the contents of @self’s “Expect” header

pub fn headers_type(&self) -> MessageHeadersType

Gets the type of headers.

Returns

the header’s type.

pub fn list(&self, name: &str) -> Option<GString>

Gets the value of header @name in @self.

Use this for headers whose values are comma-delimited lists, and which are therefore allowed to appear multiple times in the headers. For non-list-valued headers, use one().

If @name appears multiple times in @self, list() will concatenate all of the values together, separated by commas. This is sometimes awkward to parse (eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal with it anyway, because the HTTP spec explicitly states that this transformation is allowed, and so an upstream proxy could do the same thing.

name

header name

Returns

the header’s value or None if not found.

pub fn one(&self, name: &str) -> Option<GString>

Gets the value of header @name in @self.

Use this for headers whose values are not comma-delimited lists, and which therefore can only appear at most once in the headers. For list-valued headers, use list().

If @self does erroneously contain multiple copies of the header, it is not defined which one will be returned. (Ideally, it will return whichever one makes libsoup most compatible with other HTTP implementations.)

name

header name

Returns

the header’s value or None if not found.

pub fn header_contains(&self, name: &str, token: &str) -> bool

Checks whether the list-valued header @name is present in @self, and contains a case-insensitive match for @token.

(If @name is present in @self, then this is equivalent to calling header_contains() on its value.)

name

header name

token

token to look for

Returns

true if the header is present and contains @token, false otherwise.

pub fn header_equals(&self, name: &str, value: &str) -> bool

Checks whether the header @name is present in @self and is (case-insensitively) equal to @value.

name

header name

value

expected value

Returns

true if the header is present and its value is @value, false otherwise.

pub fn remove(&self, name: &str)

Removes @name from @self.

If there are multiple values for @name, they are all removed.

name

the header name to remove

pub fn replace(&self, name: &str, value: &str)

Replaces the value of the header @name in @self with @value.

See also append().

The caller is expected to make sure that @name and @value are syntactically correct.

name

the header name to replace

value

the new value of @name

pub fn set_content_length(&self, content_length: i64)

Sets the message body length that @self will declare, and sets @self’s encoding to Encoding::ContentLength.

You do not normally need to call this; if @self is set to use Content-Length encoding, libsoup will automatically set its Content-Length header for you immediately before sending the headers. One situation in which this method is useful is when generating the response to a HEAD request; Calling set_content_length() allows you to put the correct content length into the response without needing to waste memory by filling in a response body which won’t actually be sent.

content_length

the message body length

pub fn set_content_range(&self, start: i64, end: i64, total_length: i64)

Sets @self’s Content-Range header according to the given values.

(Note that @total_length is the total length of the entire resource that this is a range of, not simply @end - @start + 1.)

Server has built-in handling for range requests, and you do not normally need to call this function youself. See MessageHeaders::get_ranges() for more details.

start

the start of the range

end

the end of the range

total_length

the total length of the resource, or -1 if unknown

pub fn set_encoding(&self, encoding: Encoding)

Sets the message body encoding that @self will declare.

In particular, you should use this if you are going to send a request or response in chunked encoding.

encoding

a #SoupEncoding

pub fn set_expectations(&self, expectations: Expectation)

Sets @self’s “Expect” header according to @expectations.

Currently Expectation::CONTINUE is the only known expectation value. You should set this value on a request if you are sending a large message body (eg, via POST or PUT), and want to give the server a chance to reject the request after seeing just the headers (eg, because it will require authentication before allowing you to post, or because you’re POSTing to a URL that doesn’t exist). This saves you from having to transmit the large request body when the server is just going to ignore it anyway.

expectations

the expectations to set

pub fn set_range(&self, start: i64, end: i64)

Sets @self’s Range header to request the indicated range.

@start and @end are interpreted as in a Range.

If you need to request multiple ranges, use MessageHeaders::set_ranges().

start

the start of the range to request

end

the end of the range to request

impl MessageHeaders

pub fn content_disposition(&self) -> Option<(GString, HashMap<String, String>)>

Looks up the “Content-Disposition” header in @self, parses it, and returns its value in *@disposition and *@params.

@params can be None if you are only interested in the disposition-type.

In HTTP, the most common use of this header is to set a disposition-type of “attachment”, to suggest to the browser that a response should be saved to disk rather than displayed in the browser. If @params contains a “filename” parameter, this is a suggestion of a filename to use. (If the parameter value in the header contains an absolute or relative path, libsoup will truncate it down to just the final path component, so you do not need to test this yourself.)

Content-Disposition is also used in “multipart/form-data”, however this is handled automatically by Multipart and the associated form methods.

Returns

true if @self contains a “Content-Disposition” header, false if not (in which case *@disposition and *@params will be unchanged).

disposition

return location for the disposition-type, or None

params

return location for the Content-Disposition parameters, or None

pub fn set_content_disposition( &self, disposition: Option<impl IntoGStr>, params: Option<HashMap<String, String>> )

Sets the “Content-Disposition” header in @self to @disposition, optionally with additional parameters specified in @params.

See content_disposition() for a discussion of how Content-Disposition is used in HTTP.

disposition

the disposition-type

params

additional parameters

pub fn content_type(&self) -> Option<(GString, HashMap<String, String>)>

Looks up the “Content-Type” header in @self, parses it, and returns its value in *@content_type and *@params.

@params can be None if you are only interested in the content type itself.

Returns

a string with the value of the “Content-Type” header or None if @self does not contain that header or it cannot be parsed (in which case *@params will be unchanged).

params

return location for the Content-Type parameters (eg, “charset”), or None

pub fn set_content_type( &self, content_type: Option<impl IntoGStr>, params: Option<HashMap<String, String>> )

Sets the “Content-Type” header in @self to @content_type.

Accepts additional parameters specified in @params.

content_type

the MIME type

params

additional parameters

Trait Implementations

impl Clone for MessageHeaders

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MessageHeaders

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<MessageHeaders> for Value

fn from(s: MessageHeaders) -> Self

Converts to this type from the input type.

impl HasParamSpec for MessageHeaders

type ParamSpec = ParamSpecBoxed

type SetValue = MessageHeaders

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, MessageHeaders>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for MessageHeaders

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for MessageHeaders

fn cmp(&self, other: &MessageHeaders) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for MessageHeaders

fn eq(&self, other: &MessageHeaders) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for MessageHeaders

fn partial_cmp(&self, other: &MessageHeaders) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for MessageHeaders

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for MessageHeaders

impl StructuralPartialEq for MessageHeaders