|
|
|
Catalina Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | ||||
#define CATALINA_STORAGE_ERROR enum CatalinaStorageError; CatalinaStoragePrivate; CatalinaStorage; CatalinaStorage* catalina_storage_new (void); void catalina_storage_open_async (CatalinaStorage *storage, const gchar *env_dir, const gchar *name, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_open_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error); gboolean catalina_storage_open (CatalinaStorage *storage, const gchar *env_dir, const gchar *name, GError **error); void catalina_storage_close_async (CatalinaStorage *storage, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_close_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error); gboolean catalina_storage_close (CatalinaStorage *storage, GError **error); void catalina_storage_get_async (CatalinaStorage *storage, const gchar *key, gssize key_length, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_get_finish (CatalinaStorage *storage, GAsyncResult *result, gchar **value, gsize *value_length, GError **error); gboolean catalina_storage_get (CatalinaStorage *storage, const gchar *key, gssize key_length, gchar **value, gsize *value_length, GError **error); void catalina_storage_set_async (CatalinaStorage *storage, const gchar *key, gssize key_length, const gchar *value, gssize value_length, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_set_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error); gboolean catalina_storage_set (CatalinaStorage *storage, const gchar *key, gssize key_length, const gchar *value, gssize value_length, GError **error); void catalina_storage_get_value_async (CatalinaStorage *storage, const gchar *key, gssize key_length, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_get_value_finish (CatalinaStorage *storage, GAsyncResult *result, GValue *value, GError **error); gboolean catalina_storage_get_value (CatalinaStorage *storage, const gchar *key, gssize key_length, GValue *value, GError **error); void catalina_storage_set_value_async (CatalinaStorage *storage, const gchar *key, gssize key_length, const GValue *value, GAsyncReadyCallback callback, gpointer user_data); gboolean catalina_storage_set_value_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error); gboolean catalina_storage_set_value (CatalinaStorage *storage, const gchar *key, gssize key_length, const GValue *value, GError **error); gboolean catalina_storage_get_use_idle (CatalinaStorage *storage); void catalina_storage_set_use_idle (CatalinaStorage *storage, gboolean use_idle); CatalinaFormatter* catalina_storage_get_formatter (CatalinaStorage *storage); void catalina_storage_set_formatter (CatalinaStorage *storage, CatalinaFormatter *formatter); CatalinaTransform* catalina_storage_get_transform (CatalinaStorage *storage); void catalina_storage_set_transform (CatalinaStorage *storage, CatalinaTransform *transform); GQuark catalina_storage_error_quark (void);
"formatter" CatalinaFormatter* : Read / Write "transform" CatalinaTransform* : Read / Write "use-idle" gboolean : Read / Write
CatalinaStorage is an asynchronous data store.
The asynchronous part of the data store is implemented using Iris. iris_arbiter_coordinate()
is used to manage all of the concurrent vs exclusive requests to the data-store.
There are two ways you can manipulate the data on the way in or out of the data-store. Using the "transform" property, you can alter the buffers directly before the write, or right after the read. Using the "formatter" property, you can control how the content in GValue's are serialized to disk. This would allow the storage in formats such as JSON or a lightweight binary format implemented in CatalinaBinaryFormatter.
The properties are not thread-safe, and therefore should only be changed before the storage instance is opened.
You can use the storage in either a synchronous or asynchronous manner. You may even mix and match. However, keep in mind the code is written in such a way that prefers the asynchronous implementations.
Asynchronous example
Compile with gcc -o example example.c `pkg-config --libs --cflags catalina-1.0`.
#include <gio/gio.h>
#include <catalina/catalina.h>
#include <iris/iris.h>
static void
test_get_cb (CatalinaStorage *storage,
GAsyncResult *result,
gpointer user_data)
{
gchar *buffer = NULL;
gsize buffer_length = 0;
catalina_storage_get_finish (storage, result, &buffer, &buffer_length, NULL);
g_free (buffer);
g_main_loop_quit (user_data);
}
static void
test_open_cb (CatalinaStorage *storage,
GAsyncResult *result,
gpointer user_data)
{
if (catalina_storage_open_finish (storage, result, NULL)) {
catalina_storage_get_async (storage, "key", -1, (GAsyncReadyCallback)test_get_cb, user_data);
}
}
int
main (int argc, char *argv[])
{
g_type_init ();
iris_init ();
CatalinaStorage *storage = catalina_storage_new ();
GMainLoop *loop = g_main_loop_new (NULL, FALSE);
catalina_storage_open_async (storage, ".", "catalina.db", (GAsyncReadyCallback)test_open_cb, loop);
g_main_loop_run (loop);
return 0;
}
Synchronous example
CatalinaStorage *storage = catalina_storage_new ();
GError *oerror = NULL;
if (catalina_storage_open (storage, ".", "catalina.db", &oerror)) {
gchar *buffer = NULL;
gsize buffer_length = 0;
GError *error = NULL;
if (catalina_storage_get (storage, "key", -1, &buffer, &buffer_length, &error)) {
g_print ("Found data!\n");
g_free (buffer);
}
else
g_printerr ("Error: %s\n", error->message);
}
else
g_printerr ("Error: %s", oerror->message);
#define CATALINA_STORAGE_ERROR (catalina_storage_error_quark ())
CatalinaStorage GError domain.
typedef enum {
CATALINA_STORAGE_ERROR_STATE,
CATALINA_STORAGE_ERROR_DB,
CATALINA_STORAGE_ERROR_NO_SUCH_KEY,
} CatalinaStorageError;
CatalinaStorage error enumeration.
CatalinaStorage* catalina_storage_new (void);
Creates a new instance of CatalinaStorage.
Returns : |
the newly created CatalinaStorage instance |
void catalina_storage_open_async (CatalinaStorage *storage, const gchar *env_dir, const gchar *name, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously opens the underlying data-store. Call catalina_storage_open_finish()
from within callback to complete the request.
|
A CatalinaStorage |
|
environment directory for database or NULL for current working directory
|
|
name of the database |
|
A GAsyncReadyCallback |
|
data for callback
|
gboolean catalina_storage_open_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error);
Completes an asynchronous operation to open the CatalinaStorage. If there was an error,
FALSE is returned and error is set.
|
A CatalinaStorage |
|
A GAsyncResult |
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
gboolean catalina_storage_open (CatalinaStorage *storage, const gchar *env_dir, const gchar *name, GError **error);
Synchronously opens the underlying data-store for use. This method is not the preferred
way to perform the operation. See using catalina_storage_open_async() for the preferred
alternative.
On failure, FALSE is returned and error is set.
|
A CatalinaStorage |
|
the environment directory for the database |
|
the name of the database |
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
void catalina_storage_close_async (CatalinaStorage *storage, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously closes the underlying data-store. Use catalina_storage_close_finish()
from within callback to complete the request.
|
A CatalinaStorage |
|
A GAsyncReadyCallback |
|
A gpointer |
gboolean catalina_storage_close_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error);
Completes the asynchronous request to close the underlying data-store.
Upon failure, FALSE is returned and error is set.
|
A CatalinaStorage |
|
A GAsyncResult |
|
A GError |
Returns : |
TRUE on success
|
gboolean catalina_storage_close (CatalinaStorage *storage, GError **error);
Synchronously closes the underlying data-store. This method is not the preferred
implementation. See catalina_storage_close_async() for the preferred method.
Upon failure, FALSE is returned and error is set.
|
A CatalinaStorage |
|
A location for a GError |
Returns : |
TRUE on success
|
void catalina_storage_get_async (CatalinaStorage *storage, const gchar *key, gssize key_length, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously requests the retrieval of the data associated with key.
The result will be completed asynchronously and provided to callback which
should in turn call catalina_storage_get_finish() to complete the request.
|
A CatalinaStorage |
|
the key to lookup |
|
the length of key in bytes
|
|
A GAsyncReadyCallback |
|
data for callback
|
gboolean catalina_storage_get_finish (CatalinaStorage *storage, GAsyncResult *result, gchar **value, gsize *value_length, GError **error);
Completes an asynchronous get request.
Upon failure, FALSE is returned and error is set.
See catalina_storage_get_async().
|
A CatalinaStorage |
|
A GAsyncResult |
|
A location for the requested buffer |
|
A location for the requested buffer size, or NULL
|
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
gboolean catalina_storage_get (CatalinaStorage *storage, const gchar *key, gssize key_length, gchar **value, gsize *value_length, GError **error);
Synchronously retreives the data found for key. Keep in mind that
CatalinaStorage is an asynchronous data-store in nature. Therefore, making
synchronous calls is not the most efficient way to complete the task.
In the case of an error, FALSE is returned and error is set.
See catalina_storage_get_async().
|
A CatalinaStorage |
|
the key to lookup |
|
the length of key in bytes or -1 if it is NULL terminated
|
|
a location to store the resulting buffer |
|
a location to store the size of the resulting buffer or NULL
|
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
void catalina_storage_set_async (CatalinaStorage *storage, const gchar *key, gssize key_length, const gchar *value, gssize value_length, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously stores value to the underlying data-store with key. Call
catalina_storage_set_finish() from within callback.
|
A CatalinaStorage |
|
the key of which to assign value
|
|
the length of key in bytes
|
|
the content to store |
|
the length of value in bytes
|
|
A GAsyncReadyCallback |
|
data for callback
|
gboolean catalina_storage_set_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error);
Completes an asynchronous set request. Upon failure, FALSE is returned and error is set.
See catalina_storage_set_async().
|
A CatalinaStorage |
|
A GAsyncResult |
|
A location for GError or NULL
|
Returns : |
TRUE on success
|
gboolean catalina_storage_set (CatalinaStorage *storage, const gchar *key, gssize key_length, const gchar *value, gssize value_length, GError **error);
Synchronously performs a set request.
Upon failure, FALSE is returned and error is set.
See catalina_storage_set_async().
|
A CatalinaStorage |
|
the key of which to store value
|
|
the length of key in bytes or -1 if the key is NULL terminated
|
|
the data to store |
|
the length of data in bytes
|
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
void catalina_storage_get_value_async (CatalinaStorage *storage, const gchar *key, gssize key_length, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously requests the content for key. In the process, the data is retrieved from
storage and deserialized by the CatalinaStorage instance's "formatter" property.
|
A CatalinaStorage |
|
the key to lookup |
|
the length of key in bytes
|
|
A GAsyncReadyCallback |
|
data for callback
|
gboolean catalina_storage_get_value_finish (CatalinaStorage *storage, GAsyncResult *result, GValue *value, GError **error);
Completes an asynchronous request to retreive the content from storage and deserialize using the instance's "formatter" property.
Upon failure, FALSE is returned and error is set.
|
A CatalinaStorage |
|
A GAsyncResult |
|
A GValue |
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
gboolean catalina_storage_get_value (CatalinaStorage *storage, const gchar *key, gssize key_length, GValue *value, GError **error);
Synchronously requests the content for key and deserializes using the instances
"formatter" property.
Upon failure, FALSE is returned and error is set.
void catalina_storage_set_value_async (CatalinaStorage *storage, const gchar *key, gssize key_length, const GValue *value, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously requests the serialization of value and storage to the underlying
data-store.
value is serialized using the instances "formatter" property.
Call catalina_storage_set_value_finish() from within callback.
|
A CatalinaStorage |
|
A buffer containing the key |
|
the length of key in bytes or -1 if key is NULL terminated
|
|
A GValue to serialize and store |
|
A GAsyncReadyCallback |
|
A gpointer |
gboolean catalina_storage_set_value_finish (CatalinaStorage *storage, GAsyncResult *result, GError **error);
Completes and asynchronous request to catalina_storage_set_value_async().
Upon failure, FALSE is returned and error is set.
|
A CatalinaStorage |
|
A GAsyncResult |
|
A location for a GError or NULL
|
Returns : |
TRUE on success
|
gboolean catalina_storage_set_value (CatalinaStorage *storage, const gchar *key, gssize key_length, const GValue *value, GError **error);
Synchronously requests the serialization of value and storage to the underlying data-store.
Upon error, FALSE is returned and error is set.
See catalina_storage_set_value_async().
gboolean catalina_storage_get_use_idle (CatalinaStorage *storage);
Whether or not the asynchronous callbacks should occur from within an idle-timeout within the applications main-loop.
|
A CatalinaStorage |
Returns : |
TRUE if the callbacks will occur in the main-loop
|
void catalina_storage_set_use_idle (CatalinaStorage *storage, gboolean use_idle);
Sets whether or not callbacks should occur from within an idle timeout in the main-loop.
|
A CatalinaStorage |
|
a gboolean |
CatalinaFormatter* catalina_storage_get_formatter (CatalinaStorage *storage);
This method is not thread-safe.
|
A CatalinaStorage |
Returns : |
The CatalinaFormatter property |
void catalina_storage_set_formatter (CatalinaStorage *storage, CatalinaFormatter *formatter);
Sets the "formatter" property.
This method is not thread-safe.
|
A CatalinaStorage |
|
A CatalinaFormatter |
CatalinaTransform* catalina_storage_get_transform (CatalinaStorage *storage);
This method is not thread-safe.
|
A CatalinaStorage |
Returns : |
the CatalinaTransform for the storage instance.
|
void catalina_storage_set_transform (CatalinaStorage *storage, CatalinaTransform *transform);
Sets the CatalinaTransform for the storage. This is the "transform" property.
This method is not thread-safe.
|
A CatalinaStorage |
|
A CatalinaTransform |
"formatter" property"formatter" CatalinaFormatter* : Read / Write
The "formatter" property. The formatter is used when catalina_storage_get_value()
or catalina_storage_set_value() are called. It is responsible for serializing and
deserializing the contents of a GValue into a buffer.
See catalina_formatter_serialize() and catalina_formatter_deserialize().
"transform" property"transform" CatalinaTransform* : Read / Write
The "transform" property. The transform has the ability to manipulate the buffer on the way to and from the data-store. This can be used to add features such as encryption or compression.
See catalina_transform_read() and catalina_transform_write().