You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2023/05/31 09:10:33 UTC
[incubator-opendal] branch main updated: docs(bindings/C): The documentation for OpenDAL C binding (#2373)
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 1adbb5457 docs(bindings/C): The documentation for OpenDAL C binding (#2373)
1adbb5457 is described below
commit 1adbb54579701f740869ec606b60df5ff6ad41ea
Author: xyJi <je...@outlook.com>
AuthorDate: Wed May 31 17:10:28 2023 +0800
docs(bindings/C): The documentation for OpenDAL C binding (#2373)
* all classes included, we should now rewrite the documentation in rust code
* template mainpage
* contributing
* rewrite doc for opendal_operator_ptr_new
* disable doxygen including apache header in weird place
* add apache copyright footer
* main page working
* add licence to footer.html
* rewrite doc for opendal_operator_blocking_write
* rewrite doc for lib.rs
* error.rs
* result.rs
* more doc
* change opendal_operator_new to accept null options
* to be polished
* polished data field documentations
* mainpage
* fix typo in doxyfile
* fix bold in mainpage
* remove pages
* gha
* remove all empty values and comments
* minor
* remove macro
* change licencerc to alloc SLASHSTAR style licence header for c/h file
---
.github/workflows/docs.yml | 33 ++
bindings/c/CONTRIBUTING.md | 8 +
bindings/c/Doxyfile | 291 ++++++++++++++++++
bindings/c/Makefile | 12 +-
bindings/c/README.md | 58 +++-
bindings/c/cbindgen.toml | 4 +-
bindings/c/include/opendal.h | 718 ++++++++++++++++++++++++++++---------------
bindings/c/src/error.rs | 8 +-
bindings/c/src/lib.rs | 224 ++++++++++----
bindings/c/src/macros.rs | 31 --
bindings/c/src/result.rs | 28 +-
bindings/c/src/types.rs | 162 +++++++---
bindings/c/tests/bdd.cpp | 4 +-
licenserc.toml | 5 +
14 files changed, 1189 insertions(+), 397 deletions(-)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 1a0537040..939a55414 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -138,6 +138,32 @@ jobs:
name: python-docs
path: ./bindings/python/docs
+ build-c-doc:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Setup Rust toolchain
+ uses: ./.github/actions/setup
+
+ - name: Setup doxygen
+ run: sudo apt-get install doxygen
+
+ - name: Build C binding
+ working-directory: "bindings/c"
+ run: make build
+
+ - name: Build Docs
+ working-directory: bindings/c
+ run: make doc
+
+ - name: Upload docs
+ uses: actions/upload-artifact@v3
+ with:
+ name: C-docs
+ path: ./bindings/c/docs/doxygen/html
+
build-website:
runs-on: ubuntu-latest
needs:
@@ -145,6 +171,7 @@ jobs:
- build-java-doc
- build-nodejs-doc
- build-python-doc
+ - build-c-doc
steps:
- uses: actions/checkout@v3
@@ -183,6 +210,12 @@ jobs:
name: java-docs
path: ./website/static/docs/java
+ - name: Download C docs
+ uses: actions/download-artifact@v3
+ with:
+ name: C-docs
+ path: ./website/static/docs/c
+
- name: Install Dependencies
working-directory: website
run: yarn install --immutable
diff --git a/bindings/c/CONTRIBUTING.md b/bindings/c/CONTRIBUTING.md
index a71c7838e..1108e46bc 100644
--- a/bindings/c/CONTRIBUTING.md
+++ b/bindings/c/CONTRIBUTING.md
@@ -78,3 +78,11 @@ make test
[ PASSED ] 1 test.
```
+## Documentation
+The documentation index page source is under `./docs/doxygen/html/index.html`.
+If you want to build the documentations yourself, you could use
+```sh
+# this requires you to install doxygen
+make doc
+```
+
diff --git a/bindings/c/Doxyfile b/bindings/c/Doxyfile
new file mode 100644
index 000000000..eb55736bc
--- /dev/null
+++ b/bindings/c/Doxyfile
@@ -0,0 +1,291 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+PROJECT_NAME = "OpenDAL C Binding"
+PROJECT_BRIEF = "The C binding for Apache OpenDAL"
+OUTPUT_DIRECTORY = ./docs/doxygen
+EXCLUDE_SYMBOLS = "HashMap_String__String" \
+ "BlockingOperator" \
+ "Metadata"
+USE_MDFILE_AS_MAINPAGE = "README.md"
+
+DOXYFILE_ENCODING = UTF-8
+CREATE_SUBDIRS = NO
+CREATE_SUBDIRS_LEVEL = 8
+ALLOW_UNICODE_NAMES = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = NO
+JAVADOC_BANNER = NO
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+PYTHON_DOCSTRING = YES
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 4
+OPTIMIZE_OUTPUT_FOR_C = NO
+OPTIMIZE_OUTPUT_JAVA = NO
+OPTIMIZE_FOR_FORTRAN = NO
+OPTIMIZE_OUTPUT_VHDL = NO
+OPTIMIZE_OUTPUT_SLICE = NO
+MARKDOWN_SUPPORT = YES
+TOC_INCLUDE_HEADINGS = 5
+AUTOLINK_SUPPORT = YES
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+IDL_PROPERTY_SUPPORT = YES
+DISTRIBUTE_GROUP_DOC = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS = NO
+TYPEDEF_HIDES_STRUCT = NO
+LOOKUP_CACHE_SIZE = 0
+NUM_PROC_THREADS = 1
+EXTRACT_ALL = ALL
+EXTRACT_PRIVATE = NO
+EXTRACT_PRIV_VIRTUAL = NO
+EXTRACT_PACKAGE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = SYSTEM
+HIDE_SCOPE_NAMES = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_HEADERFILE = YES
+SHOW_INCLUDE_FILES = YES
+SHOW_GROUPED_MEMB_INC = NO
+FORCE_LOCAL_INCLUDES = NO
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+STRICT_PROTO_MATCHING = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_FILES = YES
+SHOW_NAMESPACES = YES
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC = NO
+WARN_AS_ERROR = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LINE_FORMAT = "at line $line of file $file"
+INPUT = ./include ./README.md
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.java \
+ *.ii \
+ *.ixx \
+ *.ipp \
+ *.i++ \
+ *.inl \
+ *.idl \
+ *.ddl \
+ *.odl \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.l \
+ *.cs \
+ *.d \
+ *.php \
+ *.php4 \
+ *.php5 \
+ *.phtml \
+ *.inc \
+ *.m \
+ *.markdown \
+ *.md \
+ *.mm \
+ *.dox \
+ *.py \
+ *.pyw \
+ *.f90 \
+ *.f95 \
+ *.f03 \
+ *.f08 \
+ *.f18 \
+ *.f \
+ *.for \
+ *.vhd \
+ *.vhdl \
+ *.ucf \
+ *.qsf \
+ *.ice
+RECURSIVE = NO
+EXCLUDE_SYMLINKS = NO
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+FILTER_SOURCE_FILES = NO
+FORTRAN_COMMENT_AFTER = 72
+SOURCE_BROWSER = NO
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+ALPHABETICAL_INDEX = YES
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_COLORSTYLE = AUTO_LIGHT
+HTML_COLORSTYLE_HUE = 220
+HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_GAMMA = 80
+HTML_TIMESTAMP = NO
+HTML_DYNAMIC_MENUS = YES
+HTML_DYNAMIC_SECTIONS = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET = NO
+DOCSET_FEEDNAME = "Doxygen generated docs"
+DOCSET_BUNDLE_ID = org.doxygen.Project
+DOCSET_PUBLISHER_ID = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME = Publisher
+GENERATE_HTMLHELP = NO
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+GENERATE_QHP = NO
+QHP_NAMESPACE = org.doxygen.Project
+QHP_VIRTUAL_FOLDER = doc
+GENERATE_ECLIPSEHELP = NO
+ECLIPSE_DOC_ID = org.doxygen.Project
+DISABLE_INDEX = NO
+GENERATE_TREEVIEW = NO
+FULL_SIDEBAR = NO
+ENUM_VALUES_PER_LINE = 4
+TREEVIEW_WIDTH = 250
+EXT_LINKS_IN_WINDOW = NO
+OBFUSCATE_EMAILS = YES
+HTML_FORMULA_FORMAT = png
+FORMULA_FONTSIZE = 10
+USE_MATHJAX = NO
+MATHJAX_VERSION = MathJax_2
+MATHJAX_FORMAT = HTML-CSS
+SEARCHENGINE = YES
+SERVER_BASED_SEARCH = NO
+EXTERNAL_SEARCH = NO
+SEARCHDATA_FILE = searchdata.xml
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+MAKEINDEX_CMD_NAME = makeindex
+LATEX_MAKEINDEX_CMD = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4
+PDF_HYPERLINKS = YES
+USE_PDFLATEX = YES
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+LATEX_BIB_STYLE = plain
+LATEX_TIMESTAMP = NO
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_PROGRAMLISTING = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+GENERATE_DOCBOOK = NO
+DOCBOOK_OUTPUT = docbook
+GENERATE_AUTOGEN_DEF = NO
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+SKIP_FUNCTION_MACROS = YES
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+EXTERNAL_PAGES = YES
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = NO
+DOT_NUM_THREADS = 0
+DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10"
+DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10"
+DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4"
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = NO
+UML_LIMIT_NUM_FIELDS = 10
+DOT_UML_DETAILS = NO
+DOT_WRAP_THRESHOLD = 17
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DIR_GRAPH_MAX_DEPTH = 1
+DOT_IMAGE_FORMAT = png
+INTERACTIVE_SVG = NO
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 0
+DOT_MULTI_TARGETS = NO
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
diff --git a/bindings/c/Makefile b/bindings/c/Makefile
index 7455cd7b9..36b1547ad 100644
--- a/bindings/c/Makefile
+++ b/bindings/c/Makefile
@@ -16,10 +16,13 @@
# under the License.
RPATH=$(PWD)/../../target/debug
+OBJ_DIR=./build
+DOC_DIR=./docs
+
CXXFLAGS=-I./include -std=c++14
LDFLAGS=-L$(RPATH) -Wl,-rpath,$(RPATH)
+
LIBS=-lopendal_c -lgtest -lpthread
-OBJ_DIR=./build
.PHONY: all
all: build test
@@ -38,7 +41,14 @@ test:
$(CXX) tests/bdd.cpp -o $(OBJ_DIR)/bdd $(CXXFLAGS) $(LDFLAGS) $(LIBS)
$(OBJ_DIR)/bdd
+.PHONY: doc
+doc:
+ mkdir -p $(DOC_DIR)
+ doxygen Doxyfile
+
.PHONY: clean
clean:
cargo clean
rm -rf $(OBJ_DIR)
+ rm -rf $(DOC_DIR)
+
diff --git a/bindings/c/README.md b/bindings/c/README.md
index 7779077f2..ec340336c 100644
--- a/bindings/c/README.md
+++ b/bindings/c/README.md
@@ -2,17 +2,63 @@
# Build C bindings
-To compile OpenDAL from source code, you'll need:
-- C/C++ Toolchain: provides basic tools for compiling and linking OpenDAL C binding. This is available as `build-essential` on Ubuntu and similar names on other platforms.
-- `clang-format`: OpenDAL uses clang-format to keep C binding code base clean. The `opendal.h` should be included and formatted by users manually.
+To build OpenDAL C binding, the following is all you need:
+- **A C++ compiler** that supports **c++14**, *e.g.* clang++ and g++
-```bash
-make
-make format
+- To format the code, you need to install **clang-format**
+ - The `opendal.h` is not formatted by hands when you contribute, please do not format the file. **Use `make format` only.**
+ - If your contribution is related to the files under `./tests`, you may format it before submitting your pull request. But notice that different versions of `clang-format` may format the files differently.
+
+- **GTest(Google Test)** need to be installed to build the BDD (Behavior Driven Development) tests. To see how to build, check [here](https://github.com/google/googletest).
+- (optional) **Doxygen** need to be installed to generate documentations.
+
+For Ubuntu and Debian:
+```shell
+# install C/C++ toolchain
+sudo apt install -y build-essential
+
+# install clang-format
+sudo apt install clang-format
+
+# install and build GTest library under /usr/lib and softlink to /usr/local/lib
+sudo apt-get install libgtest-dev
+cd /usr/src/gtest
+sudo cmake CMakeLists.txt
+sudo make
+sudo cp lib/*.a /usr/lib
+sudo ln -s /usr/lib/libgtest.a /usr/local/lib/libgtest.a
+sudo ln -s /usr/lib/libgtest_main.a /usr/local/lib/libgtest_main.a
+```
+
+## Build
+To build the library and header file.
+```shell
make build
+```
+
+- The header file `opendal.h` is under `./include`
+- The library is under `../../target/debug` after building.
+
+To clean the build results.
+```shell
+make clean
+```
+
+## Test
+To build and run the tests. (Note that you need to install GTest)
+```shell
make test
```
+## Documentation
+The documentation index page source is under `./docs/doxygen/html/index.html`.
+If you want to build the documentations yourself, you could use
+```sh
+# this requires you to install doxygen
+make doc
+```
+
+
## License
[Apache v2.0](https://www.apache.org/licenses/LICENSE-2.0)
diff --git a/bindings/c/cbindgen.toml b/bindings/c/cbindgen.toml
index 82db7cc87..aafbb6d5f 100644
--- a/bindings/c/cbindgen.toml
+++ b/bindings/c/cbindgen.toml
@@ -19,9 +19,9 @@
# for detailed documentation of every option here.
cpp_compat = true
-documentation_style = "c"
+documentation_style = "doxy"
header = """
-/**
+/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
diff --git a/bindings/c/include/opendal.h b/bindings/c/include/opendal.h
index 45bc2ee94..04a809a95 100644
--- a/bindings/c/include/opendal.h
+++ b/bindings/c/include/opendal.h
@@ -1,4 +1,4 @@
-/**
+/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
@@ -25,172 +25,239 @@
#include <stddef.h>
#include <stdbool.h>
-/*
- The error code for opendal APIs in C binding
+/**
+ * \brief The error code for all opendal APIs in C binding.
+ * \todo The error handling is not complete, the error with error message will be
+ * added in the future.
*/
typedef enum opendal_code {
- /*
- All is well
+ /**
+ * All is well
*/
OPENDAL_OK,
- /*
- General error
+ /**
+ * General error
*/
OPENDAL_ERROR,
- /*
- returning it back. For example, s3 returns an internal service error.
+ /**
+ * returning it back. For example, s3 returns an internal service error.
*/
OPENDAL_UNEXPECTED,
- /*
- Underlying service doesn't support this operation.
+ /**
+ * Underlying service doesn't support this operation.
*/
OPENDAL_UNSUPPORTED,
- /*
- The config for backend is invalid.
+ /**
+ * The config for backend is invalid.
*/
OPENDAL_CONFIG_INVALID,
- /*
- The given path is not found.
+ /**
+ * The given path is not found.
*/
OPENDAL_NOT_FOUND,
- /*
- The given path doesn't have enough permission for this operation
+ /**
+ * The given path doesn't have enough permission for this operation
*/
OPENDAL_PERMISSION_DENIED,
- /*
- The given path is a directory.
+ /**
+ * The given path is a directory.
*/
OPENDAL_IS_A_DIRECTORY,
- /*
- The given path is not a directory.
+ /**
+ * The given path is not a directory.
*/
OPENDAL_NOT_A_DIRECTORY,
- /*
- The given path already exists thus we failed to the specified operation on it.
+ /**
+ * The given path already exists thus we failed to the specified operation on it.
*/
OPENDAL_ALREADY_EXISTS,
- /*
- Requests that sent to this path is over the limit, please slow down.
+ /**
+ * Requests that sent to this path is over the limit, please slow down.
*/
OPENDAL_RATE_LIMITED,
- /*
- The given file paths are same.
+ /**
+ * The given file paths are same.
*/
OPENDAL_IS_SAME_FILE,
} opendal_code;
-/*
- BlockingOperator is the entry for all public blocking APIs.
-
- Read [`concepts`][docs::concepts] for know more about [`Operator`].
-
- # Examples
-
- Read more backend init examples in [`services`]
-
- ```
- # use anyhow::Result;
- use opendal::services::Fs;
- use opendal::BlockingOperator;
- use opendal::Operator;
- #[tokio::main]
- async fn main() -> Result<()> {
- // Create fs backend builder.
- let mut builder = Fs::default();
- // Set the root for fs, all operations will happen under this root.
- //
- // NOTE: the root must be absolute path.
- builder.root("/tmp");
-
- // Build an `BlockingOperator` to start operating the storage.
- let _: BlockingOperator = Operator::new(builder)?.finish().blocking();
-
- Ok(())
- }
- ```
+/**
+ * BlockingOperator is the entry for all public blocking APIs.
+ *
+ * Read [`concepts`][docs::concepts] for know more about [`Operator`].
+ *
+ * # Examples
+ *
+ * Read more backend init examples in [`services`]
+ *
+ * ```
+ * # use anyhow::Result;
+ * use opendal::services::Fs;
+ * use opendal::BlockingOperator;
+ * use opendal::Operator;
+ * #[tokio::main]
+ * async fn main() -> Result<()> {
+ * // Create fs backend builder.
+ * let mut builder = Fs::default();
+ * // Set the root for fs, all operations will happen under this root.
+ * //
+ * // NOTE: the root must be absolute path.
+ * builder.root("/tmp");
+ *
+ * // Build an `BlockingOperator` to start operating the storage.
+ * let _: BlockingOperator = Operator::new(builder)?.finish().blocking();
+ *
+ * Ok(())
+ * }
+ * ```
*/
typedef struct BlockingOperator BlockingOperator;
typedef struct HashMap_String__String HashMap_String__String;
-/*
- Metadata carries all metadata associated with a path.
-
- # Notes
-
- mode and content_length are required metadata that all services
- should provide during `stat` operation. But in `list` operation,
- a.k.a., `Entry`'s content length could be `None`.
+/**
+ * Metadata carries all metadata associated with a path.
+ *
+ * # Notes
+ *
+ * mode and content_length are required metadata that all services
+ * should provide during `stat` operation. But in `list` operation,
+ * a.k.a., `Entry`'s content length could be `None`.
*/
typedef struct Metadata Metadata;
-/*
- The [`opendal_operator_ptr`] owns a pointer to a [`od::BlockingOperator`].
- It is also the key struct that OpenDAL's APIs access the real
- operator's memory. The use of OperatorPtr is zero cost, it
- only returns a reference of the underlying Operator.
-
- The [`opendal_operator_ptr`] also has a transparent layout, allowing you
- to check its validity by native boolean operator.
- e.g. you could check by (!ptr) on a [`opendal_operator_ptr`]
+/**
+ * \brief Used to access almost all OpenDAL APIs. It represents a
+ * operator that provides the unified interfaces provided by OpenDAL.
+ *
+ * @see opendal_operator_new This function construct the operator
+ * @see opendal_operator_free This function frees the heap memory of the operator
+ *
+ * \note The opendal_operator_ptr actually owns a pointer to
+ * a opendal::BlockingOperator, which is inside the Rust core code.
+ *
+ * \remark You may use the field `ptr` to check whether this is a NULL
+ * operator.
*/
-typedef const struct BlockingOperator *opendal_operator_ptr;
+typedef struct opendal_operator_ptr {
+ /**
+ * The pointer to the opendal::BlockingOperator in the Rust code.
+ * Only touch this on judging whether it is NULL.
+ */
+ const struct BlockingOperator *ptr;
+} opendal_operator_ptr;
-/*
- [`opendal_operator_options`] represents a series of string type key-value pairs, it may be used for initialization
+/**
+ * \brief The configuration for the initialization of opendal_operator_ptr.
+ *
+ * \note This is also a heap-allocated struct, please free it after you use it
+ *
+ * @see opendal_operator_new has an example of using opendal_operator_options
+ * @see opendal_operator_options_new This function construct the operator
+ * @see opendal_operator_options_free This function frees the heap memory of the operator
+ * @see opendal_operator_options_set This function allow you to set the options
*/
-typedef struct HashMap_String__String *opendal_operator_options;
+typedef struct opendal_operator_options {
+ /**
+ * The pointer to the Rust HashMap<String, String>
+ * Only touch this on judging whether it is NULL.
+ */
+ struct HashMap_String__String *inner;
+} opendal_operator_options;
-/*
- The [`opendal_bytes`] type is a C-compatible substitute for [`Vec`]
- in Rust, it will not be deallocated automatically like what
- has been done in Rust. Instead, you have to call [`opendal_free_bytes`]
- to free the heap memory to avoid memory leak.
+/**
+ * \brief opendal_bytes carries raw-bytes with its length
+ *
+ * The opendal_bytes type is a C-compatible substitute for Vec type
+ * in Rust, it has to be manually freed. You have to call opendal_bytes_free()
+ * to free the heap memory to avoid memory leak.
+ *
+ * @see opendal_bytes_free
*/
typedef struct opendal_bytes {
+ /**
+ * Pointing to the byte array on heap
+ */
const uint8_t *data;
+ /**
+ * The length of the byte array
+ */
uintptr_t len;
} opendal_bytes;
-/*
- The Rust-like Result type of opendal C binding, it contains
- the data that the read operation returns and a error code
- If the read operation failed, the `data` fields should be a nullptr
- and the error code is NOT OPENDAL_OK.
+/**
+ * \brief The result type returned by opendal's read operation.
+ *
+ * The result type of read operation in opendal C binding, it contains
+ * the data that the read operation returns and a error code.
+ * If the read operation failed, the `data` fields should be a nullptr
+ * and the error code is **NOT** OPENDAL_OK.
*/
typedef struct opendal_result_read {
+ /**
+ * The byte array with length returned by read operations
+ */
struct opendal_bytes *data;
+ /**
+ * The error code, should be OPENDAL_OK if succeeds
+ */
enum opendal_code code;
} opendal_result_read;
-/*
- The result type for [`opendal_operator_is_exist()`], the field `is_exist`
- contains whether the path exists, and the field `code` contains the
- corresponding error code.
+/**
+ * \brief The result type returned by opendal_operator_is_exist().
+ *
+ * The result type for opendal_operator_is_exist(), the field `is_exist`
+ * contains whether the path exists, and the field `code` contains the
+ * corresponding error code.
+ *
+ * \note If the opendal_operator_is_exist() fails, the `is_exist` field
+ * will be set to false.
*/
typedef struct opendal_result_is_exist {
+ /**
+ * Whether the path exists
+ */
bool is_exist;
+ /**
+ * The error code, should be OPENDAL_OK if succeeds
+ */
enum opendal_code code;
} opendal_result_is_exist;
-/*
- Metadata carries all metadata associated with an path.
-
- # Notes
-
- mode and content_length are required metadata that all services
- should provide during `stat` operation. But in `list` operation,
- a.k.a., `Entry`'s content length could be NULL.
+/**
+ * \brief Carries all metadata associated with a path.
+ *
+ * The metadata of the "thing" under a path. Please **only** use the opendal_metadata
+ * with our provided API, e.g. opendal_metadata_content_length().
+ *
+ * \note The metadata is also heap-allocated, please call opendal_metadata_free() on this
+ * to free the heap memory.
+ *
+ * @see opendal_metadata_free
*/
-typedef const struct Metadata *opendal_metadata;
+typedef struct opendal_metadata {
+ /**
+ * The pointer to the opendal::Metadata in the Rust code.
+ * Only touch this on judging whether it is NULL.
+ */
+ const struct Metadata *inner;
+} opendal_metadata;
-/*
- The result type for [`opendal_operator_stat()`], the meta contains the metadata
- of the path, the code represents whether the stat operation is successful. Note
- that the operation could be successful even if the path does not exist.
+/**
+ * \brief The result type returned by opendal_operator_stat().
+ *
+ * The result type for opendal_operator_stat(), the field `meta` contains the metadata
+ * of the path, the field `code` represents whether the stat operation is successful.
*/
typedef struct opendal_result_stat {
- opendal_metadata meta;
+ /**
+ * The metadata output of the stat
+ */
+ struct opendal_metadata meta;
+ /**
+ * The error code, should be OPENDAL_OK if succeeds
+ */
enum opendal_code code;
} opendal_result_stat;
@@ -198,177 +265,344 @@ typedef struct opendal_result_stat {
extern "C" {
#endif // __cplusplus
-/*
- Uses an array of key-value pairs to initialize the operator based on provided scheme.
-
- # Example
-
- Following is a C example.
- ```no_run
- opendal_operator_options options = opendal_operator_options_new();
- opendal_operator_options_set(&options, "root", "/myroot");
-
- opendal_operator_ptr ptr = opendal_operator_new("memory", options);
- opendal_operator_options_free(&options);
-
- // ... your operations
- ```
-
- # Safety
-
- This function is unsafe because it deferences and casts the raw pointers.
-
- It is [safe] under two cases below
- * The memory pointed to by `scheme` must contain a valid nul terminator at the end of
- the string.
- * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr
-
- # Returns
-
- Returns a result type [`opendal_result_op`], with operator_ptr. If the construction succeeds
- the error is nullptr, otherwise it contains the error information.
+/**
+ * \brief Construct an operator based on `scheme` and `options`
+ *
+ * Uses an array of key-value pairs to initialize the operator based on provided `scheme`
+ * and `options`. For each scheme, i.e. Backend, different options could be set, you may
+ * reference the [documentation](https://opendal.apache.org/docs/category/services/) for
+ * each service, especially for the **Configuration Part**.
+ *
+ * @param scheme the service scheme you want to specify, e.g. "fs", "s3", "supabase"
+ * @param options the pointer to the options for this operators, it could be NULL, which means no
+ * option is set
+ * @see opendal_operator_options
+ * @return A valid opendal_operator_ptr setup with the `scheme` and `options` is the construction
+ * succeeds. A null opendal_operator_ptr if any error happens.
+ *
+ * \remark You may use the `ptr` field of opendal_operator_ptr to check if it is NULL.
+ *
+ * # Example
+ *
+ * Following is an example.
+ * ```C
+ * // Allocate a new options
+ * opendal_operator_options options = opendal_operator_options_new();
+ * // Set the options you need
+ * opendal_operator_options_set(&options, "root", "/myroot");
+ *
+ * // Construct the operator based on the options and scheme
+ * opendal_operator_ptr ptr = opendal_operator_new("memory", options);
+ *
+ * // you could free the options right away since the options is not used afterwards
+ * opendal_operator_options_free(&options);
+ *
+ * // ... your operations
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under two cases below
+ * * The memory pointed to by `scheme` contain a valid nul terminator at the end of
+ * the string.
+ * * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr.
*/
-opendal_operator_ptr opendal_operator_new(const char *scheme, opendal_operator_options options);
+struct opendal_operator_ptr opendal_operator_new(const char *scheme,
+ const struct opendal_operator_options *options);
-/*
- Write the data into the path blockingly by operator, returns the error code OPENDAL_OK
- if succeeds, others otherwise
-
- # Safety
-
- It is [safe] under the cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the end of
- the string.
-
- # Panic
-
- * If the `path` points to NULL, this function panics
+/**
+ * \brief Blockingly write raw bytes to `path`.
+ *
+ * Write the `bytes` into the `path` blockingly by `op_ptr`, returns the opendal_code OPENDAL_OK
+ * if succeeds, others otherwise
+ *
+ * @param ptr The opendal_operator_ptr created previously
+ * @param path The designated path you want to write your bytes in
+ * @param bytes The opendal_byte typed bytes to be written
+ * @see opendal_operator_ptr
+ * @see opendal_bytes
+ * @see opendal_code
+ * @return OPENDAL_OK if succeeds others otherwise
+ *
+ * # Example
+ *
+ * Following is an example
+ * ```C
+ * //...prepare your opendal_operator_ptr, named ptr for example
+ *
+ * // prepare your data
+ * char* data = "Hello, World!";
+ * opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
+ *
+ * // now you can write!
+ * opendal_code code = opendal_operator_blocking_write(ptr, "/testpath", bytes);
+ *
+ * // Assert that this succeeds
+ * assert(code == OPENDAL_OK)
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under the cases below
+ * * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ * the string.
+ * * The `bytes` provided has valid byte in the `data` field and the `len` field is set
+ * correctly.
+ *
+ * # Panic
+ *
+ * * If the `path` points to NULL, this function panics, i.e. exits with information
*/
-enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr,
+enum opendal_code opendal_operator_blocking_write(struct opendal_operator_ptr ptr,
const char *path,
struct opendal_bytes bytes);
-/*
- Read the data out from path into a [`Bytes`] blockingly by operator, returns
- a result with error code. If the error code is not OPENDAL_OK, the `data` field
- of the result points to NULL.
-
- # Safety
-
- It is [safe] under the cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the end of
- the string.
-
- # Panic
-
- * If the `path` points to NULL, this function panics
+/**
+ * \brief Blockingly read the data from `path`.
+ *
+ * Read the data out from `path` blockingly by operator, returns
+ * an opendal_result_read with error code.
+ *
+ * @param ptr The opendal_operator_ptr created previously
+ * @param path The path you want to read the data out
+ * @see opendal_operator_ptr
+ * @see opendal_result_read
+ * @see opendal_code
+ * @return Returns opendal_result_read, the `data` field is a pointer to a newly allocated
+ * opendal_bytes, the `code` field contains the error code. If the `code` is not OPENDAL_OK,
+ * the `data` field points to NULL.
+ *
+ * \note If the read operation succeeds, the returned opendal_bytes is newly allocated on heap.
+ * After your usage of that, please call opendal_bytes_free() to free the space.
+ *
+ * # Example
+ *
+ * Following is an example
+ * ```C
+ * // ... you have write "Hello, World!" to path "/testpath"
+ *
+ * opendal_result_read r = opendal_operator_blocking_read(ptr, "testpath");
+ * assert(r.code == OPENDAL_OK);
+ *
+ * opendal_bytes *bytes = r.data;
+ * assert(bytes->len == 13);
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under the cases below
+ * * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ * the string.
+ *
+ * # Panic
+ *
+ * * If the `path` points to NULL, this function panics, i.e. exits with information
*/
-struct opendal_result_read opendal_operator_blocking_read(opendal_operator_ptr op_ptr,
+struct opendal_result_read opendal_operator_blocking_read(struct opendal_operator_ptr ptr,
const char *path);
-/*
- Check whether the path exists.
-
- If the operation succeeds, no matter the path exists or not,
- the error code should be opendal_code::OPENDAL_OK. Otherwise,
- the field `is_exist` is filled with false, and the error code
- is set correspondingly.
-
- # Safety
-
- It is [safe] under the cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the end of
- the string.
-
- # Panic
-
- * If the `path` points to NULL, this function panics
+/**
+ * \brief Check whether the path exists.
+ *
+ * If the operation succeeds, no matter the path exists or not,
+ * the error code should be opendal_code::OPENDAL_OK. Otherwise,
+ * the field `is_exist` is filled with false, and the error code
+ * is set correspondingly.
+ *
+ * @param ptr The opendal_operator_ptr created previously
+ * @param path The path you want to check existence
+ * @see opendal_operator_ptr
+ * @see opendal_result_is_exist
+ * @see opendal_code
+ * @return Returns opendal_result_is_exist, the `is_exist` field contains whether the path exists.
+ * However, it the operation fails, the `is_exist` will contains false and the error code will be
+ * stored in the `code` field.
+ *
+ * # Example
+ *
+ * ```C
+ * // .. you previously wrote some data to path "/mytest/obj"
+ * opendal_result_is_exist e = opendal_operator_is_exist(ptr, "/mytest/obj");
+ * assert(e.code == OPENDAL_OK);
+ * assert(e.is_exist);
+ *
+ * // but you previously did **not** write any data to path "/yourtest/obj"
+ * opendal_result_is_exist e = opendal_operator_is_exist(ptr, "yourtest/obj");
+ * assert(e.code == OPENDAL_OK);
+ * assert(!e.is_exist);
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under the cases below
+ * * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ * the string.
+ *
+ * # Panic
+ *
+ * * If the `path` points to NULL, this function panics, i.e. exits with information
*/
-struct opendal_result_is_exist opendal_operator_is_exist(opendal_operator_ptr op_ptr,
+struct opendal_result_is_exist opendal_operator_is_exist(struct opendal_operator_ptr ptr,
const char *path);
-/*
- Stat the path, return its metadata.
-
- If the operation succeeds, no matter the path exists or not,
- the error code should be opendal_code::OPENDAL_OK. Otherwise,
- the field `meata` is filled with a NULL pointer, and the error code
- is set correspondingly.
-
- # Safety
-
- It is [safe] under the cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the end of
- the string.
-
- # Panic
-
- * If the `path` points to NULL, this function panics
+/**
+ * \brief Stat the path, return its metadata.
+ *
+ * If the operation succeeds, the error code should be
+ * OPENDAL_OK. Otherwise, the field `meta` is filled with
+ * a NULL pointer, and the error code is set correspondingly.
+ *
+ * @param ptr The opendal_operator_ptr created previously
+ * @param path The path you want to stat
+ * @see opendal_operator_ptr
+ * @see opendal_result_stat
+ * @see opendal_metadata
+ * @return Returns opendal_result_stat, containing a metadata and a opendal_code.
+ * If the operation succeeds, the `meta` field would holds a valid metadata and
+ * the `code` field should hold OPENDAL_OK. Otherwise the metadata will contain a
+ * NULL pointer, i.e. invalid, and the `code` will be set correspondingly.
+ *
+ * # Example
+ *
+ * ```C
+ * // ... previously you wrote "Hello, World!" to path "/testpath"
+ * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * assert(s.code == OPENDAL_OK);
+ *
+ * opendal_metadata meta = s.meta;
+ *
+ * // ... you could now use your metadata, notice that please only access metadata
+ * // using the APIs provided by OpenDAL
+ * ```
+ *
+ * # Safety
+ *
+ * It is **safe** under the cases below
+ * * The memory pointed to by `path` must contain a valid nul terminator at the end of
+ * the string.
+ *
+ * # Panic
+ *
+ * * If the `path` points to NULL, this function panics, i.e. exits with information
*/
-struct opendal_result_stat opendal_operator_stat(opendal_operator_ptr op_ptr, const char *path);
+struct opendal_result_stat opendal_operator_stat(struct opendal_operator_ptr ptr, const char *path);
-/*
- Free the allocated operator pointed by [`opendal_operator_ptr`]
+/**
+ * \brief Free the heap-allocated operator pointed by opendal_operator_ptr.
+ *
+ * Please only use this for a pointer pointing at a valid opendal_operator_ptr.
+ * Calling this function on NULL does nothing, but calling this function on pointers
+ * of other type will lead to segfault.
+ *
+ * # Example
+ *
+ * ```C
+ * opendal_operator_ptr ptr = opendal_operator_new("fs", NULL);
+ * // ... use this ptr, maybe some reads and writes
+ *
+ * // free this operator
+ * opendal_operator_free(&ptr);
+ * ```
*/
-void opendal_operator_free(const opendal_operator_ptr *self);
+void opendal_operator_free(const struct opendal_operator_ptr *self);
-/*
- Frees the heap memory used by the [`opendal_bytes`]
+/**
+ * \brief Frees the heap memory used by the opendal_bytes
*/
void opendal_bytes_free(const struct opendal_bytes *self);
-/*
- Free the allocated metadata
+/**
+ * \brief Free the heap-allocated metadata used by opendal_metadata
*/
-void opendal_metadata_free(const opendal_metadata *self);
+void opendal_metadata_free(const struct opendal_metadata *self);
-/*
- Return the content_length of the metadata
+/**
+ * \brief Return the content_length of the metadata
+ *
+ * # Example
+ * ```C
+ * // ... previously you wrote "Hello, World!" to path "/testpath"
+ * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * assert(s.code == OPENDAL_OK);
+ *
+ * opendal_metadata meta = s.meta;
+ * assert(opendal_metadata_content_length(&meta) == 13);
+ * ```
*/
-uint64_t opendal_metadata_content_length(const opendal_metadata *self);
+uint64_t opendal_metadata_content_length(const struct opendal_metadata *self);
-/*
- Return whether the path represents a file
+/**
+ * \brief Return whether the path represents a file
+ *
+ * # Example
+ * ```C
+ * // ... previously you wrote "Hello, World!" to path "/testpath"
+ * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * assert(s.code == OPENDAL_OK);
+ *
+ * opendal_metadata meta = s.meta;
+ * assert(opendal_metadata_is_file(&meta));
+ * ```
*/
-bool opendal_metadata_is_file(const opendal_metadata *self);
+bool opendal_metadata_is_file(const struct opendal_metadata *self);
-/*
- Return whether the path represents a directory
+/**
+ * \brief Return whether the path represents a directory
+ *
+ * # Example
+ * ```C
+ * // ... previously you wrote "Hello, World!" to path "/testpath"
+ * opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ * assert(s.code == OPENDAL_OK);
+ *
+ * opendal_metadata meta = s.meta;
+ *
+ * // this is not a directory
+ * assert(!opendal_metadata_is_dir(&meta));
+ * ```
+ *
+ * \todo This is not a very clear example. A clearer example will be added
+ * after we support opendal_operator_mkdir()
*/
-bool opendal_metadata_is_dir(const opendal_metadata *self);
+bool opendal_metadata_is_dir(const struct opendal_metadata *self);
-/*
- Construct a heap-allocated opendal_operator_options
+/**
+ * \brief Construct a heap-allocated opendal_operator_options
+ *
+ * @return An empty opendal_operator_option, which could be set by
+ * opendal_operator_option_set().
+ *
+ * @see opendal_operator_option_set
*/
-opendal_operator_options opendal_operator_options_new(void);
-
-/*
- Set a Key-Value pair inside opendal_operator_options
-
- # Safety
-
- This function is unsafe because it dereferences and casts the raw pointers
- Make sure the pointer of `key` and `value` point to a valid string.
+struct opendal_operator_options opendal_operator_options_new(void);
- # Example
-
- ```C
- opendal_operator_options options = opendal_operator_options_new();
- opendal_operator_options_set(&options, "root", "/myroot");
-
- // .. use your opendal_operator_options
-
- opendal_operator_options_free(options);
- ```
+/**
+ * \brief Set a Key-Value pair inside opendal_operator_options
+ *
+ * # Safety
+ *
+ * This function is unsafe because it dereferences and casts the raw pointers
+ * Make sure the pointer of `key` and `value` point to a valid string.
+ *
+ * # Example
+ *
+ * ```C
+ * opendal_operator_options options = opendal_operator_options_new();
+ * opendal_operator_options_set(&options, "root", "/myroot");
+ *
+ * // .. use your opendal_operator_options
+ *
+ * opendal_operator_options_free(options);
+ * ```
*/
-void opendal_operator_options_set(opendal_operator_options *self,
+void opendal_operator_options_set(struct opendal_operator_options *self,
const char *key,
const char *value);
-/*
- Free the allocated memory used by [`opendal_operator_options`]
+/**
+ * \brief Free the allocated memory used by [`opendal_operator_options`]
*/
-void opendal_operator_options_free(const opendal_operator_options *self);
+void opendal_operator_options_free(const struct opendal_operator_options *self);
#ifdef __cplusplus
} // extern "C"
diff --git a/bindings/c/src/error.rs b/bindings/c/src/error.rs
index 61696a061..8aa8c87ca 100644
--- a/bindings/c/src/error.rs
+++ b/bindings/c/src/error.rs
@@ -19,15 +19,17 @@ use ::opendal as od;
/// The wrapper type for opendal's error, wrapped because of the
/// orphan rule
-pub struct opendal_error(od::Error);
+struct opendal_error(od::Error);
-/// The error code for opendal APIs in C binding
+/// \brief The error code for all opendal APIs in C binding.
+/// \todo The error handling is not complete, the error with error message will be
+/// added in the future.
#[repr(C)]
pub enum opendal_code {
/// All is well
OPENDAL_OK,
/// General error
- // todo: make details in the `opendal_error *`
+ // \todo: make details in the `opendal_error *`
OPENDAL_ERROR,
/// returning it back. For example, s3 returns an internal service error.
OPENDAL_UNEXPECTED,
diff --git a/bindings/c/src/lib.rs b/bindings/c/src/lib.rs
index ad12e4d29..4e367be72 100644
--- a/bindings/c/src/lib.rs
+++ b/bindings/c/src/lib.rs
@@ -18,7 +18,6 @@
#![allow(non_camel_case_types)]
mod error;
-mod macros;
mod result;
mod types;
@@ -27,27 +26,42 @@ use std::os::raw::c_char;
use std::str::FromStr;
use ::opendal as od;
-use error::opendal_code;
-use result::opendal_result_is_exist;
-use result::opendal_result_read;
-use result::opendal_result_stat;
-use types::opendal_metadata;
-use types::opendal_operator_options;
-use crate::types::opendal_bytes;
-use crate::types::opendal_operator_ptr;
+use crate::error::opendal_code;
+use crate::result::{opendal_result_is_exist, opendal_result_read, opendal_result_stat};
+use crate::types::{
+ opendal_bytes, opendal_metadata, opendal_operator_options, opendal_operator_ptr,
+};
-/// Uses an array of key-value pairs to initialize the operator based on provided scheme.
+/// \brief Construct an operator based on `scheme` and `options`
+///
+/// Uses an array of key-value pairs to initialize the operator based on provided `scheme`
+/// and `options`. For each scheme, i.e. Backend, different options could be set, you may
+/// reference the [documentation](https://opendal.apache.org/docs/category/services/) for
+/// each service, especially for the **Configuration Part**.
+///
+/// @param scheme the service scheme you want to specify, e.g. "fs", "s3", "supabase"
+/// @param options the pointer to the options for this operators, it could be NULL, which means no
+/// option is set
+/// @see opendal_operator_options
+/// @return A valid opendal_operator_ptr setup with the `scheme` and `options` is the construction
+/// succeeds. A null opendal_operator_ptr if any error happens.
+///
+/// \remark You may use the `ptr` field of opendal_operator_ptr to check if it is NULL.
///
/// # Example
///
-/// Following is a C example.
-/// ```no_run
+/// Following is an example.
+/// ```C
+/// // Allocate a new options
/// opendal_operator_options options = opendal_operator_options_new();
+/// // Set the options you need
/// opendal_operator_options_set(&options, "root", "/myroot");
///
+/// // Construct the operator based on the options and scheme
/// opendal_operator_ptr ptr = opendal_operator_new("memory", options);
-// free the options right away since the options is not used later on
+///
+/// // you could free the options right away since the options is not used afterwards
/// opendal_operator_options_free(&options);
///
/// // ... your operations
@@ -55,23 +69,16 @@ use crate::types::opendal_operator_ptr;
///
/// # Safety
///
-/// This function is unsafe because it deferences and casts the raw pointers.
-///
-/// It is [safe] under two cases below
-/// * The memory pointed to by `scheme` must contain a valid nul terminator at the end of
+/// It is **safe** under two cases below
+/// * The memory pointed to by `scheme` contain a valid nul terminator at the end of
/// the string.
-/// * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr
-///
-/// # Returns
-///
-/// Returns a result type [`opendal_result_op`], with operator_ptr. If the construction succeeds
-/// the error is nullptr, otherwise it contains the error information.
+/// * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr.
#[no_mangle]
pub unsafe extern "C" fn opendal_operator_new(
scheme: *const c_char,
- options: opendal_operator_options,
+ options: *const opendal_operator_options,
) -> opendal_operator_ptr {
- if scheme.is_null() || options.is_null() {
+ if scheme.is_null() {
return opendal_operator_ptr::null();
}
@@ -84,17 +91,18 @@ pub unsafe extern "C" fn opendal_operator_new(
};
let mut map = HashMap::default();
- for (k, v) in options.as_ref() {
- map.insert(k.to_string(), v.to_string());
+ if !options.is_null() {
+ for (k, v) in (*options).as_ref() {
+ map.insert(k.to_string(), v.to_string());
+ }
}
- let op = match scheme {
- od::Scheme::Memory => generate_operator!(od::services::Memory, map),
- _ => {
+ let op = match od::Operator::via_map(scheme, map) {
+ Ok(o) => o.blocking(),
+ Err(_) => {
return opendal_operator_ptr::null();
}
- }
- .blocking();
+ };
// this prevents the operator memory from being dropped by the Box
let op = Box::leak(Box::new(op));
@@ -102,21 +110,50 @@ pub unsafe extern "C" fn opendal_operator_new(
opendal_operator_ptr::from(op)
}
-/// Write the data into the path blockingly by operator, returns the error code OPENDAL_OK
+/// \brief Blockingly write raw bytes to `path`.
+///
+/// Write the `bytes` into the `path` blockingly by `op_ptr`, returns the opendal_code OPENDAL_OK
/// if succeeds, others otherwise
///
+/// @param ptr The opendal_operator_ptr created previously
+/// @param path The designated path you want to write your bytes in
+/// @param bytes The opendal_byte typed bytes to be written
+/// @see opendal_operator_ptr
+/// @see opendal_bytes
+/// @see opendal_code
+/// @return OPENDAL_OK if succeeds others otherwise
+///
+/// # Example
+///
+/// Following is an example
+/// ```C
+/// //...prepare your opendal_operator_ptr, named ptr for example
+///
+/// // prepare your data
+/// char* data = "Hello, World!";
+/// opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
+///
+/// // now you can write!
+/// opendal_code code = opendal_operator_blocking_write(ptr, "/testpath", bytes);
+///
+/// // Assert that this succeeds
+/// assert(code == OPENDAL_OK)
+/// ```
+///
/// # Safety
///
-/// It is [safe] under the cases below
+/// It is **safe** under the cases below
/// * The memory pointed to by `path` must contain a valid nul terminator at the end of
/// the string.
+/// * The `bytes` provided has valid byte in the `data` field and the `len` field is set
+/// correctly.
///
/// # Panic
///
-/// * If the `path` points to NULL, this function panics
+/// * If the `path` points to NULL, this function panics, i.e. exits with information
#[no_mangle]
pub unsafe extern "C" fn opendal_operator_blocking_write(
- op_ptr: opendal_operator_ptr,
+ ptr: opendal_operator_ptr,
path: *const c_char,
bytes: opendal_bytes,
) -> opendal_code {
@@ -124,7 +161,7 @@ pub unsafe extern "C" fn opendal_operator_blocking_write(
panic!("The path given is pointing at NULL");
}
- let op = op_ptr.get_ref();
+ let op = ptr.as_ref();
let path = unsafe { std::ffi::CStr::from_ptr(path).to_str().unwrap() };
match op.write(path, bytes) {
Ok(_) => opendal_code::OPENDAL_OK,
@@ -132,29 +169,55 @@ pub unsafe extern "C" fn opendal_operator_blocking_write(
}
}
-/// Read the data out from path into a [`Bytes`] blockingly by operator, returns
-/// a result with error code. If the error code is not OPENDAL_OK, the `data` field
-/// of the result points to NULL.
+/// \brief Blockingly read the data from `path`.
+///
+/// Read the data out from `path` blockingly by operator, returns
+/// an opendal_result_read with error code.
+///
+/// @param ptr The opendal_operator_ptr created previously
+/// @param path The path you want to read the data out
+/// @see opendal_operator_ptr
+/// @see opendal_result_read
+/// @see opendal_code
+/// @return Returns opendal_result_read, the `data` field is a pointer to a newly allocated
+/// opendal_bytes, the `code` field contains the error code. If the `code` is not OPENDAL_OK,
+/// the `data` field points to NULL.
+///
+/// \note If the read operation succeeds, the returned opendal_bytes is newly allocated on heap.
+/// After your usage of that, please call opendal_bytes_free() to free the space.
+///
+/// # Example
+///
+/// Following is an example
+/// ```C
+/// // ... you have write "Hello, World!" to path "/testpath"
+///
+/// opendal_result_read r = opendal_operator_blocking_read(ptr, "testpath");
+/// assert(r.code == OPENDAL_OK);
+///
+/// opendal_bytes *bytes = r.data;
+/// assert(bytes->len == 13);
+/// ```
///
/// # Safety
///
-/// It is [safe] under the cases below
+/// It is **safe** under the cases below
/// * The memory pointed to by `path` must contain a valid nul terminator at the end of
/// the string.
///
/// # Panic
///
-/// * If the `path` points to NULL, this function panics
+/// * If the `path` points to NULL, this function panics, i.e. exits with information
#[no_mangle]
pub unsafe extern "C" fn opendal_operator_blocking_read(
- op_ptr: opendal_operator_ptr,
+ ptr: opendal_operator_ptr,
path: *const c_char,
) -> opendal_result_read {
if path.is_null() {
panic!("The path given is pointing at NULL");
}
- let op = op_ptr.get_ref();
+ let op = ptr.as_ref();
let path = unsafe { std::ffi::CStr::from_ptr(path).to_str().unwrap() };
let data = op.read(path);
match data {
@@ -172,32 +235,55 @@ pub unsafe extern "C" fn opendal_operator_blocking_read(
}
}
-/// Check whether the path exists.
+/// \brief Check whether the path exists.
///
/// If the operation succeeds, no matter the path exists or not,
/// the error code should be opendal_code::OPENDAL_OK. Otherwise,
/// the field `is_exist` is filled with false, and the error code
/// is set correspondingly.
///
+/// @param ptr The opendal_operator_ptr created previously
+/// @param path The path you want to check existence
+/// @see opendal_operator_ptr
+/// @see opendal_result_is_exist
+/// @see opendal_code
+/// @return Returns opendal_result_is_exist, the `is_exist` field contains whether the path exists.
+/// However, it the operation fails, the `is_exist` will contains false and the error code will be
+/// stored in the `code` field.
+///
+/// # Example
+///
+/// ```C
+/// // .. you previously wrote some data to path "/mytest/obj"
+/// opendal_result_is_exist e = opendal_operator_is_exist(ptr, "/mytest/obj");
+/// assert(e.code == OPENDAL_OK);
+/// assert(e.is_exist);
+///
+/// // but you previously did **not** write any data to path "/yourtest/obj"
+/// opendal_result_is_exist e = opendal_operator_is_exist(ptr, "yourtest/obj");
+/// assert(e.code == OPENDAL_OK);
+/// assert(!e.is_exist);
+/// ```
+///
/// # Safety
///
-/// It is [safe] under the cases below
+/// It is **safe** under the cases below
/// * The memory pointed to by `path` must contain a valid nul terminator at the end of
/// the string.
///
/// # Panic
///
-/// * If the `path` points to NULL, this function panics
+/// * If the `path` points to NULL, this function panics, i.e. exits with information
#[no_mangle]
pub unsafe extern "C" fn opendal_operator_is_exist(
- op_ptr: opendal_operator_ptr,
+ ptr: opendal_operator_ptr,
path: *const c_char,
) -> opendal_result_is_exist {
if path.is_null() {
panic!("The path given is pointing at NULL");
}
- let op = op_ptr.get_ref();
+ let op = ptr.as_ref();
let path = unsafe { std::ffi::CStr::from_ptr(path).to_str().unwrap() };
match op.is_exist(path) {
Ok(e) => opendal_result_is_exist {
@@ -211,32 +297,54 @@ pub unsafe extern "C" fn opendal_operator_is_exist(
}
}
-/// Stat the path, return its metadata.
+/// \brief Stat the path, return its metadata.
///
-/// If the operation succeeds, no matter the path exists or not,
-/// the error code should be opendal_code::OPENDAL_OK. Otherwise,
-/// the field `meata` is filled with a NULL pointer, and the error code
-/// is set correspondingly.
+/// If the operation succeeds, the error code should be
+/// OPENDAL_OK. Otherwise, the field `meta` is filled with
+/// a NULL pointer, and the error code is set correspondingly.
+///
+/// @param ptr The opendal_operator_ptr created previously
+/// @param path The path you want to stat
+/// @see opendal_operator_ptr
+/// @see opendal_result_stat
+/// @see opendal_metadata
+/// @return Returns opendal_result_stat, containing a metadata and a opendal_code.
+/// If the operation succeeds, the `meta` field would holds a valid metadata and
+/// the `code` field should hold OPENDAL_OK. Otherwise the metadata will contain a
+/// NULL pointer, i.e. invalid, and the `code` will be set correspondingly.
+///
+/// # Example
+///
+/// ```C
+/// // ... previously you wrote "Hello, World!" to path "/testpath"
+/// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+/// assert(s.code == OPENDAL_OK);
+///
+/// opendal_metadata meta = s.meta;
+///
+/// // ... you could now use your metadata, notice that please only access metadata
+/// // using the APIs provided by OpenDAL
+/// ```
///
/// # Safety
///
-/// It is [safe] under the cases below
+/// It is **safe** under the cases below
/// * The memory pointed to by `path` must contain a valid nul terminator at the end of
/// the string.
///
/// # Panic
///
-/// * If the `path` points to NULL, this function panics
+/// * If the `path` points to NULL, this function panics, i.e. exits with information
#[no_mangle]
pub unsafe extern "C" fn opendal_operator_stat(
- op_ptr: opendal_operator_ptr,
+ ptr: opendal_operator_ptr,
path: *const c_char,
) -> opendal_result_stat {
if path.is_null() {
panic!("The path given is pointing at NULL");
}
- let op = op_ptr.get_ref();
+ let op = ptr.as_ref();
let path = unsafe { std::ffi::CStr::from_ptr(path).to_str().unwrap() };
match op.stat(path) {
Ok(m) => opendal_result_stat {
diff --git a/bindings/c/src/macros.rs b/bindings/c/src/macros.rs
deleted file mode 100644
index f77811d1a..000000000
--- a/bindings/c/src/macros.rs
+++ /dev/null
@@ -1,31 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-/// Macro used to generate operator upon construction and return C-compatible
-/// error if failed
-#[macro_export]
-macro_rules! generate_operator {
- ($type:ty, $map:expr) => {{
- let b = od::Operator::from_map::<$type>($map);
- match b {
- Ok(b) => b.finish(),
- Err(_) => {
- return opendal_operator_ptr::null();
- }
- }
- }};
-}
diff --git a/bindings/c/src/result.rs b/bindings/c/src/result.rs
index 74f0b9a58..345d3d353 100644
--- a/bindings/c/src/result.rs
+++ b/bindings/c/src/result.rs
@@ -24,30 +24,44 @@ use crate::error::opendal_code;
use crate::types::opendal_bytes;
use crate::types::opendal_metadata;
-/// The Rust-like Result type of opendal C binding, it contains
-/// the data that the read operation returns and a error code
+/// \brief The result type returned by opendal's read operation.
+///
+/// The result type of read operation in opendal C binding, it contains
+/// the data that the read operation returns and a error code.
/// If the read operation failed, the `data` fields should be a nullptr
-/// and the error code is NOT OPENDAL_OK.
+/// and the error code is **NOT** OPENDAL_OK.
#[repr(C)]
pub struct opendal_result_read {
+ /// The byte array with length returned by read operations
pub data: *mut opendal_bytes,
+ /// The error code, should be OPENDAL_OK if succeeds
pub code: opendal_code,
}
-/// The result type for [`opendal_operator_is_exist()`], the field `is_exist`
+/// \brief The result type returned by opendal_operator_is_exist().
+///
+/// The result type for opendal_operator_is_exist(), the field `is_exist`
/// contains whether the path exists, and the field `code` contains the
/// corresponding error code.
+///
+/// \note If the opendal_operator_is_exist() fails, the `is_exist` field
+/// will be set to false.
#[repr(C)]
pub struct opendal_result_is_exist {
+ /// Whether the path exists
pub is_exist: bool,
+ /// The error code, should be OPENDAL_OK if succeeds
pub code: opendal_code,
}
-/// The result type for [`opendal_operator_stat()`], the meta contains the metadata
-/// of the path, the code represents whether the stat operation is successful. Note
-/// that the operation could be successful even if the path does not exist.
+/// \brief The result type returned by opendal_operator_stat().
+///
+/// The result type for opendal_operator_stat(), the field `meta` contains the metadata
+/// of the path, the field `code` represents whether the stat operation is successful.
#[repr(C)]
pub struct opendal_result_stat {
+ /// The metadata output of the stat
pub meta: opendal_metadata,
+ /// The error code, should be OPENDAL_OK if succeeds
pub code: opendal_code,
}
diff --git a/bindings/c/src/types.rs b/bindings/c/src/types.rs
index 8c47bcbf5..a0346a7a9 100644
--- a/bindings/c/src/types.rs
+++ b/bindings/c/src/types.rs
@@ -20,21 +20,40 @@ use std::os::raw::c_char;
use ::opendal as od;
-/// The [`opendal_operator_ptr`] owns a pointer to a [`od::BlockingOperator`].
-/// It is also the key struct that OpenDAL's APIs access the real
-/// operator's memory. The use of OperatorPtr is zero cost, it
-/// only returns a reference of the underlying Operator.
+/// \brief Used to access almost all OpenDAL APIs. It represents a
+/// operator that provides the unified interfaces provided by OpenDAL.
///
-/// The [`opendal_operator_ptr`] also has a transparent layout, allowing you
-/// to check its validity by native boolean operator.
-/// e.g. you could check by (!ptr) on a [`opendal_operator_ptr`]
-#[repr(transparent)]
+/// @see opendal_operator_new This function construct the operator
+/// @see opendal_operator_free This function frees the heap memory of the operator
+///
+/// \note The opendal_operator_ptr actually owns a pointer to
+/// a opendal::BlockingOperator, which is inside the Rust core code.
+///
+/// \remark You may use the field `ptr` to check whether this is a NULL
+/// operator.
+#[repr(C)]
pub struct opendal_operator_ptr {
+ /// The pointer to the opendal::BlockingOperator in the Rust code.
+ /// Only touch this on judging whether it is NULL.
ptr: *const od::BlockingOperator,
}
impl opendal_operator_ptr {
- /// Free the allocated operator pointed by [`opendal_operator_ptr`]
+ /// \brief Free the heap-allocated operator pointed by opendal_operator_ptr.
+ ///
+ /// Please only use this for a pointer pointing at a valid opendal_operator_ptr.
+ /// Calling this function on NULL does nothing, but calling this function on pointers
+ /// of other type will lead to segfault.
+ ///
+ /// # Example
+ ///
+ /// ```C
+ /// opendal_operator_ptr ptr = opendal_operator_new("fs", NULL);
+ /// // ... use this ptr, maybe some reads and writes
+ ///
+ /// // free this operator
+ /// opendal_operator_free(&ptr);
+ /// ```
#[no_mangle]
pub extern "C" fn opendal_operator_free(&self) {
if self.is_null() {
@@ -46,9 +65,7 @@ impl opendal_operator_ptr {
impl opendal_operator_ptr {
/// Creates an OperatorPtr will nullptr, indicating this [`opendal_operator_ptr`]
- /// is invalid. The `transparent` layout also guarantees that if the
- /// underlying field `ptr` is a nullptr, the [`opendal_operator_ptr`] has the
- /// same layout as the nullptr.
+ /// is invalid.
pub(crate) fn null() -> Self {
Self {
ptr: std::ptr::null(),
@@ -61,7 +78,7 @@ impl opendal_operator_ptr {
}
/// Returns a reference to the underlying [`od::BlockingOperator`]
- pub(crate) fn get_ref(&self) -> &od::BlockingOperator {
+ pub(crate) fn as_ref(&self) -> &od::BlockingOperator {
unsafe { &*(self.ptr) }
}
}
@@ -80,26 +97,23 @@ impl From<&mut od::BlockingOperator> for opendal_operator_ptr {
}
}
-/// The [`opendal_bytes`] type is a C-compatible substitute for [`Vec`]
-/// in Rust, it will not be deallocated automatically like what
-/// has been done in Rust. Instead, you have to call [`opendal_free_bytes`]
+/// \brief opendal_bytes carries raw-bytes with its length
+///
+/// The opendal_bytes type is a C-compatible substitute for Vec type
+/// in Rust, it has to be manually freed. You have to call opendal_bytes_free()
/// to free the heap memory to avoid memory leak.
+///
+/// @see opendal_bytes_free
#[repr(C)]
pub struct opendal_bytes {
+ /// Pointing to the byte array on heap
pub data: *const u8,
+ /// The length of the byte array
pub len: usize,
}
impl opendal_bytes {
- /// Construct a [`opendal_bytes`] from the Rust [`Vec`] of bytes
- pub(crate) fn from_vec(vec: Vec<u8>) -> Self {
- let data = vec.as_ptr() as *const u8;
- let len = vec.len();
- std::mem::forget(vec); // To avoid deallocation of the vec.
- Self { data, len }
- }
-
- /// Frees the heap memory used by the [`opendal_bytes`]
+ /// \brief Frees the heap memory used by the opendal_bytes
#[no_mangle]
pub extern "C" fn opendal_bytes_free(&self) {
unsafe {
@@ -110,6 +124,16 @@ impl opendal_bytes {
}
}
+impl opendal_bytes {
+ /// Construct a [`opendal_bytes`] from the Rust [`Vec`] of bytes
+ pub(crate) fn from_vec(vec: Vec<u8>) -> Self {
+ let data = vec.as_ptr() as *const u8;
+ let len = vec.len();
+ std::mem::forget(vec); // To avoid deallocation of the vec.
+ Self { data, len }
+ }
+}
+
#[allow(clippy::from_over_into)]
impl Into<bytes::Bytes> for opendal_bytes {
fn into(self) -> bytes::Bytes {
@@ -118,20 +142,24 @@ impl Into<bytes::Bytes> for opendal_bytes {
}
}
-/// Metadata carries all metadata associated with an path.
+/// \brief Carries all metadata associated with a path.
+///
+/// The metadata of the "thing" under a path. Please **only** use the opendal_metadata
+/// with our provided API, e.g. opendal_metadata_content_length().
///
-/// # Notes
+/// \note The metadata is also heap-allocated, please call opendal_metadata_free() on this
+/// to free the heap memory.
///
-/// mode and content_length are required metadata that all services
-/// should provide during `stat` operation. But in `list` operation,
-/// a.k.a., `Entry`'s content length could be NULL.
-#[repr(transparent)]
+/// @see opendal_metadata_free
+#[repr(C)]
pub struct opendal_metadata {
+ /// The pointer to the opendal::Metadata in the Rust code.
+ /// Only touch this on judging whether it is NULL.
pub inner: *const od::Metadata,
}
impl opendal_metadata {
- /// Free the allocated metadata
+ /// \brief Free the heap-allocated metadata used by opendal_metadata
#[no_mangle]
pub extern "C" fn opendal_metadata_free(&self) {
if self.inner.is_null() {
@@ -140,7 +168,17 @@ impl opendal_metadata {
let _ = unsafe { Box::from_raw(self.inner as *mut od::Metadata) };
}
- /// Return the content_length of the metadata
+ /// \brief Return the content_length of the metadata
+ ///
+ /// # Example
+ /// ```C
+ /// // ... previously you wrote "Hello, World!" to path "/testpath"
+ /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ /// assert(s.code == OPENDAL_OK);
+ ///
+ /// opendal_metadata meta = s.meta;
+ /// assert(opendal_metadata_content_length(&meta) == 13);
+ /// ```
#[no_mangle]
pub extern "C" fn opendal_metadata_content_length(&self) -> u64 {
// Safety: the inner should never be null once constructed
@@ -148,7 +186,17 @@ impl opendal_metadata {
unsafe { (*self.inner).content_length() }
}
- /// Return whether the path represents a file
+ /// \brief Return whether the path represents a file
+ ///
+ /// # Example
+ /// ```C
+ /// // ... previously you wrote "Hello, World!" to path "/testpath"
+ /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ /// assert(s.code == OPENDAL_OK);
+ ///
+ /// opendal_metadata meta = s.meta;
+ /// assert(opendal_metadata_is_file(&meta));
+ /// ```
#[no_mangle]
pub extern "C" fn opendal_metadata_is_file(&self) -> bool {
// Safety: the inner should never be null once constructed
@@ -156,7 +204,22 @@ impl opendal_metadata {
unsafe { (*self.inner).is_file() }
}
- /// Return whether the path represents a directory
+ /// \brief Return whether the path represents a directory
+ ///
+ /// # Example
+ /// ```C
+ /// // ... previously you wrote "Hello, World!" to path "/testpath"
+ /// opendal_result_stat s = opendal_operator_stat(ptr, "/testpath");
+ /// assert(s.code == OPENDAL_OK);
+ ///
+ /// opendal_metadata meta = s.meta;
+ ///
+ /// // this is not a directory
+ /// assert(!opendal_metadata_is_dir(&meta));
+ /// ```
+ ///
+ /// \todo This is not a very clear example. A clearer example will be added
+ /// after we support opendal_operator_mkdir()
#[no_mangle]
pub extern "C" fn opendal_metadata_is_dir(&self) -> bool {
// Safety: the inner should never be null once constructed
@@ -182,14 +245,28 @@ impl opendal_metadata {
}
}
-/// [`opendal_operator_options`] represents a series of string type key-value pairs, it may be used for initialization
-#[repr(transparent)]
+/// \brief The configuration for the initialization of opendal_operator_ptr.
+///
+/// \note This is also a heap-allocated struct, please free it after you use it
+///
+/// @see opendal_operator_new has an example of using opendal_operator_options
+/// @see opendal_operator_options_new This function construct the operator
+/// @see opendal_operator_options_free This function frees the heap memory of the operator
+/// @see opendal_operator_options_set This function allow you to set the options
+#[repr(C)]
pub struct opendal_operator_options {
+ /// The pointer to the Rust HashMap<String, String>
+ /// Only touch this on judging whether it is NULL.
inner: *mut HashMap<String, String>,
}
impl opendal_operator_options {
- /// Construct a heap-allocated opendal_operator_options
+ /// \brief Construct a heap-allocated opendal_operator_options
+ ///
+ /// @return An empty opendal_operator_option, which could be set by
+ /// opendal_operator_option_set().
+ ///
+ /// @see opendal_operator_option_set
#[no_mangle]
pub extern "C" fn opendal_operator_options_new() -> Self {
let map: HashMap<String, String> = HashMap::default();
@@ -198,7 +275,7 @@ impl opendal_operator_options {
}
}
- /// Set a Key-Value pair inside opendal_operator_options
+ /// \brief Set a Key-Value pair inside opendal_operator_options
///
/// # Safety
///
@@ -237,12 +314,7 @@ impl opendal_operator_options {
unsafe { &*(self.inner) }
}
- /// Returns whether the underlying HashMap points to NULL
- pub(crate) fn is_null(&self) -> bool {
- self.inner.is_null()
- }
-
- /// Free the allocated memory used by [`opendal_operator_options`]
+ /// \brief Free the allocated memory used by [`opendal_operator_options`]
#[no_mangle]
pub extern "C" fn opendal_operator_options_free(&self) {
if self.inner.is_null() {
diff --git a/bindings/c/tests/bdd.cpp b/bindings/c/tests/bdd.cpp
index 3b3dd497c..e28798725 100644
--- a/bindings/c/tests/bdd.cpp
+++ b/bindings/c/tests/bdd.cpp
@@ -40,8 +40,8 @@ protected:
opendal_operator_options_set(&options, "root", "/myroot");
// Given A new OpenDAL Blocking Operator
- this->p = opendal_operator_new(scheme.c_str(), options);
- EXPECT_TRUE(this->p);
+ this->p = opendal_operator_new(scheme.c_str(), &options);
+ EXPECT_TRUE(this->p.ptr);
opendal_operator_options_free(&options);
}
diff --git a/licenserc.toml b/licenserc.toml
index bbd10e576..92975b72b 100644
--- a/licenserc.toml
+++ b/licenserc.toml
@@ -36,3 +36,8 @@ excludes = [
[properties]
inceptionYear = 2023
+
+# allow SLASH_STAR_STYLE licence header for c code and headers
+[mapping.SLASHSTAR_STYLE]
+extensions = ["c", "h"]
+