Package org.freedesktop.gstreamer.gst

Class Uri

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.Uri

All Implemented Interfaces:

Proxy

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

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

Constructor Summary

Constructors

Constructor	Description
Uri(@Nullable String scheme, @Nullable String userinfo, @Nullable String host, int port, @Nullable String path, @Nullable String query, @Nullable String fragment)	Creates a new GstUri object with the given URI parts.
Uri(MemorySegment address)	Create a Uri proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
boolean	appendPath(@Nullable String relativePath)	Append a path onto the end of the path in the URI.
boolean	appendPathSegment(@Nullable String pathSegment)	Append a single path segment onto the end of the URI path.
static String	construct(String protocol, String location)	Deprecated. Use GstURI instead.
Uri	copy()	Create a new GstUri object with the same data as this GstUri object.
boolean	equal(Uri second)	Compares two GstUri objects to see if they represent the same normalized URI.
static Uri	fromString(String uri)	Parses a URI string into a new GstUri object.
static Uri	fromStringEscaped(String uri)	Parses a URI string into a new GstUri object.
Uri	fromStringWithBase(String uri)	Like gst_uri_from_string() but also joins with a base URI.
String	getFragment()	Get the fragment name from the URI or null if it doesn't exist.
String	getHost()	Get the host name from the URI or null if it doesn't exist.
static String	getLocation(String uri)	Extracts the location out of a given valid URI, ie.
HashTable<String,String>	getMediaFragmentTable()	Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0".
String	getPath()	Extract the path string from the URI object.
List<String>	getPathSegments()	Get a list of path segments from the URI.
String	getPathString()	Extract the path string from the URI object as a percent encoded URI path.
int	getPort()	Get the port number from the URI or GST_URI_NO_PORT if it doesn't exist.
static String	getProtocol(String uri)	Extracts the protocol out of a given valid URI.
List<String>	getQueryKeys()	Get a list of the query keys from the URI.
String	getQueryString()	Get a percent encoded URI query string from the this Uri.
String	getQueryStringOrdered(@Nullable List<String> keys)	Get a percent encoded URI query string from the this Uri, with query parameters in the order provided by the keys list.
HashTable<String,String>	getQueryTable()	Get the query table from the URI.
String	getQueryValue(String queryKey)	Get the value associated with the queryKey key.
String	getScheme()	Get the scheme name from the URI or null if it doesn't exist.
static Type	getType()	Get the GType of the Uri class
String	getUserinfo()	Get the userinfo (usually in the form "username:password") from the URI or null if it doesn't exist.
static boolean	hasProtocol(String uri, String protocol)	Checks if the protocol of a given valid URI matches protocol.
boolean	isNormalized()	Tests the this Uri to see if it is normalized.
static boolean	isValid(String uri)	Tests if the given string is a valid URI identifier.
boolean	isWritable()	Check if it is safe to write to this GstUri.
Uri	join(@Nullable Uri refUri)	Join a reference URI onto a base URI using the method from RFC 3986.
static String	joinStrings(String baseUri, String refUri)	This is a convenience function to join two URI strings and return the result.
Uri	makeWritable()	Make the GstUri writable.
Uri	newWithBase(@Nullable String scheme, @Nullable String userinfo, @Nullable String host, int port, @Nullable String path, @Nullable String query, @Nullable String fragment)	Like gst_uri_new(), but joins the new URI onto a base URI.
boolean	normalize()	Normalization will remove extra path segments ("." and "..") from the URI.
static boolean	protocolIsSupported(URIType type, String protocol)	Checks if an element exists that supports the given URI protocol.
static boolean	protocolIsValid(String protocol)	Tests if the given string is a valid protocol identifier.
boolean	queryHasKey(String queryKey)	Check if there is a query table entry for the queryKey key.
Uri	ref()	Add a reference to this GstUri object.
boolean	removeQueryKey(String queryKey)	Remove an entry from the query table by key.
boolean	setFragment(@Nullable String fragment)	Sets the fragment string in the URI.
boolean	setHost(String host)	Set or unset the host for the URI.
boolean	setPath(@Nullable String path)	Sets or unsets the path in the URI.
boolean	setPathSegments(@Nullable List<String> pathSegments)	Replace the path segments list in the URI.
boolean	setPathString(String path)	Sets or unsets the path in the URI.
boolean	setPort(int port)	Set or unset the port number for the URI.
boolean	setQueryString(@Nullable String query)	Sets or unsets the query table in the URI.
boolean	setQueryTable(@Nullable HashTable<String,String> queryTable)	Set the query table to use in the URI.
boolean	setQueryValue(String queryKey, @Nullable String queryValue)	This inserts or replaces a key in the query table.
boolean	setScheme(String scheme)	Set or unset the scheme for the URI.
boolean	setUserinfo(String userinfo)	Set or unset the user information for the URI.
String	toString()	Convert the URI to a string.
String	toStringWithKeys(@Nullable List<String> keys)	Convert the URI to a string, with the query arguments in a specific order.
void	unref()	Decrement the reference count to this GstUri object.

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

equals, handle, hashCode

Methods inherited from class java.lang.Object

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

Constructor Details

Uri

public Uri(MemorySegment address)

Create a Uri proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Uri

public Uri(@Nullable
 @Nullable String scheme,
 @Nullable
 @Nullable String userinfo,
 @Nullable
 @Nullable String host,
 int port,
 @Nullable
 @Nullable String path,
 @Nullable
 @Nullable String query,
 @Nullable
 @Nullable String fragment)

Creates a new GstUri 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.

Parameters:

scheme - The scheme for the new URI.

userinfo - The user-info for the new URI.

host - The host name for the new URI.

port - The port number for the new URI or GST_URI_NO_PORT.

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

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

fragment - The fragment name for the new URI.

Method Details

getType

public static Type getType()

Get the GType of the Uri class

Returns:

the GType

construct

@Deprecated
public static String construct(String protocol,
 String location)

Deprecated.

Use GstURI instead.

Constructs a URI for a given valid protocol and location.

Free-function: g_free

Parameters:

protocol - Protocol for URI

location - Location for URI

Returns:

a new string for this URI.

fromString

public static Uri fromString(String uri)

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

Parameters:

uri - The URI string to parse.

Returns:

A new GstUri object, or NULL.

fromStringEscaped

public static Uri fromStringEscaped(String uri)

Parses a URI string into a new GstUri object. Will return NULL if the URI cannot be parsed. This is identical to gst_uri_from_string() except that the userinfo and fragment components of the URI will not be unescaped while parsing.

Use this when you need to extract a username and password from the userinfo such as https://user:passwordexample.com since either may contain a URI-escaped ':' character. gst_uri_from_string() will unescape the entire userinfo component, which will make it impossible to know which ':' delineates the username and password.

The same applies to the fragment component of the URI, such as https://example.com/pathfragment which may contain a URI-escaped ''.

Parameters:

uri - The URI string to parse.

Returns:

A new GstUri object, or NULL.

getLocation

public static String getLocation(String uri)

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

Free-function: g_free

Parameters:

uri - A URI string

Returns:

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

getProtocol

public static String getProtocol(String uri)

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

Parameters:

uri - A URI string

Returns:

The protocol for this URI.

hasProtocol

public static boolean hasProtocol(String uri,
 String protocol)

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

Parameters:

uri - a URI string

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

Returns:

true if the protocol matches.

isValid

public static boolean isValid(String 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.

Parameters:

uri - A URI string

Returns:

true if the string is a valid URI

joinStrings

public static String joinStrings(String baseUri,
 String refUri)

This is a convenience function to join two URI strings and return the result. The returned string should be g_free()'d after use.

Parameters:

baseUri - The percent-encoded base URI.

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

Returns:

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

protocolIsSupported

public static boolean protocolIsSupported(URIType type,
 String protocol)

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 gst_element_make_from_uri() is guaranteed to work.

Parameters:

type - Whether to check for a source or a sink

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

Returns:

true

protocolIsValid

public static boolean protocolIsValid(String protocol)

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.

Parameters:

protocol - A string

Returns:

true if the string is a valid protocol identifier, false otherwise.

appendPath

public boolean appendPath(@Nullable
 @Nullable String relativePath)

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.

Parameters:

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

Returns:

true if the path was appended successfully.

appendPathSegment

public boolean appendPathSegment(@Nullable
 @Nullable String pathSegment)

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

Parameters:

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

Returns:

true if the path was appended successfully.

copy

public Uri copy()

Create a new GstUri object with the same data as this GstUri object. If this Uri is null then returns null.

Returns:

A new GstUri object which is a copy of this GstUri or null.

equal

public boolean equal(Uri second)

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

Parameters:

second - Second GstUri to compare.

Returns:

true if the normalized versions of the two URI's would be equal.

fromStringWithBase

public Uri fromStringWithBase(String uri)

Like gst_uri_from_string() but also joins with a base URI.

Parameters:

uri - The URI string to parse.

Returns:

A new GstUri object.

getFragment

public String getFragment()

Get the fragment name from the URI or null if it doesn't exist. If this Uri is null then returns null.

Returns:

The host name from the GstUri object or null.

getHost

public String getHost()

Get the host name from the URI or null if it doesn't exist. If this Uri is null then returns null.

Returns:

The host name from the GstUri object or null.

getMediaFragmentTable

public HashTable<String,String> getMediaFragmentTable()

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 null to indicate that the key should appear in the fragment string in the URI, but does not have a value. Free the returned GHashTable 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/

Returns:

The fragment hash table from the URI.

getPath

public String getPath()

Extract the path string from the URI object.

Returns:

The path from the URI. Once finished with the string should be g_free()'d.

getPathSegments

public List<String> getPathSegments()

Get a list of path segments from the URI.

Returns:

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

getPathString

public String getPathString()

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

Returns:

The path from the URI. Once finished with the string should be g_free()'d.

getPort

public int getPort()

Get the port number from the URI or GST_URI_NO_PORT if it doesn't exist. If this Uri is null then returns GST_URI_NO_PORT.

Returns:

The port number from the GstUri object or GST_URI_NO_PORT.

getQueryKeys

public List<String> getQueryKeys()

Get a list of the query keys from the URI.

Returns:

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

getQueryString

public String getQueryString()

Get a percent encoded URI query string from the this Uri.

Returns:

A percent encoded query string. Use g_free() when no longer needed.

getQueryStringOrdered

public String getQueryStringOrdered(@Nullable
 @Nullable List<String> keys)

Get a percent encoded URI query string from the this Uri, with query parameters in the order provided by the keys list. Only parameter keys in the list will be added to the resulting URI string. This method can be used by retrieving the keys with gst_uri_get_query_keys() and then sorting the list, for example.

Parameters:

keys - A GList containing the query argument key strings.

Returns:

A percent encoded query string. Use g_free() when no longer needed.

getQueryTable

public HashTable<String,String> getQueryTable()

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 null to indicate that the key should appear in the query string in the URI, but does not have a value. Free the returned GHashTable with g_hash_table_unref() when it is no longer required. Modifying this hash table will modify the query in the URI.

Returns:

The query hash table from the URI.

getQueryValue

public String getQueryValue(String queryKey)

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

Parameters:

queryKey - The key to lookup.

Returns:

The value for the given key, or null if not found.

getScheme

public String getScheme()

Get the scheme name from the URI or null if it doesn't exist. If this Uri is null then returns null.

Returns:

The scheme from the GstUri object or null.

getUserinfo

public String getUserinfo()

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

Returns:

The userinfo from the GstUri object or null.

isNormalized

public boolean isNormalized()

Tests the this Uri to see if it is normalized. A null this Uri is considered to be normalized.

Returns:

TRUE if the URI is normalized or is null.

isWritable

public boolean isWritable()

Check if it is safe to write to this GstUri.

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

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

Returns:

true if it is safe to write to the object.

join

public Uri join(@Nullable
 @Nullable Uri refUri)

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

Parameters:

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

Returns:

A GstUri which represents the base with the reference URI joined on.

makeWritable

public Uri makeWritable()

Make the GstUri writable.

Checks if this 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 this Uri and returns a reference to the new GstUri. If this Uri is null then null is returned.

Returns:

A writable version of this Uri.

newWithBase

public Uri newWithBase(@Nullable
 @Nullable String scheme,
 @Nullable
 @Nullable String userinfo,
 @Nullable
 @Nullable String host,
 int port,
 @Nullable
 @Nullable String path,
 @Nullable
 @Nullable String query,
 @Nullable
 @Nullable String fragment)

Like gst_uri_new(), but joins the new URI onto a base URI.

Parameters:

scheme - The scheme for the new URI.

userinfo - The user-info for the new URI.

host - The host name for the new URI.

port - The port number for the new URI or GST_URI_NO_PORT.

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

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

fragment - The fragment name for the new URI.

Returns:

The new URI joined onto this Uri.

normalize

public boolean normalize()

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 GstUri object must be writable. Check with gst_uri_is_writable() or use gst_uri_make_writable() first.

Returns:

TRUE if the URI was modified.

queryHasKey

public boolean queryHasKey(String queryKey)

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

Parameters:

queryKey - The key to lookup.

Returns:

true if queryKey exists in the URI query table.

ref

public Uri ref()

Add a reference to this GstUri object. See gst_mini_object_ref() for further info.

Returns:

This object with the reference count incremented.

removeQueryKey

public boolean removeQueryKey(String queryKey)

Remove an entry from the query table by key.

Parameters:

queryKey - The key to remove.

Returns:

true if the key existed in the table and was removed.

setFragment

public boolean setFragment(@Nullable
 @Nullable String fragment)

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

Parameters:

fragment - The fragment string to set.

Returns:

true if the fragment was set/unset successfully.

setHost

public boolean setHost(String host)

Set or unset the host for the URI.

Parameters:

host - The new host string to set or null to unset.

Returns:

true if the host was set/unset successfully.

setPath

public boolean setPath(@Nullable
 @Nullable String path)

Sets or unsets the path in the URI.

Parameters:

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

Returns:

true if the path was set successfully.

setPathSegments

public boolean setPathSegments(@Nullable
 @Nullable List<String> pathSegments)

Replace the path segments list in the URI.

Parameters:

pathSegments - The new path list to set.

Returns:

true if the path segments were set successfully.

setPathString

public boolean setPathString(String path)

Sets or unsets the path in the URI.

Parameters:

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

Returns:

true if the path was set successfully.

setPort

public boolean setPort(int port)

Set or unset the port number for the URI.

Parameters:

port - The new port number to set or GST_URI_NO_PORT to unset.

Returns:

true if the port number was set/unset successfully.

setQueryString

public boolean setQueryString(@Nullable
 @Nullable String query)

Sets or unsets the query table in the URI.

Parameters:

query - The new percent encoded query string to use to populate the query table, or use null to unset the query table.

Returns:

true if the query table was set successfully.

setQueryTable

public boolean setQueryTable(@Nullable
 @Nullable HashTable<String,String> queryTable)

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 null for queryTable will remove the query string from the URI.

Parameters:

queryTable - The new query table to use.

Returns:

true if the new table was successfully used for the query table.

setQueryValue

public boolean setQueryValue(String queryKey,
 @Nullable
 @Nullable String queryValue)

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

Parameters:

queryKey - The key for the query entry.

queryValue - The value for the key.

Returns:

true if the query table was successfully updated.

setScheme

public boolean setScheme(String scheme)

Set or unset the scheme for the URI.

Parameters:

scheme - The new scheme to set or null to unset the scheme.

Returns:

true if the scheme was set/unset successfully.

setUserinfo

public boolean setUserinfo(String userinfo)

Set or unset the user information for the URI.

Parameters:

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

Returns:

true if the user information was set/unset successfully.

toString

public String toString()

Convert the URI to a string.

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

Overrides:

toString in class Object

Returns:

The string version of the URI.

toStringWithKeys

public String toStringWithKeys(@Nullable
 @Nullable List<String> keys)

Convert the URI to a string, with the query arguments in a specific order. Only the keys in the keys list will be added to the resulting string.

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

Parameters:

keys - A GList containing the query argument key strings.

Returns:

The string version of the URI.

unref

public void unref()

Decrement the reference count to this GstUri object.

If the reference count drops to 0 then finalize this object.

See gst_mini_object_unref() for further info.