ceph/src/include/libcephsqlite.h

   1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3
   4 /*
   5  * Ceph - scalable distributed file system
   6  *
   7  * Copyright (C) 2021 Red Hat, Inc.
   8  *
   9  * This is free software; you can redistribute it and/or modify it under the
  10  * terms of the GNU Lesser General Public License version 2.1, as published by
  11  * the Free Software Foundation.  See file COPYING.
  12  *
  13  */
  14
  15 #ifndef LIBCEPHSQLITE_H
  16 #define LIBCEPHSQLITE_H
  17
  18 /* This loadable extension does not generally require using this header. It is
  19  * here to allow controlling which version of the library is linked in. See
  20  * also sqlite3_cephsqlite_init below. Additionally, you may specify which
  21  * CephContext to use rather than the library instantiating its own and using
  22  * whatever the default credential is.
  23  */
  24
  25 #include <sqlite3.h>
  26
  27 #ifdef _WIN32
  28 #  define LIBCEPHSQLITE_API __declspec(dllexport)
  29 #else
  30 #  define LIBCEPHSQLITE_API [[gnu::visibility("default")]]
  31 #endif
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36 /* This is the SQLite entry point when loaded as a dynamic library. You also
  37  * need to ensure SQLite calls this method when using libcephsqlite as a static
  38  * library or a dynamic library linked at compile time. For the latter case,
  39  * you can do this by:
  40  *
  41  *   sqlite3_auto_extension((void (*)())sqlite3_cephsqlite_init);
  42  *   sqlite3* db = nullptr;
  43  *   int rc = sqlite3_open_v2(":memory:", &db, SQLITE_OPEN_READWRITE, nullptr);
  44  *   if (rc == SQLITE_DONE) {
  45  *     sqlite3_close(db);
  46  *   } else {
  47  *     // failure
  48  *   }
  49  *
  50  * The throwaway database created (name == "") is a memory database opened so
  51  * that SQLite runs the libcephsqlite initialization routine to register the
  52  * VFS. AFter that's done, the VFS is available for a future database open with
  53  * the VFS set to "ceph":
  54  *
  55  *   sqlite3_open_v2("foo:bar/baz.db", &db, SQLITE_OPEN_READWRITE, "ceph");
  56  *
  57  * You MUST do this before calling any other libcephsqlite routine so that
  58  * sqlite3 can pass its API routines to the libcephsqlite extension.
  59  */
  60
  61 LIBCEPHSQLITE_API int sqlite3_cephsqlite_init(sqlite3* db, char** err, const sqlite3_api_routines* api);
  62
  63 /* If you prefer to have libcephsqlite use a CephContext managed by your
  64  * application, use this routine to set that. libcephsqlite can only have one
  65  * context globally.
  66  */
  67
  68 LIBCEPHSQLITE_API int cephsqlite_setcct(class CephContext* cct, char** ident);
  69 #ifdef __cplusplus
  70 }
  71 #endif
  72
  73 #endif