Couchbase Lite C
Couchbase Lite C API
Typedefs | Enumerations | Functions | Variables
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 CBLBlobCBLBlob_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_ContentType (const CBLBlob *)
 Returns a blob's MIME type, if its metadata has a content_type property. More...
 
FLString CBLBlob_Digest (const CBLBlob *)
 Returns the cryptographic digest of a blob's content (from its digest 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 content 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 CBLBlobCBLBlob_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 CBLBlobCBLBlob_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)
 Get a CBLBlob object from the database using the CBLBlob properties. More...
 
bool CBLDatabase_SaveBlob (CBLDatabase *db, CBLBlob *blob, CBLError *_cbl_nullable outError)
 Save a new CBLBlob object into the database without associating it with any documents. 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

A stream for reading a blob's content.

◆ 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 content 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
contentTypeThe MIME type (optional).
contentsThe 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
contentTypeThe MIME type (optional).
writerThe 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
streamThe stream to read from.
dstThe address to copy the read data to.
maxLengthThe maximum number of bytes to read.
outErrorOn 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
streamThe stream to reposition.
offsetThe byte offset in the stream (relative to the mode).
baseThe base position from which the offset is calculated.
outErrorOn 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
writerThe stream to write to.
dataThe address of the data to write.
lengthThe length of the data to write.
outErrorOn 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 
)

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
dbThe database.
propertiesThe properties for getting the CBLBlob object.
outErrorOn 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 
)

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
dbThe database.
blobThe The CBLBlob to save.
outErrorOn 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
blobDictA 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
arrayThe array to store into.
blobThe 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
arrayThe array to store into.
indexThe position in the array at which to store the blob reference.
blobThe 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
dictThe Dict to store into.
keyThe key to associate the blob reference with.
blobThe 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
valueThe 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"