Skip to content

GitLab

Commit 42cf49ae authored by Pekka Pessi's avatar Pekka Pessi
Browse files

url: updated doxygen documentation. 

darcs-hash:20060918145527-65a35-4c82ffc4b1eed5df84d73d408483f811d2e39b5f.gz
parent d7d6eca1
Hide whitespace changes
Inline Side-by-side
Showing with 190 additions and 107 deletions
libsofia-sip-ua/url/sofia-sip/url.h
View file @ 42cf49ae
......@@ -110,57 +110,57 @@ typedef union {
SOFIA_BEGIN_DECLS
/** Initializer for an #url_t structure. @HI
*
* The macro URL_INIT_AS() is used to initialize a #url_t structure with a
* known url type:
* @code
* url_t urls[2] = { URL_INIT_AS(sip), URL_INIT_AS(http) };
* @endcode
*/
#define URL_INIT_AS(type) \
{ "\0\0", url_##type, 0, url_##type != url_any ? #type : "*" }
/** Convert a string to a url struct. */
SOFIAPUBFUN url_t *url_make(su_home_t *h, char const *str);
/** Init an url as given type */
SOFIAPUBFUN void url_init(url_t *url, enum url_type_e type);
/** Convert a string formatting result to a url struct. */
SOFIAPUBFUN url_t *url_format(su_home_t *h, char const *fmt, ...);
/** Convert #url_t to a string allocated from @a home */
SOFIAPUBFUN char *url_as_string(su_home_t *home, url_t const *url);
/** Duplicate the url to memory allocated via home */
SOFIAPUBFUN url_t *url_hdup(su_home_t *h, url_t const *src);
/** Sanitize a URL. */
SOFIAPUBFUN int url_sanitize(url_t *u);
/** Get URL scheme. */
/** Get URL scheme by type. */
SOFIAPUBFUN char const *url_scheme(enum url_type_e type);
/** Decode an URL */
SOFIAPUBFUN int url_d(url_t *url, char *s);
/* ---------------------------------------------------------------------- */
/* URL comparison */
/** Calculate the lengh of URL when encoded. */
SOFIAPUBFUN isize_t url_len(url_t const * url);
/** Compare two URLs lazily. */
SOFIAPUBFUN int url_cmp(url_t const *a, url_t const *b);
/** Encode an URL. */
SOFIAPUBFUN issize_t url_e(char buffer[], isize_t n, url_t const *url);
/** Compare two URLs conservatively. */
SOFIAPUBFUN int url_cmp_all(url_t const *a, url_t const *b);
/** Encode an URL: use @a buf up to @a end. @HI */
#define URL_E(buf, end, url) \
(buf) += url_e((buf), (buf) < (end) ? (end) - (buf) : 0, (url))
/* ---------------------------------------------------------------------- */
/* Parameter handling */
/** Calculate the size of srings attached to the url. */
SOFIAPUBFUN isize_t url_xtra(url_t const * url);
/** Search for a parameter. */
SOFIAPUBFUN isize_t url_param(char const *params, char const *tag,
char value[], isize_t vlen);
/** Duplicate the url */
SOFIAPUBFUN issize_t url_dup(char *, isize_t , url_t *dst, url_t const *src);
/** Check for a parameter. */
SOFIAPUBFUN int url_has_param(url_t const *url, char const *name);
/** Duplicate the url: use @a buf up to @a end. @HI */
#define URL_DUP(buf, end, dst, src) \
(buf) += url_dup((buf), (isize_t)((buf) < (end) ? (end) - (buf) : 0), (dst), (src))
/** Check for a presence of a parameter. */
SOFIAPUBFUN isize_t url_have_param(char const *params, char const *tag);
/** Duplicate the url to memory allocated via home */
SOFIAPUBFUN url_t *url_hdup(su_home_t *h, url_t const *src);
/** Add a parameter. */
SOFIAPUBFUN int url_param_add(su_home_t *h, url_t *url, char const *param);
/** Convert an string to an url struct. */
SOFIAPUBFUN url_t *url_make(su_home_t *h, char const *str);
/** Strip transport-specific stuff away from URI. */
SOFIAPUBFUN int url_strip_transport(url_t *u);
/** Convert a string formatting result to an url struct. */
url_t *url_format(su_home_t *h, char const *fmt, ...);
/** Test if url has any transport-specific stuff. */
SOFIAPUBFUN int url_have_transport(url_t const *u);
/** Convert @a url to a string allocated from @a home */
SOFIAPUBFUN char *url_as_string(su_home_t *home, url_t const *url);
/* ---------------------------------------------------------------------- */
/* Handling url-escque strings */
/** Test if string contains url-reserved characters. */
SOFIAPUBFUN int url_reserved_p(char const *s);
......@@ -171,33 +171,28 @@ SOFIAPUBFUN char *url_escape(char *d, char const *s, char const reserved[]);
/** Calculate length of string when escaped. */
SOFIAPUBFUN int url_esclen(char const *s, char const reserved[]);
/** Unescape an string */
/** Unescape a string */
SOFIAPUBFUN char *url_unescape(char *d, char const *s);
/** Search for a parameter. */
SOFIAPUBFUN isize_t url_param(char const *params, char const *tag,
char value[], isize_t vlen);
/** Check for a parameter. */
SOFIAPUBFUN int url_has_param(url_t const *url, char const *name);
/** Check a parameter. */
SOFIAPUBFUN isize_t url_have_param(char const *params, char const *tag);
/* ---------------------------------------------------------------------- */
/* Initializing */
/** Add an parameter. */
SOFIAPUBFUN int url_param_add(su_home_t *h, url_t *url, char const *param);
/** Compare two URLs lazily. */
SOFIAPUBFUN int url_cmp(url_t const *a, url_t const *b);
/** Compare two URLs conservatively. */
SOFIAPUBFUN int url_cmp_all(url_t const *a, url_t const *b);
/** Initializer for an #url_t structure. @HI
*
* The macro URL_INIT_AS() is used to initialize a #url_t structure with a
* known url type:
* @code
* url_t urls[2] = { URL_INIT_AS(sip), URL_INIT_AS(http) };
* @endcode
*/
#define URL_INIT_AS(type) \
{ "\0\0", url_##type, 0, url_##type != url_any ? #type : "*" }
/** Strip transport-specific stuff away from URI. */
SOFIAPUBFUN int url_strip_transport(url_t *u);
/** Init a url structure as given type */
SOFIAPUBFUN void url_init(url_t *url, enum url_type_e type);
/** Test if url has any transport-specific stuff. */
SOFIAPUBFUN int url_have_transport(url_t const *u);
/* ---------------------------------------------------------------------- */
/* Resolving helpers */
/** Return default port number corresponding to the url type. */
SOFIAPUBFUN char const *url_port_default(enum url_type_e url_type);
......@@ -213,6 +208,9 @@ SOFIAPUBFUN char const *url_port(url_t const *u);
((u) && (u)->url_port ? (u)->url_port : \
url_port_default((u) ? (u)->url_type : url_any))
/* ---------------------------------------------------------------------- */
/* url_string_t handling */
/** Test if a pointer to #url_string_t is a string
* (not a pointer to a #url_t structure). */
#define URL_STRING_P(u) ((u) && *((url_string_t*)(u))->us_str != 0)
......@@ -233,8 +231,8 @@ SOFIAPUBFUN int url_is_string(url_string_t const * url);
#define URL_STRING_MAKE(s) \
((url_string_t *)((s) && *((char *)(s)) ? (s) : NULL))
/** Sanitize a URL. */
SOFIAPUBFUN int url_sanitize(url_t *u);
/* ---------------------------------------------------------------------- */
/* Printing URL */
/** Format string used when printing url with printf(). @HI */
#define URL_PRINT_FORMAT "%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s%s"
......@@ -259,6 +257,9 @@ SOFIAPUBFUN int url_sanitize(url_t *u);
(u)->url_headers ? "?" : "", (u)->url_headers ? (u)->url_headers : "", \
(u)->url_fragment ? "#" : "", (u)->url_fragment ? (u)->url_fragment : ""
/* ---------------------------------------------------------------------- */
/* URL digests */
struct su_md5_t;
/** Update MD5 sum with URL contents. */
......@@ -268,6 +269,31 @@ SOFIAPUBFUN void url_update(struct su_md5_t *md5, url_t const *url);
SOFIAPUBFUN void url_digest(void *hash, int hsize,
url_t const *, char const *key);
/* ---------------------------------------------------------------------- */
/* Parsing and manipulating URLs */
/** Decode a URL. */
SOFIAPUBFUN int url_d(url_t *url, char *s);
/** Calculate the encoding length of URL. */
SOFIAPUBFUN isize_t url_len(url_t const * url);
/** Encode a URL. */
SOFIAPUBFUN issize_t url_e(char buffer[], isize_t n, url_t const *url);
/** Encode a URL: use @a buf up to @a end. @HI */
#define URL_E(buf, end, url) \
(buf) += url_e((buf), (buf) < (end) ? (end) - (buf) : 0, (url))
/** Calculate the size of srings attached to the url. */
SOFIAPUBFUN isize_t url_xtra(url_t const * url);
/** Duplicate the url in the provided memory area. */
SOFIAPUBFUN issize_t url_dup(char *, isize_t , url_t *dst, url_t const *src);
/** Duplicate the url: use @a buf up to @a end. @HI */
#define URL_DUP(buf, end, dst, src) \
(buf) += url_dup((buf), (isize_t)((buf) < (end) ? (end) - (buf) : 0), (dst), (src))
SOFIA_END_DECLS
#endif
......
libsofia-sip-ua/url/url.c
View file @ 42cf49ae
......@@ -145,6 +145,8 @@ static char *url_canonize2(char *d, char const *s, size_t n,
static int url_tel_cmp_numbers(char const *A, char const *B);
/**Test if string contains excluded or url-reserved characters.
*
*
*
* @param s string to be searched
*
......@@ -164,17 +166,16 @@ int url_reserved_p(char const *s)
return 0;
}
/** Calculate length of string escaped.
/** Calculate length of string when escaped with %-notation.
*
* The function url_esclen() calculates the length of string @a s when
* the excluded or reserved characters in it have been escaped.
* Calculate the length of string @a s when the excluded or reserved
* characters in it have been escaped.
*
* @param s String with reserved URL characters. [IN
* @param reserved Optional array of reserved characters [IN]
*
* @return
* The function url_esclen() returns the number of characters in
* corresponding but escaped string.
* The number of characters in corresponding but escaped string.
*
* You can handle a part of URL with reserved characters like this:
* @code
......@@ -186,7 +187,6 @@ int url_reserved_p(char const *s)
* if (n) strcpy(n, s);
* }
* @endcode
*
*/
int url_esclen(char const *s, char const reserved[])
{
......@@ -260,7 +260,7 @@ char *url_escape(char *d, char const *s, char const reserved[])
* @param d destination buffer
* @param s string to be copied
*
* @return Pointer to the destination array.
* @return Pointer to the destination buffer.
*/
char *url_unescape(char *d, char const *s)
{
......@@ -355,7 +355,11 @@ char *url_canonize2(char *d, char const *s, size_t n,
}
/** Canonize a URL component (with precomputed mask) */
/** Canonize a URL component (with precomputed mask).
*
* This version does not flag error if *s contains character that should
* be escaped.
*/
static
char *url_canonize3(char *d, char const *s, size_t n,
unsigned m32, unsigned m64, unsigned m96)
......@@ -1359,7 +1363,7 @@ int url_strip_transport2(url_t *url, int modify)
* - "method=" parameter
*
* @note
* The @a url must be a pointer to a URL structure.
* The @a url must be a pointer to a URL structure. It is stripped in-place.
*
* @note
* If the parameter string contains empty parameters, they are stripped, too.
......
libsofia-sip-ua/url/url.docs
View file @ 42cf49ae
......@@ -63,14 +63,17 @@ tel:+358718008000
@subsection url_parsing Converting a String to #url_t
The decoding function url_d() takes a string and splits it into parts as
shown above. The substrings are stored into the ##url_t structure. When
decoding, the hex encoding using \% is removed if the encoded character can
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.)
For example, when we parse the url below
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
@code
sip:joe%2Euser@example%2Ecom;method=%4D%45%53%53%41%47%45?body=CANNED%20MSG
@endcode
......@@ -90,47 +93,97 @@ as follows:
url_fragment = NULL
@endcode
Other functions parsing URLs are as follows:
- url_hdup() (it takes a string as @a url parameter)
You can use the function url_param() and url_have_param() to access
particular parameters from @ref url_t::url_params "url->url_params" string.
@subsection url_parsing Converting a #url_t structure to string
The url_e() encodes the url, in other words, it joins the substrings in
#url_t to the provided buffer.
The function url_as_string() converts contents of #url_t structure to a
newly allocated string.
@subsection url_reference Functions and Macros in URL Module
The @b url parsing, printing, copying and access functions are defined in
the url.h include file:
- url_d()
- url_len()
- url_e()
- url_xtra()
- url_dup()
- url_hdup()
- url_as_string()
- url_reserved_p()
- url_esclen()
- url_escape()
- url_unescape()
- url_param()
- url_param_add()
- url_cmp()
- url_strip_transport()
- url_have_transport()
- url_port()
- url_sanitize()
- url_update()
- url_digest()
The include file <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:
@code
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);
isize_t url_have_param(char const *params, char const *tag);
int url_param_add(su_home_t *h, url_t *url, char const *param);
@endcode
There are functions for handling %-encoding used in URLs:
@code
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);
@endcode
There are a few function and macros helping resolving URLs:
@code
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)
@endcode
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:
- url_string_p()
- URL_STRING_P()
- URL_STRING_MAKE()
@code
#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)
@endcode
There are a macros for printf()-like formatting of URLs:
@code
#define URL_PRINT_FORMAT
#define URL_PRINT_ARGS(u)
@endcode
These functions calculate MD5 digest of URL or contribute contents of the
URL to MD5 sum:
@code
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);
@endcode
SIP or SIPS URIs have some parameters that control transport of the request.
In some cases, they should be detected and removed:
@code
int url_have_transport(url_t const *u);
int url_strip_transport(url_t *u);
@endcode
Finally, there are functions used as building blocks for protocol parsers
using URLs:
@code
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)
@endcode
For printf()-style formatting, macros #URL_PRINT_FORMAT and
URL_PRINT_ARGS() are provided.
*/
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment