CouchdbDatabase

CouchdbDatabase

Synopsis

                    CouchdbDatabase;
                    CouchdbDatabaseClass;
CouchdbDatabase *   couchdb_database_new                (CouchdbSession *session,
                                                         const char *dbname);
GSList *            couchdb_database_list_documents     (CouchdbDatabase *database,
                                                         GError **error);
GSList *            couchdb_database_get_design_documents
                                                        (CouchdbDatabase *database,
                                                         GError **error);
GSList *            couchdb_database_get_all_documents  (CouchdbDatabase *database,
                                                         GError **error);
GSList *            couchdb_database_execute_view       (CouchdbDatabase *database,
                                                         const char *design_doc,
                                                         const char *view_name,
                                                         GError **error);
void                couchdb_database_free_document_list (GSList *doclist);
CouchdbDocument *   couchdb_database_get_document       (CouchdbDatabase *database,
                                                         const char *docid,
                                                         GError **error);
CouchdbDesignDocument * couchdb_database_get_design_document
                                                        (CouchdbDatabase *database,
                                                         const char *docid,
                                                         GError **error);
gboolean            couchdb_database_put_document       (CouchdbDatabase *database,
                                                         CouchdbDocument *document,
                                                         GError **error);
gboolean            couchdb_database_delete_document    (CouchdbDatabase *database,
                                                         CouchdbDocument *document,
                                                         GError **error);
void                couchdb_database_listen_for_changes (CouchdbDatabase *database);
CouchdbSession *    couchdb_database_get_session        (CouchdbDatabase *database);
const char *        couchdb_database_get_name           (CouchdbDatabase *database);
                    CouchdbDatabasePrivate;

Object Hierarchy

  GObject
   +----CouchdbDatabase

Description

Details

CouchdbDatabase

typedef struct _CouchdbDatabase CouchdbDatabase;


CouchdbDatabaseClass

typedef struct {
	GObjectClass parent_class;

	/* Signals */
	void (* document_created) (CouchdbDatabase *database, CouchdbDocument *document);
	void (* document_updated) (CouchdbDatabase *database, CouchdbDocument *document);
	void (* document_deleted) (CouchdbDatabase *database, const char *docid);
} CouchdbDatabaseClass;


couchdb_database_new ()

CouchdbDatabase *   couchdb_database_new                (CouchdbSession *session,
                                                         const char *dbname);

Create a new CouchdbDatabase object, which is to be used for operations on specific databases on the underlying CouchDB instance.

session :

A CouchdbSession object

dbname :

Name of the database

Returns :

A new CouchdbDatabase object.

couchdb_database_list_documents ()

GSList *            couchdb_database_list_documents     (CouchdbDatabase *database,
                                                         GError **error);

Retrieve the list of all documents from a database on a running CouchDB instance. For each document, a CouchdbDocumentInfo object is returned on the list, which can then be used for retrieving specific information for each document.

database :

A CouchdbDatabase object

error :

Placeholder for error information

Returns :

a list of CouchdbDocumentInfo objects, or NULL if there are none or there was an error (in which case the error argument will contain information about the error). Once no longer needed, the list should be freed by calling couchdb_database_free_document_list.

couchdb_database_get_design_documents ()

GSList *            couchdb_database_get_design_documents
                                                        (CouchdbDatabase *database,
                                                         GError **error);

Retrieve all design documents from the given database.

Design documents are special documents (well, they are really normal documents in the CouchDB database, just with a special ID) that contain views' code, which are used to create queries on the database that are cached and so make access to the database much quicker.

database :

A CouchdbDatabase object

error :

Placeholder for error information

Returns :

A list of CouchdbDesignDocument objects, or NULL if there are none or there was an error (in which case the error argument will contain information about the error). Once no longer needed, the list should be freed by calling couchdb_database_free_document_list.

couchdb_database_get_all_documents ()

GSList *            couchdb_database_get_all_documents  (CouchdbDatabase *database,
                                                         GError **error);

Retrieve all documents from a database on a running CouchDB instance. For each document found in the database, a CouchdbDocument object is returned on the list, which represents the document's contents as found on the underlying database.

database :

A CouchdbDatabase object

error :

Placeholder for error information

Returns :

a list of CouchdbDocument objects, or NULL if there are none or there was an error (in which case the error argument will contain information about the error). Once no longer needed, the list should be freed by calling couchdb_database_free_document_list.

couchdb_database_execute_view ()

GSList *            couchdb_database_execute_view       (CouchdbDatabase *database,
                                                         const char *design_doc,
                                                         const char *view_name,
                                                         GError **error);

Run a view on the database to retrieve documents. For each document found in the database, a CouchdbDocument object is returned on the list, which represents the document's contents as found on the underlying database.

database :

A CouchdbDatabase object

design_doc :

Name of the design document where the view to execute is

view_name :

Name of the view to execute

error :

Placeholder for error information

Returns :

a list of CouchdbDocument objects, or NULL if there are none or there was an error (in which case the error argument will contain information about the error). Once no longer needed, the list should be freed by calling couchdb_database_free_document_list.

couchdb_database_free_document_list ()

void                couchdb_database_free_document_list (GSList *doclist);


couchdb_database_get_document ()

CouchdbDocument *   couchdb_database_get_document       (CouchdbDatabase *database,
                                                         const char *docid,
                                                         GError **error);

Retrieve the last revision of a document from the given database.

database :

A CouchdbDatabase object

docid :

Unique ID of the document to be retrieved

error :

Placeholder for error information

Returns :

A CouchdbDocument object if successful, NULL otherwise, in which case, the error argument will contain information about the error.

couchdb_database_get_design_document ()

CouchdbDesignDocument * couchdb_database_get_design_document
                                                        (CouchdbDatabase *database,
                                                         const char *docid,
                                                         GError **error);

Retrieve a design document from the given database.

database :

A CouchdbDatabase object

docid :

ID of the design document

error :

Placeholder for error information

Returns :

A CouchdbDesignDocument object if successful, NULL otherwise, in which case, the error argument will contain information about the error.

couchdb_database_put_document ()

gboolean            couchdb_database_put_document       (CouchdbDatabase *database,
                                                         CouchdbDocument *document,
                                                         GError **error);

Store a document on a CouchDB database.

If it is a new document, and hence does not have a unique ID, a unique ID will be generated and stored on the CouchdbDocument object. Likewise, whether the document is new or just an update to an existing one, the CouchdbDocument object passed to this function will be updated to contain the latest revision of the document, as returned by CouchDB (revision that can be retrieved by calling couchdb_document_get_revision).

database :

A CouchdbDatabase object

document :

A CouchdbDocument object

error :

Placeholder for error information

Returns :

TRUE if successful, FALSE otherwise, in which case the error argument will contain information about the error.

couchdb_database_delete_document ()

gboolean            couchdb_database_delete_document    (CouchdbDatabase *database,
                                                         CouchdbDocument *document,
                                                         GError **error);

Delete an existing document from a CouchDB instance.

Please take note that this operation can fail if there was an update to the document and that last revision was not retrieved by the calling application. This is due to the fact that, to remove a document from CouchDB, the latest revision needs to be sent, so if the CouchdbDocument object passed to this function does not contain the last revision, the operation will fail. In that case, retrieving the latest revision from CouchDB (with couchdb_database_get_document) and trying the delete operation again should fix the issue.

database :

A CouchdbDatabase object

document :

A CouchdbDocument object

error :

Placeholder for error information

Returns :

TRUE if successful, FALSE otherwise, in which case the error argument will contain information about the error.

couchdb_database_listen_for_changes ()

void                couchdb_database_listen_for_changes (CouchdbDatabase *database);

Setup a listener to get information about changes done to a specific database. Please note that changes done in the application using couchdb-glib will be notified without the need of calling this function. But if the application wants to receive notifications of changes done externally (by another application, or by any other means, like replication with a remote database), it needs to call this function.

For each change, one of the signals on the CouchdbDatabase object will be emitted, so applications just have to connect to those signals before calling this function.

database :

A CouchdbDatabase object

couchdb_database_get_session ()

CouchdbSession *    couchdb_database_get_session        (CouchdbDatabase *database);

Retrieve the CouchdbSession associated with the given database object.

database :

A CouchdbDatabase object

Returns :

A CouchdbSession object.

couchdb_database_get_name ()

const char *        couchdb_database_get_name           (CouchdbDatabase *database);

Retrieve the name of the database the given CouchdbDatabase object maps to.

database :

A CouchdbDatabase object

Returns :

The name of the database

CouchdbDatabasePrivate

typedef struct _CouchdbDatabasePrivate CouchdbDatabasePrivate;