Blobs

Data Structures
struct	C4BlobKey
	A unique identifier of a blob based on a SHA-1 digest of its contents. More...

Blob Keys
CBL_CORE_API bool	c4blob_keyFromString (C4String str, C4BlobKey *)
	Decodes a string of the form "sha1-"+base64 into a raw key.
CBL_CORE_API C4StringResult	c4blob_keyToString (C4BlobKey)
	Encodes a blob key to a string of the form "sha1-"+base64.

Blob Store API
CBL_CORE_API C4BlobStore *	c4db_getBlobStore (C4Database *db, C4Error *outError)
	Returns the BlobStore associated with a bundled database.
NODISCARD CBL_CORE_API C4BlobStore *	c4blob_openStore (C4String dirPath, C4DatabaseFlags flags, const C4EncryptionKey *encryptionKey, C4Error *outError)
	Opens a BlobStore in a directory.
CBL_CORE_API void	c4blob_freeStore (C4BlobStore *)
	Closes/frees a BlobStore.
CBL_CORE_API bool	c4blob_deleteStore (C4BlobStore *, C4Error *)
	Deletes the BlobStore's blobs and directory, and (if successful) frees the object.

Blob API
CBL_CORE_API int64_t	c4blob_getSize (C4BlobStore *, C4BlobKey)
	Gets the content size of a blob given its key.
CBL_CORE_API C4SliceResult	c4blob_getContents (C4BlobStore *, C4BlobKey, C4Error *)
	Reads the entire contents of a blob into memory.
CBL_CORE_API C4StringResult	c4blob_getFilePath (C4BlobStore *, C4BlobKey, C4Error *)
	Returns the path of the file that stores the blob, if possible.
NODISCARD CBL_CORE_API C4BlobKey	c4blob_computeKey (C4Slice contents)
	Derives the key of the given data, without storing it.
NODISCARD CBL_CORE_API bool	c4blob_create (C4BlobStore *store, C4Slice contents, const C4BlobKey *expectedKey, C4BlobKey *outKey, C4Error *error)
	Stores a blob.
NODISCARD CBL_CORE_API bool	c4blob_delete (C4BlobStore *, C4BlobKey, C4Error *)
	Deletes a blob from the store given its key.

Streamed Reads
NODISCARD CBL_CORE_API C4ReadStream *	c4blob_openReadStream (C4BlobStore *, C4BlobKey, C4Error *)
	Opens a blob for reading, as a random-access byte stream.
NODISCARD CBL_CORE_API size_t	c4stream_read (C4ReadStream *stream, void *buffer, size_t maxBytesToRead, C4Error *error)
	Reads from an open stream.
CBL_CORE_API int64_t	c4stream_getLength (C4ReadStream *, C4Error *)
	Returns the exact length in bytes of the stream.
NODISCARD CBL_CORE_API bool	c4stream_seek (C4ReadStream *, uint64_t position, C4Error *)
	Moves to a random location in the stream; the next c4stream_read call will read from that location.

Streamed Writes
NODISCARD CBL_CORE_API C4WriteStream *	c4blob_openWriteStream (C4BlobStore *, C4Error *)
	Opens a write stream for creating a new blob.
NODISCARD CBL_CORE_API bool	c4stream_write (C4WriteStream *, const void *bytes, size_t length, C4Error *)
	Writes data to a stream.
CBL_CORE_API uint64_t	c4stream_bytesWritten (C4WriteStream *)
	Returns the number of bytes written to the stream.
NODISCARD CBL_CORE_API C4BlobKey	c4stream_computeBlobKey (C4WriteStream *)
	Computes the blob-key (digest) of the data written to the stream.
NODISCARD CBL_CORE_API bool	c4stream_install (C4WriteStream *, const C4BlobKey *expectedKey, C4Error *)
	Adds the data written to the stream as a finished blob to the store.

Detailed Description

Function Documentation

c4blob_computeKey()

NODISCARD CBL_CORE_API C4BlobKey c4blob_computeKey

(

C4Slice

contents

)

Derives the key of the given data, without storing it.

c4blob_create()

NODISCARD CBL_CORE_API bool c4blob_create	(	C4BlobStore *	store,
		C4Slice	contents,
		const C4BlobKey *	expectedKey,
		C4BlobKey *	outKey,
		C4Error *	error )

Stores a blob.

The associated key will be written to outKey, if non-NULL. If expectedKey is not NULL, then the operation will fail unless the contents actually have that key.

c4blob_delete()

NODISCARD CBL_CORE_API bool c4blob_delete	(	C4BlobStore *	,
		C4BlobKey	,
		C4Error *	)

Deletes a blob from the store given its key.

c4blob_deleteStore()

CBL_CORE_API bool c4blob_deleteStore	(	C4BlobStore *	,
		C4Error *	)

Deletes the BlobStore's blobs and directory, and (if successful) frees the object.

Note

This function is thread-safe.

Warning

This should only be used for unit testing. Never delete a BlobStore belonging to a C4Database.

c4blob_freeStore()

CBL_CORE_API void c4blob_freeStore

(

C4BlobStore *

)

Closes/frees a BlobStore.

(A NULL parameter is allowed.)

Note

This function is thread-safe.

Warning

This should only be used for unit testing. Never free a BlobStore belonging to a C4Database.

c4blob_getContents()

CBL_CORE_API C4SliceResult c4blob_getContents	(	C4BlobStore *	,
		C4BlobKey	,
		C4Error *	)

Reads the entire contents of a blob into memory.

Caller is responsible for freeing it.

c4blob_getFilePath()

CBL_CORE_API C4StringResult c4blob_getFilePath	(	C4BlobStore *	,
		C4BlobKey	,
		C4Error *	)

Returns the path of the file that stores the blob, if possible.

This call may fail with error kC4ErrorWrongFormat if the blob is encrypted (in which case the file would be unreadable by the caller) or with kC4ErrorUnsupported if for some implementation reason the blob isn't stored as a standalone file. Thus, the caller MUST use this function only as an optimization, and fall back to reading the contents via the API if it fails. Also, it goes without saying that the caller MUST not modify the file!

c4blob_getSize()

CBL_CORE_API int64_t c4blob_getSize	(	C4BlobStore *	,
		C4BlobKey	)

Gets the content size of a blob given its key.

Returns -1 if it doesn't exist. WARNING: If the blob is encrypted, the return value is a conservative estimate that may be up to 16 bytes larger than the actual size.

c4blob_keyFromString()

CBL_CORE_API bool c4blob_keyFromString	(	C4String	str,
		C4BlobKey *	)

Decodes a string of the form "sha1-"+base64 into a raw key.

Note

This function is thread-safe.

c4blob_keyToString()

CBL_CORE_API C4StringResult c4blob_keyToString

(

C4BlobKey

)

Encodes a blob key to a string of the form "sha1-"+base64.

Note

This function is thread-safe.

c4blob_openReadStream()

NODISCARD CBL_CORE_API C4ReadStream * c4blob_openReadStream	(	C4BlobStore *	,
		C4BlobKey	,
		C4Error *	)

Opens a blob for reading, as a random-access byte stream.

Note

This function is thread-safe.

c4blob_openStore()

NODISCARD CBL_CORE_API C4BlobStore * c4blob_openStore	(	C4String	dirPath,
		C4DatabaseFlags	flags,
		const C4EncryptionKey *	encryptionKey,
		C4Error *	outError )

Opens a BlobStore in a directory.

If the flags allow creating, the directory will be created if necessary. Call c4blob_freeStore() when finished using the BlobStore.

Note

This function is thread-safe.

Warning

This should only be used for unit testing. Naked BlobStores are not supported.

Parameters

dirPath	The filesystem path of the directory holding the attachments.
flags	Specifies options like create, read-only
encryptionKey	Optional encryption algorithm & key
outError	Error is returned here

Returns

The BlobStore reference, or NULL on error

c4blob_openWriteStream()

NODISCARD CBL_CORE_API C4WriteStream * c4blob_openWriteStream	(	C4BlobStore *	,
		C4Error *	)

Opens a write stream for creating a new blob.

You should then call c4stream_write to write the data, ending with c4stream_install to compute the blob's key and add it to the store, and then c4stream_closeWriter.

Note

This function is thread-safe.

c4db_getBlobStore()

CBL_CORE_API C4BlobStore * c4db_getBlobStore	(	C4Database *	db,
		C4Error *	outError )

Returns the BlobStore associated with a bundled database.

Note

The caller must use a lock for Database when this function is called.

Fails if the database is not bundled. DO NOT call c4blob_freeStore on this! The C4Database will free it when it closes.

c4stream_bytesWritten()

CBL_CORE_API uint64_t c4stream_bytesWritten

(

C4WriteStream *

)

Returns the number of bytes written to the stream.

Note

The caller must use a lock for WriteStream when this function is called.

c4stream_computeBlobKey()

NODISCARD CBL_CORE_API C4BlobKey c4stream_computeBlobKey

(

C4WriteStream *

)

Computes the blob-key (digest) of the data written to the stream.

This should only be called after writing the entire data. No more data can be written after this call.

Note

The caller must use a lock for WriteStream when this function is called.

c4stream_getLength()

CBL_CORE_API int64_t c4stream_getLength	(	C4ReadStream *	,
		C4Error *	)

Returns the exact length in bytes of the stream.

Note

This function is thread-safe.

c4stream_install()

NODISCARD CBL_CORE_API bool c4stream_install	(	C4WriteStream *	,
		const C4BlobKey *	expectedKey,
		C4Error *	)

Adds the data written to the stream as a finished blob to the store.

If expectedKey is not NULL, then the operation will fail unless the contents actually have that key. (If you don't know ahead of time what the key should be, call c4stream_computeBlobKey beforehand to derive it, and pass NULL for expectedKey.) This function does not close the writer.

Note

The caller must use a lock for WriteStream when this function is called.

c4stream_read()

NODISCARD CBL_CORE_API size_t c4stream_read	(	C4ReadStream *	stream,
		void *	buffer,
		size_t	maxBytesToRead,
		C4Error *	error )

Reads from an open stream.

Note

The caller must use a lock for ReadStream when this function is called.

Parameters

stream	The open stream to read from
buffer	Where to copy the read data to
maxBytesToRead	The maximum number of bytes to read to the buffer
error	Error is returned here

Returns

The actual number of bytes read, or 0 if an error occurred

c4stream_seek()

NODISCARD CBL_CORE_API bool c4stream_seek	(	C4ReadStream *	,
		uint64_t	position,
		C4Error *	)

Moves to a random location in the stream; the next c4stream_read call will read from that location.

Note

The caller must use a lock for ReadStram when this function is called.

c4stream_write()

NODISCARD CBL_CORE_API bool c4stream_write	(	C4WriteStream *	,
		const void *	bytes,
		size_t	length,
		C4Error *	)

Writes data to a stream.

Note

The caller must use a lock for WriteStream when this function is called.