Main Page | Class List | File List | Class Members | File Members

cddb_conn.h File Reference

#include <stdio.h>
#include <netinet/in.h>

Go to the source code of this file.

Classes

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

Defines

#define CDDB_CONN_H   1
#define CACHE_OFF   0
 do not use local CDDB cache, network only
#define CACHE_ON   1
 use local CDDB cache, if possible
#define CACHE_ONLY   2
 only use local CDDB cache, no network access
#define cddb_get_server_name(c)   (c)->server_name
 Get the host name of the CDDB server that is currently being used.
#define cddb_get_server_port(c)   (c)->server_port
 Get the port of the CDDB server that is currently being used.
#define cddb_get_timeout(c)   (c)->timeout
 Get the network time out value (in seconds).
#define cddb_set_timeout(c, t)   (c)->timeout = t
 Set the network time out value (in seconds).
#define cddb_get_http_path_query(c)   (c)->http_path_query
 Get the URL path for querying a CDDB server through HTTP.
#define cddb_get_http_path_submit(c)   (c)->http_path_submit
 Get the URL path for submitting to a CDDB server through HTTP.
#define cddb_is_http_enabled(c)   (c)->is_http_enabled
 Returns true if the HTTP protocol is currently enabled and false if CDDBP is enabled.
#define cddb_is_http_proxy_enabled(c)   (c)->is_http_proxy_enabled
 Returns true if the proxy support is currently enabled and false if it is not.
#define cddb_get_http_proxy_server_name(c)   (c)->http_proxy_server
 Get the host name of the HTTP proxy server.
#define cddb_get_http_proxy_server_port(c)   (c)->http_proxy_server_port
 Get the port of the HTTP proxy server.
#define cddb_errno(c)   (c)->errnum
 Get the error number returned by the last libcddb command.
#define cddb_cache_mode(c)   (c)->use_cache
 Returns the current cache mode.
#define cddb_cache_enable(c)   (c)->use_cache = CACHE_ON
 Enable caching of CDDB entries locally.
#define cddb_cache_only(c)   (c)->use_cache = CACHE_ONLY
 Only use the local CDDB cache.
#define cddb_cache_disable(c)   (c)->use_cache = CACHE_OFF
 Disable caching of CDDB entries locally.
#define cddb_cache_get_dir(c)   (c)->cache_dir;
 Return the directory currently being used for caching.

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.

Functions

cddb_conn_tcddb_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.
void cddb_set_server_name (cddb_conn_t *c, const char *server)
 Set the host name of the CDDB server.
void cddb_set_server_port (cddb_conn_t *c, int port)
 Set the port of the CDDB server.
void cddb_set_http_path_query (cddb_conn_t *c, const char *path)
 Set the URL path for querying 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.
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.
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.
void cddb_set_http_proxy_server_name (cddb_conn_t *c, const char *server)
 Set the host name 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_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.
int cddb_cache_set_dir (cddb_conn_t *c, const char *dir)
 Change the directory used for caching CDDB entries locally.


Define Documentation

#define CACHE_OFF   0
 

do not use local CDDB cache, network only

#define CACHE_ON   1
 

use local CDDB cache, if possible

#define CACHE_ONLY   2
 

only use local CDDB cache, no network access

#define cddb_cache_disable  )     (c)->use_cache = CACHE_OFF
 

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.

#define cddb_cache_enable  )     (c)->use_cache = CACHE_ON
 

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.

#define cddb_cache_get_dir  )     (c)->cache_dir;
 

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.

#define cddb_cache_mode  )     (c)->use_cache
 

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.

#define cddb_cache_only  )     (c)->use_cache = CACHE_ONLY
 

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.

#define CDDB_CONN_H   1
 

#define cddb_errno  )     (c)->errnum
 

Get the error number returned by the last libcddb command.

Parameters:
c The CDDB connection structure.
Returns:
The error number.

#define cddb_get_http_path_query  )     (c)->http_path_query
 

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.

#define cddb_get_http_path_submit  )     (c)->http_path_submit
 

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.

#define cddb_get_http_proxy_server_name  )     (c)->http_proxy_server
 

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.

#define cddb_get_http_proxy_server_port  )     (c)->http_proxy_server_port
 

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.

#define cddb_get_server_name  )     (c)->server_name
 

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.

#define cddb_get_server_port  )     (c)->server_port
 

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.

#define cddb_get_timeout  )     (c)->timeout
 

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.

#define cddb_is_http_enabled  )     (c)->is_http_enabled
 

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.

#define cddb_is_http_proxy_enabled  )     (c)->is_http_proxy_enabled
 

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.

#define cddb_set_timeout c,
 )     (c)->timeout = 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.


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.


Function Documentation

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.

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.

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.

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_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_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.


Generated on Sat Oct 16 18:12:36 2004 for libcddb by doxygen 1.3.8