quasardb C API: Binary large objects (blob) operations

quasardb C API

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Binary large objects (blob) operations

## Functions
QDB_API_LINKAGE qdb_error_t | qdb_blob_get_noalloc (qdb_handle_t handle, const char *alias, void *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_blob_get (qdb_handle_t handle, const char *alias, const void **content, qdb_size_t *content_length)
| Retrieves an entry's content from the quasardb server. More...
QDB_API_LINKAGE qdb_error_t | qdb_reserved_blob_get (qdb_handle_t handle, const char *alias, const void **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_blob_get_and_remove (qdb_handle_t handle, const char *alias, const void **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_blob_put (qdb_handle_t handle, const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)
| Creates a new entry and sets its content to the provided blob. More...
QDB_API_LINKAGE qdb_error_t | qdb_blob_update (qdb_handle_t handle, const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)
| Creates or updates an entry and sets its content to the provided blob. More...
QDB_API_LINKAGE qdb_error_t | qdb_reserved_blob_merge (qdb_handle_t handle, const char *alias, const void *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_blob_get_and_update (qdb_handle_t handle, const char *alias, const void *update_content, qdb_size_t update_content_length, qdb_time_t expiry_time, const void **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_blob_compare_and_swap (qdb_handle_t handle, const char *alias, const void *new_value, qdb_size_t new_value_length, const void *comparand, qdb_size_t comparand_length, qdb_time_t expiry_time, const void **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_blob_remove_if (qdb_handle_t handle, const char *alias, const void *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_blob_scan (qdb_handle_t handle, const void *pattern, qdb_size_t pattern_length, qdb_int_t max_count, const char ***aliases, size_t *alias_count)
| Retrieves all blobs that have content matching the specified pattern. More...
QDB_API_LINKAGE qdb_error_t | qdb_blob_scan_regex (qdb_handle_t handle, const char *pattern, qdb_int_t max_count, const char ***aliases, size_t *alias_count)
| Retrieves all blobs that have content matching the specified regular expression (regex) More...

## Detailed Description

## Function Documentation

QDB_API_LINKAGE qdb_error_t qdb_blob_compare_and_swap | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | new_value,
|  | qdb_size_t | new_value_length,
|  | const void * | comparand,
|  | qdb_size_t | comparand_length,
|  | qdb_time_t | expiry_time,
|  | const void ** | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  | new_value | A pointer to a buffer that represents the entry's content to be updated to the server in case of match.
  | new_value_length | The length of the buffer, in bytes
  | comparand | A pointer to a buffer that represents the entry's content to be compared to.
  | comparand_length | The length of the buffer, in bytes
  | expiry_time | An optional absolute expiry time expressed in UTC UNIX epoch.
  [out] | original_value | A 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_length | A 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_blob_get | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void ** | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | content | A pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
  [out] | content_length | A 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_blob_get_and_remove | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void ** | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | content | A pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
  [out] | content_length | A 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_blob_get_and_update | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | update_content,
|  | qdb_size_t | update_content_length,
|  | qdb_time_t | expiry_time,
|  | const void ** | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  | update_content | A pointer to the buffer with the new blob content
  | update_content_length | The length of the buffer, in bytes
  | expiry_time | An optional absolute expiry time expressed in UTC UNIX epoch.
  [out] | get_content | A pointer to a pointer to an API-allocated buffer holding the entry content, before the update.
  [out] | get_content_length | A 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_blob_get_noalloc | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | void * | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [in,out] | content | A pointer to a user-allocated buffer that will receive the entry's content.
  [out] | content_length | A 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_blob_put | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | content,
|  | qdb_size_t | content_length,
|  | qdb_time_t | expiry_time
| ) |  |

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

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

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  content | A pointer to the buffer with the blob content
  content_length | The length of the buffer, in bytes
  expiry_time | An 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_blob_remove_if | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | 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

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  comparand | A pointer to a buffer to use a comparand
  comparand_length | The length of the buffer, in bytes

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_blob_scan | ( | qdb_handle_t | handle,
|  | const void * | pattern,
|  | qdb_size_t | pattern_length,
|  | qdb_int_t | max_count,
|  | const char *** | aliases,
|  | size_t * | alias_count
| ) |  |

Retrieves all blobs 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | pattern | A pointer to the pattern buffer to search for
  | pattern_length | The length of the pattern buffer, in bytes
  | max_count | An integer limiting the number of results returned by the function
  [out] | aliases | A pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries matching the requested pattern.
  [out] | alias_count | A 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_blob_scan_regex | ( | qdb_handle_t | handle,
|  | const char * | pattern,
|  | qdb_int_t | max_count,
|  | const char *** | aliases,
|  | size_t * | alias_count
| ) |  |

Retrieves all blobs 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | pattern | A 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_count | An integer limiting the number of results returned by the function.
  [out] | aliases | A pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries matching the requested pattern.
  [out] | alias_count | A 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_blob_update | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | content,
|  | qdb_size_t | content_length,
|  | qdb_time_t | expiry_time
| ) |  |

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

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

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  content | A pointer to the buffer with the blob content
  content_length | The length of the buffer, in bytes
  expiry_time | An 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_reserved_blob_get | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void ** | 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

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | content | A pointer to a pointer that will be set to a function-allocated buffer holding the entry's content.
  [out] | content_length | A 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.
  | offset | Offset 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_blob_merge | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | const void * | 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

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  content | A pointer to the content to merge
  content_length | The length of the buffer, in bytes
  offset | Offset at which merge content
  truncate | 1 - the entry will be truncated at the end of the new buffer. 0 - the original content will be preserved.
  expiry_time | An optional absolute expiry time expressed in UTC UNIX epoch.

Returns
  A qdb_error_t code indicating success or failure.