Couchbase Lite C
Couchbase Lite C API
CBLBlob.h
Go to the documentation of this file.
1//
2// CBLBlob.h
3//
4// Copyright (c) 2018 Couchbase, Inc All rights reserved.
5//
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17//
18
19#pragma once
20#include "CBLBase.h"
21
23
57 CBL_PUBLIC extern const FLSlice kCBLBlobType;
61
62
64
65
71
76
77#ifdef __APPLE__
78#pragma mark - BLOB METADATA:
79#endif
80
82 uint64_t CBLBlob_Length(const CBLBlob*) CBLAPI;
83
86
89
93
97
98#ifdef __APPLE__
99#pragma mark - READING:
100#endif
101
106 CBLError* _cbl_nullable outError) CBLAPI;
107
110
115
123 void *dst,
124 size_t maxLength,
125 CBLError* _cbl_nullable outError) CBLAPI;
126
128 typedef CBL_ENUM(uint8_t, CBLSeekBase) {
132 };
133
141 int64_t offset,
142 CBLSeekBase base,
143 CBLError* _cbl_nullable outError) CBLAPI;
144
147
150
152 bool CBLBlob_Equals(CBLBlob* blob, CBLBlob* anotherBlob) CBLAPI;
153
154#ifdef __APPLE__
155#pragma mark - CREATING:
156#endif
157
166
169
178
181
189 const void *data,
190 size_t length,
191 CBLError* _cbl_nullable outError) CBLAPI;
192
203 CBLBlobWriteStream* writer) CBLAPI;
204
205#ifdef __APPLE__
206#pragma mark - FLEECE UTILITIES:
207#endif
208
211 static inline bool FLValue_IsBlob(FLValue _cbl_nullable v) {
212 return FLDict_IsBlob(FLValue_AsDict(v));
213 }
214
220 return FLDict_GetBlob(FLValue_AsDict(value));
221 }
222
224
229 static inline void FLMutableArray_SetBlob(FLMutableArray array, uint32_t index, CBLBlob *blob) {
230 FLSlot_SetBlob(FLMutableArray_Set(array, index), blob);
231 }
232
236 static inline void FLMutableArray_AppendBlob(FLMutableArray array, CBLBlob *blob) {
238 }
239
244 static inline void FLMutableDict_SetBlob(FLMutableDict dict, FLString key, CBLBlob *blob) {
245 FLSlot_SetBlob(FLMutableDict_Set(dict, key), blob);
246 }
247
248
249#ifdef __APPLE__
250#pragma mark - BINDING DEV SUPPORT FOR BLOB:
251#endif
252
268 CBLError* _cbl_nullable outError) CBLAPI;
269
285 CBLError* _cbl_nullable outError) CBLAPI;
286
#define CBLAPI
Definition: CBL_Compat.h:104
#define _cbl_nullable
Definition: CBL_Compat.h:92
#define CBL_CAPI_BEGIN
Definition: CBL_Compat.h:105
#define CBL_CAPI_END
Definition: CBL_Compat.h:106
#define CBL_PUBLIC
Definition: CBL_Compat.h:123
#define CBL_ENUM(_type, _name)
Definition: CBL_Compat.h:62
#define _cbl_warn_unused
Definition: CBL_Compat.h:40
FLEECE_PUBLIC FLDict FL_NULLABLE FLValue_AsDict(FLValue FL_NULLABLE) FLPURE
If a FLValue represents a dictionary, returns it as an FLDict, else NULL.
NODISCARD FLEECE_PUBLIC FLSlot FLMutableArray_Append(FLMutableArray)
Appends a null value to the array and returns an FLSlot that refers to that position.
NODISCARD FLEECE_PUBLIC FLSlot FLMutableArray_Set(FLMutableArray, uint32_t index)
Returns an FLSlot that refers to the given index of the given array.
NODISCARD FLEECE_PUBLIC FLSlot FLMutableDict_Set(FLMutableDict, FLString key)
Returns an FLSlot that refers to the given key/value pair of the given dictionary.
_cbl_warn_unused CBLBlob * CBLBlob_CreateWithData(FLString contentType, FLSlice contents)
Creates a new blob given its contents as a single block of data.
CBL_PUBLIC const FLSlice kCBLBlobContentTypeProperty
"content_type"
bool CBLBlob_Equals(CBLBlob *blob, CBLBlob *anotherBlob)
Compares whether the two given blobs are equal based on their content.
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.
int64_t CBLBlobReader_Seek(CBLBlobReadStream *stream, int64_t offset, CBLSeekBase base, CBLError *_cbl_nullable outError)
Sets the position of a CBLBlobReadStream.
bool FLDict_IsBlob(FLDict _cbl_nullable)
Returns true if a dictionary in a document is a blob reference.
static bool FLValue_IsBlob(FLValue _cbl_nullable v)
Returns true if a value in a document is a blob reference.
Definition: CBLBlob.h:211
_cbl_warn_unused CBLBlob * CBLBlob_CreateWithStream(FLString contentType, CBLBlobWriteStream *writer)
Creates a new blob after its data has been written to a CBLBlobWriteStream.
uint64_t CBLBlobReader_Position(CBLBlobReadStream *stream)
Returns the current position of a CBLBlobReadStream.
int CBLBlobReader_Read(CBLBlobReadStream *stream, void *dst, size_t maxLength, CBLError *_cbl_nullable outError)
Reads data from a blob.
FLString CBLBlob_Digest(const CBLBlob *)
Returns the cryptographic digest of a blob's content (from its digest property).
_cbl_warn_unused FLStringResult CBLBlob_CreateJSON(const CBLBlob *blob)
Returns a blob's metadata as JSON.
FLString CBLBlob_ContentType(const CBLBlob *)
Returns a blob's MIME type, if its metadata has a content_type property.
CBLSeekBase
Defines the interpretation of offset in CBLBlobReader_Seek.
Definition: CBLBlob.h:128
void CBLBlobWriter_Close(CBLBlobWriteStream *_cbl_nullable)
Closes a blob-writing stream, if you need to give up without creating a CBLBlob.
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.
static void FLMutableArray_SetBlob(FLMutableArray array, uint32_t index, CBLBlob *blob)
Stores a blob reference into an array.
Definition: CBLBlob.h:229
void FLSlot_SetBlob(FLSlot slot, CBLBlob *blob)
static void FLMutableDict_SetBlob(FLMutableDict dict, FLString key, CBLBlob *blob)
Stores a blob reference into a Dict.
Definition: CBLBlob.h:244
struct CBLBlobReadStream CBLBlobReadStream
A stream for reading a blob's content.
Definition: CBLBlob.h:109
static void FLMutableArray_AppendBlob(FLMutableArray array, CBLBlob *blob)
Appends a blob reference to an array.
Definition: CBLBlob.h:236
FLDict CBLBlob_Properties(const CBLBlob *)
Returns a blob's metadata.
CBL_PUBLIC const FLSlice kCBLBlobLengthProperty
"length"
struct CBLBlobWriteStream CBLBlobWriteStream
A stream for writing a new blob to the database.
Definition: CBLBlob.h:168
CBL_PUBLIC const FLSlice kCBLBlobType
"blob"
_cbl_warn_unused CBLBlobReadStream *_cbl_nullable CBLBlob_OpenContentStream(const CBLBlob *blob, CBLError *_cbl_nullable)
Opens a stream for reading a blob's content.
CBL_PUBLIC const FLSlice kCBLBlobDigestProperty
"digest"
const CBLBlob *_cbl_nullable FLDict_GetBlob(FLDict _cbl_nullable blobDict)
Returns a CBLBlob object corresponding to a blob dictionary in a document.
_cbl_warn_unused CBLBlobWriteStream *_cbl_nullable CBLBlobWriter_Create(CBLDatabase *db, CBLError *_cbl_nullable)
Opens a stream for writing a new blob.
struct CBLBlob CBLBlob
A binary data value associated with a CBLDocument.
Definition: CBLBase.h:209
_cbl_warn_unused FLSliceResult CBLBlob_Content(const CBLBlob *blob, CBLError *_cbl_nullable outError)
Reads the blob's content into memory and returns them.
uint64_t CBLBlob_Length(const CBLBlob *)
Returns the length in bytes of a blob's content (from its length property).
void CBLBlobReader_Close(CBLBlobReadStream *_cbl_nullable)
Closes a CBLBlobReadStream.
static const CBLBlob *_cbl_nullable FLValue_GetBlob(FLValue _cbl_nullable value)
Instantiates a CBLBlob object corresponding to a blob dictionary in a document.
Definition: CBLBlob.h:219
bool CBLBlobWriter_Write(CBLBlobWriteStream *writer, const void *data, size_t length, CBLError *_cbl_nullable outError)
Writes data to a new blob.
@ kCBLSeekModeRelative
Offset is relative to the current stream position.
Definition: CBLBlob.h:130
@ kCBLSeekModeFromStart
Offset is an absolute position starting from 0.
Definition: CBLBlob.h:129
@ kCBLSeekModeFromEnd
Offset is relative to the end of the blob.
Definition: CBLBlob.h:131
struct CBLDatabase CBLDatabase
A connection to an open database.
Definition: CBLBase.h:182
#define CBL_REFCOUNTED(TYPE, NAME)
Definition: CBLBase.h:170
struct _FLDict * FLMutableDict
A reference to a mutable dictionary.
Definition: FLBase.h:40
const struct _FLDict * FLDict
A reference to a dictionary (map) value.
Definition: FLBase.h:37
struct _FLSlot * FLSlot
A reference to a mutable array/dict item.
Definition: FLBase.h:38
struct _FLArray * FLMutableArray
A reference to a mutable array.
Definition: FLBase.h:39
const struct _FLValue * FLValue
A reference to a value of any type.
Definition: FLBase.h:35
A struct holding information about an error.
Definition: CBLBase.h:104
A simple reference to a block of memory.
Definition: FLSlice.h:45
A heap-allocated block of memory returned from an API call.
Definition: FLSlice.h:63