c4Base.h

Go to the documentation of this file.

//
// c4Base.h
//
// Copyright 2015-Present Couchbase, Inc.
//
// Use of this software is governed by the Business Source License included
// in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
// in that file, in accordance with the Business Source License, use of this
// software will be governed by the Apache License, Version 2.0, included in
// the file licenses/APL2.txt.
//
 
#pragma once
#include "c4Compat.h"
#include "c4Error.h"
#include "fleece/FLSlice.h"
#ifdef __cplusplus
#    include <cstdarg>
#else
#    include <stdarg.h>
#endif
 
#if LITECORE_CPP_API
#    include "c4EnumUtil.hh"
#endif
 
C4_ASSUME_NONNULL_BEGIN
C4API_BEGIN_DECLS
 
 
// Corresponds to Couchbase Lite product version number, with 2 digits for minor and patch versions.
// i.e. `10000 * MajorVersion + 100 * MinorVersion + PatchVersion`
#define LITECORE_VERSION 30100
 
// This number has no absolute meaning but is bumped whenever the LiteCore public API changes.
#define LITECORE_API_VERSION 352
 

 
 
#pragma mark - SLICES:
 
 
// (This is just renaming stuff from FLSlice.h ... feel free to use the FL names instead.)
 
typedef FLSlice       C4Slice;
typedef FLHeapSlice   C4HeapSlice;
typedef FLSliceResult C4SliceResult;
typedef C4Slice       C4String;
typedef C4HeapSlice   C4HeapString;
typedef C4SliceResult C4StringResult;
 
static C4INLINE C4Slice c4str(const char* C4NULLABLE str) { return FLStr(str); }
 
#define C4STR(STR)   FLSTR(STR)
#define kC4SliceNull kFLSliceNull
 
inline bool c4SliceEqual(C4Slice a, C4Slice b) { return FLSlice_Equal(a, b); }
 
inline void c4slice_free(C4SliceResult s) { FLSliceResult_Release(s); }
 
#pragma mark - COMMON TYPES:
 
 
#if LITECORE_CPP_API
C4API_END_DECLS  // GCC doesn't like this stuff inside `extern "C" {}`

        enum class C4SequenceNumber : uint64_t {
            None = 0,
            Max  = UINT64_MAX
        };
 
inline C4SequenceNumber operator""_seq(unsigned long long n) { return C4SequenceNumber(n); }
DEFINE_ENUM_INC_DEC(C4SequenceNumber)
DEFINE_ENUM_ADD_SUB_INT(C4SequenceNumber)
 
 

enum class C4Timestamp : int64_t { None = 0, Error = -1 };
DEFINE_ENUM_ADD_SUB_INT(C4Timestamp)
 
C4API_BEGIN_DECLS
#else
typedef uint64_t C4SequenceNumber;

typedef int64_t C4Timestamp;
#endif
 

typedef struct C4ExtraInfo {
    void* C4NULLABLE pointer;                  
    void (*C4NULLABLE destructor)(void* ptr);  
} C4ExtraInfo;
 

typedef struct C4BlobKey C4BlobKey;

typedef struct C4Address C4Address;

typedef struct C4BlobStore C4BlobStore;

typedef struct C4Cert C4Cert;

typedef struct C4Collection C4Collection;

typedef struct C4CollectionObserver C4CollectionObserver;
 
#ifndef C4_STRICT_COLLECTION_API
typedef C4CollectionObserver C4DatabaseObserver;
#endif

typedef struct C4Database C4Database;

typedef struct C4Document C4Document;

typedef struct C4DocumentObserver C4DocumentObserver;

typedef struct C4DocEnumerator C4DocEnumerator;

typedef struct C4Index C4Index;

typedef struct C4IndexUpdater C4IndexUpdater;

typedef struct C4KeyPair C4KeyPair;

typedef struct C4Listener C4Listener;

typedef struct C4LogObserver C4LogObserver;

typedef struct C4PeerSync C4PeerSync;

typedef struct C4Query C4Query;

typedef struct C4QueryEnumerator C4QueryEnumerator;

typedef struct C4QueryObserver C4QueryObserver;

typedef struct C4RawDocument C4RawDocument;

typedef struct C4ReadStream C4ReadStream;

typedef struct C4Replicator C4Replicator;

typedef struct C4Socket C4Socket;

typedef struct C4SocketFactory C4SocketFactory;

typedef struct C4WriteStream C4WriteStream;
 
 
#pragma mark - REFERENCE COUNTING:
 
 
// The actual functions behind c4xxx_retain / c4xxx_release; don't call directly
CBL_CORE_API void* c4base_retain(void* C4NULLABLE obj) C4API;
CBL_CORE_API void  c4base_release(void* C4NULLABLE obj) C4API;
 
// These types are reference counted and have c4xxx_retain / c4xxx_release functions:
inline C4Cert* C4NULLABLE c4cert_retain(C4Cert* C4NULLABLE r) C4API { return (C4Cert*)c4base_retain(r); }
 
inline C4Collection* C4NULLABLE c4coll_retain(C4Collection* C4NULLABLE r) C4API {
    return (C4Collection*)c4base_retain(r);
}
 
inline C4Database* C4NULLABLE c4db_retain(C4Database* C4NULLABLE r) C4API { return (C4Database*)c4base_retain(r); }
 
inline C4Index* C4NULLABLE c4index_retain(C4Index* C4NULLABLE r) C4API { return (C4Index*)c4base_retain(r); }
 
inline C4IndexUpdater* C4NULLABLE c4indexupdater_retain(C4IndexUpdater* C4NULLABLE r) C4API {
    return (C4IndexUpdater*)c4base_retain(r);
}
 
inline C4KeyPair* C4NULLABLE c4keypair_retain(C4KeyPair* C4NULLABLE r) C4API { return (C4KeyPair*)c4base_retain(r); }
 
inline C4LogObserver* C4NULLABLE c4logobserver_retain(C4LogObserver* C4NULLABLE r) C4API {
    return (C4LogObserver*)c4base_retain(r);
}
 
inline C4Query* C4NULLABLE c4query_retain(C4Query* C4NULLABLE r) C4API { return (C4Query*)c4base_retain(r); }
 
CBL_CORE_API C4Document* C4NULLABLE        c4doc_retain(C4Document* C4NULLABLE) C4API;
CBL_CORE_API C4QueryEnumerator* C4NULLABLE c4queryenum_retain(C4QueryEnumerator* C4NULLABLE) C4API;
CBL_CORE_API C4Socket* C4NULLABLE          c4socket_retain(C4Socket* C4NULLABLE) C4API;
 
inline void c4cert_release(C4Cert* C4NULLABLE r) C4API { c4base_release(r); }

inline void c4coll_release(C4Collection* C4NULLABLE r) C4API { c4base_release(r); }

inline void c4db_release(C4Database* C4NULLABLE r) C4API { c4base_release(r); }
 
inline void c4index_release(C4Index* C4NULLABLE i) C4API { c4base_release(i); }
 
inline void c4indexupdater_release(C4IndexUpdater* C4NULLABLE u) C4API { c4base_release(u); }
 
inline void c4keypair_release(C4KeyPair* C4NULLABLE r) C4API { c4base_release(r); }

inline void c4logobserver_release(C4LogObserver* C4NULLABLE r) C4API { c4base_release(r); }

inline void c4query_release(C4Query* C4NULLABLE r) C4API { c4base_release(r); }

CBL_CORE_API void c4doc_release(C4Document* C4NULLABLE) C4API;
CBL_CORE_API void c4queryenum_release(C4QueryEnumerator* C4NULLABLE) C4API;
CBL_CORE_API void c4socket_release(C4Socket* C4NULLABLE) C4API;
 
// These types are _not_ ref-counted, but must be freed after use:
CBL_CORE_API void c4dbobs_free(C4CollectionObserver* C4NULLABLE) C4API;
CBL_CORE_API void c4docobs_free(C4DocumentObserver* C4NULLABLE) C4API;
CBL_CORE_API void c4enum_free(C4DocEnumerator* C4NULLABLE) C4API;
CBL_CORE_API void c4listener_free(C4Listener* C4NULLABLE) C4API;
CBL_CORE_API void c4peersync_free(C4PeerSync* C4NULLABLE) C4API;
CBL_CORE_API void c4queryobs_free(C4QueryObserver* C4NULLABLE) C4API;
CBL_CORE_API void c4raw_free(C4RawDocument* C4NULLABLE) C4API;
CBL_CORE_API void c4repl_free(C4Replicator* C4NULLABLE) C4API;
CBL_CORE_API void c4stream_close(C4ReadStream* C4NULLABLE) C4API;
CBL_CORE_API void c4stream_closeWriter(C4WriteStream* C4NULLABLE) C4API;
 

CBL_CORE_API int c4_getObjectCount(void) C4API;

CBL_CORE_API void c4_dumpInstances(void) C4API;
 

 
 
#pragma mark - INFO:
 

 

CBL_CORE_API C4StringResult c4_getBuildInfo(void) C4API;

CBL_CORE_API C4StringResult c4_getVersion(void) C4API;
 
#define kC4EnvironmentTimezoneKey      "tz"
#define kC4EnvironmentSupportedLocales "supported_locales"

C4SliceResult c4_getEnvironmentInfo(void) C4API;

CBL_CORE_API C4Timestamp c4_now(void) C4API;
 

NODISCARD CBL_CORE_API bool c4_setTempDir(C4String path, C4Error* C4NULLABLE err) C4API;
 

CBL_CORE_API void c4_runAsyncTask(void (*task)(void*), void* C4NULLABLE context) C4API;
 

 
 
C4API_END_DECLS
C4_ASSUME_NONNULL_END