URL Parsing and Manipulation#

Functions#

struct OmniClientUrl * omniClientBreakUrl(char const *url): Break a URL into components.
struct OmniClientUrl * omniClientBreakUrlReference(char const *urlReference): Break a URL into components.
char * omniClientCombineUrls(char const *baseUrl, char const *otherUrl, char *buffer, size_t *bufferSize): This combines a URL with an explicit base URL.
struct OmniClientUrl * omniClientCombineUrls2(struct OmniClientUrl const *baseUrl, char const *otherUrl): This combines a URL with an explicit base URL.
char * omniClientCombineWithBaseUrl(char const *otherUrl, char *buffer, size_t *bufferSize): This calls omniClientCombineUrls with the URL on the top of the stack.
struct OmniClientUrl * omniClientCombineWithBaseUrl2(char const *otherUrl): This calls omniClientCombineUrls with the URL on the top of the stack.
void omniClientFreeUrl(struct OmniClientUrl *url): Free the URL structure allocated by omniClientBreakUrlReference or omniClientBreakUrl .
char * omniClientMakeFileUrl(char const *path, char *buffer, size_t *bufferSize): This creates a "file:" URL from a path.
char * omniClientMakePrintable(char const *string, char *buffer, size_t *bufferSize): This makes a URL safe for printing in a UI or to a console window.
char * omniClientMakeRelativeUrl(char const *baseUrl, char const *otherUrl, char *buffer, size_t *bufferSize): This makes "otherUrl" relative to "baseUrl".
char * omniClientMakeUrl(struct OmniClientUrl const *url, char *buffer, size_t *bufferSize): This creates a URL from the pieces provided.
char * omniClientNormalizeUrl(char const *url, char *buffer, size_t *bufferSize): This normalizes a URL by parsing it then recomposing it.

Structs#

OmniClientUrl: A URL broken into the component pieces.

Functions#

struct OmniClientUrl *omniClientBreakUrl(char const *url)#

Break a URL into components.

This assumes the URL is either a full URL (starting with a scheme such as “http:”) or a raw local file path such as “C:\path” (Windows) or “/path” (Linux).

This affects percent-encoding and handling of ? and # for paths such as “/test%20test?”, which will be decoded to “/test test” by omniClientBreakUrlReference, but left as-is by omniClientBreakUrl

If the return value has “isRaw” set to true then “urlAbsolute” was determined to be a raw path, and only the “path” value is set.

Parameters:: url – The URL to break into components
Returns:: A pointer to the URL components structure, or nullptr on error

struct OmniClientUrl *omniClientBreakUrlReference( char const *urlReference, )#

Break a URL into components.

The full rules are defined by https://tools.ietf.org/html/rfc3986

This version should be used instead of omniClientBreakUrl if you have a URL reference such as “/path?query#fragment” which would be interpreted as a file path by omniClientBreakUrl

The returned structure should be freed by omniClientFreeUrl

Parameters:: urlReference – The URL reference to break into components
Returns:: A pointer to the URL components structure, or nullptr on error

char *omniClientCombineUrls( char const *baseUrl, char const *otherUrl, char *buffer, size_t *bufferSize, )#

This combines a URL with an explicit base URL.

The full rules are mostly defined by https://tools.ietf.org/html/rfc3986#section-5 Although we do some special magic for raw file paths Note that trailing slashes matter here! (“/a/b/c”, “d”) = “/a/b/d” (“/a/b/c/”, “d”) = “/a/b/c/d” The trailing slash rule makes more sense with real files: (“/path/file1.usd”, “file2.usd”) = “/path/file2.usd” (“/path/subdir/”, “file.usd”) = “/path/subdir/file.usd” buffer rules are the same as omniClientMakeUrl

Parameters:

baseUrl – The base URL to combine with
otherUrl – The relative URL to combine
buffer – The buffer to write the combined URL into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the combined URL, or nullptr if the buffer is too small

struct OmniClientUrl *omniClientCombineUrls2( struct OmniClientUrl const *baseUrl, char const *otherUrl, )#

This combines a URL with an explicit base URL.

This differs from omniClientCombineUrls in the return type and type of “baseUrl”

Call omniClientFreeUrl to free the returned structure.

Parameters:

baseUrl – The base URL components to combine with
otherUrl – The relative URL to combine

Returns:

A pointer to the combined URL components, or nullptr on error

char *omniClientCombineWithBaseUrl( char const *otherUrl, char *buffer, size_t *bufferSize, )#

This calls omniClientCombineUrls with the URL on the top of the stack.

See also

omniClientPushBaseUrl

Parameters:: otherUrl – The relative URL to combine with the base URL
Returns:: A pointer to the combined URL components, or nullptr on error

void omniClientFreeUrl(struct OmniClientUrl *url)#

Free the URL structure allocated by omniClientBreakUrlReference or omniClientBreakUrl.

Parameters:: url – The URL structure to free

char *omniClientMakeFileUrl( char const *path, char *buffer, size_t *bufferSize, )#

This creates a “file:” URL from a path.

This uses the rules defined by: https://en.wikipedia.org/wiki/File_URI_scheme

This is equivalent to calling:

OmniClientUrl fileUrl{};
fileUrl.scheme = "file";
fileUrl.path = path;
omniClientMakeUrl(&fileUrl, buffer, bufferSize);

buffer rules are the same as omniClientMakeUrl

Parameters:

path – The file path to convert to a URL
buffer – The buffer to write the URL into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the constructed file URL, or nullptr if the buffer is too small

char *omniClientMakePrintable( char const *string, char *buffer, size_t *bufferSize, )#

This makes a URL safe for printing in a UI or to a console window.

The input is expected to be a full, potentially with percent-encoded, URL.

It percent-encodes any ASCII control characters or invalid UTF-8 characters. It percent-decodes any valid UTF-8 characters, and ASCII characters that are not reserved by the URL specification.

buffer rules are the same as omniClientMakeUrl

Parameters:

string – The string to make printable
buffer – The buffer to write the printable string into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the printable string, or nullptr if the buffer is too small

char *omniClientMakeRelativeUrl( char const *baseUrl, char const *otherUrl, char *buffer, size_t *bufferSize, )#

This makes “otherUrl” relative to “baseUrl”.

It attempts to make the shortest URL possible while guaranteeing that you can pass the returned relative URL and baseUrl to omniClientCombineUrls and get back the original otherUrl (except that the returned URL is normalized) buffer rules are the same as omniClientMakeUrl Note that trailing slashes matter here! (“/a/b/c”, “/a/d”) = “../d” (“/a/b/c/”, “/a/d”) = “../../d” The reason is because trailing slashes also matter in the baseUrl for omniClientCombineUrls

Parameters:

baseUrl – The base URL to make relative to
otherUrl – The URL to make relative
buffer – The buffer to write the relative URL into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the relative URL, or nullptr if the buffer is too small

char *omniClientMakeUrl( struct OmniClientUrl const *url, char *buffer, size_t *bufferSize, )#

This creates a URL from the pieces provided.

“bufferSize” is an in-out parameter; set it to the size of the buffer before calling this function and it will be set to the actual size when the function returns.

If the size required is more than the size provided, this function returns null, otherwise it returns ‘buffer’.

Parameters:

url – The URL components to combine
buffer – The buffer to write the URL into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the constructed URL, or nullptr if the buffer is too small

char *omniClientNormalizeUrl( char const *url, char *buffer, size_t *bufferSize, )#

This normalizes a URL by parsing it then recomposing it.

This is equivalent to calling omniClientBreakUrl then omniClientMakeUrl;

buffer rules are the same as omniClientMakeUrl

Parameters:

url – The URL to normalize
buffer – The buffer to write the normalized URL into
bufferSize – On input, the size of the buffer; on output, the actual size needed

Returns:

A pointer to the normalized URL, or nullptr if the buffer is too small