GI.Soup.Structs.URI

A URI represents a (parsed) URI. URI supports RFC 3986 (URI Generic Syntax), and can parse any valid URI. However, libsoup only uses "http" and "https" URIs internally; You can use SOUP_URI_VALID_FOR_HTTP() to test if a URI is a valid HTTP URI.

scheme will always be set in any URI. It is an interned string and is always all lowercase. (If you parse a URI with a non-lowercase scheme, it will be converted to lowercase.) The macros SOUP_URI_SCHEME_HTTP and SOUP_URI_SCHEME_HTTPS provide the interned values for "http" and "https" and can be compared against URI scheme values.

user and password are parsed as defined in the older URI specs (ie, separated by a colon; RFC 3986 only talks about a single "userinfo" field). Note that password is not included in the output of uRIToString. libsoup does not normally use these fields; authentication is handled via Session signals.

host contains the hostname, and port the port specified in the URI. If the URI doesn't contain a hostname, host will be Nothing, and if it doesn't specify a port, port may be 0. However, for "http" and "https" URIs, host is guaranteed to be non-Nothing (trying to parse an http URI with no host will return Nothing), and port will always be non-0 (because libsoup knows the default value to use when it is not specified in the URI).

path is always non-Nothing. For http/https URIs, path will never be an empty string either; if the input URI has no path, the parsed URI will have a path of "/".

query and fragment are optional for all URI types. formDecode may be useful for parsing query.

Note that path, query, and fragment may contain %<!-- -->-encoded characters. uRINew calls uriNormalize on them, but not uriDecode. This is necessary to ensure that uRIToString will generate a URI that has exactly the same meaning as the original. (In theory, URI should leave user, password, and host partially-encoded as well, but this would be more annoying than useful.)

Exported types

newtype URI

Memory-managed wrapper type.

Constructors

URI (ManagedPtr URI)

Instances

Eq URI

Defined in GI.Soup.Structs.URI

Methods

(==) :: URI -> URI -> Bool

(/=) :: URI -> URI -> Bool

GBoxed URI

Defined in GI.Soup.Structs.URI

ManagedPtrNewtype URI

Defined in GI.Soup.Structs.URI

Methods

toManagedPtr :: URI -> ManagedPtr URI

TypedObject URI

Defined in GI.Soup.Structs.URI

Methods

glibType :: IO GType

HasParentTypes URI

Defined in GI.Soup.Structs.URI

tag ~ 'AttrSet => Constructible URI tag

Defined in GI.Soup.Structs.URI

Methods

new :: MonadIO m => (ManagedPtr URI -> URI) -> [AttrOp URI tag] -> m URI

IsGValue (Maybe URI)

Convert URI to and from GValue. See toGValue and fromGValue.

Defined in GI.Soup.Structs.URI

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe URI -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe URI)

type ParentTypes URI

Defined in GI.Soup.Structs.URI

type ParentTypes URI = '[] :: [Type]

newZeroURI :: MonadIO m => m URI

Construct a URI struct initialized to zero.

Methods

Click to display all available methods, including inherited ones

Methods

copy, copyHost, equal, free, hostEqual, hostHash, toString, usesDefaultPort.

Getters

getFragment, getHost, getPassword, getPath, getPort, getQuery, getScheme, getUser.

Setters

setFragment, setHost, setPassword, setPath, setPort, setQuery, setQueryFromForm, setScheme, setUser.

copy

uRICopy

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m URI

Returns: a copy of uri, which must be freed with uRIFree

Copies uri

copyHost

uRICopyHost

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m URI

Returns: the new URI

Makes a copy of uri, considering only the protocol, host, and port

Since: 2.28

decode

uRIDecode

Arguments

:: (HasCallStack, MonadIO m)

=> Text

part: a URI part

-> m Text

Returns: the decoded URI part.

Fully %<!-- -->-decodes part.

In the past, this would return Nothing if part contained invalid percent-encoding, but now it just ignores the problem (as uRINew already did).

encode

uRIEncode

Arguments

:: (HasCallStack, MonadIO m)

=> Text

part: a URI part

-> Maybe Text

escapeExtra: additional reserved characters to escape (or Nothing)

-> m Text

Returns: the encoded URI part

This %<!-- -->-encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.

equal

uRIEqual

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri1: a URI

-> URI

uri2: another URI

-> m Bool

Returns: True or False

Tests whether or not uri1 and uri2 are equal in all parts

free

uRIFree

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m ()

Frees uri.

getFragment

uRIGetFragment

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's fragment.

Gets uri's fragment.

Since: 2.32

getHost

uRIGetHost

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's host.

Gets uri's host.

Since: 2.32

getPassword

uRIGetPassword

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's password.

Gets uri's password.

Since: 2.32

getPath

uRIGetPath

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's path.

Gets uri's path.

Since: 2.32

getPort

uRIGetPort

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Word32

Returns: uri's port.

Gets uri's port.

Since: 2.32

getQuery

uRIGetQuery

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's query.

Gets uri's query.

Since: 2.32

getScheme

uRIGetScheme

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's scheme.

Gets uri's scheme.

Since: 2.32

getUser

uRIGetUser

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Text

Returns: uri's user.

Gets uri's user.

Since: 2.32

hostEqual

uRIHostEqual

Arguments

:: (HasCallStack, MonadIO m)

=> URI

v1: a URI with a non-Nothing host member

-> URI

v2: a URI with a non-Nothing host member

-> m Bool

Returns: whether or not the URIs are equal in scheme, host, and port.

Compares v1 and v2, considering only the scheme, host, and port.

Since: 2.28

hostHash

uRIHostHash

Arguments

:: (HasCallStack, MonadIO m)

=> URI

key: a URI with a non-Nothing host member

-> m Word32

Returns: a hash

Hashes key, considering only the scheme, host, and port.

Since: 2.28

new

uRINew

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

uriString: a URI

-> m (Maybe URI)

Returns: a URI, or Nothing if the given string was found to be invalid.

Parses an absolute URI.

You can also pass Nothing for uriString if you want to get back an "empty" URI that you can fill in by hand. (You will need to call at least uRISetScheme and uRISetPath, since those fields are required.)

newWithBase

uRINewWithBase

Arguments

:: (HasCallStack, MonadIO m)

=> URI

base: a base URI

-> Text

uriString: the URI

-> m URI

Returns: a parsed URI.

Parses uriString relative to base.

normalize

uRINormalize

Arguments

:: (HasCallStack, MonadIO m)

=> Text

part: a URI part

-> Maybe Text

unescapeExtra: reserved characters to unescape (or Nothing)

-> m Text

Returns: the normalized URI part

%<!-- -->-decodes any "unreserved" characters (or characters in unescapeExtra) in part, and %<!-- -->-encodes any non-ASCII characters, spaces, and non-printing characters in part.

"Unreserved" characters are those that are not allowed to be used for punctuation according to the URI spec. For example, letters are unreserved, so uriNormalize will turn <literal>http://example.com/foo/b%<!-- -->61r</literal> into <literal>http://example.com/foo/bar</literal>, which is guaranteed to mean the same thing. However, "/" is "reserved", so <literal>http://example.com/foo%<!-- -->2Fbar</literal> would not be changed, because it might mean something different to the server.

In the past, this would return Nothing if part contained invalid percent-encoding, but now it just ignores the problem (as uRINew already did).

setFragment

uRISetFragment

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Maybe Text

fragment: the fragment

-> m ()

Sets uri's fragment to fragment.

setHost

uRISetHost

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Maybe Text

host: the hostname or IP address, or Nothing

-> m ()

Sets uri's host to host.

If host is an IPv6 IP address, it should not include the brackets required by the URI syntax; they will be added automatically when converting uri to a string.

http and https URIs should not have a Nothing host.

setPassword

uRISetPassword

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Maybe Text

password: the password, or Nothing

-> m ()

Sets uri's password to password.

setPath

uRISetPath

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Text

path: the non-Nothing path

-> m ()

Sets uri's path to path.

setPort

uRISetPort

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Word32

port: the port, or 0

-> m ()

Sets uri's port to port. If port is 0, uri will not have an explicitly-specified port.

setQuery

uRISetQuery

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Maybe Text

query: the query

-> m ()

Sets uri's query to query.

setQueryFromForm

uRISetQueryFromForm

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Map Text Text

form: a HashTable containing HTML form information

-> m ()

Sets uri's query to the result of encoding form according to the HTML form rules. See formEncodeHash for more information.

setScheme

uRISetScheme

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Text

scheme: the URI scheme

-> m ()

Sets uri's scheme to scheme. This will also set uri's port to the default port for scheme, if known.

setUser

uRISetUser

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Maybe Text

user: the username, or Nothing

-> m ()

Sets uri's user to user.

toString

uRIToString

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> Bool

justPathAndQuery: if True, output just the path and query portions

-> m Text

Returns: a string representing uri, which the caller must free.

Returns a string representing uri.

If justPathAndQuery is True, this concatenates the path and query together. That is, it constructs the string that would be needed in the Request-Line of an HTTP request for uri.

Note that the output will never contain a password, even if uri does.

usesDefaultPort

uRIUsesDefaultPort

Arguments

:: (HasCallStack, MonadIO m)

=> URI

uri: a URI

-> m Bool

Returns: True or False

Tests if uri uses the default port for its scheme. (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not know the default ports of other protocols.)

Properties

fragment

a fragment identifier within path, or Nothing

clearURIFragment :: MonadIO m => URI -> m ()

Set the value of the “fragment” field to Nothing. When overloading is enabled, this is equivalent to

clear #fragment

getURIFragment :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “fragment” field. When overloading is enabled, this is equivalent to

get uRI #fragment

setURIFragment :: MonadIO m => URI -> CString -> m ()

Set the value of the “fragment” field. When overloading is enabled, this is equivalent to

set uRI [ #fragment := value ]

host

the hostname or IP address, or Nothing

clearURIHost :: MonadIO m => URI -> m ()

Set the value of the “host” field to Nothing. When overloading is enabled, this is equivalent to

clear #host

getURIHost :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “host” field. When overloading is enabled, this is equivalent to

get uRI #host

setURIHost :: MonadIO m => URI -> CString -> m ()

Set the value of the “host” field. When overloading is enabled, this is equivalent to

set uRI [ #host := value ]

password

a password, or Nothing

clearURIPassword :: MonadIO m => URI -> m ()

Set the value of the “password” field to Nothing. When overloading is enabled, this is equivalent to

clear #password

getURIPassword :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “password” field. When overloading is enabled, this is equivalent to

get uRI #password

setURIPassword :: MonadIO m => URI -> CString -> m ()

Set the value of the “password” field. When overloading is enabled, this is equivalent to

set uRI [ #password := value ]

path

the path on host

clearURIPath :: MonadIO m => URI -> m ()

Set the value of the “path” field to Nothing. When overloading is enabled, this is equivalent to

clear #path

getURIPath :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “path” field. When overloading is enabled, this is equivalent to

get uRI #path

setURIPath :: MonadIO m => URI -> CString -> m ()

Set the value of the “path” field. When overloading is enabled, this is equivalent to

set uRI [ #path := value ]

port

the port number on host

getURIPort :: MonadIO m => URI -> m Word32

Get the value of the “port” field. When overloading is enabled, this is equivalent to

get uRI #port

setURIPort :: MonadIO m => URI -> Word32 -> m ()

Set the value of the “port” field. When overloading is enabled, this is equivalent to

set uRI [ #port := value ]

query

a query for path, or Nothing

clearURIQuery :: MonadIO m => URI -> m ()

Set the value of the “query” field to Nothing. When overloading is enabled, this is equivalent to

clear #query

getURIQuery :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “query” field. When overloading is enabled, this is equivalent to

get uRI #query

setURIQuery :: MonadIO m => URI -> CString -> m ()

Set the value of the “query” field. When overloading is enabled, this is equivalent to

set uRI [ #query := value ]

scheme

the URI scheme (eg, "http")

clearURIScheme :: MonadIO m => URI -> m ()

Set the value of the “scheme” field to Nothing. When overloading is enabled, this is equivalent to

clear #scheme

getURIScheme :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “scheme” field. When overloading is enabled, this is equivalent to

get uRI #scheme

setURIScheme :: MonadIO m => URI -> CString -> m ()

Set the value of the “scheme” field. When overloading is enabled, this is equivalent to

set uRI [ #scheme := value ]

user

a username, or Nothing

clearURIUser :: MonadIO m => URI -> m ()

Set the value of the “user” field to Nothing. When overloading is enabled, this is equivalent to

clear #user

getURIUser :: MonadIO m => URI -> m (Maybe Text)

Get the value of the “user” field. When overloading is enabled, this is equivalent to

get uRI #user

setURIUser :: MonadIO m => URI -> CString -> m ()

Set the value of the “user” field. When overloading is enabled, this is equivalent to

set uRI [ #user := value ]