quasardb C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
String operations

Functions

QDB_API_LINKAGE qdb_error_t qdb_string_get_noalloc (qdb_handle_t handle, const char *alias, char *content, qdb_size_t *content_length)
 Retrieves an entry's content from the quasardb server. The caller is responsible for allocating and freeing the provided buffer. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_get (qdb_handle_t handle, const char *alias, const char **content, qdb_size_t *content_length)
 Retrieves an entry's content from the quasardb server. More...
 
QDB_API_LINKAGE qdb_error_t qdb_reserved_string_get (qdb_handle_t handle, const char *alias, const char **content, qdb_size_t *content_length, qdb_size_t offset)
 Retrieves a part of an entry's content from the quasardb server. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_get_and_remove (qdb_handle_t handle, const char *alias, const char **content, qdb_size_t *content_length)
 Atomically gets an entry from the quasardb server and removes it. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_put (qdb_handle_t handle, const char *alias, const char *content, qdb_size_t content_length, qdb_time_t expiry_time)
 Creates a new entry and sets its content to the provided string. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_update (qdb_handle_t handle, const char *alias, const char *content, qdb_size_t content_length, qdb_time_t expiry_time)
 Creates or updates an entry and sets its content to the provided string. More...
 
QDB_API_LINKAGE qdb_error_t qdb_reserved_string_merge (qdb_handle_t handle, const char *alias, const char *content, qdb_size_t content_length, qdb_size_t offset, int truncate, qdb_time_t expiry_time)
 This function is reserved for internal use and its usage is discouraged. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_get_and_update (qdb_handle_t handle, const char *alias, const char *update_content, qdb_size_t update_content_length, qdb_time_t expiry_time, const char **get_content, qdb_size_t *get_content_length)
 Atomically gets and updates (in this order) the entry on the quasardb server. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_compare_and_swap (qdb_handle_t handle, const char *alias, const char *new_value, qdb_size_t new_value_length, const char *comparand, qdb_size_t comparand_length, qdb_time_t expiry_time, const char **original_value, qdb_size_t *original_value_length)
 Atomically compares the entry with comparand and updates it to new_value if, and only if, they match. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_remove_if (qdb_handle_t handle, const char *alias, const char *comparand, qdb_size_t comparand_length)
 Atomically removes the entry on the server if the content matches. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_scan (qdb_handle_t handle, const char *pattern, qdb_size_t pattern_length, qdb_int_t max_count, const char ***aliases, size_t *alias_count)
 Retrieves all strings that have content matching the specified pattern. More...
 
QDB_API_LINKAGE qdb_error_t qdb_string_scan_regex (qdb_handle_t handle, const char *pattern, qdb_int_t max_count, const char ***aliases, size_t *alias_count)
 Retrieves all strings that have content matching the specified regular expression (regex) More...
 

Detailed Description

Function Documentation

QDB_API_LINKAGE qdb_error_t qdb_reserved_string_get ( qdb_handle_t  handle,
const char *  alias,
const char **  content,
qdb_size_t content_length,
qdb_size_t  offset 
)

Retrieves a part of an entry's content from the quasardb server.

If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

The function will allocate a buffer large enough to hold the entry's content. This buffer must be released by the caller with a call to qdb_release().

The returned content will be a subset of the entry's data in the range [offset, offset + *content_length).

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
[out]contentA pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
[out]content_lengthA pointer to a qdb_size_t that holds the length of the requested content and that will be set to the returned content's size, in bytes. If content length is equal to zero or is greater than entry's length minus offset, then all the content from offset until the end will be returned.
offsetOffset from which to get content, in bytes.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_reserved_string_merge ( qdb_handle_t  handle,
const char *  alias,
const char *  content,
qdb_size_t  content_length,
qdb_size_t  offset,
int  truncate,
qdb_time_t  expiry_time 
)

This function is reserved for internal use and its usage is discouraged.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
contentA pointer to the content to merge
content_lengthThe length of the buffer, in bytes
offsetOffset at which merge content
truncate1 - the entry will be truncated at the end of the new buffer. 0 - the original content will be preserved.
expiry_timeAn optional absolute expiry time expressed in UTC UNIX epoch.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_compare_and_swap ( qdb_handle_t  handle,
const char *  alias,
const char *  new_value,
qdb_size_t  new_value_length,
const char *  comparand,
qdb_size_t  comparand_length,
qdb_time_t  expiry_time,
const char **  original_value,
qdb_size_t original_value_length 
)

Atomically compares the entry with comparand and updates it to new_value if, and only if, they match.

The function returns the original value of the entry in case of a mismatch. When it matches, no content is returned.

The entry must already exist.

Update will occur if and only if the content of the entry matches bit for bit the content of the comparand buffer.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
new_valueA pointer to a buffer that represents the entry's content to be updated to the server in case of match.
new_value_lengthThe length of the buffer, in bytes
comparandA pointer to a buffer that represents the entry's content to be compared to.
comparand_lengthThe length of the buffer, in bytes
expiry_timeAn optional absolute expiry time expressed in UTC UNIX epoch.
[out]original_valueA pointer to a pointer that will be set to a function-allocated buffer holding the entry's original content, before the update, if any.
[out]original_value_lengthA pointer to a qdb_size_t that will be set to the content's size, in bytes.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_get ( qdb_handle_t  handle,
const char *  alias,
const char **  content,
qdb_size_t content_length 
)

Retrieves an entry's content from the quasardb server.

If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

The function will allocate a buffer large enough to hold the entry's content. This buffer must be released by the caller with a call to qdb_release().

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
[out]contentA pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
[out]content_lengthA pointer to a qdb_size_t that will be set to the content's size, in bytes.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_get_and_remove ( qdb_handle_t  handle,
const char *  alias,
const char **  content,
qdb_size_t content_length 
)

Atomically gets an entry from the quasardb server and removes it.

If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

The function will allocate a buffer large enough to hold the entry's content. This buffer must be released by the caller with a call to qdb_release().

If the buffer is not large enough to hold the data, the function will fail and return qdb_e_buffer_too_small. content_length will nevertheless be updated with entry size so that the caller may resize its buffer and try again.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
[out]contentA pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
[out]content_lengthA pointer to a qdb_size_t that will be set to the content's size, in bytes.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_get_and_update ( qdb_handle_t  handle,
const char *  alias,
const char *  update_content,
qdb_size_t  update_content_length,
qdb_time_t  expiry_time,
const char **  get_content,
qdb_size_t get_content_length 
)

Atomically gets and updates (in this order) the entry on the quasardb server.

The entry must already exist.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
update_contentA pointer to the buffer with the new string content
update_content_lengthThe length of the buffer, in bytes
expiry_timeAn optional absolute expiry time expressed in UTC UNIX epoch.
[out]get_contentA pointer to a pointer to an API-allocated buffer holding the entry content, before the update.
[out]get_content_lengthA pointer to a qdb_size_t that will be set to the content's size, in bytes.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_get_noalloc ( qdb_handle_t  handle,
const char *  alias,
char *  content,
qdb_size_t content_length 
)

Retrieves an entry's content from the quasardb server. The caller is responsible for allocating and freeing the provided buffer.

If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

If the buffer is not large enough to hold the data, the function will fail and return qdb_e_buffer_too_small. content_length will nevertheless be updated with entry size so that the caller may resize its buffer and try again.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
[in,out]contentA pointer to a user-allocated buffer that will receive the entry's content.
[out]content_lengthA pointer to a qdb_size_t initialized with the length of the destination buffer, in bytes. It will be updated with the length of the retrieved content, even if the buffer is not large enough to hold all the data.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_put ( qdb_handle_t  handle,
const char *  alias,
const char *  content,
qdb_size_t  content_length,
qdb_time_t  expiry_time 
)

Creates a new entry and sets its content to the provided string.

If the entry already exists the function will fail and will return qdb_e_alias_already_exists.

You can specify an expiry or use qdb_never_expires if you don't want the entry to expire.

There is no software-defined limit to the size of strings.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
contentA pointer to the buffer with the string content
content_lengthThe length of the buffer, in bytes
expiry_timeAn optional absolute expiry time expressed in UTC UNIX epoch.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_remove_if ( qdb_handle_t  handle,
const char *  alias,
const char *  comparand,
qdb_size_t  comparand_length 
)

Atomically removes the entry on the server if the content matches.

The entry must already exist.

Removal will occur if and only if the content of the entry matches bit for bit the content of the comparand buffer.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
comparandA pointer to a buffer to use a comparand
comparand_lengthThe length of the buffer, in bytes
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_scan ( qdb_handle_t  handle,
const char *  pattern,
qdb_size_t  pattern_length,
qdb_int_t  max_count,
const char ***  aliases,
size_t *  alias_count 
)

Retrieves all strings that have content matching the specified pattern.

Warning
This function is experimental.

The complexity of this function is linear in the number of entries.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
patternA pointer to the pattern buffer to search for
pattern_lengthThe length of the pattern buffer, in bytes
max_countAn integer limiting the number of results returned by the function
[out]aliasesA pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries matching the requested pattern.
[out]alias_countA pointer to an integer that will receive the number of returned aliases.
Returns
A qdb_error_t code indicating success or failure.
QDB_API_LINKAGE qdb_error_t qdb_string_scan_regex ( qdb_handle_t  handle,
const char *  pattern,
qdb_int_t  max_count,
const char ***  aliases,
size_t *  alias_count 
)

Retrieves all strings that have content matching the specified regular expression (regex)

Warning
This function is experimental.

The complexity of this function is linear in the number of entries.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
patternA pointer to a null-terminated UTF-8 string representing the regular expression to search for. The regex syntax is defined by ECMA-262 grammar.
max_countAn integer limiting the number of results returned by the function.
[out]aliasesA pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries matching the requested pattern.
[out]alias_countA pointer to an integer that will receive the number of returned aliases.
Returns
A qdb_error_t code indicating success or failure.
See Also
http://ecma-international.org/ecma-262/5.1/#sec-15.10
QDB_API_LINKAGE qdb_error_t qdb_string_update ( qdb_handle_t  handle,
const char *  alias,
const char *  content,
qdb_size_t  content_length,
qdb_time_t  expiry_time 
)

Creates or updates an entry and sets its content to the provided string.

If the entry already exists, the function will modify the entry.

You can specify an expiry or use qdb_never_expires if you don't want the entry to expire.

There is no software-defined limit to the size of strings.

Parameters
handleA valid handle previously initialized by qdb_open or qdb_open_tcp.
aliasA pointer to a null-terminated UTF-8 string representing the alias of the entry.
contentA pointer to the buffer with the string content
content_lengthThe length of the buffer, in bytes
expiry_timeAn optional absolute expiry time expressed in UTC UNIX epoch.
Returns
A qdb_error_t code indicating success or failure.