Class Soup

java.lang.Object
org.gnome.soup.Soup
@Generated("org.javagi.JavaGI") public final class Soup extends Object
Constants and functions that are declared in the global Soup namespace.

  • Field Details

    • FORM_MIME_TYPE_MULTIPART

      public static final String FORM_MIME_TYPE_MULTIPART
      A macro containing the value multipart/form-data; the MIME type used for posting form data that contains files to be uploaded.
      See Also:

    • FORM_MIME_TYPE_URLENCODED

      public static final String FORM_MIME_TYPE_URLENCODED
      A macro containing the value application/x-www-form-urlencoded; the default MIME type for POSTing HTML form data.
      See Also:

    • HSTS_POLICY_MAX_AGE_PAST

      public static final int HSTS_POLICY_MAX_AGE_PAST
      An expiration date that is always in the past.
      See Also:

    • HTTP_URI_FLAGS

      public static final int HTTP_URI_FLAGS
      The set of GUriFlags libsoup expects all GUri to use.
      See Also:

    • MAJOR_VERSION

      public static final int MAJOR_VERSION
      Like getMajorVersion(), but from the headers used at application compile time, rather than from the library linked against at application run time.
      See Also:

    • MICRO_VERSION

      public static final int MICRO_VERSION
      Like getMicroVersion(), but from the headers used at application compile time, rather than from the library linked against at application run time.
      See Also:

    • MINOR_VERSION

      public static final int MINOR_VERSION
      Like getMinorVersion(), but from the headers used at application compile time, rather than from the library linked against at application run time.
      See Also:

    • VERSION_MIN_REQUIRED

      public static final int VERSION_MIN_REQUIRED

      A macro that should be defined by the user prior to including libsoup.h.

      The definition should be one of the predefined libsoup version macros: SOUP_VERSION_2_24, SOUP_VERSION_2_26, ...

      This macro defines the earliest version of libsoup that the package is required to be able to compile against.

      If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version SOUP_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not).

      See Also:

  • Constructor Details

    • Soup

      public Soup()

  • Method Details

    • javagi$ensureInitialized

      public static void javagi$ensureInitialized()

    • checkVersion

      public static boolean checkVersion(int major, int minor, int micro)

      Like org.gnome.soup.Soup.CHECKVERSION, but the check for soup_check_version is at runtime instead of compile time.

      This is useful for compiling against older versions of libsoup, but using features from newer versions.

      Parameters:
      major - the major version to check
      minor - the minor version to check
      micro - the micro version to check
      Returns:
      true if the version of the libsoup currently loaded is the same as or newer than the passed-in version.

    • cookiesFree

      public static void cookiesFree(SList<Cookie> cookies)
      Frees cookies.
      Parameters:
      cookies - a GSList of Cookie

    • cookiesFromRequest

      public static SList<Cookie> cookiesFromRequest(Message msg)

      Parses msg's Cookie request header and returns a GLib.SList of SoupCookies.

      As the "Cookie" header, unlike "Set-Cookie", only contains cookie names and values, none of the other Cookie fields will be filled in. (Thus, you can't generally pass a cookie returned from this method directly to cookiesToResponse(SList, Message).)

      Parameters:
      msg - a SoupMessage containing a "Cookie" request header
      Returns:
      a GSList of SoupCookies, which can be freed with Cookie.free().

    • cookiesFromResponse

      public static SList<Cookie> cookiesFromResponse(Message msg)

      Parses msg's Set-Cookie response headers and returns a GLib.SList of SoupCookies.

      Cookies that do not specify "path" or "domain" attributes will have their values defaulted from msg.

      Parameters:
      msg - a SoupMessage containing a "Set-Cookie" response header
      Returns:
      a GSList of SoupCookies, which can be freed with Cookie.free().

    • cookiesToCookieHeader

      public static String cookiesToCookieHeader(SList<Cookie> cookies)
      Serializes a GLib.SList of Cookie into a string suitable for setting as the value of the "Cookie" header.
      Parameters:
      cookies - a GSList of Cookie
      Returns:
      the serialization of cookies

    • cookiesToRequest

      public static void cookiesToRequest(SList<Cookie> cookies, Message msg)

      Adds the name and value of each cookie in cookies to msg's "Cookie" request.

      If msg already has a "Cookie" request header, these cookies will be appended to the cookies already present. Be careful that you do not append the same cookies twice, eg, when requeuing a message.

      Parameters:
      cookies - a GSList of Cookie
      msg - a SoupMessage

    • cookiesToResponse

      public static void cookiesToResponse(SList<Cookie> cookies, Message msg)

      Appends a "Set-Cookie" response header to msg for each cookie in cookies.

      This is in addition to any other "Set-Cookie" headers msg may already have.

      Parameters:
      cookies - a GSList of Cookie
      msg - a SoupMessage

    • dateTimeNewFromHttpString

      public static @Nullable DateTime dateTimeNewFromHttpString(String dateString)

      Parses dateString and tries to extract a date from it.

      This recognizes all of the "HTTP-date" formats from RFC 2616, RFC 2822 dates, and reasonable approximations thereof. (Eg, it is lenient about whitespace, leading "0"s, etc.)

      Parameters:
      dateString - The date as a string
      Returns:
      a new GDateTime, or null if dateString could not be parsed.

    • dateTimeToString

      public static String dateTimeToString(DateTime date, DateFormat format)
      Converts date to a string in the format described by format.
      Parameters:
      date - a GDateTime
      format - the format to generate the date in
      Returns:
      date as a string or null

    • formDecode

      public static HashTable<String,String> formDecode(String encodedForm)

      Decodes form.

      which is an urlencoded dataset as defined in the HTML 4.01 spec.

      Parameters:
      encodedForm - data of type "application/x-www-form-urlencoded"
      Returns:
      a hash table containing the name/value pairs from encodedForm, which you can free with HashTable#destroy.

    • formDecodeMultipart

      public static @Nullable HashTable<String,String> formDecodeMultipart(Multipart multipart, @Nullable String fileControlName, @Nullable Out<String> filename, @Nullable Out<String> contentType, @Nullable Out<byte[]> file)

      Decodes the "multipart/form-data" request in multipart.

      this is a convenience method for the case when you have a single file upload control in a form. (Or when you don't have any file upload controls, but are still using "multipart/form-data" anyway.) Pass the name of the file upload control in fileControlName, and formDecodeMultipart(Multipart, String, Out, Out, Out) will extract the uploaded file data into filename, contentType, and file. All of the other form control data will be returned (as strings, as with formDecode(String) in the returned GLib.HashTable.

      You may pass null for filename, contentType and/or file if you do not care about those fields. formDecodeMultipart(Multipart, String, Out, Out, Out) may also return null in those fields if the client did not provide that information. You must free the returned filename and content-type with GLib#free, and the returned file data with org.gnome.glib.Bytes.unref.

      If you have a form with more than one file upload control, you will need to decode it manually, using Multipart.fromMessage(MessageHeaders, byte[]) and Multipart.getPart(int, Out, Out).

      Parameters:
      multipart - a SoupMultipart
      fileControlName - the name of the HTML file upload control
      filename - return location for the name of the uploaded file
      contentType - return location for the MIME type of the uploaded file
      file - return location for the uploaded file data
      Returns:
      a hash table containing the name/value pairs (other than fileControlName) from msg, which you can free with HashTable#destroy. On error, it will return null.

    • formEncode

      public static String formEncode(String firstField, Object... varargs)

      Encodes the given field names and values into a value of type "application/x-www-form-urlencoded".

      Encodes as defined in the HTML 4.01 spec.

      This method requires you to know the names of the form fields (or at the very least, the total number of fields) at compile time; for working with dynamic forms, use formEncodeHash(HashTable) or formEncodeDatalist(Data[]).

      See also: Message.fromEncodedForm(String, String, String).

      Parameters:
      firstField - name of the first form field
      varargs - value of firstField, followed by additional field names and values, terminated by null.
      Returns:
      the encoded form

    • formEncodeDatalist

      public static String formEncodeDatalist(Data[] formDataSet)

      Encodes formDataSet into a value of type "application/x-www-form-urlencoded".

      Encodes as defined in the HTML 4.01 spec. Unlike formEncodeHash(HashTable), this preserves the ordering of the form elements, which may be required in some situations.

      See also: Message.fromEncodedForm(String, String, String).

      Parameters:
      formDataSet - a datalist containing name/value pairs
      Returns:
      the encoded form

    • formEncodeHash

      public static String formEncodeHash(HashTable<String,String> formDataSet)

      Encodes formDataSet into a value of type "application/x-www-form-urlencoded".

      Encodes as defined in the HTML 4.01 spec.

      Note that the HTML spec states that "The control names/values are listed in the order they appear in the document." Since this method takes a hash table, it cannot enforce that; if you care about the ordering of the form fields, use formEncodeDatalist(Data[]).

      See also: Message.fromEncodedForm(String, String, String).

      Parameters:
      formDataSet - a hash table containing name/value pairs (as strings)
      Returns:
      the encoded form

    • getMajorVersion

      public static int getMajorVersion()

      Returns the major version number of the libsoup library.

      e.g. in libsoup version 2.42.0 this is 2.

      This function is in the library, so it represents the libsoup library your code is running against. Contrast with the SOUP_MAJOR_VERSION macro, which represents the major version of the libsoup headers you have included when compiling your code.

      Returns:
      the major version number of the libsoup library

    • getMicroVersion

      public static int getMicroVersion()

      Returns the micro version number of the libsoup library.

      e.g. in libsoup version 2.42.0 this is 0.

      This function is in the library, so it represents the libsoup library your code is running against. Contrast with the SOUP_MICRO_VERSION macro, which represents the micro version of the libsoup headers you have included when compiling your code.

      Returns:
      the micro version number of the libsoup library

    • getMinorVersion

      public static int getMinorVersion()

      Returns the minor version number of the libsoup library.

      e.g. in libsoup version 2.42.0 this is 42.

      This function is in the library, so it represents the libsoup library your code is running against. Contrast with the SOUP_MINOR_VERSION macro, which represents the minor version of the libsoup headers you have included when compiling your code.

      Returns:
      the minor version number of the libsoup library

    • headerContains

      public static boolean headerContains(String header, String token)

      Parses header to see if it contains the token token (matched case-insensitively).

      Note that this can't be used with lists that have qvalues.

      Parameters:
      header - An HTTP header suitable for parsing with headerParseList(String)
      token - a token
      Returns:
      whether or not header contains token

    • headerFreeList

      public static void headerFreeList(SList<MemorySegment> list)
      Frees list.
      Parameters:
      list - a GSList returned from headerParseList(String) or headerParseQualityList(String, Out)

    • headerFreeParamList

      public static void headerFreeParamList(HashTable<String,String> paramList)
      Frees paramList.
      Parameters:
      paramList - a GHashTable returned from headerParseParamList(String) or headerParseSemiParamList(String)

    • headerGStringAppendParam

      public static void headerGStringAppendParam(String string, String name, @Nullable String value)

      Appends something like name=value to string, taking care to quote value if needed, and if so, to escape any quotes or backslashes in value.

      Alternatively, if value is a non-ASCII UTF-8 string, it will be appended using RFC5987 syntax. Although in theory this is supposed to work anywhere in HTTP that uses this style of parameter, in reality, it can only be used portably with the Content-Disposition "filename" parameter.

      If value is null, this will just append name to string.

      Parameters:
      string - a GString being used to construct an HTTP header value
      name - a parameter name
      value - a parameter value, or null

    • headerGStringAppendParamQuoted

      public static void headerGStringAppendParamQuoted(String string, String name, String value)

      Appends something like name="value" to string, taking care to escape any quotes or backslashes in value.

      If value is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like headerGStringAppendParam(String, String, String).

      Parameters:
      string - a GString being used to construct an HTTP header value
      name - a parameter name
      value - a parameter value

    • headerParseList

      public static SList<String> headerParseList(String header)

      Parses a header whose content is described by RFC2616 as #something.

      "something" does not itself contain commas, except as part of quoted-strings.

      Parameters:
      header - a header value
      Returns:
      a GSList of list elements, as allocated strings

    • headerParseParamList

      public static HashTable<String,String> headerParseParamList(String header)

      Parses a header which is a comma-delimited list of something like: token [ "=" ( token | quoted-string ) ].

      Tokens that don't have an associated value will still be added to the resulting hash table, but with a null value.

      This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

      Parameters:
      header - a header value
      Returns:
      a GHashTable of list elements, which can be freed with headerFreeParamList(HashTable).

    • headerParseParamListStrict

      public static @Nullable HashTable<String,String> headerParseParamListStrict(String header)

      A strict version of headerParseParamList(String) that bails out if there are duplicate parameters.

      Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use headerParseParamList(String) instead.

      Parameters:
      header - a header value
      Returns:
      a GHashTable of list elements, which can be freed with headerFreeParamList(HashTable) or null if there are duplicate elements.

    • headerParseQualityList

      public static SList<String> headerParseQualityList(String header, @Nullable Out<SList<String>> unacceptable)

      Parses a header whose content is a list of items with optional "qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, Accept-Language, TE).

      If unacceptable is not null, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list.

      Parameters:
      header - a header value
      unacceptable - on return, will contain a list of unacceptable values
      Returns:
      a GSList of acceptable values (as allocated strings), highest-qvalue first.

    • headerParseSemiParamList

      public static HashTable<String,String> headerParseSemiParamList(String header)

      Parses a header which is a semicolon-delimited list of something like: token [ "=" ( token | quoted-string ) ].

      Tokens that don't have an associated value will still be added to the resulting hash table, but with a null value.

      This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

      Parameters:
      header - a header value
      Returns:
      a GHashTable of list elements, which can be freed with headerFreeParamList(HashTable).

    • headerParseSemiParamListStrict

      public static @Nullable HashTable<String,String> headerParseSemiParamListStrict(String header)

      A strict version of headerParseSemiParamList(String) that bails out if there are duplicate parameters.

      Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use headerParseSemiParamList(String) instead.

      Parameters:
      header - a header value
      Returns:
      a GHashTable of list elements, which can be freed with headerFreeParamList(HashTable) or null if there are duplicate elements.

    • headersParse

      public static boolean headersParse(String str, int len, MessageHeaders dest)

      Parses the headers of an HTTP request or response in str and stores the results in dest.

      Beware that dest may be modified even on failure.

      This is a low-level method; normally you would use headersParseRequest(String, int, MessageHeaders, Out, Out, Out) or headersParseResponse(String, int, MessageHeaders, Out, Out, Out).

      Parameters:
      str - the header string (including the Request-Line or Status-Line, but not the trailing blank line)
      len - length of str
      dest - SoupMessageHeaders to store the header values in
      Returns:
      success or failure

    • headersParseRequest

      public static int headersParseRequest(String str, int len, MessageHeaders reqHeaders, @Nullable Out<String> reqMethod, @Nullable Out<String> reqPath, @Nullable Out<HTTPVersion> ver)

      Parses the headers of an HTTP request in str and stores the results in reqMethod, reqPath, ver, and reqHeaders.

      Beware that reqHeaders may be modified even on failure.

      Parameters:
      str - the headers (up to, but not including, the trailing blank line)
      len - length of str
      reqHeaders - SoupMessageHeaders to store the header values in
      reqMethod - if non-null, will be filled in with the request method
      reqPath - if non-null, will be filled in with the request path
      ver - if non-null, will be filled in with the HTTP version
      Returns:
      Status.OK if the headers could be parsed, or an HTTP error to be returned to the client if they could not be.

    • headersParseResponse

      public static boolean headersParseResponse(String str, int len, MessageHeaders headers, @Nullable Out<HTTPVersion> ver, @Nullable Out<Integer> statusCode, @Nullable Out<String> reasonPhrase)

      Parses the headers of an HTTP response in str and stores the results in ver, statusCode, reasonPhrase, and headers.

      Beware that headers may be modified even on failure.

      Parameters:
      str - the headers (up to, but not including, the trailing blank line)
      len - length of str
      headers - SoupMessageHeaders to store the header values in
      ver - if non-null, will be filled in with the HTTP version
      statusCode - if non-null, will be filled in with the status code
      reasonPhrase - if non-null, will be filled in with the reason phrase
      Returns:
      success or failure.

    • headersParseStatusLine

      public static boolean headersParseStatusLine(String statusLine, @Nullable Out<HTTPVersion> ver, @Nullable Out<Integer> statusCode, @Nullable Out<String> reasonPhrase)

      Parses the HTTP Status-Line string in statusLine into ver, statusCode, and reasonPhrase.

      statusLine must be terminated by either "\0" or "\r\n".

      Parameters:
      statusLine - an HTTP Status-Line
      ver - if non-null, will be filled in with the HTTP version
      statusCode - if non-null, will be filled in with the status code
      reasonPhrase - if non-null, will be filled in with the reason phrase
      Returns:
      true if statusLine was parsed successfully.

    • tldDomainIsPublicSuffix

      public static boolean tldDomainIsPublicSuffix(String domain)

      Looks whether the domain passed as argument is a public domain suffix (.org, .com, .co.uk, etc) or not.

      Prior to libsoup 2.46, this function required that domain be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format.

      Parameters:
      domain - a domain name
      Returns:
      true if it is a public domain, false otherwise.

    • tldGetBaseDomain

      public static String tldGetBaseDomain(String hostname) throws GErrorException

      Finds the base domain for a given hostname

      The base domain is composed by the top level domain (such as .org, .com, .co.uk, etc) plus the second level domain, for example for myhost.mydomain.com it will return mydomain.com.

      Note that null will be returned for private URLs (those not ending with any well known TLD) because choosing a base domain for them would be totally arbitrary.

      Prior to libsoup 2.46, this function required that hostname be in UTF-8 if it was an IDN. From 2.46 on, the name can be in either UTF-8 or ASCII format (and the return value will be in the same format).

      Parameters:
      hostname - a hostname
      Returns:
      a pointer to the start of the base domain in hostname. If an error occurs, null will be returned and error set.
      Throws:
      GErrorException - see GError

    • uriCopy

      public static Uri uriCopy(Uri uri, URIComponent firstComponent, Object... varargs)

      As of 3.4.0 this will detect the default ports of HTTP(s) and WS(S) URIs when copying and set it to the default port of the new scheme. So for example copying http://localhost:80 while changing the scheme to https will result in https://localhost:443.

      Return a copy of uri with the given components updated.

      Parameters:
      uri - the GUri to copy
      firstComponent - first SoupURIComponent to update
      varargs - value of firstComponent followed by additional components and values, terminated by URIComponent.NONE
      Returns:
      a new GUri

    • uriDecodeDataUri

      public static byte[] uriDecodeDataUri(String uri, @Nullable Out<String> contentType)
      Decodes the given data URI and returns its contents and contentType.
      Parameters:
      uri - a data URI, in string form
      contentType - location to store content type
      Returns:
      a GBytes with the contents of uri, or null if uri is not a valid data URI

    • uriEqual

      public static boolean uriEqual(Uri uri1, Uri uri2)
      Tests whether or not uri1 and uri2 are equal in all parts.
      Parameters:
      uri1 - a GUri
      uri2 - another GUri
      Returns:
      true if equal otherwise false

    • websocketClientPrepareHandshake

      public static void websocketClientPrepareHandshake(Message msg, @Nullable String origin, @Nullable String @Nullable [] protocols, @Nullable TypeClass @Nullable [] supportedExtensions)

      Adds the necessary headers to msg to request a WebSocket handshake including supported WebSocket extensions.

      The message body and non-WebSocket-related headers are not modified.

      This is a low-level function; if you use Session.websocketConnectAsync(Message, String, String[], int, Cancellable, AsyncReadyCallback) to create a WebSocket connection, it will call this for you.

      Parameters:
      msg - a SoupMessage
      origin - the "Origin" header to set
      protocols - list of protocols to offer
      supportedExtensions - list of supported extension types

    • websocketClientVerifyHandshake

      public static boolean websocketClientVerifyHandshake(Message msg, @Nullable TypeClass @Nullable [] supportedExtensions, @Nullable Out<List<WebsocketExtension>> acceptedExtensions) throws GErrorException

      Looks at the response status code and headers in msg and determines if they contain a valid WebSocket handshake response (given the handshake request in msg's request headers).

      If supportedExtensions is non-null, extensions included in the response "Sec-WebSocket-Extensions" are verified too. Accepted extensions are returned in acceptedExtensions parameter if non-null.

      This is a low-level function; if you use Session.websocketConnectAsync(Message, String, String[], int, Cancellable, AsyncReadyCallback) to create a WebSocket connection, it will call this for you.

      Parameters:
      msg - SoupMessage containing both client and server sides of a WebSocket handshake
      supportedExtensions - list of supported extension types
      acceptedExtensions - a GList of WebsocketExtension objects
      Returns:
      true if msg contains a completed valid WebSocket handshake, false and an error if not.
      Throws:
      GErrorException - see GError

    • websocketServerCheckHandshake

      public static boolean websocketServerCheckHandshake(ServerMessage msg, @Nullable String origin, @Nullable String @Nullable [] protocols, @Nullable TypeClass @Nullable [] supportedExtensions) throws GErrorException

      Examines the method and request headers in msg and determines whether msg contains a valid handshake request.

      If origin is non-null, then only requests containing a matching "Origin" header will be accepted. If protocols is non-null, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If supportedExtensions is non-null, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted.

      Normally websocketServerProcessHandshake(ServerMessage, String, String[], TypeClass[], Out) will take care of this for you, and if you use Server.addWebsocketHandler(String, String, String[], ServerWebsocketCallback) to handle accepting WebSocket connections, it will call that for you. However, this function may be useful if you need to perform more complicated validation; eg, accepting multiple different Origins, or handling different protocols depending on the path.

      Parameters:
      msg - SoupServerMessage containing the client side of a WebSocket handshake
      origin - expected Origin header
      protocols - allowed WebSocket protocols.
      supportedExtensions - list of supported extension types
      Returns:
      true if msg contained a valid WebSocket handshake, false and an error if not.
      Throws:
      GErrorException - see GError

    • websocketServerProcessHandshake

      public static boolean websocketServerProcessHandshake(ServerMessage msg, @Nullable String expectedOrigin, @Nullable String @Nullable [] protocols, @Nullable TypeClass @Nullable [] supportedExtensions, @Nullable Out<List<WebsocketExtension>> acceptedExtensions)

      Examines the method and request headers in msg and (assuming msg contains a valid handshake request), fills in the handshake response.

      If expectedOrigin is non-null, then only requests containing a matching "Origin" header will be accepted. If protocols is non-null, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If supportedExtensions is non-null, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted. The accepted extensions will be returned in acceptedExtensions parameter if non-null.

      This is a low-level function; if you use Server.addWebsocketHandler(String, String, String[], ServerWebsocketCallback) to handle accepting WebSocket connections, it will call this for you.

      Parameters:
      msg - SoupServerMessage containing the client side of a WebSocket handshake
      expectedOrigin - expected Origin header
      protocols - allowed WebSocket protocols.
      supportedExtensions - list of supported extension types
      acceptedExtensions - a GList of WebsocketExtension objects
      Returns:
      true if msg contained a valid WebSocket handshake request and was updated to contain a handshake response. false if not.