Class Uri

java.lang.Object
org.javagi.base.ProxyInstance
org.freedesktop.gstreamer.gst.Uri
All Implemented Interfaces:
Proxy
@Generated("org.javagi.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 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 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. 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.
      Since:
      1.6

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Uri class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • 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 @Nullable 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.
      Since:
      1.6

    • fromStringEscaped

      public static @Nullable 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.
      Since:
      1.18

    • getLocation

      public static @Nullable 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 @Nullable 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 @Nullable 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.
      Since:
      1.6

    • 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 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.
      Since:
      1.6

    • appendPathSegment

      public boolean appendPathSegment(@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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • fromStringWithBase

      public @Nullable 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.
      Since:
      1.6

    • getFragment

      public @Nullable 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.
      Since:
      1.6

    • getHost

      public @Nullable 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.
      Since:
      1.6

    • getMediaFragmentTable

      public @Nullable 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.
      Since:
      1.12

    • getPath

      public @Nullable 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.
      Since:
      1.6

    • 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).
      Since:
      1.6

    • getPathString

      public @Nullable 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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().
      Since:
      1.6

    • getQueryString

      public @Nullable String getQueryString()
      Get a percent encoded URI query string from the uri.
      Returns:
      A percent encoded query string. Use g_free() when no longer needed.
      Since:
      1.6

    • getQueryStringOrdered

      public @Nullable String getQueryStringOrdered(@Nullable List<String> keys)
      Get a percent encoded URI query string from the 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.
      Since:
      1.24

    • getQueryTable

      public @Nullable 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.
      Since:
      1.6

    • getQueryValue

      public @Nullable 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.
      Since:
      1.6

    • getScheme

      public @Nullable 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 @Nullable 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • join

      public @Nullable Uri join(@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.
      Since:
      1.6

    • 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 uri.
      Since:
      1.6

    • newWithBase

      public 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.
      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 base.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • setFragment

      public boolean setFragment(@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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • setPath

      public boolean setPath(@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.
      Since:
      1.6

    • setPathSegments

      public boolean setPathSegments(@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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • setQueryString

      public boolean setQueryString(@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.
      Since:
      1.6

    • setQueryTable

      public boolean setQueryTable(@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.
      Since:
      1.6

    • setQueryValue

      public boolean setQueryValue(String queryKey, @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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • 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.
      Since:
      1.6

    • toStringWithKeys

      public String toStringWithKeys(@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.
      Since:
      1.24

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

      Since:
      1.6