Package org.gnome.soup

Class MessageHeaders

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.soup.MessageHeaders

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class MessageHeaders
extends ProxyInstance

The HTTP message headers associated with a request or response.

Constructor Summary

Constructors

Constructor	Description
MessageHeaders(MemorySegment address)	Create a MessageHeaders proxy instance for the provided memory address.
MessageHeaders(MessageHeadersType type)	Creates a SoupMessageHeaders.

Method Summary

Modifier and Type	Method	Description
void	append(String name, String value)	Appends a new header with name name and value value to this MessageHeaders.
void	cleanConnectionHeaders()	Removes all the headers listed in the Connection header.
void	clear()	Clears this MessageHeaders.
void	foreach(MessageHeadersForeachFunc func)	Calls func once for each header value in this MessageHeaders.
void	freeRanges(Range ranges)	Frees the array of ranges returned from getRanges(long, io.github.jwharm.javagi.base.Out<org.gnome.soup.Range[]>).
boolean	getContentDisposition(Out<String> disposition, Out<HashTable<String,String>> params)	Looks up the "Content-Disposition" header in this MessageHeaders, parses it, and returns its value in *disposition and *params.
long	getContentLength()	Gets the message body length that this MessageHeaders declare.
boolean	getContentRange(Out<Long> start, Out<Long> end, @Nullable Out<Long> totalLength)	Parses this MessageHeaders's Content-Range header and returns it in start, end, and totalLength.
String	getContentType(@Nullable Out<HashTable<String,String>> params)	Looks up the "Content-Type" header in this MessageHeaders, parses it, and returns its value in *contentType and *params.
Encoding	getEncoding()	Gets the message body encoding that this MessageHeaders declare.
Set<Expectation>	getExpectations()	Gets the expectations declared by this MessageHeaders's "Expect" header.
MessageHeadersType	getHeadersType()	Gets the type of headers.
String	getList(String name)	Gets the value of header name in this MessageHeaders.
String	getOne(String name)	Gets the value of header name in this MessageHeaders.
boolean	getRanges(long totalLength, Out<Range[]> ranges)	Parses this MessageHeaders's Range header and returns an array of the requested byte ranges.
static Type	getType()	Get the GType of the MessageHeaders class
boolean	headerContains(String name, String token)	Checks whether the list-valued header name is present in this MessageHeaders, and contains a case-insensitive match for token.
boolean	headerEquals(String name, String value)	Checks whether the header name is present in this MessageHeaders and is (case-insensitively) equal to value.
MessageHeaders	ref()	Atomically increments the reference count of this MessageHeaders by one.
void	remove(String name)	Removes name from this MessageHeaders.
void	replace(String name, String value)	Replaces the value of the header name in this MessageHeaders with value.
void	setContentDisposition(String disposition, @Nullable HashTable<String,String> params)	Sets the "Content-Disposition" header in this MessageHeaders to disposition, optionally with additional parameters specified in params.
void	setContentLength(long contentLength)	Sets the message body length that this MessageHeaders will declare, and sets this MessageHeaders's encoding to Encoding.CONTENT_LENGTH.
void	setContentRange(long start, long end, long totalLength)	Sets this MessageHeaders's Content-Range header according to the given values.
void	setContentType(String contentType, @Nullable HashTable<String,String> params)	Sets the "Content-Type" header in this MessageHeaders to contentType.
void	setEncoding(Encoding encoding)	Sets the message body encoding that this MessageHeaders will declare.
void	setExpectations(Set<Expectation> expectations)	Sets this MessageHeaders's "Expect" header according to expectations.
void	setExpectations(Expectation... expectations)	Sets this MessageHeaders's "Expect" header according to expectations.
void	setRange(long start, long end)	Sets this MessageHeaders's Range header to request the indicated range.
void	setRanges(Range ranges, int length)	Sets this MessageHeaders's Range header to request the indicated ranges.
void	unref()	Atomically decrements the reference count of this MessageHeaders by one.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MessageHeaders

public MessageHeaders(MemorySegment address)

Create a MessageHeaders proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

MessageHeaders

public MessageHeaders(MessageHeadersType type)
               throws UnsupportedPlatformException

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.)

Parameters:

type - the type of headers

Throws:

UnsupportedPlatformException - when run on a platform other than linux

Method Details

getType

public static Type getType()

Get the GType of the MessageHeaders class

Returns:

the GType

append

public void append(String name,
 String value)

Appends a new header with name name and value value to this MessageHeaders.

(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(java.lang.String, java.lang.String).)

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

Parameters:

name - the header name to add

value - the new value of name

cleanConnectionHeaders

public void cleanConnectionHeaders()

Removes all the headers listed in the Connection header.

clear

public void clear()

Clears this MessageHeaders.

foreach

public void foreach(MessageHeadersForeachFunc func)

Calls func once for each header value in this MessageHeaders.

Beware that unlike getList(java.lang.String), 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(java.lang.String, java.lang.String) 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.

Parameters:

func - callback function to run for each header

freeRanges

public void freeRanges(Range ranges)

Frees the array of ranges returned from getRanges(long, io.github.jwharm.javagi.base.Out<org.gnome.soup.Range[]>).

Parameters:

ranges - an array of SoupRange

getContentDisposition

public boolean getContentDisposition(Out<String> disposition,
 Out<HashTable<String,String>> params)

Looks up the "Content-Disposition" header in this MessageHeaders, parses it, and returns its value in *disposition and *params.

params can be null 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.

Parameters:

disposition - return location for the disposition-type, or null

params - return location for the Content-Disposition parameters, or null

Returns:

true if this MessageHeaders contains a "Content-Disposition" header, false if not (in which case *disposition and *params will be unchanged).

getContentLength

public long getContentLength()

Gets the message body length that this MessageHeaders declare.

This will only be non-0 if getEncoding() returns Encoding.CONTENT_LENGTH.

Returns:

the message body length declared by this MessageHeaders.

getContentRange

public boolean getContentRange(Out<Long> start,
 Out<Long> end,
 @Nullable
 @Nullable Out<Long> totalLength)

Parses this MessageHeaders's Content-Range header and returns it in start, end, and totalLength. If the total length field in the header was specified as "*", then totalLength will be set to -1.

Parameters:

start - return value for the start of the range

end - return value for the end of the range

totalLength - return value for the total length of the resource, or null if you don't care.

Returns:

true if this MessageHeaders contained a "Content-Range" header containing a byte range which could be parsed, false otherwise.

getContentType

public String getContentType(@Nullable
 @Nullable Out<HashTable<String,String>> params)

Looks up the "Content-Type" header in this MessageHeaders, parses it, and returns its value in *contentType and *params.

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

Parameters:

params - return location for the Content-Type parameters (eg, "charset"), or null

Returns:

a string with the value of the "Content-Type" header or null if this MessageHeaders does not contain that header or it cannot be parsed (in which case *params will be unchanged).

getEncoding

public Encoding getEncoding()

Gets the message body encoding that this MessageHeaders 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 this MessageHeaders.

getExpectations

public Set<Expectation> getExpectations()

Gets the expectations declared by this MessageHeaders's "Expect" header.

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

Returns:

the contents of this MessageHeaders's "Expect" header

getHeadersType

public MessageHeadersType getHeadersType()

Gets the type of headers.

Returns:

the header's type.

getList

public String getList(String name)

Gets the value of header name in this MessageHeaders.

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 getOne(java.lang.String).

If name appears multiple times in this MessageHeaders, getList(java.lang.String) 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.

Parameters:

name - header name

Returns:

the header's value or null if not found.

getOne

public String getOne(String name)

Gets the value of header name in this MessageHeaders.

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 getList(java.lang.String).

If this MessageHeaders 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.)

Parameters:

name - header name

Returns:

the header's value or null if not found.

getRanges

public boolean getRanges(long totalLength,
 Out<Range[]> ranges)

Parses this MessageHeaders's Range header and returns an array of the requested byte ranges.

The returned array must be freed with freeRanges(org.gnome.soup.Range).

If totalLength is non-0, its value will be used to adjust the returned ranges to have explicit start and end values, and the returned ranges will be sorted and non-overlapping. If totalLength is 0, then some ranges may have an end value of -1, as described under Range, and some of the ranges may be redundant.

Beware that even if given a totalLength, this function does not check that the ranges are satisfiable.

SoupServer has built-in handling for range requests. If your server handler returns a Status.OK response containing the complete response body (rather than pausing the message and returning some of the response body later), and there is a Range header in the request, then libsoup will automatically convert the response to a Status.PARTIAL_CONTENT response containing only the range(s) requested by the client.

The only time you need to process the Range header yourself is if either you need to stream the response body rather than returning it all at once, or you do not already have the complete response body available, and only want to generate the parts that were actually requested by the client.

Parameters:

totalLength - the total_length of the response body

ranges - return location for an array of SoupRange

Returns:

true if this MessageHeaders contained a syntactically-valid "Range" header, false otherwise (in which case range and length will not be set).

headerContains

public boolean headerContains(String name,
 String token)

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

(If name is present in this MessageHeaders, then this is equivalent to calling Soup.headerContains(java.lang.String, java.lang.String) on its value.)

Parameters:

name - header name

token - token to look for

Returns:

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

headerEquals

public boolean headerEquals(String name,
 String value)

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

Parameters:

name - header name

value - expected value

Returns:

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

ref

public MessageHeaders ref()

Atomically increments the reference count of this MessageHeaders by one.

Returns:

the passed in SoupMessageHeaders

remove

public void remove(String name)

Removes name from this MessageHeaders.

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

Parameters:

name - the header name to remove

replace

public void replace(String name,
 String value)

Replaces the value of the header name in this MessageHeaders with value.

See also append(java.lang.String, java.lang.String).

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

Parameters:

name - the header name to replace

value - the new value of name

setContentDisposition

public void setContentDisposition(String disposition,
 @Nullable
 @Nullable HashTable<String,String> params)

Sets the "Content-Disposition" header in this MessageHeaders to disposition, optionally with additional parameters specified in params.

See getContentDisposition(io.github.jwharm.javagi.base.Out<java.lang.String>, io.github.jwharm.javagi.base.Out<org.gnome.glib.HashTable<java.lang.String, java.lang.String>>) for a discussion of how Content-Disposition is used in HTTP.

Parameters:

disposition - the disposition-type

params - additional parameters

setContentLength

public void setContentLength(long contentLength)

Sets the message body length that this MessageHeaders will declare, and sets this MessageHeaders's encoding to Encoding.CONTENT_LENGTH.

You do not normally need to call this; if this MessageHeaders 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 setContentLength(long) 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.

Parameters:

contentLength - the message body length

setContentRange

public void setContentRange(long start,
 long end,
 long totalLength)

Sets this MessageHeaders's Content-Range header according to the given values.

(Note that totalLength 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 getRanges(long, io.github.jwharm.javagi.base.Out<org.gnome.soup.Range[]>) for more details.

Parameters:

start - the start of the range

end - the end of the range

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

setContentType

public void setContentType(String contentType,
 @Nullable
 @Nullable HashTable<String,String> params)

Sets the "Content-Type" header in this MessageHeaders to contentType.

Accepts additional parameters specified in params.

Parameters:

contentType - the MIME type

params - additional parameters

setEncoding

public void setEncoding(Encoding encoding)

Sets the message body encoding that this MessageHeaders will declare.

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

Parameters:

encoding - a SoupEncoding

setExpectations

public void setExpectations(Set<Expectation> expectations)

Sets this MessageHeaders'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.

Parameters:

expectations - the expectations to set

setExpectations

public void setExpectations(Expectation... expectations)

Sets this MessageHeaders'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.

Parameters:

expectations - the expectations to set

setRange

public void setRange(long start,
 long end)

Sets this MessageHeaders'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 setRanges(org.gnome.soup.Range, int).

Parameters:

start - the start of the range to request

end - the end of the range to request

setRanges

public void setRanges(Range ranges,
 int length)

Sets this MessageHeaders's Range header to request the indicated ranges.

If you only want to request a single range, you can use setRange(long, long).

Parameters:

ranges - an array of SoupRange

length - the length of range

unref

public void unref()

Atomically decrements the reference count of this MessageHeaders by one.

When the reference count reaches zero, the resources allocated by this MessageHeaders are freed