url.h

Internet Phone, Chat, Conferencing

/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

/**@file url.h
 *
 * URL struct and helper functions.
 *
 * @author Pekka Pessi <[e-mail]>
 *
 * @date Created: Thu Jun  8 19:28:55 2000 ppessi
 */

#ifndef URL_H_TYPES
#define URL_H_TYPES

/** Recognized URL schemes (value of url_t.url_type). */
enum url_type_e {
  url_invalid = -2,		/**< Invalid url. */
  url_unknown = -1,		/**< Unknown scheme. */
  url_any = 0,			/**< @c "*" */
  url_sip,			/**< @c "sip:" */
  url_sips,			/**< @c "sips:" */
  url_tel,			/**< @c "tel:" */
  url_fax,			/**< @c "fax:" */
  url_modem,			/**< @c "modem:" */
  url_http,			/**< @c "http:" */
  url_https,			/**< @c "https:" */
  url_ftp,			/**< @c "ftp:" */
  url_file,			/**< @c "file:" */
  url_rtsp,			/**< @c "rtsp:" */
  url_rtspu,			/**< @c "rtspu:" */
  url_mailto,			/**< @c "mailto:" */
  url_im,			/**< @c "im:" (simple instant messaging) */
  url_pres,			/**< @c "pres:" (simple presence) */
  url_cid,			/**< @c "cid:" (Content-ID) */
  url_msrp,			/**< @c "msrp:" (message session relay)  */
  url_wv,			/**< @c "wv:" (Wireless village) */
  _url_none
};

/** URL structure. 
 * 
 * This structure is used to present a parsed URL.
 */
typedef struct {
  char                url_pad[sizeof(void *) - 2];   
				    /**< Zero pad for URL_STRING_P(). */
  signed char         url_type;	    /**< URL type (url_type_e). */
  char                url_root;	    /**< Nonzero if root "//" */
  char const         *url_scheme;   /**< URL type as string. */
  char const         *url_user;	    /**< User part */
  char const         *url_password; /**< Password */
  char const         *url_host;     /**< Host part */
  char const         *url_port;     /**< Port */
  char const         *url_path;     /**< Path part, starts with "/" */
  char const         *url_params;   /**< Parameters (separated by ;) */
  char const         *url_headers;  /**< Headers (separated by ? and &) */
  char const         *url_fragment; /**< Fragment (separated by #) */
} url_t;

enum { 
  /** Maximum size of a URL. */
  URL_MAXLEN = 65536
};

/** Type to present either a parsed URL or string.
 * 
 * The union type url_string_t is used to pass a parsed URL or string as a
 * parameter. The URL_STRING_P() checks if a passed pointer points to a
 * string or a parsed URL. Testing requires that the first character of the
 * string is nonzero. Use URL_STRING_MAKE() to properly cast a string
 * pointer as a pointer to url_string_t.
 */
typedef union {
  char  us_str[URL_MAXLEN];	/**< URL as a string. */
  url_t us_url[1];		/**< Parsed URL. */
} url_string_t;

#endif

#ifndef URL_H /** Defined when url.h has been included. */
#define URL_H

#ifndef SU_ALLOC_H
#include <sofia-sip/su_alloc.h>
#endif

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 : "*" }

/** Init an url as given type */
URL_DLL
void url_init(url_t *url, enum url_type_e type);

/** Get URL scheme. */
URL_DLL
char const *url_scheme(enum url_type_e type);

/** Decode an URL */
URL_DLL
int url_d(url_t *url, char *s);

/** Calculate the lengh of URL when encoded. */
URL_DLL
int url_len(url_t const * url);

/** Encode an URL. */
URL_DLL
int url_e(char buffer[], int n, url_t const *url);

/** 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))

/** Calculate the size of srings attached to the url. */
URL_DLL
int url_xtra(url_t const * url);

/** Duplicate the url */ 
URL_DLL
int url_dup(char *buf, int bufsize, 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), (buf) < (end) ? (end) - (buf) : 0, (dst), (src))

/** Duplicate the url to memory allocated via home */ 
URL_DLL
url_t *url_hdup(su_home_t *h, url_t const *src);

/** Convert an string to an url struct. */ 
URL_DLL
url_t *url_make(su_home_t *h, char const *str);

/** Convert a string formatting result to an url struct. */
url_t *url_format(su_home_t *h, char const *fmt, ...);

/** Convert @a url to a string allocated from @a home */
URL_DLL
char *url_as_string(su_home_t *home, url_t const *url);

/** Test if string contains url-reserved characters. */
URL_DLL
int url_reserved_p(char const *s);

/** Escape a string. */
URL_DLL
char *url_escape(char *d, char const *s, char const reserved[]);

/** Calculate length of string when escaped. */
URL_DLL
int url_esclen(char const *s, char const reserved[]);

/** Unescape an string */
URL_DLL
char *url_unescape(char *d, char const *s);

/** Search for a parameter. */
URL_DLL
int url_param(char const *params, char const *tag, char value[], int vlen);

/** Check for a parameter. */
URL_DLL
int url_has_param(url_t const *url, char const *name);

/** Check a parameter. */
URL_DLL
int url_have_param(char const *params, char const *tag);

/** Add an parameter. */
URL_DLL
int url_param_add(su_home_t *h, url_t *url, char const *param);

/** Compare two URLs. */
URL_DLL
int url_cmp(url_t const *a, url_t const *b);

/** Strip transport-specific stuff away from URI. */
URL_DLL
int url_strip_transport(url_t *u);

/** Test if url has any transport-specific stuff. */
URL_DLL
int url_have_transport(url_t const *u);

/** Return default port number corresponding to the url type. */
URL_DLL
char const *url_port_default(enum url_type_e url_type);

/** Return default transport name corresponding to the url type */
URL_DLL
char const *url_tport_default(enum url_type_e url_type);

/** Return the URL port string, using default port if not present. */
URL_DLL
char const *url_port(url_t const *u);

/** Return the URL port string, using default port if none present. */
#define URL_PORT(u) \
  ((u) && (u)->url_port ? (u)->url_port : \
  url_port_default((u) ? (u)->url_type : url_any))

/** 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)

/** Test if a pointer to #url_string_t is a string 
 * (not a pointer to a #url_t structure). */
#define URL_IS_STRING(u) ((u) && *((url_string_t*)(u))->us_str != 0)

/** Test if a pointer to #url_string_t is a string
 * (not a pointer to a #url_t structure). */
URL_DLL
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). */
URL_DLL
int url_is_string(url_string_t const * url);

/** Cast a string to a #url_string_t. @HI */
#define URL_STRING_MAKE(s) \
  ((url_string_t *)((s) && *((char *)(s)) ? (s) : NULL))

/** Sanitize a URL. */
int url_sanitize(url_t *u);

/** 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"
#define URL_FORMAT_STRING URL_PRINT_FORMAT

/** Argument list used when printing url with printf(). @HI */
#define URL_PRINT_ARGS(u) \
  (u)->url_scheme ? (u)->url_scheme : "",	\
  (u)->url_type != url_any && (u)->url_scheme && (u)->url_scheme[0] \
    ? ":" : "", \
  (u)->url_root && ((u)->url_host || (u)->url_user) ? "//" : "", \
  (u)->url_user ? (u)->url_user : "", \
  (u)->url_user && (u)->url_password ? ":" : "", \
  (u)->url_user && (u)->url_password ? (u)->url_password : "", \
  (u)->url_user && (u)->url_host ? "@" : "", \
  (u)->url_host ? (u)->url_host : "", \
  (u)->url_host && (u)->url_port ? ":" : "", \
  (u)->url_host && (u)->url_port ? (u)->url_port : "", \
  (u)->url_root && (u)->url_path ? "/" : "", \
  (u)->url_path ? (u)->url_path : "", \
  (u)->url_params ? ";" : "", (u)->url_params ? (u)->url_params : "", \
  (u)->url_headers ? "?" : "", (u)->url_headers ? (u)->url_headers : "", \
  (u)->url_fragment ? "#" : "", (u)->url_fragment ? (u)->url_fragment : ""

struct su_md5_t;

/** Update MD5 sum with URL contents. */
URL_DLL
void url_update(struct su_md5_t *md5, url_t const *url);

/** Calculate a digest from URL contents. */
URL_DLL
void url_digest(void *hash, int hsize, url_t const *url, char const *key);


SOFIA_END_DECLS
#endif