opendal.h File Reference

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Classes
struct	opendal_bytes
	opendal_bytes carries raw-bytes with its length More...
struct	opendal_error
	The opendal error type for C binding, containing an error code and corresponding error message. More...
struct	opendal_entry
	opendal_list_entry is the entry under a path, which is listed from the opendal_lister More...
struct	opendal_result_lister_next
	The result type returned by opendal_lister_next(). The list entry is the list result of the list operation, the error field is the error code and error message. If the operation succeeds, the error should be NULL. More...
struct	opendal_lister
	BlockingLister is designed to list entries at given path in a blocking manner. More...
struct	opendal_metadata
	Carries all metadata associated with a path. More...
struct	opendal_operator
	Used to access almost all OpenDAL APIs. It represents an operator that provides the unified interfaces provided by OpenDAL. More...
struct	opendal_result_operator_new
	The result type returned by opendal_operator_new() operation. More...
struct	opendal_operator_options
	The configuration for the initialization of opendal_operator. More...
struct	opendal_result_read
	The result type returned by opendal's read operation. More...
struct	opendal_reader
	The result type returned by opendal's reader operation. More...
struct	opendal_result_operator_reader
	The result type returned by opendal_operator_reader(). The result type for opendal_operator_reader(), the field reader contains the reader of the path, which is an iterator of the objects under the path. the field code represents whether the stat operation is successful. More...
struct	opendal_writer
	The result type returned by opendal's writer operation. More...
struct	opendal_result_operator_writer
	The result type returned by opendal_operator_writer(). The result type for opendal_operator_writer(), the field writer contains the writer of the path, which is an iterator of the objects under the path. the field code represents. More...
struct	opendal_result_is_exist
	The result type returned by opendal_operator_is_exist(). More...
struct	opendal_result_exists
	The result type returned by opendal_operator_exists(). More...
struct	opendal_result_stat
	The result type returned by opendal_operator_stat(). More...
struct	opendal_result_list
	The result type returned by opendal_operator_list(). More...
struct	opendal_operator_info
	Metadata for operator, users can use this metadata to get information of operator. More...
struct	opendal_capability
	Capability is used to describe what operations are supported by current Operator. More...
struct	opendal_result_reader_read
	The is the result type returned by opendal_reader_read(). The result type contains a size field, which is the size of the data read, which is zero on error. The error field is the error code and error message. More...
struct	opendal_result_writer_write
	The result type returned by opendal_writer_write(). The result type contains a size field, which is the size of the data written, which is zero on error. The error field is the error code and error message. More...

Typedefs
typedef enum opendal_code	opendal_code
	The error code for all opendal APIs in C binding.
typedef struct opendal_bytes	opendal_bytes
	opendal_bytes carries raw-bytes with its length
typedef struct opendal_error	opendal_error
	The opendal error type for C binding, containing an error code and corresponding error message.
typedef struct opendal_entry	opendal_entry
	opendal_list_entry is the entry under a path, which is listed from the opendal_lister
typedef struct opendal_result_lister_next	opendal_result_lister_next
	The result type returned by opendal_lister_next(). The list entry is the list result of the list operation, the error field is the error code and error message. If the operation succeeds, the error should be NULL.
typedef struct opendal_lister	opendal_lister
	BlockingLister is designed to list entries at given path in a blocking manner.
typedef struct opendal_metadata	opendal_metadata
	Carries all metadata associated with a path.
typedef struct opendal_operator	opendal_operator
	Used to access almost all OpenDAL APIs. It represents an operator that provides the unified interfaces provided by OpenDAL.
typedef struct opendal_result_operator_new	opendal_result_operator_new
	The result type returned by opendal_operator_new() operation.
typedef struct opendal_operator_options	opendal_operator_options
	The configuration for the initialization of opendal_operator.
typedef struct opendal_result_read	opendal_result_read
	The result type returned by opendal's read operation.
typedef struct opendal_reader	opendal_reader
	The result type returned by opendal's reader operation.
typedef struct opendal_result_operator_reader	opendal_result_operator_reader
	The result type returned by opendal_operator_reader(). The result type for opendal_operator_reader(), the field reader contains the reader of the path, which is an iterator of the objects under the path. the field code represents whether the stat operation is successful.
typedef struct opendal_writer	opendal_writer
	The result type returned by opendal's writer operation.
typedef struct opendal_result_operator_writer	opendal_result_operator_writer
	The result type returned by opendal_operator_writer(). The result type for opendal_operator_writer(), the field writer contains the writer of the path, which is an iterator of the objects under the path. the field code represents.
typedef struct opendal_result_is_exist	opendal_result_is_exist
	The result type returned by opendal_operator_is_exist().
typedef struct opendal_result_exists	opendal_result_exists
	The result type returned by opendal_operator_exists().
typedef struct opendal_result_stat	opendal_result_stat
	The result type returned by opendal_operator_stat().
typedef struct opendal_result_list	opendal_result_list
	The result type returned by opendal_operator_list().
typedef struct opendal_operator_info	opendal_operator_info
	Metadata for operator, users can use this metadata to get information of operator.
typedef struct opendal_capability	opendal_capability
	Capability is used to describe what operations are supported by current Operator.
typedef struct opendal_result_reader_read	opendal_result_reader_read
	The is the result type returned by opendal_reader_read(). The result type contains a size field, which is the size of the data read, which is zero on error. The error field is the error code and error message.
typedef struct opendal_result_writer_write	opendal_result_writer_write
	The result type returned by opendal_writer_write(). The result type contains a size field, which is the size of the data written, which is zero on error. The error field is the error code and error message.

Enumerations
enum	opendal_code {   OPENDAL_UNEXPECTED , OPENDAL_UNSUPPORTED , OPENDAL_CONFIG_INVALID , OPENDAL_NOT_FOUND ,   OPENDAL_PERMISSION_DENIED , OPENDAL_IS_A_DIRECTORY , OPENDAL_NOT_A_DIRECTORY , OPENDAL_ALREADY_EXISTS ,   OPENDAL_RATE_LIMITED , OPENDAL_IS_SAME_FILE , OPENDAL_CONDITION_NOT_MATCH , OPENDAL_RANGE_NOT_SATISFIED }
	The error code for all opendal APIs in C binding. More...

Functions
void	opendal_error_free (struct opendal_error *ptr)
	Frees the opendal_error, ok to call on NULL.
struct opendal_result_lister_next	opendal_lister_next (struct opendal_lister *self)
	Return the next object to be listed.
void	opendal_lister_free (struct opendal_lister *ptr)
	Free the heap-allocated metadata used by opendal_lister.
void	opendal_metadata_free (struct opendal_metadata *ptr)
	Free the heap-allocated metadata used by opendal_metadata.
uint64_t	opendal_metadata_content_length (const struct opendal_metadata *self)
	Return the content_length of the metadata.
bool	opendal_metadata_is_file (const struct opendal_metadata *self)
	Return whether the path represents a file.
bool	opendal_metadata_is_dir (const struct opendal_metadata *self)
	Return whether the path represents a directory.
int64_t	opendal_metadata_last_modified_ms (const struct opendal_metadata *self)
	Return the last_modified of the metadata, in milliseconds.
void	opendal_operator_free (const struct opendal_operator *ptr)
	Free the heap-allocated operator pointed by opendal_operator.
struct opendal_result_operator_new	opendal_operator_new (const char *scheme, const struct opendal_operator_options *options)
	Construct an operator based on scheme and options
struct opendal_error *	opendal_operator_write (const struct opendal_operator *op, const char *path, const struct opendal_bytes *bytes)
	Blocking write raw bytes to path.
struct opendal_result_read	opendal_operator_read (const struct opendal_operator *op, const char *path)
	Blocking read the data from path.
struct opendal_result_operator_reader	opendal_operator_reader (const struct opendal_operator *op, const char *path)
	Blocking read the data from path.
struct opendal_result_operator_writer	opendal_operator_writer (const struct opendal_operator *op, const char *path)
	Blocking create a writer for the specified path.
struct opendal_error *	opendal_operator_delete (const struct opendal_operator *op, const char *path)
	Blocking delete the object in path.
	__attribute__ ((deprecated("Use opendal_operator_exists() instead."))) struct opendal_result_is_exist opendal_operator_is_exist(const struct opendal_operator *op
	Check whether the path exists.
struct opendal_result_exists	opendal_operator_exists (const struct opendal_operator *op, const char *path)
	Check whether the path exists.
struct opendal_result_stat	opendal_operator_stat (const struct opendal_operator *op, const char *path)
	Stat the path, return its metadata.
struct opendal_result_list	opendal_operator_list (const struct opendal_operator *op, const char *path)
	Blocking list the objects in path.
struct opendal_error *	opendal_operator_create_dir (const struct opendal_operator *op, const char *path)
	Blocking create the directory in path.
struct opendal_error *	opendal_operator_rename (const struct opendal_operator *op, const char *src, const char *dest)
	Blocking rename the object in path.
struct opendal_error *	opendal_operator_copy (const struct opendal_operator *op, const char *src, const char *dest)
	Blocking copy the object in path.
struct opendal_operator_info *	opendal_operator_info_new (const struct opendal_operator *op)
	Get information of underlying accessor.
void	opendal_operator_info_free (struct opendal_operator_info *ptr)
	Free the heap-allocated opendal_operator_info.
char *	opendal_operator_info_get_scheme (const struct opendal_operator_info *self)
	Return the nul-terminated operator's scheme, i.e. service.
char *	opendal_operator_info_get_root (const struct opendal_operator_info *self)
	Return the nul-terminated operator's working root path.
char *	opendal_operator_info_get_name (const struct opendal_operator_info *self)
	Return the nul-terminated operator backend's name, could be empty if underlying backend has no namespace concept.
struct opendal_capability	opendal_operator_info_get_full_capability (const struct opendal_operator_info *self)
	Return the operator's full capability.
struct opendal_capability	opendal_operator_info_get_native_capability (const struct opendal_operator_info *self)
	Return the operator's native capability.
void	opendal_bytes_free (struct opendal_bytes *ptr)
	Frees the heap memory used by the opendal_bytes.
struct opendal_operator_options *	opendal_operator_options_new (void)
	Construct a heap-allocated opendal_operator_options.
void	opendal_operator_options_set (struct opendal_operator_options *self, const char *key, const char *value)
	Set a Key-Value pair inside opendal_operator_options.
void	opendal_operator_options_free (struct opendal_operator_options *ptr)
	Free the allocated memory used by [opendal_operator_options].
char *	opendal_entry_path (const struct opendal_entry *self)
	Path of entry.
char *	opendal_entry_name (const struct opendal_entry *self)
	Name of entry.
void	opendal_entry_free (struct opendal_entry *ptr)
	Frees the heap memory used by the opendal_list_entry.
struct opendal_result_reader_read	opendal_reader_read (struct opendal_reader *self, uint8_t *buf, uintptr_t len)
	Read data from the reader.
void	opendal_reader_free (struct opendal_reader *ptr)
	Frees the heap memory used by the opendal_reader.
struct opendal_result_writer_write	opendal_writer_write (struct opendal_writer *self, const struct opendal_bytes *bytes)
	Write data to the writer.
void	opendal_writer_free (struct opendal_writer *ptr)
	Frees the heap memory used by the opendal_writer.

Variables
const char *	path

Typedef Documentation

opendal_bytes

typedef struct opendal_bytes opendal_bytes

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 also

opendal_bytes_free

opendal_capability

typedef struct opendal_capability opendal_capability

Capability is used to describe what operations are supported by current Operator.

opendal_code

typedef enum opendal_code opendal_code

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.

opendal_entry

typedef struct opendal_entry opendal_entry

opendal_list_entry is the entry under a path, which is listed from the opendal_lister

For examples, please see the comment section of opendal_operator_list()

See also

opendal_operator_list()

opendal_list_entry_path()

opendal_list_entry_name()

opendal_error

typedef struct opendal_error opendal_error

The opendal error type for C binding, containing an error code and corresponding error message.

The normal operations returns a pointer to the opendal_error, and the nullptr normally represents no error has taken placed. If any error has taken place, the caller should check the error code and print the error message.

The error code is represented in opendal_code, which is an enum on different type of errors. The error messages is represented in opendal_bytes, which is a non-null terminated byte array.

Note

1. The error message is on heap, so the error needs to be freed by the caller, by calling opendal_error_free. 2. The error message is not null terminated, so the caller should never use "%s" to print the error message.

See also

opendal_code

opendal_bytes

opendal_error_free

opendal_lister

typedef struct opendal_lister opendal_lister

BlockingLister is designed to list entries at given path in a blocking manner.

Users can construct Lister by blocking_list or blocking_scan(currently not supported in C binding)

For examples, please see the comment section of opendal_operator_list()

See also

opendal_operator_list()

opendal_metadata

typedef struct opendal_metadata opendal_metadata

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 also

opendal_metadata_free

opendal_operator

typedef struct opendal_operator opendal_operator

Used to access almost all OpenDAL APIs. It represents an operator that provides the unified interfaces provided by OpenDAL.

See also

opendal_operator_new This function construct the operator

opendal_operator_free This function frees the heap memory of the operator

Note

The opendal_operator actually owns a pointer to an opendal::BlockingOperator, which is inside the Rust core code.

Remarks

You may use the field ptr to check whether this is a NULL operator.

opendal_operator_info

typedef struct opendal_operator_info opendal_operator_info

Metadata for operator, users can use this metadata to get information of operator.

opendal_operator_options

typedef struct opendal_operator_options opendal_operator_options

The configuration for the initialization of opendal_operator.

Note

This is also a heap-allocated struct, please free it after you use it

See also

opendal_operator_new has an example of using opendal_operator_options

opendal_operator_options_new This function construct the operator

opendal_operator_options_free This function frees the heap memory of the operator

opendal_operator_options_set This function allow you to set the options

opendal_reader

typedef struct opendal_reader opendal_reader

The result type returned by opendal's reader operation.

Note

The opendal_reader actually owns a pointer to a opendal::BlockingReader, which is inside the Rust core code.

opendal_result_exists

typedef struct opendal_result_exists opendal_result_exists

The result type returned by opendal_operator_exists().

The result type for opendal_operator_exists(), the field exists contains whether the path exists, and the field error contains the corresponding error. If successful, the error field is null.

Note

If the opendal_operator_exists() fails, the exists field will be set to false.

opendal_result_is_exist

typedef struct opendal_result_is_exist opendal_result_is_exist

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 error contains the corresponding error. If successful, the error field is null.

Note

If the opendal_operator_is_exist() fails, the is_exist field will be set to false.

opendal_result_list

typedef struct opendal_result_list opendal_result_list

The result type returned by opendal_operator_list().

The result type for opendal_operator_list(), the field lister contains the lister of the path, which is an iterator of the objects under the path. the field error represents whether the stat operation is successful. If successful, the error field is null.

opendal_result_lister_next

typedef struct opendal_result_lister_next opendal_result_lister_next

The result type returned by opendal_lister_next(). The list entry is the list result of the list operation, the error field is the error code and error message. If the operation succeeds, the error should be NULL.

Note

Please notice if the lister reaches the end, both the list_entry and error will be NULL.

opendal_result_operator_new

typedef struct opendal_result_operator_new opendal_result_operator_new

The result type returned by opendal_operator_new() operation.

If the init logic is successful, the op field will be set to a valid pointer, and the error field will be set to null. If the init logic fails, the op field will be set to null, and the error field will be set to a valid pointer with error code and error message.

See also

opendal_operator_new()

opendal_operator

opendal_error

opendal_result_operator_reader

typedef struct opendal_result_operator_reader opendal_result_operator_reader

The result type returned by opendal_operator_reader(). The result type for opendal_operator_reader(), the field reader contains the reader of the path, which is an iterator of the objects under the path. the field code represents whether the stat operation is successful.

opendal_result_operator_writer

typedef struct opendal_result_operator_writer opendal_result_operator_writer

The result type returned by opendal_operator_writer(). The result type for opendal_operator_writer(), the field writer contains the writer of the path, which is an iterator of the objects under the path. the field code represents.

opendal_result_read

typedef struct opendal_result_read opendal_result_read

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 an NULL error. If the read operation failed, the data fields should be a nullptr and the error is not NULL.

opendal_result_reader_read

typedef struct opendal_result_reader_read opendal_result_reader_read

The is the result type returned by opendal_reader_read(). The result type contains a size field, which is the size of the data read, which is zero on error. The error field is the error code and error message.

opendal_result_stat

typedef struct opendal_result_stat opendal_result_stat

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 error represents whether the stat operation is successful. If successful, the error field is null.

opendal_result_writer_write

typedef struct opendal_result_writer_write opendal_result_writer_write

The result type returned by opendal_writer_write(). The result type contains a size field, which is the size of the data written, which is zero on error. The error field is the error code and error message.

opendal_writer

typedef struct opendal_writer opendal_writer

The result type returned by opendal's writer operation.

Note

The opendal_writer actually owns a pointer to an opendal::BlockingWriter, which is inside the Rust core code.

Enumeration Type Documentation

opendal_code

enum opendal_code

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.

Enumerator
OPENDAL_UNEXPECTED	returning it back. For example, s3 returns an internal service error.
OPENDAL_UNSUPPORTED	Underlying service doesn't support this operation.
OPENDAL_CONFIG_INVALID	The config for backend is invalid.
OPENDAL_NOT_FOUND	The given path is not found.
OPENDAL_PERMISSION_DENIED	The given path doesn't have enough permission for this operation
OPENDAL_IS_A_DIRECTORY	The given path is a directory.
OPENDAL_NOT_A_DIRECTORY	The given path is not a directory.
OPENDAL_ALREADY_EXISTS	The given path already exists thus we failed to the specified operation on it.
OPENDAL_RATE_LIMITED	Requests that sent to this path is over the limit, please slow down.
OPENDAL_IS_SAME_FILE	The given file paths are same.
OPENDAL_CONDITION_NOT_MATCH	The condition of this operation is not match.
OPENDAL_RANGE_NOT_SATISFIED	The range of the content is not satisfied.

Function Documentation

__attribute__()

__attribute__

(

(deprecated("Use opendal_operator_exists() instead."))

)

const

Check whether the path exists.

If the operation succeeds, no matter the path exists or not, the error should be a nullptr. Otherwise, the field is_exist is filled with false, and the error is set

Parameters

op	The opendal_operator created previously
path	The path you want to check existence

See also

opendal_operator

opendal_result_is_exist

opendal_error

Returns

Returns opendal_result_is_exist, the is_exist field contains whether the path exists. However, it the operation fails, the is_exist will contain false and the error will be set.

Example

// .. you previously wrote some data to path "/mytest/obj"
opendal_result_is_exist e = opendal_operator_is_exist(op, "/mytest/obj");
assert(e.error == NULL);
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(op, "/yourtest/obj");
assert(e.error == NULL);
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

opendal_bytes_free()

void opendal_bytes_free

(

struct opendal_bytes *

ptr

)

Frees the heap memory used by the opendal_bytes.

opendal_entry_free()

void opendal_entry_free

(

struct opendal_entry *

ptr

)

Frees the heap memory used by the opendal_list_entry.

opendal_entry_name()

char * opendal_entry_name

(

const struct opendal_entry *

self

)

Name of entry.

Name is the last segment of path. If this entry is a dir, Name MUST endswith / Otherwise, Name MUST NOT endswith /.

Note

To free the string, you can directly call free()

opendal_entry_path()

char * opendal_entry_path

(

const struct opendal_entry *

self

)

Path of entry.

Path is relative to operator's root. Only valid in current operator.

Note

To free the string, you can directly call free()

opendal_error_free()

void opendal_error_free

(

struct opendal_error *

ptr

)

Frees the opendal_error, ok to call on NULL.

opendal_lister_free()

void opendal_lister_free

(

struct opendal_lister *

ptr

)

Free the heap-allocated metadata used by opendal_lister.

opendal_lister_next()

struct opendal_result_lister_next opendal_lister_next

(

struct opendal_lister *

self

)

Return the next object to be listed.

Lister is an iterator of the objects under its path, this method is the same as calling next() on the iterator

For examples, please see the comment section of opendal_operator_list()

See also

opendal_operator_list()

opendal_metadata_content_length()

uint64_t opendal_metadata_content_length

(

const struct opendal_metadata *

self

)

Return the content_length of the metadata.

Example

// ... previously you wrote "Hello, World!" to path "/testpath"
opendal_result_stat s = opendal_operator_stat(op, "/testpath");
assert(s.error == NULL);
 
opendal_metadata *meta = s.meta;
assert(opendal_metadata_content_length(meta) == 13);

opendal_metadata_free()

void opendal_metadata_free

(

struct opendal_metadata *

ptr

)

Free the heap-allocated metadata used by opendal_metadata.

opendal_metadata_is_dir()

bool opendal_metadata_is_dir

(

const struct opendal_metadata *

self

)

Return whether the path represents a directory.

Example

// ... previously you wrote "Hello, World!" to path "/testpath"
opendal_result_stat s = opendal_operator_stat(op, "/testpath");
assert(s.error == NULL);
 
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()

opendal_metadata_is_file()

bool opendal_metadata_is_file

(

const struct opendal_metadata *

self

)

Return whether the path represents a file.

Example

// ... previously you wrote "Hello, World!" to path "/testpath"
opendal_result_stat s = opendal_operator_stat(op, "/testpath");
assert(s.error == NULL);
 
opendal_metadata *meta = s.meta;
assert(opendal_metadata_is_file(meta));

opendal_metadata_last_modified_ms()

int64_t opendal_metadata_last_modified_ms

(

const struct opendal_metadata *

self

)

Return the last_modified of the metadata, in milliseconds.

Example

// ... previously you wrote "Hello, World!" to path "/testpath"
opendal_result_stat s = opendal_operator_stat(op, "/testpath");
assert(s.error == NULL);
 
opendal_metadata *meta = s.meta;
assert(opendal_metadata_last_modified_ms(meta) != -1);

opendal_operator_copy()

struct opendal_error * opendal_operator_copy	(	const struct opendal_operator *	op,
		const char *	src,
		const char *	dest
	)

Blocking copy the object in path.

Copy the object in src to dest blocking by op. Error is NULL if successful, otherwise it contains the error code and error message.

Parameters

op	The opendal_operator created previously
src	The designated source path you want to copy
dest	The designated destination path you want to copy

See also

opendal_operator

opendal_error

Returns

NULL if succeeds, otherwise it contains the error code and error message.

Example

Following is an example

//...prepare your opendal_operator, named op for example
 
// prepare your data
char* data = "Hello, World!";
opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
 
assert(error == NULL);
 
// now you can rename!
opendal_error *error = opendal_operator_copy(op, "/testpath", "/testpath2");
 
// Assert that this succeeds
assert(error == 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 src or dest points to NULL, this function panics, i.e. exits with information

opendal_operator_create_dir()

struct opendal_error * opendal_operator_create_dir	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking create the directory in path.

Create the directory in path blocking by op_ptr. Error is NULL if successful, otherwise it contains the error code and error message.

Parameters

op	The opendal_operator created previously
path	The designated directory you want to create

See also

opendal_operator

opendal_error

Returns

NULL if succeeds, otherwise it contains the error code and error message.

Example

Following is an example

//...prepare your opendal_operator, named op for example
 
// create your directory
opendal_error *error = opendal_operator_create_dir(op, "/testdir/");
 
// Assert that this succeeds
assert(error == 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, i.e. exits with information

opendal_operator_delete()

struct opendal_error * opendal_operator_delete	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking delete the object in path.

Delete the object in path blocking by op_ptr. Error is NULL if successful, otherwise it contains the error code and error message.

Parameters

op	The opendal_operator created previously
path	The designated path you want to delete

See also

opendal_operator

opendal_error

Returns

NULL if succeeds, otherwise it contains the error code and error message.

Example

Following is an example

//...prepare your opendal_operator, named op for example
 
// prepare your data
char* data = "Hello, World!";
opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
 
assert(error == NULL);
 
// now you can delete!
opendal_error *error = opendal_operator_delete(op, "/testpath");
 
// Assert that this succeeds
assert(error == 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, i.e. exits with information

opendal_operator_exists()

struct opendal_result_exists opendal_operator_exists	(	const struct opendal_operator *	op,
		const char *	path
	)

Check whether the path exists.

If the operation succeeds, no matter the path exists or not, the error should be a nullptr. Otherwise, the field exists is filled with false, and the error is set

Parameters

op	The opendal_operator created previously
path	The path you want to check existence

See also

opendal_operator

opendal_result_exists

opendal_error

Returns

Returns opendal_result_exists, the exists field contains whether the path exists. However, it the operation fails, the exists will contain false and the error will be set.

Example

// .. you previously wrote some data to path "/mytest/obj"
opendal_result_exists e = opendal_operator_exists(op, "/mytest/obj");
assert(e.error == NULL);
assert(e.exists);
 
// but you previously did **not** write any data to path "/yourtest/obj"
opendal_result_exists e = opendal_operator_exists(op, "/yourtest/obj");
assert(e.error == NULL);
assert(!e.exists);

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

opendal_operator_free()

void opendal_operator_free

(

const struct opendal_operator *

ptr

)

Free the heap-allocated operator pointed by opendal_operator.

Please only use this for a pointer pointing at a valid opendal_operator. Calling this function on NULL does nothing, but calling this function on pointers of other type will lead to segfault.

Example

opendal_operator *op = opendal_operator_new("fs", NULL);
// ... use this op, maybe some reads and writes
 
// free this operator
opendal_operator_free(op);

opendal_operator_info_free()

void opendal_operator_info_free

(

struct opendal_operator_info *

ptr

)

Free the heap-allocated opendal_operator_info.

opendal_operator_info_get_full_capability()

struct opendal_capability opendal_operator_info_get_full_capability

(

const struct opendal_operator_info *

self

)

Return the operator's full capability.

opendal_operator_info_get_name()

char * opendal_operator_info_get_name

(

const struct opendal_operator_info *

self

)

Return the nul-terminated operator backend's name, could be empty if underlying backend has no namespace concept.

Note

: The string is on heap, remember to free it

opendal_operator_info_get_native_capability()

struct opendal_capability opendal_operator_info_get_native_capability

(

const struct opendal_operator_info *

self

)

Return the operator's native capability.

opendal_operator_info_get_root()

char * opendal_operator_info_get_root

(

const struct opendal_operator_info *

self

)

Return the nul-terminated operator's working root path.

Note

: The string is on heap, remember to free it

opendal_operator_info_get_scheme()

char * opendal_operator_info_get_scheme

(

const struct opendal_operator_info *

self

)

Return the nul-terminated operator's scheme, i.e. service.

Note

: The string is on heap, remember to free it

opendal_operator_info_new()

struct opendal_operator_info * opendal_operator_info_new

(

const struct opendal_operator *

op

)

Get information of underlying accessor.

Example

 
char *scheme;
opendal_operator_info *info = opendal_operator_info_new(op);
 
scheme = opendal_operator_info_get_scheme(info);
assert(!strcmp(scheme, "memory"));
 
free(scheme);
opendal_operator_info_free(info);

opendal_operator_list()

struct opendal_result_list opendal_operator_list	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking list the objects in path.

List the object in path blocking by op_ptr, return a result with an opendal_lister. Users should call opendal_lister_next() on the lister.

Parameters

op	The opendal_operator created previously
path	The designated path you want to list

See also

opendal_lister

Returns

Returns opendal_result_list, containing a lister and an opendal_error. If the operation succeeds, the lister field would hold a valid lister and the error field should hold nullptr. Otherwise, the listerwill contain a NULL pointer, i.e. invalid, and theerror` will be set correspondingly.

Example

Following is an example

// You have written some data into some files path "root/dir1"
// Your opendal_operator was called op
opendal_result_list l = opendal_operator_list(op, "root/dir1");
assert(l.error == ERROR);
 
opendal_lister *lister = l.lister;
opendal_list_entry *entry;
 
while ((entry = opendal_lister_next(lister)) != NULL) {
    const char* de_path = opendal_list_entry_path(entry);
    const char* de_name = opendal_list_entry_name(entry);
    // ...... your operations
 
    // remember to free the entry after you are done using it
    opendal_list_entry_free(entry);
}
 
// and remember to free the lister
opendal_lister_free(lister);

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

opendal_operator_new()

struct opendal_result_operator_new opendal_operator_new	(	const char *	scheme,
		const struct opendal_operator_options *	options
	)

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 for each service, especially for the Configuration Part.

Parameters

scheme	the service scheme you want to specify, e.g. "fs", "s3", "supabase"
options	the pointer to the options for this operator, it could be NULL, which means no option is set

See also

opendal_operator_options

Returns

A valid opendal_result_operator_new setup with the scheme and options is the construction succeeds. On success the operator field is a valid pointer to a newly allocated opendal_operator, and the error field is NULL. Otherwise, the operator field is a NULL pointer and the error field.

Example

Following is an example.

// 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_result_operator_new result = opendal_operator_new("memory", options);
opendal_operator* op = result.op;
 
// you could free the options right away since the options is not used afterwards
opendal_operator_options_free(options);
 
// ... your operations

Safety

The only unsafe case is passing an invalid c string pointer to the scheme argument.

opendal_operator_options_free()

void opendal_operator_options_free

(

struct opendal_operator_options *

ptr

)

Free the allocated memory used by [opendal_operator_options].

opendal_operator_options_new()

struct opendal_operator_options * opendal_operator_options_new

(

void

)

Construct a heap-allocated opendal_operator_options.

Returns

An empty opendal_operator_option, which could be set by opendal_operator_option_set().

See also

opendal_operator_option_set

opendal_operator_options_set()

void opendal_operator_options_set	(	struct opendal_operator_options *	self,
		const char *	key,
		const char *	value
	)

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

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);

opendal_operator_read()

struct opendal_result_read opendal_operator_read	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking read the data from path.

Read the data out from path blocking by operator.

Parameters

op	The opendal_operator created previously
path	The path you want to read the data out

See also

opendal_operator

opendal_result_read

opendal_error

Returns

Returns opendal_result_read, the data field is a pointer to a newly allocated opendal_bytes, the error field contains the error. If the error is not NULL, then the operation failed and the data field is a nullptr.

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

// ... you have write "Hello, World!" to path "/testpath"
 
opendal_result_read r = opendal_operator_read(op, "testpath");
assert(r.error == NULL);
 
opendal_bytes bytes = r.data;
assert(bytes.len == 13);
opendal_bytes_free(&bytes);

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

opendal_operator_reader()

struct opendal_result_operator_reader opendal_operator_reader	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking read the data from path.

Read the data out from path blocking by operator, returns an opendal_result_read with error code.

Parameters

op	The opendal_operator created previously
path	The path you want to read the data out

See also

opendal_operator

opendal_result_read

opendal_code

Returns

Returns opendal_code

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

// ... you have created an operator named op
 
opendal_result_operator_reader result = opendal_operator_reader(op, "/testpath");
assert(result.error == NULL);
// The reader is in result.reader
opendal_reader *reader = result.reader;

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

opendal_operator_rename()

struct opendal_error * opendal_operator_rename	(	const struct opendal_operator *	op,
		const char *	src,
		const char *	dest
	)

Blocking rename the object in path.

Rename the object in src to dest blocking by op. Error is NULL if successful, otherwise it contains the error code and error message.

Parameters

op	The opendal_operator created previously
src	The designated source path you want to rename
dest	The designated destination path you want to rename

See also

opendal_operator

opendal_error

Returns

NULL if succeeds, otherwise it contains the error code and error message.

Example

Following is an example

//...prepare your opendal_operator, named op for example
 
// prepare your data
char* data = "Hello, World!";
opendal_bytes bytes = opendal_bytes { .data = (uint8_t*)data, .len = 13 };
opendal_error *error = opendal_operator_write(op, "/testpath", bytes);
 
assert(error == NULL);
 
// now you can rename!
opendal_error *error = opendal_operator_rename(op, "/testpath", "/testpath2");
 
// Assert that this succeeds
assert(error == 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 src or dest points to NULL, this function panics, i.e. exits with information

opendal_operator_stat()

struct opendal_result_stat opendal_operator_stat	(	const struct opendal_operator *	op,
		const char *	path
	)

Stat the path, return its metadata.

Error is NULL if successful, otherwise it contains the error code and error message.

Parameters

op	The opendal_operator created previously
path	The path you want to stat

See also

opendal_operator

opendal_result_stat

opendal_metadata

Returns

Returns opendal_result_stat, containing a metadata and an opendal_error. If the operation succeeds, the meta field would hold a valid metadata and the error field should hold nullptr. Otherwise, the metadata will contain a NULL pointer, i.e. invalid, and the error will be set correspondingly.

Example

// ... previously you wrote "Hello, World!" to path "/testpath"
opendal_result_stat s = opendal_operator_stat(op, "/testpath");
assert(s.error == NULL);
 
const 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

opendal_operator_write()

struct opendal_error * opendal_operator_write	(	const struct opendal_operator *	op,
		const char *	path,
		const struct opendal_bytes *	bytes
	)

Blocking write raw bytes to path.

Write the bytes into the path blocking by op_ptr. Error is NULL if successful, otherwise it contains the error code and error message.

Note

It is important to notice that the bytes that is passes in will be consumed by this function. Therefore, you should not use the bytes after this function returns.

Parameters

op	The opendal_operator created previously
path	The designated path you want to write your bytes in
bytes	The opendal_byte typed bytes to be written

See also

opendal_operator

opendal_bytes

opendal_error

Returns

NULL if succeeds, otherwise it contains the error code and error message.

Example

Following is an example

//...prepare your opendal_operator, named op 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_error *err = opendal_operator_write(op, "/testpath", bytes);
 
// Assert that this succeeds
assert(err == 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.
• 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

opendal_operator_writer()

struct opendal_result_operator_writer opendal_operator_writer	(	const struct opendal_operator *	op,
		const char *	path
	)

Blocking create a writer for the specified path.

This function prepares a writer that can be used to write data to the specified path using the provided operator. If successful, it returns a valid writer; otherwise, it returns an error.

Parameters

op	The opendal_operator created previously
path	The designated path where the writer will be used

See also

opendal_operator

opendal_result_operator_writer

opendal_error

Returns

Returns opendal_result_operator_writer, containing a writer and an opendal_error. If the operation succeeds, the writer field holds a valid writer and the error field is null. Otherwise, the writer will be null and the error will be set correspondingly.

Example

Following is an example

//...prepare your opendal_operator, named op for example
 
opendal_result_operator_writer result = opendal_operator_writer(op, "/testpath");
assert(result.error == NULL);
opendal_writer *writer = result.writer;
// Use the writer to write data...

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

opendal_reader_free()

void opendal_reader_free

(

struct opendal_reader *

ptr

)

Frees the heap memory used by the opendal_reader.

opendal_reader_read()

struct opendal_result_reader_read opendal_reader_read	(	struct opendal_reader *	self,
		uint8_t *	buf,
		uintptr_t	len
	)

Read data from the reader.

opendal_writer_free()

void opendal_writer_free

(

struct opendal_writer *

ptr

)

Frees the heap memory used by the opendal_writer.

Note

This function make sure all data have been stored.

opendal_writer_write()

struct opendal_result_writer_write opendal_writer_write	(	struct opendal_writer *	self,
		const struct opendal_bytes *	bytes
	)

Write data to the writer.

Variable Documentation

path

const char* path