Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (inaki@blueleaf.cc)
Safe Haskell	None
Language	Haskell2010

GI.Soup.Functions

Contents

Methods

Description

Synopsis

checkVersion :: (HasCallStack, MonadIO m) => Word32 -> Word32 -> Word32 -> m Bool
cookiesFromRequest :: (HasCallStack, MonadIO m, IsMessage a) => a -> m [Cookie]
cookiesFromResponse :: (HasCallStack, MonadIO m, IsMessage a) => a -> m [Cookie]
cookiesToCookieHeader :: (HasCallStack, MonadIO m) => [Cookie] -> m Text
cookiesToRequest :: (HasCallStack, MonadIO m, IsMessage a) => [Cookie] -> a -> m ()
cookiesToResponse :: (HasCallStack, MonadIO m, IsMessage a) => [Cookie] -> a -> m ()
formEncodeDatalist :: (HasCallStack, MonadIO m) => Data -> m Text
formEncodeHash :: (HasCallStack, MonadIO m) => Map Text Text -> m Text
formRequestNewFromDatalist :: (HasCallStack, MonadIO m) => Text -> Text -> Data -> m Message
formRequestNewFromHash :: (HasCallStack, MonadIO m) => Text -> Text -> Map Text Text -> m Message
formRequestNewFromMultipart :: (HasCallStack, MonadIO m) => Text -> Multipart -> m Message
getMajorVersion :: (HasCallStack, MonadIO m) => m Word32
getMicroVersion :: (HasCallStack, MonadIO m) => m Word32
getMinorVersion :: (HasCallStack, MonadIO m) => m Word32
headerContains :: (HasCallStack, MonadIO m) => Text -> Text -> m Bool
headerFreeParamList :: (HasCallStack, MonadIO m) => Map Text Text -> m ()
headerGStringAppendParam :: (HasCallStack, MonadIO m) => String -> Text -> Text -> m ()
headerGStringAppendParamQuoted :: (HasCallStack, MonadIO m) => String -> Text -> Text -> m ()
headerParseList :: (HasCallStack, MonadIO m) => Text -> m [Text]
headerParseParamList :: (HasCallStack, MonadIO m) => Text -> m (Map Text Text)
headerParseParamListStrict :: (HasCallStack, MonadIO m) => Text -> m (Maybe (Map Text Text))
headerParseQualityList :: (HasCallStack, MonadIO m) => Text -> m ([Text], [Text])
headerParseSemiParamList :: (HasCallStack, MonadIO m) => Text -> m (Map Text Text)
headerParseSemiParamListStrict :: (HasCallStack, MonadIO m) => Text -> m (Maybe (Map Text Text))
headersParse :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m Bool
headersParseRequest :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m (Word32, Text, Text, HTTPVersion)
headersParseResponse :: (HasCallStack, MonadIO m) => Text -> Int32 -> MessageHeaders -> m (Bool, HTTPVersion, Word32, Text)
headersParseStatusLine :: (HasCallStack, MonadIO m) => Text -> m (Bool, HTTPVersion, Word32, Text)
httpErrorQuark :: (HasCallStack, MonadIO m) => m Word32
strCaseEqual :: (HasCallStack, MonadIO m) => Ptr () -> Ptr () -> m Bool
strCaseHash :: (HasCallStack, MonadIO m) => Ptr () -> m Word32
tldDomainIsPublicSuffix :: (HasCallStack, MonadIO m) => Text -> m Bool
tldGetBaseDomain :: (HasCallStack, MonadIO m) => Text -> m Text
valueArrayNew :: (HasCallStack, MonadIO m) => m ValueArray
websocketClientPrepareHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> Maybe Text -> Maybe [Text] -> m ()
websocketClientVerifyHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> m ()
websocketServerCheckHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> Maybe Text -> Maybe [Text] -> m ()
websocketServerProcessHandshake :: (HasCallStack, MonadIO m, IsMessage a) => a -> Maybe Text -> Maybe [Text] -> m Bool
xmlrpcBuildMethodCall :: (HasCallStack, MonadIO m) => Text -> [GValue] -> m (Maybe Text)
xmlrpcBuildMethodResponse :: (HasCallStack, MonadIO m) => GValue -> m (Maybe Text)
xmlrpcBuildRequest :: (HasCallStack, MonadIO m) => Text -> GVariant -> m Text
xmlrpcBuildResponse :: (HasCallStack, MonadIO m) => GVariant -> m Text
xmlrpcMessageNew :: (HasCallStack, MonadIO m) => Text -> Text -> GVariant -> m Message
xmlrpcMessageSetResponse :: (HasCallStack, MonadIO m, IsMessage a) => a -> GVariant -> m ()
xmlrpcParseMethodCall :: (HasCallStack, MonadIO m) => Text -> Int32 -> m (Bool, Text, ValueArray)
xmlrpcParseMethodResponse :: (HasCallStack, MonadIO m) => Text -> Int32 -> m GValue
xmlrpcParseRequest :: (HasCallStack, MonadIO m) => Text -> Int32 -> m (Text, XMLRPCParams)
xmlrpcParseResponse :: (HasCallStack, MonadIO m) => Text -> Int32 -> Maybe Text -> m GVariant
xmlrpcVariantGetDatetime :: (HasCallStack, MonadIO m) => GVariant -> m Date
xmlrpcVariantNewDatetime :: (HasCallStack, MonadIO m) => Date -> m GVariant

Methods

checkVersion

checkVersion Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Word32	`major`: the major version to check
-> Word32	`minor`: the minor version to check
-> Word32	`micro`: the micro version to check
-> m Bool	Returns: `True` if the version of the libsoup currently loaded is the same as or newer than the passed-in version.

Like SOUP_CHECK_VERSION, 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.

Since: 2.42

cookiesFromRequest

cookiesFromRequest Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: a `Message` containing a "Cookie" request header
-> m [Cookie]	Returns: a `SList` of `Cookie`<!-- -->s, which can be freed with `soup_cookies_free()`.

Parses msg's Cookie request header and returns a SList of Cookies. 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.)

Since: 2.24

cookiesFromResponse

cookiesFromResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: a `Message` containing a "Set-Cookie" response header
-> m [Cookie]	Returns: a `SList` of `Cookie`<!-- -->s, which can be freed with `soup_cookies_free()`.

Parses msg's Set-Cookie response headers and returns a SList of Cookies. Cookies that do not specify "path" or "domain" attributes will have their values defaulted from msg.

Since: 2.24

cookiesToCookieHeader

cookiesToCookieHeader Source #

Arguments

:: (HasCallStack, MonadIO m)
=> [Cookie]	`cookies`: a `SList` of `Cookie`
-> m Text	Returns: the serialization of `cookies`

Serializes a SList of Cookie into a string suitable for setting as the value of the "Cookie" header.

Since: 2.24

cookiesToRequest

cookiesToRequest Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> [Cookie]	`cookies`: a `SList` of `Cookie`
-> a	`msg`: a `Message`
-> m ()

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

Since: 2.24

cookiesToResponse

cookiesToResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> [Cookie]	`cookies`: a `SList` of `Cookie`
-> a	`msg`: a `Message`
-> m ()

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

Since: 2.24

formEncodeDatalist

formEncodeDatalist Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Data	`formDataSet`: a datalist containing name/value pairs
-> m Text	Returns: the encoded form

Encodes formDataSet into a value of type "application/x-www-form-urlencoded", as defined in the HTML 4.01 spec. Unlike formEncodeHash, this preserves the ordering of the form elements, which may be required in some situations.

formEncodeHash

formEncodeHash Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Map Text Text	`formDataSet`: a hash table containing name/value pairs (as strings)
-> m Text	Returns: the encoded form

Encodes formDataSet into a value of type "application/x-www-form-urlencoded", 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.

formRequestNewFromDatalist

formRequestNewFromDatalist Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`method`: the HTTP method, either "GET" or "POST"
-> Text	`uri`: the URI to send the form data to
-> Data	`formDataSet`: the data to send to `uri`
-> m Message	Returns: the new `SoupMessage`

Creates a new SoupMessage and sets it up to send formDataSet to uri via method, as with soup_form_request_new().

formRequestNewFromHash

formRequestNewFromHash Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`method`: the HTTP method, either "GET" or "POST"
-> Text	`uri`: the URI to send the form data to
-> Map Text Text	`formDataSet`: the data to send to `uri`
-> m Message	Returns: the new `SoupMessage`

Creates a new SoupMessage and sets it up to send formDataSet to uri via method, as with soup_form_request_new().

formRequestNewFromMultipart

formRequestNewFromMultipart Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`uri`: the URI to send the form data to
-> Multipart	`multipart`: a "multipart/form-data" `Multipart`
-> m Message	Returns: the new `SoupMessage`

Creates a new SoupMessage and sets it up to send multipart to uri via POST.

To send a <literal>"multipart/form-data"</literal> POST, first create a Multipart, using FORM_MIME_TYPE_MULTIPART as the MIME type. Then use multipartAppendFormString and multipartAppendFormFile to add the value of each form control to the multipart. (These are just convenience methods, and you can use multipartAppendPart if you need greater control over the part headers.) Finally, call formRequestNewFromMultipart to serialize the multipart structure and create a Message.

Since: 2.26

getMajorVersion

getMajorVersion Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Word32	Returns: the major version number of the libsoup library

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 MAJOR_VERSION macro, which represents the major version of the libsoup headers you have included when compiling your code.

Since: 2.42

getMicroVersion

getMicroVersion Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Word32	Returns: the micro version number of the libsoup library

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 MICRO_VERSION macro, which represents the micro version of the libsoup headers you have included when compiling your code.

Since: 2.42

getMinorVersion

getMinorVersion Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Word32	Returns: the minor version number of the libsoup library

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 MINOR_VERSION macro, which represents the minor version of the libsoup headers you have included when compiling your code.

Since: 2.42

headerContains

headerContains Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: An HTTP header suitable for parsing with `headerParseList`
-> Text	`token`: a token
-> m Bool	Returns: whether or not `header` contains `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.

headerFreeParamList

headerFreeParamList Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Map Text Text	`paramList`: a `HashTable` returned from `headerParseParamList` or `headerParseSemiParamList`
-> m ()

Frees paramList.

headerGStringAppendParam

headerGStringAppendParam Source #

Arguments

:: (HasCallStack, MonadIO m)
=> String	`string`: a `String` being used to construct an HTTP header value
-> Text	`name`: a parameter name
-> Text	`value`: a parameter value, or `Nothing`
-> m ()

Appends something like <literal>name=value</literal> 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 Nothing, this will just append name to string.

Since: 2.26

headerGStringAppendParamQuoted

headerGStringAppendParamQuoted Source #

Arguments

:: (HasCallStack, MonadIO m)
=> String	`string`: a `String` being used to construct an HTTP header value
-> Text	`name`: a parameter name
-> Text	`value`: a parameter value
-> m ()

Appends something like <literal>name="value"</literal> 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.

Since: 2.30

headerParseList

headerParseList Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m [Text]	Returns: a `SList` of list elements, as allocated strings

Parses a header whose content is described by RFC2616 as "something", where "something" does not itself contain commas, except as part of quoted-strings.

headerParseParamList

headerParseParamList Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m (Map Text Text)	Returns: a `HashTable` of list elements, which can be freed with `headerFreeParamList`.

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

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

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

headerParseParamListStrict

headerParseParamListStrict Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m (Maybe (Map Text Text))	Returns: a `HashTable` of list elements, which can be freed with `headerFreeParamList` or `Nothing` if there are duplicate elements.

A strict version of headerParseParamList 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 instead.

Since: 2.66

headerParseQualityList

headerParseQualityList Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m ([Text], [Text])	Returns: a `SList` of acceptable values (as allocated strings), highest-qvalue first.

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 Nothing, then on return, it will contain the items with qvalue 0. Either way, those items will be removed from the main list.

headerParseSemiParamList

headerParseSemiParamList Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m (Map Text Text)	Returns: a `HashTable` of list elements, which can be freed with `headerFreeParamList`.

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

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

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

Since: 2.24

headerParseSemiParamListStrict

headerParseSemiParamListStrict Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`header`: a header value
-> m (Maybe (Map Text Text))	Returns: a `HashTable` of list elements, which can be freed with `headerFreeParamList` or `Nothing` if there are duplicate elements.

A strict version of headerParseSemiParamList 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 instead.

Since: 2.66

headersParse

headersParse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`str`: the header string (including the Request-Line or Status-Line, but not the trailing blank line)
-> Int32	`len`: length of `str`
-> MessageHeaders	`dest`: `MessageHeaders` to store the header values in
-> m Bool	Returns: success or failure

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 or headersParseResponse.

Since: 2.26

headersParseRequest

headersParseRequest Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`str`: the headers (up to, but not including, the trailing blank line)
-> Int32	`len`: length of `str`
-> MessageHeaders	`reqHeaders`: `MessageHeaders` to store the header values in
-> m (Word32, Text, Text, HTTPVersion)	Returns: `StatusOk` if the headers could be parsed, or an HTTP error to be returned to the client if they could not be.

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.

headersParseResponse

headersParseResponse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`str`: the headers (up to, but not including, the trailing blank line)
-> Int32	`len`: length of `str`
-> MessageHeaders	`headers`: `MessageHeaders` to store the header values in
-> m (Bool, HTTPVersion, Word32, Text)	Returns: success or failure.

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.

headersParseStatusLine

headersParseStatusLine Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`statusLine`: an HTTP Status-Line
-> m (Bool, HTTPVersion, Word32, Text)	Returns: `True` if `statusLine` was parsed successfully.

Parses the HTTP Status-Line string in statusLine into ver, statusCode, and reasonPhrase. statusLine must be terminated by either "\0" or "\r\n".

httpErrorQuark

httpErrorQuark :: (HasCallStack, MonadIO m) => m Word32 Source #

No description available in the introspection data.

strCaseEqual

strCaseEqual Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Ptr ()	`v1`: an ASCII string
-> Ptr ()	`v2`: another ASCII string
-> m Bool	Returns: `True` if they are equal (modulo case)

Compares v1 and v2 in a case-insensitive manner

strCaseHash

strCaseHash Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Ptr ()	`key`: ASCII string to hash
-> m Word32	Returns: the hash code.

Hashes key in a case-insensitive manner.

tldDomainIsPublicSuffix

tldDomainIsPublicSuffix Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`domain`: a domain name
-> m Bool	Returns: `True` if it is a public domain, `False` otherwise.

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.

Since: 2.40

tldGetBaseDomain

tldGetBaseDomain Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`hostname`: a hostname
-> m Text	Returns: a pointer to the start of the base domain in `hostname`. If an error occurs, `Nothing` will be returned and `error` set. (Can throw `GError`)

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

Since: 2.40

valueArrayNew

valueArrayNew Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m ValueArray	Returns: a new `GValueArray`

Deprecated: Use GVariant API instead.

Creates a new GValueArray. (This is just a wrapper around valueArrayNew, for naming consistency purposes.)

websocketClientPrepareHandshake

websocketClientPrepareHandshake Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: a `Message`
-> Maybe Text	`origin`: the "Origin" header to set
-> Maybe [Text]	`protocols`: list of protocols to offer
-> m ()

Adds the necessary headers to msg to request a WebSocket handshake. The message body and non-WebSocket-related headers are not modified.

This is a low-level function; if you use sessionWebsocketConnectAsync to create a WebSocket connection, it will call this for you.

Since: 2.50

websocketClientVerifyHandshake

websocketClientVerifyHandshake Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: `Message` containing both client and server sides of a WebSocket handshake
-> m ()	(Can throw `GError`)

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

This is a low-level function; if you use sessionWebsocketConnectAsync to create a WebSocket connection, it will call this for you.

Since: 2.50

websocketServerCheckHandshake

websocketServerCheckHandshake Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: `Message` containing the client side of a WebSocket handshake
-> Maybe Text	`origin`: expected Origin header
-> Maybe [Text]	`protocols`: allowed WebSocket protocols.
-> m ()	(Can throw `GError`)

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

If origin is non-Nothing, then only requests containing a matching "Origin" header will be accepted. If protocols is non-Nothing, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted.

Normally websocketServerProcessHandshake will take care of this for you, and if you use serverAddWebsocketHandler 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.

Since: 2.50

websocketServerProcessHandshake

websocketServerProcessHandshake Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: `Message` containing the client side of a WebSocket handshake
-> Maybe Text	`expectedOrigin`: expected Origin header
-> Maybe [Text]	`protocols`: allowed WebSocket protocols.
-> m Bool	Returns: `True` if `msg` contained a valid WebSocket handshake request and was updated to contain a handshake response. `False` if not.

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-Nothing, then only requests containing a matching "Origin" header will be accepted. If protocols is non-Nothing, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted.

This is a low-level function; if you use serverAddWebsocketHandler to handle accepting WebSocket connections, it will call this for you.

Since: 2.50

xmlrpcBuildMethodCall

xmlrpcBuildMethodCall Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodName`: the name of the XML-RPC method
-> [GValue]	`params`: arguments to `method`
-> m (Maybe Text)	Returns: the text of the methodCall, or `Nothing` on error

Deprecated: Use xmlrpcBuildRequest instead.

This creates an XML-RPC methodCall and returns it as a string. This is the low-level method that soup_xmlrpc_request_new() is built on.

params is an array of Value representing the parameters to method. (It is *not* a ValueArray, although if you have a ValueArray, you can just pass its <literal>values</literal>f and <literal>n_values</literal> fields.)

The correspondence between glib types and XML-RPC types is:

int: int (G_TYPE_INT) boolean: Bool (G_TYPE_BOOLEAN) string: char* (G_TYPE_STRING) double: double (G_TYPE_DOUBLE) datetime.iso8601: Date (SOUP_TYPE_DATE) base64: ByteArray (SOUP_TYPE_BYTE_ARRAY) struct: HashTable (G_TYPE_HASH_TABLE) array: ValueArray (G_TYPE_VALUE_ARRAY)

For structs, use a HashTable that maps strings to Value; valueHashNew and related methods can help with this.

xmlrpcBuildMethodResponse

xmlrpcBuildMethodResponse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> GValue	`value`: the return value
-> m (Maybe Text)	Returns: the text of the methodResponse, or `Nothing` on error

Deprecated: Use xmlrpcBuildResponse instead.

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use soup_xmlrpc_build_fault().

The glib type to XML-RPC type mapping is as with xmlrpcBuildMethodCall, qv.

xmlrpcBuildRequest

xmlrpcBuildRequest Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodName`: the name of the XML-RPC method
-> GVariant	`params`: a `GVariant` tuple
-> m Text	Returns: the text of the methodCall, or `Nothing` on error. (Can throw `GError`)

This creates an XML-RPC methodCall and returns it as a string. This is the low-level method that xmlrpcMessageNew is built on.

params is a GVariant tuple representing the method parameters.

Serialization details: - "a{s*}" and "{s*}" are serialized as <struct> - "ay" is serialized as <base64> - Other arrays and tuples are serialized as <array> - booleans are serialized as <boolean> - byte, int16, uint16 and int32 are serialized as <int> - uint32 and int64 are serialized as the nonstandard <i8> type - doubles are serialized as <double> - Strings are serialized as <string> - Variants (i.e. "v" type) are unwrapped and their child is serialized. - GVariants created by xmlrpcVariantNewDatetime are serialized as <dateTime.iso8601> - Other types are not supported and will return Nothing and set error. This notably includes: object-paths, signatures, uint64, handles, maybes and dictionaries with non-string keys.

If params is floating, it is consumed.

Since: 2.52

xmlrpcBuildResponse

xmlrpcBuildResponse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> GVariant	`value`: the return value
-> m Text	Returns: the text of the methodResponse, or `Nothing` on error. (Can throw `GError`)

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use soup_xmlrpc_build_fault(). This is the low-level method that xmlrpcMessageSetResponse is built on.

See xmlrpcBuildRequest for serialization details, but note that since a method can only have a single return value, value should not be a tuple here (unless the return value is an array).

If value is floating, it is consumed.

Since: 2.52

xmlrpcMessageNew

xmlrpcMessageNew Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`uri`: URI of the XML-RPC service
-> Text	`methodName`: the name of the XML-RPC method to invoke at `uri`
-> GVariant	`params`: a `GVariant` tuple
-> m Message	Returns: a `Message` encoding the indicated XML-RPC request, or `Nothing` on error. (Can throw `GError`)

Creates an XML-RPC methodCall and returns a Message, ready to send, for that method call.

See xmlrpcBuildRequest for serialization details.

If params is floating, it is consumed.

Since: 2.52

xmlrpcMessageSetResponse

xmlrpcMessageSetResponse Source #

Arguments

:: (HasCallStack, MonadIO m, IsMessage a)
=> a	`msg`: an XML-RPC request
-> GVariant	`value`: a `GVariant`
-> m ()	(Can throw `GError`)

Sets the status code and response body of msg to indicate a successful XML-RPC call, with a return value given by value. To set a fault response, use soup_xmlrpc_message_set_fault().

See xmlrpcBuildRequest for serialization details.

If value is floating, it is consumed.

Since: 2.52

xmlrpcParseMethodCall

xmlrpcParseMethodCall Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodCall`: the XML-RPC methodCall string
-> Int32	`length`: the length of `methodCall`, or -1 if it is NUL-terminated
-> m (Bool, Text, ValueArray)	Returns: success or failure.

Deprecated: Use soup_xmlrpc_parse_request_full() instead.

Parses methodCall to get the name and parameters, and returns the parameter values in a ValueArray; see also soup_xmlrpc_extract_method_call(), which is more convenient if you know in advance what the types of the parameters will be.

xmlrpcParseMethodResponse

xmlrpcParseMethodResponse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodResponse`: the XML-RPC methodResponse string
-> Int32	`length`: the length of `methodResponse`, or -1 if it is NUL-terminated
-> m GValue	(Can throw `GError`)

Deprecated: Use xmlrpcParseResponse instead.

Parses methodResponse and returns the return value in value. If methodResponse is a fault, value will be unchanged, and error will be set to an error of type SOUP_XMLRPC_FAULT, with the error code containing the fault code, and the error message containing the fault string. (If methodResponse cannot be parsed at all, xmlrpcParseMethodResponse will return False, but error will be unset.)

xmlrpcParseRequest

xmlrpcParseRequest Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodCall`: the XML-RPC methodCall string
-> Int32	`length`: the length of `methodCall`, or -1 if it is NUL-terminated
-> m (Text, XMLRPCParams)	Returns: method's name, or `Nothing` on error. (Can throw `GError`)

Parses methodCall and return the method name. Method parameters can be parsed later using xMLRPCParamsParse.

Since: 2.52

xmlrpcParseResponse

xmlrpcParseResponse Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`methodResponse`: the XML-RPC methodResponse string
-> Int32	`length`: the length of `methodResponse`, or -1 if it is NUL-terminated
-> Maybe Text	`signature`: A valid `GVariant` type string, or `Nothing`
-> m GVariant	Returns: a new (non-floating) `GVariant`, or `Nothing` (Can throw `GError`)

Parses methodResponse and returns the return value. If methodResponse is a fault, Nothing is returned, and error will be set to an error in the SOUP_XMLRPC_FAULT domain, with the error code containing the fault code, and the error message containing the fault string. If methodResponse cannot be parsed, Nothing is returned, and error will be set to an error in the SOUP_XMLRPC_ERROR domain.

See xMLRPCParamsParse for deserialization details.

Since: 2.52

xmlrpcVariantGetDatetime

xmlrpcVariantGetDatetime Source #

Arguments

:: (HasCallStack, MonadIO m)
=> GVariant	`variant`: a `GVariant`
-> m Date	Returns: a new `Date`, or `Nothing` on error. (Can throw `GError`)

Get the Date from special GVariant created by xmlrpcVariantNewDatetime or by parsing a <dateTime.iso8601> node. See xMLRPCParamsParse.

If variant does not contain a datetime it will return an error but it is not considered a programmer error because it generally means parameters received are not in the expected type.

Since: 2.52

xmlrpcVariantNewDatetime

xmlrpcVariantNewDatetime Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Date	`date`: a `Date`
-> m GVariant	Returns: a floating `GVariant`.

Construct a special GVariant used to serialize a <dateTime.iso8601> node. See xmlrpcBuildRequest.

The actual type of the returned GVariant is unspecified and "v" or "*" should be used in variant format strings. For example: <informalexample><programlisting> args = g_variant_new ("(v)", soup_xmlrpc_variant_new_datetime (date)); </programlisting></informalexample>

Since: 2.52