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.