GI.Gst.Structs.Uri

A Uri object can be used to parse and split a URI string into its constituent parts. Two Uri objects can be joined to make a new Uri using the algorithm described in RFC3986.

Exported types

newtype Uri

Memory-managed wrapper type.

Constructors

Uri (ManagedPtr Uri)

Instances

BoxedObject Uri

Defined in GI.Gst.Structs.Uri

Methods

boxedType :: Uri -> IO GType

noUri :: Maybe Uri

A convenience alias for Nothing :: Maybe Uri.

Methods

appendPath

uriAppendPath

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

relativePath: Relative path to append to the end of the current path.

-> m Bool

Returns: True if the path was appended successfully.

Append a path onto the end of the path in the URI. The path is not normalized, call gst_uri_normalize() to normalize the path.

Since: 1.6

appendPathSegment

uriAppendPathSegment

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

pathSegment: The path segment string to append to the URI path.

-> m Bool

Returns: True if the path was appended successfully.

Append a single path segment onto the end of the URI path.

Since: 1.6

construct

uriConstruct

Arguments

:: (HasCallStack, MonadIO m)

=> Text

protocol: Protocol for URI

-> Text

location: Location for URI

-> m Text

Returns: a new string for this URI. Returns Nothing if the given URI protocol is not valid, or the given location is Nothing.

Deprecated: Use GstURI instead.

Constructs a URI for a given valid protocol and location.

Free-function: g_free

equal

uriEqual

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

first: First Uri to compare.

-> Uri

second: Second Uri to compare.

-> m Bool

Returns: True if the normalized versions of the two URI's would be equal.

Compares two Uri objects to see if they represent the same normalized URI.

Since: 1.6

fromString

uriFromString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

uri: The URI string to parse.

-> m (Maybe Uri)

Returns: A new Uri object, or NULL.

Parses a URI string into a new Uri object. Will return NULL if the URI cannot be parsed.

Since: 1.6

fromStringWithBase

uriFromStringWithBase

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

base: The base URI to join the new URI with.

-> Text

uri: The URI string to parse.

-> m Uri

Returns: A new Uri object.

Like uriFromString but also joins with a base URI.

Since: 1.6

getFragment

uriGetFragment

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri object.

-> m (Maybe Text)

Returns: The host name from the Uri object or Nothing.

Get the fragment name from the URI or Nothing if it doesn't exist. If uri is Nothing then returns Nothing.

Since: 1.6

getHost

uriGetHost

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri object.

-> m (Maybe Text)

Returns: The host name from the Uri object or Nothing.

Get the host name from the URI or Nothing if it doesn't exist. If uri is Nothing then returns Nothing.

Since: 1.6

getLocation

uriGetLocation

Arguments

:: (HasCallStack, MonadIO m)

=> Text

uri: A URI string

-> m (Maybe Text)

Returns: the location for this URI. Returns Nothing if the URI isn't valid. If the URI does not contain a location, an empty string is returned.

Extracts the location out of a given valid URI, ie. the protocol and "://" are stripped from the URI, which means that the location returned includes the hostname if one is specified. The returned string must be freed using free.

Free-function: g_free

getMediaFragmentTable

uriGetMediaFragmentTable

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the fragment table from.

-> m (Maybe (Map Text Text))

Returns: The fragment hash table from the URI.

Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". Hash table returned by this API is a list of "key-value" pairs, and the each pair is generated by splitting "URI fragment" per "&" sub-delims, then "key" and "value" are split by "=" sub-delims. The "key" returned by this API may be undefined keyword by standard. A value may be Nothing to indicate that the key should appear in the fragment string in the URI, but does not have a value. Free the returned HashTable with g_hash_table_unref() when it is no longer required. Modifying this hash table does not affect the fragment in the URI.

See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/

Since: 1.12

getPath

uriGetPath

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the path from.

-> m (Maybe Text)

Returns: The path from the URI. Once finished with the string should be 'GI.GLib.Functions.free'\'d.

Extract the path string from the URI object.

Since: 1.6

getPathSegments

uriGetPathSegments

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the path from.

-> m [Text]

Returns: A List of path segment strings or Nothing if no path segments are available. Free the list when no longer needed with g_list_free_full(list, g_free).

Get a list of path segments from the URI.

Since: 1.6

getPathString

uriGetPathString

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the path from.

-> m (Maybe Text)

Returns: The path from the URI. Once finished with the string should be 'GI.GLib.Functions.free'\'d.

Extract the path string from the URI object as a percent encoded URI path.

Since: 1.6

getPort

uriGetPort

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri object.

-> m Word32

Returns: The port number from the Uri object or URI_NO_PORT.

Get the port number from the URI or URI_NO_PORT if it doesn't exist. If uri is Nothing then returns URI_NO_PORT.

Since: 1.6

getProtocol

uriGetProtocol

Arguments

:: (HasCallStack, MonadIO m)

=> Text

uri: A URI string

-> m (Maybe Text)

Returns: The protocol for this URI.

Extracts the protocol out of a given valid URI. The returned string must be freed using free.

getQueryKeys

uriGetQueryKeys

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to examine.

-> m [Text]

Returns: A list of keys from the URI query. Free the list with g_list_free().

Get a list of the query keys from the URI.

Since: 1.6

getQueryString

uriGetQueryString

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the query string from.

-> m (Maybe Text)

Returns: A percent encoded query string. Use free when no longer needed.

Get a percent encoded URI query string from the uri.

Since: 1.6

getQueryTable

uriGetQueryTable

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to get the query table from.

-> m (Maybe (Map Text Text))

Returns: The query hash table from the URI.

Get the query table from the URI. Keys and values in the table are freed with g_free when they are deleted. A value may be Nothing to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned HashTable with g_hash_table_unref() when it is no longer required. Modifying this hash table will modify the query in the URI.

Since: 1.6

getQueryValue

uriGetQueryValue

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to examine.

-> Text

queryKey: The key to lookup.

-> m (Maybe Text)

Returns: The value for the given key, or Nothing if not found.

Get the value associated with the queryKey key. Will return Nothing if the key has no value or if the key does not exist in the URI query table. Because Nothing is returned for both missing keys and keys with no value, you should use uriQueryHasKey to determine if a key is present in the URI query.

Since: 1.6

getScheme

uriGetScheme

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri object.

-> m (Maybe Text)

Returns: The scheme from the Uri object or Nothing.

Get the scheme name from the URI or Nothing if it doesn't exist. If uri is Nothing then returns Nothing.

getUserinfo

uriGetUserinfo

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri object.

-> m (Maybe Text)

Returns: The userinfo from the Uri object or Nothing.

Get the userinfo (usually in the form "username:password") from the URI or Nothing if it doesn't exist. If uri is Nothing then returns Nothing.

Since: 1.6

hasProtocol

uriHasProtocol

Arguments

:: (HasCallStack, MonadIO m)

=> Text

uri: a URI string

-> Text

protocol: a protocol string (e.g. "http")

-> m Bool

Returns: True if the protocol matches.

Checks if the protocol of a given valid URI matches protocol.

isNormalized

uriIsNormalized

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to test to see if it is normalized.

-> m Bool

Returns: TRUE if the URI is normalized or is Nothing.

Tests the uri to see if it is normalized. A Nothing uri is considered to be normalized.

Since: 1.6

isValid

uriIsValid

Arguments

:: (HasCallStack, MonadIO m)

=> Text

uri: A URI string

-> m Bool

Returns: True if the string is a valid URI

Tests if the given string is a valid URI identifier. URIs start with a valid scheme followed by ":" and maybe a string identifying the location.

isWritable

uriIsWritable

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri object to test.

-> m Bool

Returns: True if it is safe to write to the object.

Check if it is safe to write to this Uri.

Check if the refcount of uri is exactly 1, meaning that no other reference exists to the Uri and that the Uri is therefore writable.

Modification of a Uri should only be done after verifying that it is writable.

Since: 1.6

join

uriJoin

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

baseUri: The base URI to join another to.

-> Maybe Uri

refUri: The reference URI to join onto the base URI.

-> m (Maybe Uri)

Returns: A Uri which represents the base with the reference URI joined on.

Join a reference URI onto a base URI using the method from RFC 3986. If either URI is Nothing then the other URI will be returned with the ref count increased.

Since: 1.6

joinStrings

uriJoinStrings

Arguments

:: (HasCallStack, MonadIO m)

=> Text

baseUri: The percent-encoded base URI.

-> Text

refUri: The percent-encoded reference URI to join to the baseUri.

-> m Text

Returns: A string representing the percent-encoded join of the two URIs.

This is a convenience function to join two URI strings and return the result. The returned string should be 'GI.GLib.Functions.free'\'d after use.

Since: 1.6

makeWritable

uriMakeWritable

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri object to make writable.

-> m Uri

Returns: A writable version of uri.

Make the Uri writable.

Checks if uri is writable, and if so the original object is returned. If not, then a writable copy is made and returned. This gives away the reference to uri and returns a reference to the new Uri. If uri is Nothing then Nothing is returned.

Since: 1.6

new

uriNew

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Text

scheme: The scheme for the new URI.

-> Maybe Text

userinfo: The user-info for the new URI.

-> Maybe Text

host: The host name for the new URI.

-> Word32

port: The port number for the new URI or URI_NO_PORT.

-> Maybe Text

path: The path for the new URI with '/' separating path elements.

-> Maybe Text

query: The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26".

-> Maybe Text

fragment: The fragment name for the new URI.

-> m Uri

Returns: A new Uri object.

Creates a new Uri object with the given URI parts. The path and query strings will be broken down into their elements. All strings should not be escaped except where indicated.

Since: 1.6

newWithBase

uriNewWithBase

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

base: The base URI to join the new URI to.

-> Maybe Text

scheme: The scheme for the new URI.

-> Maybe Text

userinfo: The user-info for the new URI.

-> Maybe Text

host: The host name for the new URI.

-> Word32

port: The port number for the new URI or URI_NO_PORT.

-> Maybe Text

path: The path for the new URI with '/' separating path elements.

-> Maybe Text

query: The query string for the new URI with '&' separating query elements. Elements containing '&' characters should encode them as "%26".

-> Maybe Text

fragment: The fragment name for the new URI.

-> m Uri

Returns: The new URI joined onto base.

Like uriNew, but joins the new URI onto a base URI.

Since: 1.6

normalize

uriNormalize

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to normalize.

-> m Bool

Returns: TRUE if the URI was modified.

Normalization will remove extra path segments ("." and "..") from the URI. It will also convert the scheme and host name to lower case and any percent-encoded values to uppercase.

The Uri object must be writable. Check with uriIsWritable or use uriMakeWritable first.

Since: 1.6

protocolIsSupported

uriProtocolIsSupported

Arguments

:: (HasCallStack, MonadIO m)

=> URIType

type: Whether to check for a source or a sink

-> Text

protocol: Protocol that should be checked for (e.g. "http" or "smb")

-> m Bool

Returns: True

Checks if an element exists that supports the given URI protocol. Note that a positive return value does not imply that a subsequent call to elementMakeFromUri is guaranteed to work.

protocolIsValid

uriProtocolIsValid

Arguments

:: (HasCallStack, MonadIO m)

=> Text

protocol: A string

-> m Bool

Returns: True if the string is a valid protocol identifier, False otherwise.

Tests if the given string is a valid protocol identifier. Protocols must consist of alphanumeric characters, '+', '-' and '.' and must start with a alphabetic character. See RFC 3986 Section 3.1.

queryHasKey

uriQueryHasKey

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to examine.

-> Text

queryKey: The key to lookup.

-> m Bool

Returns: True if queryKey exists in the URI query table.

Check if there is a query table entry for the queryKey key.

Since: 1.6

removeQueryKey

uriRemoveQueryKey

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

queryKey: The key to remove.

-> m Bool

Returns: True if the key existed in the table and was removed.

Remove an entry from the query table by key.

Since: 1.6

setFragment

uriSetFragment

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Maybe Text

fragment: The fragment string to set.

-> m Bool

Returns: True if the fragment was set/unset successfully.

Sets the fragment string in the URI. Use a value of Nothing in fragment to unset the fragment string.

Since: 1.6

setHost

uriSetHost

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

host: The new host string to set or Nothing to unset.

-> m Bool

Returns: True if the host was set/unset successfully.

Set or unset the host for the URI.

Since: 1.6

setPath

uriSetPath

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

path: The new path to set with path segments separated by '/', or use Nothing to unset the path.

-> m Bool

Returns: True if the path was set successfully.

Sets or unsets the path in the URI.

Since: 1.6

setPathSegments

uriSetPathSegments

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> [Text]

pathSegments: The new path list to set.

-> m Bool

Returns: True if the path segments were set successfully.

Replace the path segments list in the URI.

Since: 1.6

setPathString

uriSetPathString

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

path: The new percent encoded path to set with path segments separated by '/', or use Nothing to unset the path.

-> m Bool

Returns: True if the path was set successfully.

Sets or unsets the path in the URI.

Since: 1.6

setPort

uriSetPort

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Word32

port: The new port number to set or URI_NO_PORT to unset.

-> m Bool

Returns: True if the port number was set/unset successfully.

Set or unset the port number for the URI.

Since: 1.6

setQueryString

uriSetQueryString

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

query: The new percent encoded query string to use to populate the query table, or use Nothing to unset the query table.

-> m Bool

Returns: True if the query table was set successfully.

Sets or unsets the query table in the URI.

Since: 1.6

setQueryTable

uriSetQueryTable

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Maybe (Map Text Text)

queryTable: The new query table to use.

-> m Bool

Returns: True if the new table was successfully used for the query table.

Set the query table to use in the URI. The old table is unreferenced and a reference to the new one is used instead. A value if Nothing for queryTable will remove the query string from the URI.

Since: 1.6

setQueryValue

uriSetQueryValue

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

queryKey: The key for the query entry.

-> Maybe Text

queryValue: The value for the key.

-> m Bool

Returns: True if the query table was successfully updated.

This inserts or replaces a key in the query table. A queryValue of Nothing indicates that the key has no associated value, but will still be present in the query string.

Since: 1.6

setScheme

uriSetScheme

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

scheme: The new scheme to set or Nothing to unset the scheme.

-> m Bool

Returns: True if the scheme was set/unset successfully.

Set or unset the scheme for the URI.

Since: 1.6

setUserinfo

uriSetUserinfo

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: The Uri to modify.

-> Text

userinfo: The new user-information string to set or Nothing to unset.

-> m Bool

Returns: True if the user information was set/unset successfully.

Set or unset the user information for the URI.

Since: 1.6

toString

uriToString

Arguments

:: (HasCallStack, MonadIO m)

=> Uri

uri: This Uri to convert to a string.

-> m Text

Returns: The string version of the URI.

Convert the URI to a string.

Returns the URI as held in this object as a gchar* nul-terminated string. The caller should free the string once they are finished with it. The string is put together as described in RFC 3986.

Since: 1.6