sofia-sip/url.h File Reference


Detailed Description

URL struct and helper functions.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>
Date:
Created: Thu Jun 8 19:28:55 2000 ppessi

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

Defines

#define URL_INIT_AS(type)
 Initializer for an url_t structure.
#define URL_E(buf, end, url)
 Encode an URL: use buf up to end.
#define URL_DUP(buf, end, dst, src)
 Duplicate the url: use buf up to end.
#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().

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_wv
}
 Recognized URL schemes (value of url_t.url_type). More...
enum  { URL_MAXLEN }

Functions

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


Define Documentation

#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:
buf Buffer for non-constant strings copied from src.
end End of buf.
dst Destination URL structure.  
src Source URL structure.
Returns:
The macro URL_DUP() returns pointer to first unused byte in the buffer buf.

#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) };

#define URL_PRINT_ARGS (  ) 

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().

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

Enumerator:
URL_MAXLEN  Maximum size of a URL.

enum url_type_e

Recognized URL schemes (value of url_t.url_type).

Enumerator:
url_invalid  Invalid url.
url_unknown  Unknown scheme.
url_any  "*"
url_sip  "sip:"
url_sips  "sips:"
url_tel  "tel:"
url_fax  "fax:"
url_modem  "modem:"
url_http  "http:"
url_https  "https:"
url_ftp  "ftp:"
url_file  "file:"
url_rtsp  "rtsp:"
url_rtspu  "rtspu:"
url_mailto  "mailto:"
url_im  "im:" (simple instant messaging)
url_pres  "pres:" (simple presence)
url_cid  "cid:" (Content-ID)
url_msrp  "msrp:" (message session relay)
url_wv  "wv:" (Wireless village)


Function Documentation

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

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.

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

Compare two URLs conservatively.

Compare all parts of URLs.

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

SOFIAPUBFUN int url_d ( url_t url,
char *  s 
)

Decode an URL.

This function decodes a URL string to a url_t structure.

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

SOFIAPUBFUN int url_dup ( char *  buf,
int  bufsize,
url_t dst,
url_t const *  src 
)

Duplicate the url.

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:
buf Buffer for non-constant strings copied from src.
bufsize Size of buf.
dst Destination URL structure.  
src Source URL structure.
Returns:
The function url_dup() returns number of characters required for duplicating the strings in str, or -1 if an error occurred.

SOFIAPUBFUN int url_e ( char  buffer[],
int  n,
url_t const *  url 
)

Encode an 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:
buffer memory area to store the encoded url.
n size of buffer.
url URL to be encoded.
Returns:
The function url_e() returns 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.

SOFIAPUBFUN 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:
d Destination buffer [OUT]
s String to be copied [IN]
reserved Array of reserved characters [IN]
Returns:
Pointer to the destination array.

SOFIAPUBFUN int url_esclen ( char const *  s,
char const   reserved[] 
)

Calculate length of string when escaped.

The function url_esclen() calculates the length of string s when the excluded or reserved characters in it have been escaped.

Parameters:
s String with reserved URL characters. [IN
reserved Optional array of reserved characters [IN]
Returns:
The function url_esclen() 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);
 }

SOFIAPUBFUN int url_have_param ( char const *  params,
char const *  tag 
)

Check a parameter.

Deprecated:
Bad grammar. Use url_has_param().

SOFIAPUBFUN int url_have_transport ( url_t const *  url  ) 

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:

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.

SOFIAPUBFUN 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:
home memory home used to allocate new url object
src pointer to URL (or string)
Returns:
The function url_hdup() returns a pointer to the newly allocated url_t structure, or NULL upon an error.

SOFIAPUBFUN int url_param ( char const *  params,
char const *  tag,
char  value[],
int  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))

Parameters:
params URL parameter string (excluding first semicolon)
tag parameter name
value string to which the parameter value is copied
vlen length of string reserved for value
Return values:
positive length of parameter value (including final NUL) if found
zero if not found.

SOFIAPUBFUN int url_reserved_p ( char const *  s  ) 

Test if string contains url-reserved characters.

Parameters:
s string to be searched
Return values:
0 if no reserved characters were found.
1 if a reserved character was found.

SOFIAPUBFUN int url_sanitize ( url_t 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:

Parameters:
url pointer 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.

SOFIAPUBFUN int url_strip_transport ( url_t url  ) 

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:

Note:
The url must be a pointer to a URL structure.

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.

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

Unescape an string.

The function url_unescape() copies the string pointed by s to the array pointed by 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:
d destination buffer
s string to be copied
Returns:
Pointer to the destination array.

SOFIAPUBFUN int url_xtra ( url_t const *  url  ) 

Calculate the size of srings attached to the url.

Parameters:
url pointer to a url_t structure or string
Returns:
Number of bytes for URL


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