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.

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

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

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.

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

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.

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

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

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

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

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