Sofia-SIP辅助文档十七 - Sofia SIP用户代理库 - "url" - URL模块

http://sofia-sip.sourceforge.net/refdocs/url/index.html，翻译自官网的这张网页。

模块元信息

Sofia url模块包括一些使用URL数据类型url_t的宏和函数，他们可以解析和打印URL。

联系人:

Pekka Pessi < Pekka.Pessi@nokia-email.address.hidden>

状态:

Sofia SIP Core library

许可:

LGPL

使用URL库

URL库提供了URL的数据类型以及与之相关的辅助函数。URL解析器可以将URL里的组件分离出来放入url_t结构体内。

注：

请注意我们认为URL和URI是可互相替换的术语。

正式的URI语法在RFC 3986里被严格定义。

URLs包括可打印ASCII字符集的一个子集。这个子集不包括空格和在基于文本的协议中通常用作分隔符的字符，例如< > # %和 " （双引号），这些字符的位置在ECMA-5中预留给了国家扩展。在US-ASCII中，这些字符是：{ } | \ ^ [ ] `。

还有九个字符在URI的某些部分有着特殊的含义。这些保留字符用来分隔URL中的各个语法部分。这些保留字符是：@ / ; ? & = + and $。

URL库能够理解两种URL语法。首先，基本语法，例如被用于ftp:，http:和rtsp:这些URL：

scheme ":" ["//" [ user [":" password ] "@"] host [":" port ] ] ["/" path ] ["?" query ] ["#" fragment ]

另一种，被用于mailto:，sip:，im:，tel和pres:等URL：

scheme ":" [ [ user [":" password ] "@"] host [":" port ] ] [";" params ] ["?" query ] ["#" fragment ]

注意url解析器会认为“*”是一个合法的URL。

例如：

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

字串转换成#url_t

url_make()函数可以将一个字串转换成新生成的url_t结构体。URL中的各个组件会被分离出来。如果十六进制表示法的编码字符在URL的这一部分是合法字符，那么就可以移出这个十六进制表示的字串。例如，"%41"被解码成"A"在user部分，但"%40" (@)不做任何转换。（This is called canonization of the URL fields.）

url_format()函数可以生成URL，它有着类似于printf()函数相似的格式化功能。

例如，当我们想从如下字串中生成一个URL

sip:joe%2Euser@example%2Ecom;method=%4D%45%53%53%41%47%45?body=CANNED%20MSG

各个组件是\0结束的，canonized，向如下所示赋给结构体：

 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

可以使用url_param()和url_have_param()函数得到url->url_params字串中的特定参数。

字串转换成#url_t

url_as_string()函数可以将一个url_t结构体转换成新生成的字串。

URL模块中的函数和宏

<sofia-sip/url.h>头文件中包括了URL模块的类型、函数和宏。函数和宏在这里展示作为参考。最重要的操作URL的函数和宏是：

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

这些是URL模块中用来处理编码的函数：

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

这是一些解析URL的函数和宏：

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)

除了基本的URL结构体url_t，库接口还提供联合体类型url_string_t用来作为参数传递未解析过的字串，而不是解析过的URL：

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

有一些类printf()函数的格式化宏：

#define URL_PRINT_FORMAT
#define URL_PRINT_ARGS(u)

这些函数会计算URL中的MD5 digest，或者将URL的内容转成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或SIPS的URI有一些参数用来控制请求的传输。有些情况下，他们应该被检测到和移出：

int url_have_transport(url_t const *u);
int url_strip_transport(url_t *u);

这些函数可作为使用URL库的协议解析器的构建块：

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)