url 1.12.11devel
Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions
url.h File Reference

URL struct and helper functions. More...

#include <sofia-sip/su_alloc.h>
Include dependency graph for url.h:

Go to the source code of this file.

Data Structures

struct  url_t
 URL structure. More...
 
union  url_string_t
 Type to present either a parsed URL or string. More...
 

Macros

#define URL_H
 Defined when <sofia-sip/url.h> has been included.
 
#define URL_INIT_AS(type)
 Initializer for an url_t structure.
 
#define URL_PORT(u)
 Return the URL port string, using default port if none present.
 
#define URL_STRING_P(u)
 Test if a pointer to url_string_t is a string (not a pointer to a url_t structure).
 
#define URL_IS_STRING(u)
 Test if a pointer to url_string_t is a string (not a pointer to a url_t structure).
 
#define URL_STRING_MAKE(s)
 Cast a string to a url_string_t.
 
#define URL_PRINT_FORMAT
 Format string used when printing url with printf().
 
#define URL_PRINT_ARGS(u)
 Argument list used when printing url with printf().
 
#define URL_E(buf, end, url)
 Encode a URL: use buf up to end.
 
#define URL_DUP(buf, end, dst, src)
 Duplicate the url: use buf up to end.
 

Enumerations

enum  url_type_e {
  url_invalid ,
  url_unknown ,
  url_any ,
  url_sip ,
  url_sips ,
  url_tel ,
  url_fax ,
  url_modem ,
  url_http ,
  url_https ,
  url_ftp ,
  url_file ,
  url_rtsp ,
  url_rtspu ,
  url_mailto ,
  url_im ,
  url_pres ,
  url_cid ,
  url_msrp ,
  url_msrps ,
  url_wv ,
  _url_none
}
 Recognized URL schemes (value of url_t.url_type). More...
 
enum  { URL_MAXLEN }
 

Functions

url_turl_make (su_home_t *h, char const *str)
 Convert a string to a url struct.
 
url_turl_format (su_home_t *h, char const *fmt,...)
 Convert a string formatting result to a url struct.
 
char * url_as_string (su_home_t *home, url_t const *url)
 Convert url_t to a string allocated from home.
 
url_turl_hdup (su_home_t *h, url_t const *src)
 Duplicate the url to memory allocated via home.
 
int url_sanitize (url_t *u)
 Sanitize a URL.
 
char const * url_scheme (enum url_type_e type)
 Get URL scheme by type.
 
int url_cmp (url_t const *a, url_t const *b)
 Compare two URLs lazily.
 
int url_cmp_all (url_t const *a, url_t const *b)
 Compare two URLs conservatively.
 
isize_t url_param (char const *params, char const *tag, char value[], isize_t vlen)
 Search for a parameter.
 
int url_has_param (url_t const *url, char const *name)
 Check for a parameter.
 
isize_t url_have_param (char const *params, char const *tag)
 Check for a presence of a parameter in string.
 
int url_param_add (su_home_t *h, url_t *url, char const *param)
 Add a parameter.
 
int url_strip_transport (url_t *u)
 Strip transport-specific stuff away from URI.
 
char * url_strip_param_string (char *params, char const *name)
 Strip parameter away from URI.
 
int url_have_transport (url_t const *u)
 Test if url has any transport-specific stuff.
 
char * url_query_as_header_string (su_home_t *home, char const *query)
 Convert a URL query to a header string.
 
int url_reserved_p (char const *s)
 Test if string contains url-reserved characters.
 
char * url_escape (char *d, char const *s, char const reserved[])
 Escape a string.
 
isize_t url_esclen (char const *s, char const reserved[])
 Calculate length of string when escaped.
 
size_t url_unescape_to (char *d, char const *s, size_t n)
 Unescape characters from string.
 
char * url_unescape (char *d, char const *s)
 Unescape a string.
 
void url_init (url_t *url, enum url_type_e type)
 Init a url structure as given type.
 
char const * url_port_default (enum url_type_e url_type)
 Return default port number corresponding to the url type.
 
char const * url_tport_default (enum url_type_e url_type)
 Return default transport name corresponding to the url type.
 
char const * url_port (url_t const *u)
 Return the URL port string, using default port if not present.
 
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).
 
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).
 
void url_update (struct su_md5_t *md5, url_t const *url)
 Update MD5 sum with URL contents.
 
void url_digest (void *hash, int hsize, url_t const *, char const *key)
 Calculate a digest from URL contents.
 
int url_d (url_t *url, char *s)
 Decode a URL.
 
isize_t url_len (url_t const *url)
 Calculate the encoding length of URL.
 
issize_t url_e (char buffer[], isize_t n, url_t const *url)
 Encode a URL.
 
isize_t url_xtra (url_t const *url)
 Calculate the size of srings attached to the url.
 
issize_t url_dup (char *, isize_t, url_t *dst, url_t const *src)
 Duplicate the url in the provided memory area.
 

Detailed Description

URL struct and helper functions.

Author
Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com
Date
Created: Thu Jun 8 19:28:55 2000 ppessi

Macro Definition Documentation

◆ URL_DUP

#define URL_DUP (   buf,
  end,
  dst,
  src 
)

Duplicate the url: use buf up to end.

The macro URL_DUP() duplicates the url. The non-constant strings in src are copied to buf. However, no strings are copied past end. In other words, the size of buffer is end - buf.

The macro updates the buffer pointer buf, so that it points to the first unused byte in the buffer. The buffer pointer buf is updated, even if the buffer is too small for the duplicated strings.

Parameters
bufBuffer for non-constant strings copied from src.
endEnd of buf.
dstDestination URL structure.
srcSource URL structure.
Returns
The macro URL_DUP() returns pointer to first unused byte in the buffer buf.

◆ URL_E

#define URL_E (   buf,
  end,
  url 
)

Encode a URL: use buf up to end.

Encode an URL: use buf up to end.

◆ URL_INIT_AS

#define URL_INIT_AS (   type)

Initializer for an url_t structure.

The macro URL_INIT_AS() is used to initialize a url_t structure with a known url type:

url_t urls[2] = { URL_INIT_AS(sip), URL_INIT_AS(http) };
URL structure.
Definition url.h:70
#define URL_INIT_AS(type)
Initializer for an url_t structure.
Definition url.h:206

◆ URL_PRINT_ARGS

#define URL_PRINT_ARGS (   u)

Argument list used when printing url with printf().

The macro URL_PRINT_ARGS() is used to create a stdarg list for printf() or similar printing functions. Using it, a URL can be printed like this:

printf("%s received URL " URL_PRINT_FORMAT "\n",
my_name, URL_PRINT_ARGS(url));
#define URL_PRINT_FORMAT
Format string used when printing url with printf().
Definition url.h:256
#define URL_PRINT_ARGS(u)
Argument list used when printing url with printf().
Definition url.h:260

◆ URL_PRINT_FORMAT

#define URL_PRINT_FORMAT

Format string used when printing url with printf().

The macro URL_PRINT_FORMAT is used in format string of printf() or similar printing functions. A URL can be printed like this:

printf("%s received URL " URL_PRINT_FORMAT "\n",
my_name, URL_PRINT_ARGS(url));

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
URL_MAXLEN 

Maximum size of a URL.

◆ url_type_e

enum url_type_e

Recognized URL schemes (value of url_t.url_type).

See also
<http://www.iana.org/assignments/uri-schemes.html>
Enumerator
url_invalid 

Invalid url.

url_unknown 

Unknown scheme.

url_any 

"*"

url_sip 

"sip:".

See also
RFC 3261
url_sips 

"sips:".

See also
RFC 3261
url_tel 

"tel:"

See also
RFC3966
url_fax 

"fax:".

Note
Obsolete.
See also
RFC 2806
url_modem 

"modem:".

Note
Obsolete.
See also
RFC 2806
url_http 

"http:".

See also
RFC 2616, RFC 3986
url_https 

"https:".

See also
RFC 2618, RFC 3986
url_ftp 

"ftp:".

See also
RFC 1738
url_file 

"file:"

See also
RFC 1738
url_rtsp 

"rtsp:"

See also
RFC 2326
url_rtspu 

"rtspu:"

See also
RFC 2326
url_mailto 

"mailto:"

See also
RFC 2368
url_im 

"im:" (simple instant messaging).

See also
RFC 3860
url_pres 

"pres:" (simple presence).

See also
RFC 3859
url_cid 

"cid:" (Content-ID).

See also
RFC 2392
url_msrp 

"msrp:" (message session relay)

url_msrps 

"msrps:" (new in 1.12.2)

url_wv 

"wv:" (Wireless village)

Function Documentation

◆ url_as_string()

char * url_as_string ( su_home_t home,
url_t const *  url 
)

Convert url_t to a string allocated from home.

Convert url_t to a string allocated from home.

Parameters
homememory home to allocate the new string
urlurl to convert to string

The url can be a string, too.

Returns
Newly allocated conversion result, or NULL upon an error.

◆ url_cmp()

int url_cmp ( url_t const *  a,
url_t const *  b 
)

Compare two URLs lazily.

Compare two URLs lazily.

Compare essential parts of URLs: schema, host, port, and username.

any_url compares 0 with any other URL.

pres: and im: URIs compares 0 with SIP URIs.

Note
The a and b must be pointers to URL structures.
Currently, the url parameters are not compared. This is because the url_cmp() is used to sort URLs: taking parameters into account makes that impossible.

◆ url_cmp_all()

int url_cmp_all ( url_t const *  a,
url_t const *  b 
)

Compare two URLs conservatively.

Compare two URLs conservatively.

Compare all parts of URLs.

Note
The a and b must be pointers to URL structures.

◆ url_d()

int url_d ( url_t url,
char *  s 
)

Decode a URL.

This function decodes a URL string to a url_t structure.

Parameters
urlstructure to store the parsing result
sNUL-terminated string to be parsed
Note
The parsed string s will be modified when parsing it.
Return values
0if successful,
-1otherwise.

◆ url_dup()

issize_t url_dup ( char *  buf,
isize_t  bufsize,
url_t dst,
url_t const *  src 
)

Duplicate the url in the provided memory area.

Duplicate the url in the provided memory area.

The function url_dup() copies the url structure src and the strings attached to it to url. The non-constant strings in src are copied to buf. If the size of duplicated strings exceed bufsize, the corresponding string fields in url are set to NULL.

The calling function can calculate the size of buffer required by calling url_dup() with zero as bufsize and NULL as dst.

Parameters
bufBuffer for non-constant strings copied from src.
bufsizeSize of buf.
dstDestination URL structure.
srcSource URL structure.
Returns
Number of characters required for duplicating the strings in str, or -1 if an error occurred.

◆ url_e()

issize_t url_e ( char  buffer[],
isize_t  n,
url_t const *  url 
)

Encode a URL.

Encode a URL.

The function url_e() combines a URL from substrings in url_t structure according the URL syntax presented above. The encoded url is stored in a buffer of n bytes.

Parameters
buffermemory area to store the encoded url.
nsize of buffer.
urlURL to be encoded.
Returns
Return the number of bytes in the encoding.
Note
The function follows the convention set by C99 snprintf(). Even if the result does not fit into the buffer and it is truncated, the function returns the number of bytes in an untruncated encoding.

◆ url_escape()

char * url_escape ( char *  d,
char const *  s,
char const  reserved[] 
)

Escape a string.

The function url_escape() copies the string pointed by s to the array pointed by d, excluding the terminating \0 character. All reserved characters in s are copied in hexadecimal format, for instance, "$%#" is copied as "%24%25%23". The destination array d must be large enough to receive the escaped copy.

Parameters
dDestination buffer [OUT]
sString to be copied [IN]
reservedArray of reserved characters [IN]
Returns
Pointer to the destination array.

◆ url_esclen()

isize_t url_esclen ( char const *  s,
char const  reserved[] 
)

Calculate length of string when escaped.

Calculate length of string when escaped.

Calculate the length of string s when the excluded or reserved characters in it have been escaped.

Parameters
sString with reserved URL characters. [IN
reservedOptional array of reserved characters [IN]
Returns
The number of characters in corresponding but escaped string.

You can handle a part of URL with reserved characters like this:

if (url_reserved_p(s)) {
n = malloc(url_esclen(s, NULL) + 1);
if (n) url_escape(n, s);
} else {
n = malloc(strlen(s) + 1);
if (n) strcpy(n, s);
}
char * url_escape(char *d, char const *s, char const reserved[])
Escape a string.
Definition url.c:229
isize_t url_esclen(char const *s, char const reserved[])
Calculate length of string when escaped.
Definition url.c:198
int url_reserved_p(char const *s)
Test if string contains url-reserved characters.
Definition url.c:163

◆ url_format()

url_t * url_format ( su_home_t h,
char const *  fmt,
  ... 
)

Convert a string formatting result to a url struct.

Convert a string formatting result to a url struct.

◆ url_have_param()

isize_t url_have_param ( char const *  params,
char const *  tag 
)

Check for a presence of a parameter in string.

Check for a presence of a parameter in string.

Deprecated:
Bad grammar. Use url_has_param().

◆ url_have_transport()

int url_have_transport ( url_t const *  url)

Test if url has any transport-specific stuff.

Test if url has any transport-specific stuff.

The function url_have_transport() tests if there are transport-specific parameters in a SIP or SIPS URI. These parameters include:

  • the port number
  • "maddr=" parameters
  • "transport=" parameters
Note
The url must be a pointer to a URL structure.
Returns
The function url_have_transport() returns true, if the URL contains transport parameters, false otherwise.

◆ url_hdup()

url_t * url_hdup ( su_home_t home,
url_t const *  src 
)

Duplicate the url to memory allocated via home.

The function url_hdup() duplicates (deep copies) an url_t structure. Alternatively, it can be passed a string; string is then copied and parsed to the url_t structure.

The function url_hdup() allocates the destination structure from home as a single memory block. It is possible to free the copied url structure and all the associated strings using a single call to su_free().

Parameters
homememory home used to allocate new url object
srcpointer to URL (or string)
Returns
The function url_hdup() returns a pointer to the newly allocated url_t structure, or NULL upon an error.

◆ url_init()

void url_init ( url_t url,
enum url_type_e  type 
)

Init a url structure as given type.

Init a url structure as given type.

◆ url_len()

isize_t url_len ( url_t const *  url)

Calculate the encoding length of URL.

Calculate the encoding length of URL.

◆ url_make()

url_t * url_make ( su_home_t h,
char const *  str 
)

Convert a string to a url struct.

Convert a string to a url struct.

◆ url_param()

isize_t url_param ( char const *  params,
char const *  tag,
char  value[],
isize_t  vlen 
)

Search for a parameter.

This function searches for a parameter from a parameter list.

If you want to test if there is parameter user=phone, call this function like

if (url_param(url->url_param, "user=phone", NULL, 0))
isize_t url_param(char const *params, char const *tag, char value[], isize_t vlen)
Search for a parameter.
Definition url.c:1317
Parameters
paramsURL parameter string (excluding first semicolon)
tagparameter name
valuestring to which the parameter value is copied
vlenlength of string reserved for value
Return values
positivelength of parameter value (including final NUL) if found
zeroif not found.

◆ url_param_add()

int url_param_add ( su_home_t h,
url_t url,
char const *  param 
)

Add a parameter.

Add a parameter.

◆ url_port()

char const * url_port ( url_t const *  u)

Return the URL port string, using default port if not present.

Return the URL port string, using default port if not present.

◆ url_query_as_header_string()

char * url_query_as_header_string ( su_home_t home,
char const *  query 
)

Convert a URL query to a header string.

URL query is converted by replacing each "=" in header name "=" value pair with semicolon (":"), and the "&" separating header-name-value pairs with line feed ("\n"). The "body" pseudoheader is moved last in the string. The %-escaping is removed. Note that if the query contains %00, the resulting string will be truncated.

Parameters
homememory home used to alloate string (if NULL, malloc() it)
queryquery part from SIP URL

The result string is allocated from home, and it can be used as argument to msg_header_parse_str(), msg_header_add_str() or SIPTAG_HEADER_STR().

See also
msg_header_add_str(), SIPTAG_HEADER_STR(), sip_headers_as_url_query(), sip_url_query_as_taglist(), RFC 3261 section 19.1.1 "Headers", url_t, url_s::url_headers, url_unescape(), url_unescape_to()
Since
New in 1.12.4.

◆ url_reserved_p()

int url_reserved_p ( char const *  s)

Test if string contains url-reserved characters.

Test if string contains url-reserved characters.

Parameters
sstring to be searched
Return values
0if no reserved characters were found.
lif a reserved character was found.

◆ url_sanitize()

int url_sanitize ( url_t url)

Sanitize a URL.

Sanitize a URL.

The function url_sanitize() adds a scheme to an incomplete URL. It modifies its parameter structure url. Currently, the function follows simple heuristics:

  • URL with host name starting with ftp. is an FTP URL
  • URL with host name starting with www. is an HTTP URL
  • URL with host and path, e.g., host/foo;bar, is an HTTP URL
  • URL with host name, no path is a SIP URL.
Parameters
urlpointer to URL struct to be sanitized (IN/OUT)
Returns
The function url_sanitize() returns 0 if it considers URL to be sane, and -1 otherwise.

◆ url_scheme()

char const * url_scheme ( enum url_type_e  url_type)

Get URL scheme by type.

Get URL scheme by type.

◆ url_strip_param_string()

char * url_strip_param_string ( char *  params,
char const *  name 
)

Strip parameter away from URI.

Strip parameter away from URI.

Remove a named parameter and its possible value from the URL parameter string (url_s#url_param).

Returns
Pointer to modified string, or NULL if nothing is left in there.

◆ url_strip_transport()

int url_strip_transport ( url_t url)

Strip transport-specific stuff away from URI.

Strip transport-specific stuff away from URI.

The function url_strip_transport() removes transport-specific parameters from a SIP or SIPS URI. These parameters include:

  • the port number
  • "maddr=" parameter
  • "transport=" parameter
  • "ttl=" parameter
  • "method=" parameter
Note
The url must be a pointer to a URL structure. It is stripped in-place.
If the parameter string contains empty parameters, they are stripped, too.
Returns
The function url_strip_transport() returns true, if the URL was modified, false otherwise.

◆ url_unescape()

char * url_unescape ( char *  d,
char const *  s 
)

Unescape a string.

Unescape a string.

Unescape string s to the buffer d, including the terminating \0 character. All %-escaped triplets in s are unescaped, for instance, "%40%25%23" is copied as "@%#". The destination array d must be large enough to receive the escaped copy.

Parameters
ddestination buffer
sstring to be copied
Returns
Pointer to the destination buffer.

◆ url_unescape_to()

size_t url_unescape_to ( char *  d,
char const *  s,
size_t  n 
)

Unescape characters from string.

Unescape characters from string.

Unescape n characters from string s to the buffer d, including the terminating \0 character. All %-escaped triplets in s are unescaped, for instance, "%40%25%23" is copied as "@%#". The destination array d must be large enough to receive the escaped copy (n bytes is always enough).

Parameters
ddestination buffer
sstring to be unescaped
nmaximum number of characters to unescape
Returns
Length of unescaped string
Since
New in 1.12.4.

◆ url_update()

void url_update ( su_md5_t md5,
url_t const *  url 
)

Update MD5 sum with URL contents.

Update MD5 sum with URL contents.

◆ url_xtra()

isize_t url_xtra ( url_t const *  url)

Calculate the size of srings attached to the url.

Calculate the size of srings attached to the url.

Parameters
urlpointer to a url_t structure or string
Returns
Number of bytes for URL

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