Blobs

A CBLBlob is a binary data blob associated with a document. More...

Typedefs
typedef struct CBLBlob	CBLBlob
	A binary data value associated with a CBLDocument. More...
typedef struct CBLBlobReadStream	CBLBlobReadStream
	A stream for reading a blob's content. More...
typedef struct CBLBlobWriteStream	CBLBlobWriteStream
	A stream for writing a new blob to the database. More...

Enumerations
enum	CBLSeekBase : uint8_t { kCBLSeekModeFromStart , kCBLSeekModeRelative , kCBLSeekModeFromEnd }
	Defines the interpretation of offset in CBLBlobReader_Seek. More...

Functions
static const CBLBlob *	CBLBlob_Retain (const CBLBlob *t)
static void	CBLBlob_Release (const CBLBlob *t)
bool	FLDict_IsBlob (FLDict _cbl_nullable)
	Returns true if a dictionary in a document is a blob reference. More...
const CBLBlob *_cbl_nullable	FLDict_GetBlob (FLDict _cbl_nullable blobDict)
	Returns a CBLBlob object corresponding to a blob dictionary in a document. More...
uint64_t	CBLBlob_Length (const CBLBlob *)
	Returns the length in bytes of a blob's content (from its length property). More...
FLString	CBLBlob_Digest (const CBLBlob *)
	Returns the cryptographic digest of a blob's content (from its digest property). More...
FLString	CBLBlob_ContentType (const CBLBlob *)
	Returns a blob's MIME type, if its metadata has a content_type property. More...
FLDict	CBLBlob_Properties (const CBLBlob *)
	Returns a blob's metadata. More...
_cbl_warn_unused FLStringResult	CBLBlob_CreateJSON (const CBLBlob *blob)
	Returns a blob's metadata as JSON. More...
_cbl_warn_unused FLSliceResult	CBLBlob_Content (const CBLBlob *blob, CBLError *_cbl_nullable outError)
	Reads the blob's contents into memory and returns them. More...
_cbl_warn_unused CBLBlobReadStream *_cbl_nullable	CBLBlob_OpenContentStream (const CBLBlob *blob, CBLError *_cbl_nullable)
	Opens a stream for reading a blob's content. More...
int	CBLBlobReader_Read (CBLBlobReadStream *stream, void *dst, size_t maxLength, CBLError *_cbl_nullable outError)
	Reads data from a blob. More...
int64_t	CBLBlobReader_Seek (CBLBlobReadStream *stream, int64_t offset, CBLSeekBase base, CBLError *_cbl_nullable outError)
	Sets the position of a CBLBlobReadStream. More...
uint64_t	CBLBlobReader_Position (CBLBlobReadStream *stream)
	Returns the current position of a CBLBlobReadStream. More...
void	CBLBlobReader_Close (CBLBlobReadStream *_cbl_nullable)
	Closes a CBLBlobReadStream. More...
bool	CBLBlob_Equals (CBLBlob *blob, CBLBlob *anotherBlob)
	Compares whether the two given blobs are equal based on their content. More...
_cbl_warn_unused CBLBlob *	CBLBlob_CreateWithData (FLString contentType, FLSlice contents)
	Creates a new blob given its contents as a single block of data. More...
_cbl_warn_unused CBLBlobWriteStream *_cbl_nullable	CBLBlobWriter_Create (CBLDatabase *db, CBLError *_cbl_nullable)
	Opens a stream for writing a new blob. More...
void	CBLBlobWriter_Close (CBLBlobWriteStream *_cbl_nullable)
	Closes a blob-writing stream, if you need to give up without creating a CBLBlob. More...
bool	CBLBlobWriter_Write (CBLBlobWriteStream *writer, const void *data, size_t length, CBLError *_cbl_nullable outError)
	Writes data to a new blob. More...
_cbl_warn_unused CBLBlob *	CBLBlob_CreateWithStream (FLString contentType, CBLBlobWriteStream *writer)
	Creates a new blob after its data has been written to a CBLBlobWriteStream. More...
static bool	FLValue_IsBlob (FLValue _cbl_nullable v)
	Returns true if a value in a document is a blob reference. More...
static const CBLBlob *_cbl_nullable	FLValue_GetBlob (FLValue _cbl_nullable value)
	Instantiates a CBLBlob object corresponding to a blob dictionary in a document. More...
void	FLSlot_SetBlob (FLSlot slot, CBLBlob *blob)
static void	FLMutableArray_SetBlob (FLMutableArray array, uint32_t index, CBLBlob *blob)
	Stores a blob reference into an array. More...
static void	FLMutableArray_AppendBlob (FLMutableArray array, CBLBlob *blob)
	Appends a blob reference to an array. More...
static void	FLMutableDict_SetBlob (FLMutableDict dict, FLString key, CBLBlob *blob)
	Stores a blob reference into a Dict. More...
const CBLBlob *_cbl_nullable	CBLDatabase_GetBlob (CBLDatabase *db, FLDict properties, CBLError *_cbl_nullable outError)
	(UNCOMMITTED) Use this API if you are developing Javascript language bindings. More...
bool	CBLDatabase_SaveBlob (CBLDatabase *db, CBLBlob *blob, CBLError *_cbl_nullable outError)
	(UNCOMMITTED) Use this API if you are developing Javascript language bindings. More...

Variables
CBL_PUBLIC const FLSlice	kCBLBlobType
	"blob" More...
CBL_PUBLIC const FLSlice	kCBLBlobDigestProperty
	"digest" More...
CBL_PUBLIC const FLSlice	kCBLBlobLengthProperty
	"length" More...
CBL_PUBLIC const FLSlice	kCBLBlobContentTypeProperty
	"content_type" More...

Detailed Description

A CBLBlob is a binary data blob associated with a document.

The content of the blob is not stored in the document, but externally in the database. It is loaded only on demand, and can be streamed. Blobs can be arbitrarily large, although Sync Gateway will only accept blobs under 20MB.

The document contains only a blob reference: a dictionary with the special marker property "@type":"blob", and another property digest whose value is a hex SHA-1 digest of the blob's data. This digest is used as the key to retrieve the blob data. The dictionary usually also has the property length, containing the blob's length in bytes, and it may have the property content_type, containing a MIME type.

A CBLBlob object acts as a proxy for such a dictionary in a CBLDocument. Once you've loaded a document and located the Fleece Dictionaries holding the blob reference, call FLDict_GetBlob on it to create a CBLBlob object you can call. The object has accessors for the blob's metadata and for loading the data itself.

To create a new blob from in-memory data, call CBLBlob_CreateWithData, then call FLSlot_SetBlob to add the CBLBlob to a mutable array or dictionary in the document. For example:

FLSlot_SetBlob(FLMutableDict_Set(properties, key), blob);

To create a new blob from a stream, call CBLBlobWriter_Create to create a CBLBlobWriteStream, then make one or more calls to CBLBlobWriter_Write to write data to the blob, then finally call CBLBlob_CreateWithStream to create the blob. To store the blob into a document, do as in the previous paragraph.

Typedef Documentation

CBLBlob

typedef struct CBLBlob CBLBlob

A binary data value associated with a CBLDocument.

CBLBlobReadStream

typedef struct CBLBlobReadStream CBLBlobReadStream

A stream for reading a blob's content.

CBLBlobWriteStream

typedef struct CBLBlobWriteStream CBLBlobWriteStream

A stream for writing a new blob to the database.

Enumeration Type Documentation

CBLSeekBase

enum CBLSeekBase : uint8_t

Defines the interpretation of offset in CBLBlobReader_Seek.

Enumerator
kCBLSeekModeFromStart	Offset is an absolute position starting from 0.
kCBLSeekModeRelative	Offset is relative to the current stream position.
kCBLSeekModeFromEnd	Offset is relative to the end of the blob.

Function Documentation

CBLBlob_Content()

_cbl_warn_unused FLSliceResult CBLBlob_Content	(	const CBLBlob *	blob,
		CBLError *_cbl_nullable	outError
	)

Reads the blob's contents into memory and returns them.

Note

You are responsible for releasing the result by calling FLSliceResult_Release.

CBLBlob_ContentType()

FLString CBLBlob_ContentType

(

const CBLBlob *

)

Returns a blob's MIME type, if its metadata has a content_type property.

CBLBlob_CreateJSON()

_cbl_warn_unused FLStringResult CBLBlob_CreateJSON

(

const CBLBlob *

blob

)

Returns a blob's metadata as JSON.

CBLBlob_CreateWithData()

_cbl_warn_unused CBLBlob * CBLBlob_CreateWithData	(	FLString	contentType,
		FLSlice	contents
	)

Creates a new blob given its contents as a single block of data.

Note

You are responsible for releasing the CBLBlob, but not until after its document has been saved.

Parameters

contentType	The MIME type (optional).
contents	The data's address and length.

Returns

A new CBLBlob instance.

CBLBlob_CreateWithStream()

_cbl_warn_unused CBLBlob * CBLBlob_CreateWithStream	(	FLString	contentType,
		CBLBlobWriteStream *	writer
	)

Creates a new blob after its data has been written to a CBLBlobWriteStream.

You should then add the blob to a mutable document as a property – see FLSlot_SetBlob.

Note

You are responsible for releasing the CBLBlob reference.

Do not free the stream; the blob will do that.

Parameters

contentType	The MIME type (optional).
writer	The blob-writing stream the data was written to.

Returns

A new CBLBlob instance.

CBLBlob_Digest()

FLString CBLBlob_Digest

(

const CBLBlob *

)

Returns the cryptographic digest of a blob's content (from its digest property).

CBLBlob_Equals()

bool CBLBlob_Equals	(	CBLBlob *	blob,
		CBLBlob *	anotherBlob
	)

Compares whether the two given blobs are equal based on their content.

CBLBlob_Length()

uint64_t CBLBlob_Length

(

const CBLBlob *

)

Returns the length in bytes of a blob's content (from its length property).

CBLBlob_OpenContentStream()

_cbl_warn_unused CBLBlobReadStream *_cbl_nullable CBLBlob_OpenContentStream	(	const CBLBlob *	blob,
		CBLError *	_cbl_nullable
	)

Opens a stream for reading a blob's content.

CBLBlob_Properties()

FLDict CBLBlob_Properties

(

const CBLBlob *

)

Returns a blob's metadata.

This includes the digest, length, content_type, and @type properties, as well as any custom ones that may have been added.

CBLBlob_Release()

static void CBLBlob_Release ( const CBLBlob *  t )

inlinestatic

CBLBlob_Retain()

static const CBLBlob * CBLBlob_Retain ( const CBLBlob *  t )

inlinestatic

CBLBlobReader_Close()

void CBLBlobReader_Close

(

CBLBlobReadStream *

_cbl_nullable

)

Closes a CBLBlobReadStream.

CBLBlobReader_Position()

uint64_t CBLBlobReader_Position

(

CBLBlobReadStream *

stream

)

Returns the current position of a CBLBlobReadStream.

CBLBlobReader_Read()

int CBLBlobReader_Read	(	CBLBlobReadStream *	stream,
		void *	dst,
		size_t	maxLength,
		CBLError *_cbl_nullable	outError
	)

Reads data from a blob.

Parameters

stream	The stream to read from.
dst	The address to copy the read data to.
maxLength	The maximum number of bytes to read.
outError	On failure, an error will be stored here if non-NULL.

Returns

The actual number of bytes read; 0 if at EOF, -1 on error.

CBLBlobReader_Seek()

int64_t CBLBlobReader_Seek	(	CBLBlobReadStream *	stream,
		int64_t	offset,
		CBLSeekBase	base,
		CBLError *_cbl_nullable	outError
	)

Sets the position of a CBLBlobReadStream.

Parameters

stream	The stream to reposition.
offset	The byte offset in the stream (relative to the mode).
base	The base position from which the offset is calculated.
outError	On failure, an error will be stored here if non-NULL.

Returns

The new absolute position, or -1 on failure.

CBLBlobWriter_Close()

void CBLBlobWriter_Close

(

CBLBlobWriteStream *

_cbl_nullable

)

Closes a blob-writing stream, if you need to give up without creating a CBLBlob.

CBLBlobWriter_Create()

_cbl_warn_unused CBLBlobWriteStream *_cbl_nullable CBLBlobWriter_Create	(	CBLDatabase *	db,
		CBLError *	_cbl_nullable
	)

Opens a stream for writing a new blob.

You should next call CBLBlobWriter_Write one or more times to write the data, then CBLBlob_CreateWithStream to create the blob.

If for some reason you need to abort, just call CBLBlobWriter_Close.

CBLBlobWriter_Write()

bool CBLBlobWriter_Write	(	CBLBlobWriteStream *	writer,
		const void *	data,
		size_t	length,
		CBLError *_cbl_nullable	outError
	)

Writes data to a new blob.

Parameters

writer	The stream to write to.
data	The address of the data to write.
length	The length of the data to write.
outError	On failure, error info will be written here.

Returns

True on success, false on failure.

CBLDatabase_GetBlob()

const CBLBlob *_cbl_nullable CBLDatabase_GetBlob	(	CBLDatabase *	db,
		FLDict	properties,
		CBLError *_cbl_nullable	outError
	)

(UNCOMMITTED) Use this API if you are developing Javascript language bindings.

If you are developing a native app, you must use the CBLBlob API.

Get a CBLBlob object from the database using the CBLBlob properties.

The CBLBlob properties is a blob's metadata containing two required fields which are a special marker property "@type":"blob", and property digest whose value is a hex SHA-1 digest of the blob's data. The other optional properties are length and content_type. To obtain the CBLBlob properties from a CBLBlob, call CBLBlob_Properties function.

Note

You must release the CBLBlob when you're finished with it.

Parameters

db	The database.
properties	The properties for getting the CBLBlob object.
outError	On failure, error info will be written here if specified. A nonexistent blob is not considered a failure; in that event the error code will be zero.

Returns

A CBLBlob instance, or NULL if the doc doesn't exist or an error occurred.

CBLDatabase_SaveBlob()

bool CBLDatabase_SaveBlob	(	CBLDatabase *	db,
		CBLBlob *	blob,
		CBLError *_cbl_nullable	outError
	)

(UNCOMMITTED) Use this API if you are developing Javascript language bindings.

If you are developing a native app, you must use the CBLBlob API.

Save a new CBLBlob object into the database without associating it with any documents. The properties of the saved CBLBlob object will include information necessary for referencing the CBLBlob object in the properties of the document to be saved into the database.

Normally you do not need to use this function unless you are in the situation (e.g. developing javascript binding) that you cannot retain the CBLBlob object until the document containing the CBLBlob object is successfully saved into the database.

Note

The saved CBLBlob objects that are not associated with any documents will be removed from the database when compacting the database.

Parameters

db	The database.
blob	The The CBLBlob to save.
outError	On failure, error info will be written here.

FLDict_GetBlob()

const CBLBlob *_cbl_nullable FLDict_GetBlob

(

FLDict _cbl_nullable

blobDict

)

Returns a CBLBlob object corresponding to a blob dictionary in a document.

Parameters

blobDict

A dictionary in a document.

Returns

A CBLBlob instance for this blob, or NULL if the dictionary is not a blob.

FLDict_IsBlob()

bool FLDict_IsBlob

(

FLDict

_cbl_nullable

)

Returns true if a dictionary in a document is a blob reference.

If so, you can call FLDict_GetBlob to access it.

Note

This function tests whether the dictionary has a @type property, whose value is "blob".

FLMutableArray_AppendBlob()

static void FLMutableArray_AppendBlob ( FLMutableArray  array, CBLBlob *  blob  )

inlinestatic

Appends a blob reference to an array.

Parameters

array	The array to store into.
blob	The blob reference to be stored.

FLMutableArray_SetBlob()

static void FLMutableArray_SetBlob ( FLMutableArray  array, uint32_t  index, CBLBlob *  blob  )

inlinestatic

Stores a blob reference into an array.

Parameters

array	The array to store into.
index	The position in the array at which to store the blob reference.
blob	The blob reference to be stored.

FLMutableDict_SetBlob()

static void FLMutableDict_SetBlob ( FLMutableDict  dict, FLString  key, CBLBlob *  blob  )

inlinestatic

Stores a blob reference into a Dict.

Parameters

dict	The Dict to store into.
key	The key to associate the blob reference with.
blob	The blob reference to be stored.

FLSlot_SetBlob()

void FLSlot_SetBlob	(	FLSlot	slot,
		CBLBlob *	blob
	)

FLValue_GetBlob()

static const CBLBlob *_cbl_nullable FLValue_GetBlob ( FLValue _cbl_nullable  value )

inlinestatic

Instantiates a CBLBlob object corresponding to a blob dictionary in a document.

Parameters

value

The value (dictionary) in the document.

Returns

A CBLBlob instance for this blob, or NULL if the value is not a blob.

Note

The returned CBLBlob object will be released when its document is released.

FLValue_IsBlob()

static bool FLValue_IsBlob ( FLValue _cbl_nullable  v )

inlinestatic

Returns true if a value in a document is a blob reference.

If so, you can call FLValue_GetBlob to access it.

Variable Documentation

kCBLBlobContentTypeProperty

CBL_PUBLIC const FLSlice kCBLBlobContentTypeProperty

extern

"content_type"

kCBLBlobDigestProperty

CBL_PUBLIC const FLSlice kCBLBlobDigestProperty

extern

"digest"

kCBLBlobLengthProperty

CBL_PUBLIC const FLSlice kCBLBlobLengthProperty

extern

"length"

kCBLBlobType

CBL_PUBLIC const FLSlice kCBLBlobType

extern

"blob"