cddb_conn.h File Reference

#include <stdio.h>
#include <netinet/in.h>
#include "cddb/cddb_site.h"

Go to the source code of this file.

Defines

#define CDDB_CONN_H   1

#define SEARCHCAT(c)   (1 << (c))

Macro to be used for building the category search bit-string from the values of cddb_cat_t.

Typedefs

typedef cddb_iconv_s * cddb_iconv_t

Forward declaration of opaque structure used for character set conversions.

typedef cddb_conn_s cddb_conn_t

An opaque structure for keeping state about the connection to a CDDB server.

Enumerations

enum cddb_cache_mode_t { CACHE_OFF = 0, CACHE_ON, CACHE_ONLY }

enum cddb_search_t {
  SEARCH_NONE = 0, SEARCH_ARTIST = 1, SEARCH_TITLE = 2, SEARCH_TRACK = 4,
  SEARCH_OTHER = 8, SEARCH_ALL = ~0
}

Which fields to use for the full text search is defined by one or more of the constants below. More...

Functions

cddb_conn_t * cddb_new (void)

Creates a new CDDB connection structure.

void cddb_destroy (cddb_conn_t *c)

Free all resources associated with the given CDDB connection structure.

int cddb_set_charset (cddb_conn_t *c, const char *cs)

Set the character set.

void cddb_set_buf_size (cddb_conn_t *c, unsigned int size)

Change the size of the internal buffer.

cddb_error_t cddb_set_site (cddb_conn_t *c, const cddb_site_t *site)

Set all server details in one go through the use of a site structure.

const char * cddb_get_server_name (const cddb_conn_t *c)

Get the host name of the CDDB server that is currently being used.

void cddb_set_server_name (cddb_conn_t *c, const char *server)

Set the host name of the CDDB server.

unsigned int cddb_get_server_port (const cddb_conn_t *c)

Get the port of the CDDB server that is currently being used.

void cddb_set_server_port (cddb_conn_t *c, int port)

Set the port of the CDDB server.

unsigned int cddb_get_timeout (const cddb_conn_t *c)

Get the network time out value (in seconds).

void cddb_set_timeout (cddb_conn_t *c, unsigned int t)

Set the network time out value (in seconds).

const char * cddb_get_http_path_query (const cddb_conn_t *c)

Get the URL path for querying a CDDB server through HTTP.

void cddb_set_http_path_query (cddb_conn_t *c, const char *path)

Set the URL path for querying a CDDB server through HTTP.

const char * cddb_get_http_path_submit (const cddb_conn_t *c)

Get the URL path for submitting to a CDDB server through HTTP.

void cddb_set_http_path_submit (cddb_conn_t *c, const char *path)

Set the URL path for submitting to a CDDB server through HTTP.

unsigned int cddb_is_http_enabled (const cddb_conn_t *c)

Returns true if the HTTP protocol is currently enabled and false if CDDBP is enabled.

void cddb_http_enable (cddb_conn_t *c)

Enable HTTP tunneling to connect to the CDDB server.

void cddb_http_disable (cddb_conn_t *c)

Disable HTTP tunneling to connect to the CDDB server.

unsigned int cddb_is_http_proxy_enabled (const cddb_conn_t *c)

Returns true if the proxy support is currently enabled and false if it is not.

void cddb_http_proxy_enable (cddb_conn_t *c)

Enable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.

void cddb_http_proxy_disable (cddb_conn_t *c)

Disable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.

const char * cddb_get_http_proxy_server_name (const cddb_conn_t *c)

Get the host name of the HTTP proxy server.

void cddb_set_http_proxy_server_name (cddb_conn_t *c, const char *server)

Set the host name of the HTTP proxy server.

unsigned int cddb_get_http_proxy_server_port (const cddb_conn_t *c)

Get the port of the HTTP proxy server.

void cddb_set_http_proxy_server_port (cddb_conn_t *c, int port)

Set the port of the HTTP proxy server.

void cddb_set_http_proxy_username (cddb_conn_t *c, const char *username)

Set the HTTP proxy user name which is used when Basic Authentication is required.

const char * cddb_get_http_proxy_username (const cddb_conn_t *c)

Get the HTTP proxy user name.

void cddb_set_http_proxy_password (cddb_conn_t *c, const char *passwd)

Set the HTTP proxy password which is used when Basic Authentication is required.

const char * cddb_get_http_proxy_password (const cddb_conn_t *c)

Get the HTTP proxy password.

void cddb_set_http_proxy_credentials (cddb_conn_t *c, const char *username, const char *passwd)

Set the HTTP proxy user name and password in one go.

cddb_error_t cddb_errno (const cddb_conn_t *c)

Get the error number returned by the last libcddb command.

void cddb_set_client (cddb_conn_t *c, const char *cname, const char *cversion)

Set the name and version of the client program overwriting the previous values.

int cddb_set_email_address (cddb_conn_t *c, const char *email)

Sets the user name and host name of the local machine.

cddb_cache_mode_t cddb_cache_mode (const cddb_conn_t *c)

Returns the current cache mode.

void cddb_cache_enable (cddb_conn_t *c)

Enable caching of CDDB entries locally.

void cddb_cache_only (cddb_conn_t *c)

Only use the local CDDB cache.

void cddb_cache_disable (cddb_conn_t *c)

Disable caching of CDDB entries locally.

const char * cddb_cache_get_dir (const cddb_conn_t *c)

Return the directory currently being used for caching.

int cddb_cache_set_dir (cddb_conn_t *c, const char *dir)

Change the directory used for caching CDDB entries locally.

const cddb_site_t * cddb_first_site (cddb_conn_t *c)

Retrieve the first CDDB mirror site.

const cddb_site_t * cddb_next_site (cddb_conn_t *c)

Retrieve the next CDDB mirror site.

void cddb_search_set_fields (cddb_conn_t *c, unsigned int fields)

Set the bit-string specifying which fields to examine when performing a text search.

void cddb_search_set_categories (cddb_conn_t *c, unsigned int cats)

Set the bit-string specifying which categories to examine when performing a text search.

Define Documentation

#define CDDB_CONN_H 1

#define SEARCHCAT ( c ) (1 << (c))

Macro to be used for building the category search bit-string from the values of cddb_cat_t.

Typedef Documentation

typedef struct cddb_conn_s cddb_conn_t

An opaque structure for keeping state about the connection to a CDDB server.

typedef struct cddb_iconv_s* cddb_iconv_t

Forward declaration of opaque structure used for character set conversions.

Enumeration Type Documentation

enum cddb_cache_mode_t

Enumerator:

CACHE_OFF do not use local CDDB cache, network only

CACHE_ON use local CDDB cache, if possible

CACHE_ONLY only use local CDDB cache, no network access

enum cddb_search_t

Which fields to use for the full text search is defined by one or more of the constants below.

Enumerator:

SEARCH_NONE no fields

SEARCH_ARTIST artist name field

SEARCH_TITLE disc title field

SEARCH_TRACK track title field

SEARCH_OTHER other fields

SEARCH_ALL all fields

Function Documentation

void cddb_cache_disable ( cddb_conn_t * c )

Disable caching of CDDB entries locally.
All data will be fetched from a CDDB server everytime and the retrieved data will not be cached locally.

See also:
cddb_cache_mode
cddb_cache_enable
cddb_cache_only

Parameters:

c The connection structure.

void cddb_cache_enable ( cddb_conn_t * c )

Enable caching of CDDB entries locally.
Caching is enabled by default. The cache directory can be changed with the cddb_cache_set_dir function.

See also:
cddb_cache_mode
cddb_cache_disable
cddb_cache_only

Parameters:

c The connection structure.

const char* cddb_cache_get_dir ( const cddb_conn_t * c )

Return the directory currently being used for caching.

See also:
cddb_cache_set_dir

Parameters:

c The connection structure.

Returns:
The directory being used for caching.

cddb_cache_mode_t cddb_cache_mode ( const cddb_conn_t * c )

Returns the current cache mode.
This can be either on, off or cache only.

See also:
CACHE_ON
CACHE_ONLY
CACHE_OFF
cddb_cache_enable
cddb_cache_only
cddb_cache_disable

Parameters:

c The connection structure.

void cddb_cache_only ( cddb_conn_t * c )

Only use the local CDDB cache.
Never contact a server to retrieve any data. The cache directory can be changed with the cddb_cache_set_dir function.

See also:
cddb_cache_mode
cddb_cache_enable
cddb_cache_disable

Parameters:

c The connection structure.

int cddb_cache_set_dir ( cddb_conn_t * c,

const char * dir

)

Change the directory used for caching CDDB entries locally.
The default location of the cached entries is a subdirectory (.cddbslave) of the user's home directory. If the first character of the directory is '~', then it will be expanded to the contents of $HOME.

See also:
cddb_cache_get_dir

Parameters:

c The connection structure.

dir The directory to use for caching.

void cddb_destroy ( cddb_conn_t * c )

Free all resources associated with the given CDDB connection structure.

cddb_error_t cddb_errno ( const cddb_conn_t * c )

Get the error number returned by the last libcddb command.

Parameters:

c The CDDB connection structure.

Returns:
The error number.

const cddb_site_t* cddb_first_site ( cddb_conn_t * c )

Retrieve the first CDDB mirror site.

Parameters:

c The connection structure.

Returns:
The first mirror site or NULL if not found.

const char* cddb_get_http_path_query ( const cddb_conn_t * c )

Get the URL path for querying a CDDB server through HTTP.

See also:
cddb_set_http_path_query

Parameters:

c The connection structure.

Returns:
The URL path.

const char* cddb_get_http_path_submit ( const cddb_conn_t * c )

Get the URL path for submitting to a CDDB server through HTTP.

See also:
cddb_set_http_path_submit

Parameters:

c The connection structure.

Returns:
The URL path.

const char* cddb_get_http_proxy_password ( const cddb_conn_t * c )

Get the HTTP proxy password.

Parameters:

c The connection structure.

Returns:
The password.

const char* cddb_get_http_proxy_server_name ( const cddb_conn_t * c )

Get the host name of the HTTP proxy server.

See also:
cddb_set_http_proxy_server_name

Parameters:

c The connection structure.

Returns:
The proxy server host name.

unsigned int cddb_get_http_proxy_server_port ( const cddb_conn_t * c )

Get the port of the HTTP proxy server.

See also:
cddb_set_http_proxy_server_port

Parameters:

c The connection structure.

Returns:
The proxy server port.

const char* cddb_get_http_proxy_username ( const cddb_conn_t * c )

Get the HTTP proxy user name.

Parameters:

c The connection structure.

Returns:
The user name.

const char* cddb_get_server_name ( const cddb_conn_t * c )

Get the host name of the CDDB server that is currently being used.

See also:
cddb_set_server_name

Parameters:

c The connection structure.

Returns:
The server host name.

unsigned int cddb_get_server_port ( const cddb_conn_t * c )

Get the port of the CDDB server that is currently being used.

See also:
cddb_set_server_port

Parameters:

c The connection structure.

Returns:
The server port.

unsigned int cddb_get_timeout ( const cddb_conn_t * c )

Get the network time out value (in seconds).

See also:
cddb_set_timeout

Parameters:

c The connection structure.

Returns:
The current time out in seconds.

void cddb_http_disable ( cddb_conn_t * c )

Disable HTTP tunneling to connect to the CDDB server.
By default this option is disabled.

See also:
cddb_is_http_enabled
cddb_http_enable

Parameters:

c The CDDB connection structure.

void cddb_http_enable ( cddb_conn_t * c )

Enable HTTP tunneling to connect to the CDDB server.
By default this option is disabled.

See also:
cddb_is_http_enabled
cddb_http_disable

Parameters:

c The CDDB connection structure.

void cddb_http_proxy_disable ( cddb_conn_t * c )

Disable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.
By default this option is disabled.

See also:
cddb_is_http_proxy_enabled
cddb_http_proxy_enable

Parameters:

c The CDDB connection structure.

void cddb_http_proxy_enable ( cddb_conn_t * c )

Enable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.
The usage of an HTTP proxy implies normal HTTP tunneling instead of connecting directly to the CDDB server. By default this option is disabled.

See also:
cddb_is_http_proxy_enabled
cddb_http_proxy_disable

Parameters:

c The CDDB connection structure.

unsigned int cddb_is_http_enabled ( const cddb_conn_t * c )

Returns true if the HTTP protocol is currently enabled and false if CDDBP is enabled.

See also:
cddb_http_enable
cddb_http_disable

Parameters:

c The CDDB connection structure.

Returns:
True or false.

unsigned int cddb_is_http_proxy_enabled ( const cddb_conn_t * c )

Returns true if the proxy support is currently enabled and false if it is not.
This fucntion does not check whether HTTP is enabled. So it is possible that true will be returned while in reality the CDDBP protocol is being used (no proxy support).

See also:
cddb_http_proxy_enable
cddb_http_proxy_disable

Parameters:

c The CDDB connection structure.

Returns:
True or false.

cddb_conn_t* cddb_new ( void )

Creates a new CDDB connection structure.
This structure will have to be passed to all libcddb functions. Default values will be used for the connection parameters allowing it to contact the CDDB server at freedb.org.

Returns:
The CDDB connection structure or NULL if something went wrong.

const cddb_site_t* cddb_next_site ( cddb_conn_t * c )

Retrieve the next CDDB mirror site.

Parameters:

c The connection structure.

Returns:
The next mirror site or NULL if not found.

void cddb_search_set_categories ( cddb_conn_t * c,

unsigned int cats

)

Set the bit-string specifying which categories to examine when performing a text search.
The SEARCHCAT macro needs to be used to build the actual bit-string from individual categories. The cddb_search_t values SEARCH_NONE and SEARCH_ALL are also valid. The example below shows some possible combinations. By default all categories are searched.

unsigned int cats = SEARCHCAT(CDDB_CAT_ROCK) | SEARCHCAT(CDDB_CAT_MISC); unsigned int cats = SEARCH_ALL; unsigned int cats = SEARCH_NONE;

Parameters:

c The connection structure.

cats A bitwise ORed set of values from SEARCHCAT(cddb_cat_t).

void cddb_search_set_fields ( cddb_conn_t * c,

unsigned int fields

)

Set the bit-string specifying which fields to examine when performing a text search.
By default only the artist and disc title fields are searched.

Parameters:

c The connection structure.

fields A bitwise ORed set of values from cddb_search_t.

void cddb_set_buf_size ( cddb_conn_t * c,

unsigned int size

)

Change the size of the internal buffer.

Parameters:

c The connection structure.

size The new buffer size.

int cddb_set_charset ( cddb_conn_t * c,

const char * cs

)

Set the character set.
By default the FreeDB server uses UTF-8 when providing CD data. When a character set is defined with this function any strings retrieved from or sent to the server will automatically be converted.

Parameters:

c The connection structure.

cs The character set that will be used.

Returns:
False if the specified character set is unknown, or no conversion from/to UTF-8 is available. True otherwise.

void cddb_set_client ( cddb_conn_t * c,

const char * cname,

const char * cversion

)

Set the name and version of the client program overwriting the previous values.
This function will make a copy of the provided strings. The defaults are 'libcddb' and the version number of the libcddb library in use. Both parameters must be valid strings. If any of teh strings is NULL, this fucntion will return without changing anything.

Parameters:

c The connection structure.

cname The name of the client program.

cversion The version number of the client program.

int cddb_set_email_address ( cddb_conn_t * c,

const char * email

)

Sets the user name and host name of the local machine.
This function will parse out the user name and host name from the e-mail address.

Parameters:

c The connection structure.

email The e-mail address of the user.

void cddb_set_http_path_query ( cddb_conn_t * c,

const char * path

)

Set the URL path for querying a CDDB server through HTTP.
The default value is '/~cddb/cddb.cgi'.

See also:
cddb_get_http_path_query

Parameters:

c The connection structure.

path The URL path.

void cddb_set_http_path_submit ( cddb_conn_t * c,

const char * path

)

Set the URL path for submitting to a CDDB server through HTTP.
The default value is '/~cddb/submit.cgi'.

See also:
cddb_get_http_path_submit

Parameters:

c The connection structure.

path The URL path.

void cddb_set_http_proxy_credentials ( cddb_conn_t * c,

const char * username,

const char * passwd

)

Set the HTTP proxy user name and password in one go.
These credentials are used when Basic Authentication is required. The advantage of using this function over setting the user name and password seperately is that the cleartext user name and password are not kept in memory longer than needed.

Parameters:

c The connection structure.

username The user name.

passwd The password.

void cddb_set_http_proxy_password ( cddb_conn_t * c,

const char * passwd

)

Set the HTTP proxy password which is used when Basic Authentication is required.

Parameters:

c The connection structure.

passwd The password.

void cddb_set_http_proxy_server_name ( cddb_conn_t * c,

const char * server

)

Set the host name of the HTTP proxy server.
There is no default value.

See also:
cddb_get_http_proxy_server_name

Parameters:

c The connection structure.

server The server host name.

void cddb_set_http_proxy_server_port ( cddb_conn_t * c,

int port

)

Set the port of the HTTP proxy server.
The default value is 8080.

See also:
cddb_get_http_proxy_server_port

Parameters:

c The connection structure.

port The server port.

void cddb_set_http_proxy_username ( cddb_conn_t * c,

const char * username

)

Set the HTTP proxy user name which is used when Basic Authentication is required.

Parameters:

c The connection structure.

username The user name.

void cddb_set_server_name ( cddb_conn_t * c,

const char * server

)

Set the host name of the CDDB server.
The default value for the server is 'freedb.org'.

See also:
cddb_get_server_name

Parameters:

c The connection structure.

server The server host name.

void cddb_set_server_port ( cddb_conn_t * c,

int port

)

Set the port of the CDDB server.
The default value is 888.

See also:
cddb_get_server_port

Parameters:

c The connection structure.

port The server port.

cddb_error_t cddb_set_site ( cddb_conn_t * c,

const cddb_site_t * site

)

Set all server details in one go through the use of a site structure.
This function initializzes the server address, port, protocol and query path in case of HTTP.

See also:
cddb_sites
cddb_first_site
cddb_next_site

Parameters:

c The connection structure.

site The site to use.

Returns:
Error code: CDDB_ERR_OK or CDDB_ERR_INVALID.

void cddb_set_timeout ( cddb_conn_t * c,

unsigned int t

)

Set the network time out value (in seconds).
The default is 10 seconds.

See also:
cddb_get_timeout

Parameters:

c The connection structure.

t The new time out in seconds.

Generated on Sun Oct 15 14:49:15 2006 for libcddb by

1.4.6


Defines
#define	CDDB_CONN_H 1
#define	SEARCHCAT(c) (1 << (c))
	Macro to be used for building the category search bit-string from the values of cddb_cat_t.
Typedefs
typedef cddb_iconv_s *	cddb_iconv_t
	Forward declaration of opaque structure used for character set conversions.
typedef cddb_conn_s	cddb_conn_t
	An opaque structure for keeping state about the connection to a CDDB server.
Enumerations
enum	cddb_cache_mode_t { CACHE_OFF = 0, CACHE_ON, CACHE_ONLY }
enum	cddb_search_t { SEARCH_NONE = 0, SEARCH_ARTIST = 1, SEARCH_TITLE = 2, SEARCH_TRACK = 4, SEARCH_OTHER = 8, SEARCH_ALL = ~0 }
	Which fields to use for the full text search is defined by one or more of the constants below. More...
Functions
cddb_conn_t *	cddb_new (void)
	Creates a new CDDB connection structure.
void	cddb_destroy (cddb_conn_t *c)
	Free all resources associated with the given CDDB connection structure.
int	cddb_set_charset (cddb_conn_t c, const char cs)
	Set the character set.
void	cddb_set_buf_size (cddb_conn_t *c, unsigned int size)
	Change the size of the internal buffer.
cddb_error_t	cddb_set_site (cddb_conn_t c, const cddb_site_t site)
	Set all server details in one go through the use of a site structure.
const char *	cddb_get_server_name (const cddb_conn_t *c)
	Get the host name of the CDDB server that is currently being used.
void	cddb_set_server_name (cddb_conn_t c, const char server)
	Set the host name of the CDDB server.
unsigned int	cddb_get_server_port (const cddb_conn_t *c)
	Get the port of the CDDB server that is currently being used.
void	cddb_set_server_port (cddb_conn_t *c, int port)
	Set the port of the CDDB server.
unsigned int	cddb_get_timeout (const cddb_conn_t *c)
	Get the network time out value (in seconds).
void	cddb_set_timeout (cddb_conn_t *c, unsigned int t)
	Set the network time out value (in seconds).
const char *	cddb_get_http_path_query (const cddb_conn_t *c)
	Get the URL path for querying a CDDB server through HTTP.
void	cddb_set_http_path_query (cddb_conn_t c, const char path)
	Set the URL path for querying a CDDB server through HTTP.
const char *	cddb_get_http_path_submit (const cddb_conn_t *c)
	Get the URL path for submitting to a CDDB server through HTTP.
void	cddb_set_http_path_submit (cddb_conn_t c, const char path)
	Set the URL path for submitting to a CDDB server through HTTP.
unsigned int	cddb_is_http_enabled (const cddb_conn_t *c)
	Returns true if the HTTP protocol is currently enabled and false if CDDBP is enabled.
void	cddb_http_enable (cddb_conn_t *c)
	Enable HTTP tunneling to connect to the CDDB server.
void	cddb_http_disable (cddb_conn_t *c)
	Disable HTTP tunneling to connect to the CDDB server.
unsigned int	cddb_is_http_proxy_enabled (const cddb_conn_t *c)
	Returns true if the proxy support is currently enabled and false if it is not.
void	cddb_http_proxy_enable (cddb_conn_t *c)
	Enable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.
void	cddb_http_proxy_disable (cddb_conn_t *c)
	Disable HTTP tunneling through an HTTP proxy server to connect to the CDDB server.
const char *	cddb_get_http_proxy_server_name (const cddb_conn_t *c)
	Get the host name of the HTTP proxy server.
void	cddb_set_http_proxy_server_name (cddb_conn_t c, const char server)
	Set the host name of the HTTP proxy server.
unsigned int	cddb_get_http_proxy_server_port (const cddb_conn_t *c)
	Get the port of the HTTP proxy server.
void	cddb_set_http_proxy_server_port (cddb_conn_t *c, int port)
	Set the port of the HTTP proxy server.
void	cddb_set_http_proxy_username (cddb_conn_t c, const char username)
	Set the HTTP proxy user name which is used when Basic Authentication is required.
const char *	cddb_get_http_proxy_username (const cddb_conn_t *c)
	Get the HTTP proxy user name.
void	cddb_set_http_proxy_password (cddb_conn_t c, const char passwd)
	Set the HTTP proxy password which is used when Basic Authentication is required.
const char *	cddb_get_http_proxy_password (const cddb_conn_t *c)
	Get the HTTP proxy password.
void	cddb_set_http_proxy_credentials (cddb_conn_t c, const char username, const char *passwd)
	Set the HTTP proxy user name and password in one go.
cddb_error_t	cddb_errno (const cddb_conn_t *c)
	Get the error number returned by the last libcddb command.
void	cddb_set_client (cddb_conn_t c, const char cname, const char *cversion)
	Set the name and version of the client program overwriting the previous values.
int	cddb_set_email_address (cddb_conn_t c, const char email)
	Sets the user name and host name of the local machine.
cddb_cache_mode_t	cddb_cache_mode (const cddb_conn_t *c)
	Returns the current cache mode.
void	cddb_cache_enable (cddb_conn_t *c)
	Enable caching of CDDB entries locally.
void	cddb_cache_only (cddb_conn_t *c)
	Only use the local CDDB cache.
void	cddb_cache_disable (cddb_conn_t *c)
	Disable caching of CDDB entries locally.
const char *	cddb_cache_get_dir (const cddb_conn_t *c)
	Return the directory currently being used for caching.
int	cddb_cache_set_dir (cddb_conn_t c, const char dir)
	Change the directory used for caching CDDB entries locally.
const cddb_site_t *	cddb_first_site (cddb_conn_t *c)
	Retrieve the first CDDB mirror site.
const cddb_site_t *	cddb_next_site (cddb_conn_t *c)
	Retrieve the next CDDB mirror site.
void	cddb_search_set_fields (cddb_conn_t *c, unsigned int fields)
	Set the bit-string specifying which fields to examine when performing a text search.
void	cddb_search_set_categories (cddb_conn_t *c, unsigned int cats)
	Set the bit-string specifying which categories to examine when performing a text search.