The URLs consist of a subset of printable ASCII (ECMA-5) characters. The subset excludes space and characters commonly used as delimiters in text-based protocols, such as < > # % and " (double quote), and so called unwise characters whose positions are reserved for national extensions in ECMA-5. In US-ASCII, those characters are: { } | \ ^ [ ] `
There are also nine characters that can have special syntactic meaning in some parts of the URI. These reserved characters are used to separate syntactical parts of the URLs from each other. The reserved characters are as follows: : @ / ; ? & = + and $.
The URL library understands two alternative URL syntaxes. First, the basic syntax used by, e.g., ftp:, http: and rtsp: URLs:
scheme ":" ["//" [ user [":" password ] "@"] host [":" port ] ] ["/" path ] ["?" query ] ["#" fragment ]
Alternatively, the syntax used by mailto:, sip:, im:, tel, and pres: URLs:
scheme ":" [ [ user [":" password ] "@"] host [":" port ] ] [";" params ] ["?" query ] ["#" fragment ]
Note that url parser also considers "*" to be a valid URL (with type url_any).
For example:
http://example.org:7100/cgi-bin/query?key=90786 ftp://user:pass\@ftp.example.com/pub/ sip:user:pass\@example.com;user=ip tel:+358718008000
The function url_format() is provided for generating the URL with printf()-like formatting.
For example, when we make the url from the string below
sip:joe%2Euser@example%2Ecom;method=%4D%45%53%53%41%47%45?body=CANNED%20MSG
url_type = url_sip url_root = 0 url_scheme = "sip" url_user = "joe.user" url_password = NULL url_host = "example.com" url_port = NULL url_path = NULL url_params = "method=MESSAGE" url_headers = "body=CANNED%20MSG" url_fragment = NULL
You can use the function url_param() and url_have_param() to access particular parameters from url->url_params string.
url_t *url_make(su_home_t *h, char const *str); url_t *url_format(su_home_t *h, char const *fmt, ...); char *url_as_string(su_home_t *home, url_t const *url); url_t *url_hdup(su_home_t *h, url_t const *src); int url_sanitize(url_t *u); char const *url_scheme(enum url_type_e type); #define URL_INIT_AS(type) void url_init(url_t *url, enum url_type_e type); int url_cmp(url_t const *a, url_t const *b); int url_cmp_all(url_t const *a, url_t const *b); isize_t url_param(char const *params, char const *tag, char value[], isize_t vlen); int url_has_param(url_t const *url, char const *name); int url_param_add(su_home_t *h, url_t *url, char const *param);
There are functions for handling -encoding used in URLs:
int url_reserved_p(char const *s); char *url_escape(char *d, char const *s, char const reserved[]); int url_esclen(char const *s, char const reserved[]); char *url_unescape(char *d, char const *s);
There are a few function and macros helping resolving URLs:
char const *url_port_default(enum url_type_e url_type); char const *url_tport_default(enum url_type_e url_type); char const *url_port(url_t const *u); #define URL_PORT(u)
In addition to the basic URL structure, url_t, the library interface provides an union type url_string_t for passing unparsed strings instead of parsed URLs as function arguments:
#define URL_STRING_P(u) ((u) && *((url_string_t*)(u))->us_str != 0) #define URL_IS_STRING(u) ((u) && *((url_string_t*)(u))->us_str != 0) int url_string_p(url_string_t const * url); int url_is_string(url_string_t const * url); #define URL_STRING_MAKE(s)
There are a macros for printf()-like formatting of URLs:
#define URL_PRINT_FORMAT #define URL_PRINT_ARGS(u)
These functions calculate MD5 digest of URL or contribute contents of the URL to MD5 sum:
void url_update(struct su_md5_t *md5, url_t const *url); void url_digest(void *hash, int hsize, url_t const *, char const *key);
SIP or SIPS URIs have some parameters that control transport of the request. In some cases, they should be detected and removed:
int url_have_transport(url_t const *u); int url_strip_transport(url_t *u);
Finally, there are functions used as building blocks for protocol parsers using URLs: