url  1.12.11devel
Sofia SIP User Agent Library - "url" - URL Module

Module Meta Information

The Sofia url module contains macros and functions for using URL datatype url_t, parsing and printing URLs.

Contact:\n Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Status:\n Sofia SIP Core library
License:\n LGPL

Using URL Library

The URL library provides URL datatype and helper functions related to it. There is URL parser, which separates the URL components to the url_t structure.

Note
Please note that we use terms URL and URI interchangeable.

The formal URI syntax is defined in the RFC 3986.

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

Converting a String to #url_t

The function url_make() converts a string to a freshly allocated url_t structure. The URL components are split into parts as shown above. The hex encoding using % is removed if the encoded character can syntactically be part of the field. For instance, "%41" is decoded as "A" in the user part, but "%40" (@) is left as is. (This is called canonization of the URL fields.)

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

the components are NUL-terminated, canonized and assigned to the structure as follows:

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.

Converting a String to #url_t

The function url_as_string() converts contents of url_t structure to a newly allocated string.

Functions and Macros in URL Module

The include file <sofia-sip/url.h> contains the types, function and macros of URL module. The functions and macros are listed here for the reference, too. The most important functions and macros for manipulating URLs are here:

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);
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:

Finally, there are functions used as building blocks for protocol parsers using URLs:

int url_d(url_t *url, char *s);
isize_t url_len(url_t const * url);
issize_t url_e(char buffer[], isize_t n, url_t const *url);
#define URL_E(buf, end, url)
isize_t url_xtra(url_t const * url);
issize_t url_dup(char *, isize_t , url_t *dst, url_t const *src);
#define URL_DUP(buf, end, dst, src)
su_home_t
SU_HOME_T su_home_t
url_digest
void url_digest(void *hash, int hsize, url_t const *, char const *key)
Calculate a digest from URL contents.
Definition: url.c:2083
url_reserved_p
int url_reserved_p(char const *s)
Test if string contains url-reserved characters.
Definition: url.c:163
url_tport_default
const char * url_tport_default(enum url_type_e url_type)
Return default transport name corresponding to the url type.
Definition: url.c:1833
url_string_p
int url_string_p(url_string_t const *url)
Test if a pointer to url_string_t is a string (not a pointer to a url_t structure).
Definition: url.c:1438
url_scheme
const char * url_scheme(enum url_type_e type)
Get URL scheme by type.
Definition: url.c:469
url_has_param
int url_has_param(url_t const *url, char const *name)
Check for a parameter.
Definition: url.c:1369
url_update
void url_update(struct su_md5_t *md5, url_t const *url)
Update MD5 sum with URL contents.
Definition: url.c:2067
url_t
URL structure.
Definition: url.h:70
url_d
int url_d(url_t *url, char *s)
Decode a URL.
Definition: url.c:788
url_make
url_t * url_make(su_home_t *h, char const *str)
Convert a string to a url struct.
Definition: url.c:1242
url_sip
@ url_sip
"sip:".
Definition: url.h:45
url_xtra
isize_t url_xtra(url_t const *url)
Calculate the size of srings attached to the url.
Definition: url.c:1047
url_port_default
const char * url_port_default(enum url_type_e url_type)
Return default port number corresponding to the url type.
Definition: url.c:1792
url_strip_transport
int url_strip_transport(url_t *u)
Strip transport-specific stuff away from URI.
Definition: url.c:1530
url_have_transport
int url_have_transport(url_t const *u)
Test if url has any transport-specific stuff.
Definition: url.c:1549
url_string_t
Type to present either a parsed URL or string.
Definition: url.h:99
url_cmp_all
int url_cmp_all(url_t const *a, url_t const *b)
Compare two URLs conservatively.
Definition: url.c:1695
url_sanitize
int url_sanitize(url_t *u)
Sanitize a URL.
Definition: url.c:1905
url_format
url_t * url_format(su_home_t *h, char const *fmt,...)
Convert a string formatting result to a url struct.
Definition: url.c:1248
url_param
isize_t url_param(char const *params, char const *tag, char value[], isize_t vlen)
Search for a parameter.
Definition: url.c:1317
url_init
void url_init(url_t *url, enum url_type_e type)
Init a url structure as given type.
Definition: url.c:509
url_dup
issize_t url_dup(char *, isize_t, url_t *dst, url_t const *src)
Duplicate the url in the provided memory area.
Definition: url.c:1119
url_port
const char * url_port(url_t const *u)
Return the URL port string, using default port if not present.
Definition: url.c:1874
url_hdup
url_t * url_hdup(su_home_t *h, url_t const *src)
Duplicate the url to memory allocated via home.
Definition: url.c:1221
url_param_add
int url_param_add(su_home_t *h, url_t *url, char const *param)
Add a parameter.
Definition: url.c:1375
url_e
issize_t url_e(char buffer[], isize_t n, url_t const *url)
Encode a URL.
Definition: url.c:877
url_unescape
char * url_unescape(char *d, char const *s)
Unescape a string.
Definition: url.c:320
url_len
isize_t url_len(url_t const *url)
Calculate the encoding length of URL.
Definition: url.c:1015
url_is_string
int url_is_string(url_string_t const *url)
Test if a pointer to url_string_t is a string (not a pointer to a url_t structure).
Definition: url.c:1443
url_as_string
char * url_as_string(su_home_t *home, url_t const *url)
Convert url_t to a string allocated from home.
Definition: url.c:1280
url_escape
char * url_escape(char *d, char const *s, char const reserved[])
Escape a string.
Definition: url.c:229
su_md5_t
url_esclen
isize_t url_esclen(char const *s, char const reserved[])
Calculate length of string when escaped.
Definition: url.c:198
url_type_e
url_type_e
Recognized URL schemes (value of url_t.url_type).
Definition: url.h:41
url_cmp
int url_cmp(url_t const *a, url_t const *b)
Compare two URLs lazily.
Definition: url.c:1569

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.