/**
 * Data source name (DSN) parsing implementation
 *
 * @file	platon/dsn/dsn.h
 * @author	Peter Rockai <yenar@platon.sk>
 * @version	\$Platon: libplaton/platon/dsn/dsn.h,v 1.2 2003/04/22 14:19:52 nepto Exp $
 * @date	2003

Data source name (DSN) is URL-like string used for uniquely defining data
sources (especially relational database managment systems).

To connect to a database through interface using data source name (DSN) as a
source specification, you have to create a valid DSN. This DSN consists in
the following parts:

@verbatim
phptype: Database backend used in PHP (i.e. mysql, odbc etc.)
dbsyntax: Database used with regards to SQL syntax etc.
protocol: Communication protocol to use (i.e. tcp, unix etc.)
hostspec: Host specification (hostname[:port])
database: Database to use on the DBMS server
username: User name for login
password: Password for login
proto_opts: Maybe used with protocol
@endverbatim

The format of the supplied DSN is in its fullest form:

@verbatim
phptype(dbsyntax)://username:password@protocol+hostspec/database
@endverbatim

Most variations are allowed:

@verbatim
phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database_name
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype(dbsyntax)
phptype
@endverbatim

You can also use a second DSN format:

@verbatim
phptype(syntax)://user:pass@protocol(proto_opts)/database
@endverbatim

Example 1: connect to database through a socket
@verbatim
mysql://user@unix(/path/to/socket)/pear
@endverbatim

Example 2: connect to database on a non standard port
@verbatim
pgsql://user:pass@word@tcp(localhost:5555)/pear
@endverbatim
*/

#ifndef _PLATON_DSN_DSN_H
#define _PLATON_DSN_DSN_H

#ifndef PLATON_FUNC
# define PLATON_FUNC(_name) _name
#endif
#ifndef PLATON_FUNC_STR
# define PLATON_FUNC_STR(_name) #_name
#endif

#ifdef __cplusplus
extern "C" {
#endif

	/**
	 * Structure with data source name (DSN) elements. When parsing DSN
	 * string, extracted options are stored here.
	 *
	 * @struct	dsn_elements <platon/dsn/dsn.h>
	 * @author	Ondrej Jombik <nepto@platon.sk>
	 * @version	\$Platon: libplaton/platon/dsn/dsn.h,v 1.2 2003/04/22 14:19:52 nepto Exp $
	 * @date	2002-2003
	 */
	struct dsn_elements
	{
		char *phptype;
		char *dbsyntax;
		char *username;
		char *password;
		char *protocol;
		char *hostspec;
		char *port;
		char *socket;
		char *database;
		char *query;
	};

	/**
	 * Frees dsn_elements structure members
	 *
	 * @param	el	pointer to dsn_elements structure
	 * @return	void
	 * @author	Ondrej Jombik <nepto@platon.sk>
	 */
	void dsn_free(struct dsn_elements *el);

	/**
	 * Compiles DSN string according to dsn_elements
	 *
	 * @param	el			pointer to dsn_elements structure
	 * @return	allocated DSN string or NULL on memory allocation failure
	 * @author	Ondrej Jombik <nepto@platon.sk>
	 *
	 * Note that this method is called dsn_glue() for compatibility with
	 * glueDSN() method in PEAR repostiry (see PDBPLUS application). More
	 * appropriate name would be dsn_compile() or something like this.
	 */
	char *dsn_glue(const struct dsn_elements *el);

	/**
	 * Parses DSN string into dsn_elements structure
	 *
	 * @param	input_dsn	data source name (DSN) string
	 * @retval	el			pointer to dsn_elements structure
	 * @return	1 on success, 0 on memory failure error
	 * @author	Peter Rockai <yenar@platon.sk>
	 */
	int dsn_parse(const char *input_dsn, struct dsn_elements *el);

#ifdef __cplusplus
}
#endif

#endif /* #ifndef _PLATON_DSN_DSN_H */