Data Structures
struct	oio_sds_dl_dst_s

struct	oio_sds_dl_range_s

struct	oio_sds_dl_src_s

struct	oio_sds_ul_dst_s

struct	oio_sds_ul_src_s

struct	oio_sds_list_param_s

struct	oio_sds_list_item_s

struct	oio_sds_list_listener_s

struct	oio_sds_usage_s

Macros
#define	OIO_SDS_VERSION 20180716

#define	OIO_SDS_UPLOAD_DST_INIT {NULL, 0, 0, 0, 0, NULL, NULL, 0, 0, 0}

#define	OIO_SDS_UL__ERROR ((size_t)-2)

#define	OIO_SDS_UL__DONE ((size_t)-1)

#define	OIO_SDS_UL__NODATA ((size_t)0)

#define	OIO_SDS_UPLOAD_SRC_INIT {.type=0, .data={ .hook={.cb=NULL, .ctx=NULL, .size=0}}}

#define	LIMIT_LENGTH_NSNAME 64

#define	LIMIT_LENGTH_ACCOUNTNAME 64

#define	LIMIT_LENGTH_CONTENTPATH 1024

#define	LIMIT_LENGTH_VERSION 24

#define	LIMIT_LENGTH_USER 1024

Typedefs
typedef void(*	oio_sds_info_reporter_f )(void cb_data, enum oio_sds_content_key_e key, const char value)

typedef void(*	oio_sds_property_reporter_f )(void cb_data, const char key, const char *value)

typedef void(*	oio_sds_metachunk_reporter_f )(void *cb_data, unsigned int seq, size_t offset, size_t length)

typedef int(*	oio_sds_dl_hook_f )(void , const unsigned char , size_t)

typedef size_t(*	oio_sds_ul_hook_f )(void , unsigned char p, size_t s)

typedef void(*	on_element_f )(void ctx, const char key, const char *value)

Enumerations
enum	oio_sds_config_e { OIOSDS_CFG_TIMEOUT_PROXY = 1, OIOSDS_CFG_TIMEOUT_RAWX = 2, OIOSDS_CFG_FLAG_SYNCATDOWNLOAD = 3, OIOSDS_CFG_FLAG_ADMIN = 4, OIOSDS_CFG_FLAG_NO_SHUFFLE = 5, OIOSDS_CFG_FLAG_CHUNKSIZE = 6 }

enum	oio_sds_content_key_e { OIO_SDS_CONTENT_ID = 1, OIO_SDS_CONTENT_VERSION = 2, OIO_SDS_CONTENT_HASH = 3, OIO_SDS_CONTENT_SIZE = 4, OIO_SDS_CONTENT_CHUNKMETHOD = 5 }

enum	oio_sds_dl_dst_type_e { OIO_DL_DST_HOOK_SEQUENTIAL = 1, OIO_DL_DST_BUFFER = 2, OIO_DL_DST_FILE = 3 }

enum	oio_sds_ul_src_type_e { OIO_UL_SRC_HOOK_SEQUENTIAL = 1 }

enum	oio_url_field_e { OIOURL_NS =1, OIOURL_ACCOUNT = 2, OIOURL_USER = 3, OIOURL_PATH = 5, OIOURL_VERSION = 6, OIOURL_WHOLE = 7, OIOURL_HEXID = 8, OIOURL_CONTENTID = 9, OIOURL_FULLPATH = 10 }

Functions
void	oio_log_to_syslog (void)

void	oio_log_to_stderr (void)

void	oio_log_nothing (void)

void	oio_log_more (void)

unsigned int	oio_sds_version (void)

void	oio_error_free (struct oio_error_s *e)

void	oio_error_pfree (struct oio_error_s **pe)

int	oio_error_code (const struct oio_error_s *e)

const char *	oio_error_message (const struct oio_error_s *e)

struct oio_error_s *	oio_sds_init (struct oio_sds_s *out, const char ns)

void	oio_sds_free (struct oio_sds_s *sds)

void	oio_sds_pfree (struct oio_sds_s **psds)

int	oio_sds_configure (struct oio_sds_s sds, enum oio_sds_config_e what, void pv, unsigned int vlen)

struct oio_error_s *	oio_sds_create (struct oio_sds_s sds, struct oio_url_s url)

struct oio_error_s *	oio_sds_delete_container (struct oio_sds_s sds, struct oio_url_s url)

struct oio_error_s *	oio_sds_download (struct oio_sds_s sds, struct oio_sds_dl_src_s src, struct oio_sds_dl_dst_s *dst)

struct oio_error_s *	oio_sds_download_to_file (struct oio_sds_s sds, struct oio_url_s u, const char *local)

struct oio_error_s *	oio_sds_show_content (struct oio_sds_s sds, struct oio_url_s u, void *cb_data, oio_sds_info_reporter_f cb_info, oio_sds_metachunk_reporter_f cb_metachunks, oio_sds_property_reporter_f cb_props)

struct oio_sds_ul_s *	oio_sds_upload_init (struct oio_sds_s sds, struct oio_sds_ul_dst_s dst)

struct oio_error_s *	oio_sds_upload_prepare (struct oio_sds_ul_s *ul, size_t size)

struct oio_error_s *	oio_sds_upload_feed (struct oio_sds_ul_s ul, const unsigned char buf, size_t len)

struct oio_error_s *	oio_sds_upload_step (struct oio_sds_ul_s *ul)

struct oio_error_s *	oio_sds_upload_commit (struct oio_sds_ul_s *ul)

struct oio_error_s *	oio_sds_upload_abort (struct oio_sds_ul_s *ul)

int	oio_sds_upload_greedy (struct oio_sds_ul_s *ul)

int	oio_sds_upload_done (struct oio_sds_ul_s *ul)

int	oio_sds_upload_needs_ecd (struct oio_sds_ul_s *ul)

void	oio_sds_upload_clean (struct oio_sds_ul_s *ul)

struct oio_error_s *	oio_sds_upload (struct oio_sds_s sds, struct oio_sds_ul_src_s src, struct oio_sds_ul_dst_s *dst)

struct oio_error_s *	oio_sds_upload_from_file (struct oio_sds_s sds, struct oio_sds_ul_dst_s dst, const char *local, size_t off, size_t len)

struct oio_error_s *	oio_sds_upload_from_buffer (struct oio_sds_s sds, struct oio_sds_ul_dst_s dst, void *base, size_t len)

struct oio_error_s *	oio_sds_list (struct oio_sds_s sds, struct oio_sds_list_param_s param, struct oio_sds_list_listener_s *listener)

struct oio_error_s *	oio_sds_get_usage (struct oio_sds_s sds, struct oio_url_s u, struct oio_sds_usage_s *out)

struct oio_error_s *	oio_sds_drain (struct oio_sds_s sds, struct oio_url_s u)

struct oio_error_s *	oio_sds_delete (struct oio_sds_s sds, struct oio_url_s u)

struct oio_error_s *	oio_sds_has (struct oio_sds_s sds, struct oio_url_s url, int *phas)

struct oio_error_s *	oio_sds_get_content_properties (struct oio_sds_s sds, struct oio_url_s url, on_element_f fct, void *ctx)

struct oio_error_s *	oio_sds_set_content_properties (struct oio_sds_s sds, struct oio_url_s url, const char const val)

struct oio_error_s *	oio_sds_get_container_properties (struct oio_sds_s sds, struct oio_url_s url, on_element_f fct, void *ctx)

struct oio_error_s *	oio_sds_set_container_properties (struct oio_sds_s sds, struct oio_url_s url, const char const val)

struct oio_error_s *	oio_sds_truncate (struct oio_sds_s sds, struct oio_url_s u, size_t size)

struct oio_url_s *	oio_url_init (const char *url)

struct oio_url_s *	oio_url_init_raw (const char *url)

struct oio_url_s *	oio_url_empty (void)

struct oio_url_s *	oio_url_dup (const struct oio_url_s *u)

void	oio_url_clean (struct oio_url_s *u)

void	oio_url_cleanv (struct oio_url_s **tab)

void	oio_url_pclean (struct oio_url_s **pu)

struct oio_url_s *	oio_url_set (struct oio_url_s u, enum oio_url_field_e f, const char v)

void	oio_url_unset (struct oio_url_s *u, enum oio_url_field_e f)

const char *	oio_url_get (struct oio_url_s *u, enum oio_url_field_e f)

int	oio_url_has (const struct oio_url_s *u, enum oio_url_field_e f)

void	oio_url_set_id (struct oio_url_s u, const void id)

const void *	oio_url_get_id (struct oio_url_s *u)

size_t	oio_url_get_id_size (struct oio_url_s *u)

int	oio_url_has_fq_path (const struct oio_url_s *u)

int	oio_url_has_fq_container (const struct oio_url_s *u)

gboolean	oio_url_check (const struct oio_url_s u, const char n, const gchar **e)

Variables
volatile int	oio_sds_default_autocreate

Detailed Description

Macro Definition Documentation

#define LIMIT_LENGTH_ACCOUNTNAME 64

One plus the maximum length of an account name i.e. a size enough to store the C string

#define LIMIT_LENGTH_CONTENTPATH 1024

One plus the maximum length of a content name i.e. a size enough to store the C string

#define LIMIT_LENGTH_NSNAME 64

One plus the maximum length of a namespace name i.e. a size enough to store the C string

#define LIMIT_LENGTH_USER 1024

One plus the maximum length of the string representation of a user i.e. a size enough to store the C string

#define LIMIT_LENGTH_VERSION 24

One plus the maximum length of the string representation of a content version i.e. a size enough to store the C string

#define OIO_SDS_UL__DONE ((size_t)-1)

#define OIO_SDS_UL__ERROR ((size_t)-2)

"Male" upload API This API wraps the "female" API. The sequence is managed by the underlying API call, you just have to provide some data. When the data is called, it has to be available.

#define OIO_SDS_UL__NODATA ((size_t)0)

#define OIO_SDS_UPLOAD_DST_INIT {NULL, 0, 0, 0, 0, NULL, NULL, 0, 0, 0}

#define OIO_SDS_UPLOAD_SRC_INIT {.type=0, .data={ .hook={.cb=NULL, .ctx=NULL, .size=0}}}

#define OIO_SDS_VERSION 20180716

Version started to be defined in June, 2016. Version prior to 20160600 have no ABI incompatibilities.

Typedef Documentation

typedef int(* oio_sds_dl_hook_f)(void *, const unsigned char *, size_t)

Expected to return the number of bytes read, and something else when it failed.

typedef void(* oio_sds_info_reporter_f)(void *cb_data, enum oio_sds_content_key_e key, const char *value)

How properties are reported with oio_sds_show_content()

Parameters

key	the name of the property
value	its value ... suprising isn't it?

typedef void(* oio_sds_metachunk_reporter_f)(void *cb_data, unsigned int seq, size_t offset, size_t length)

How hints on the internal chunking are reported.

Parameters

seq	the sequence number
offset	the offset of the metachunk in the whole content
length	the size of the metachunk

typedef void(* oio_sds_property_reporter_f)(void *cb_data, const char *key, const char *value)

How properties are reported.

Parameters

key	the name of the property
value	its value ... suprising isn't it?

typedef size_t(* oio_sds_ul_hook_f)(void *, unsigned char *p, size_t s)

typedef void(* on_element_f)(void *ctx, const char *key, const char *value)

Enumeration Type Documentation

enum oio_sds_config_e

Define configuration directives for oio_sds_configure().

Enumerator
OIOSDS_CFG_TIMEOUT_PROXY	expects an integer as a number of seconds
OIOSDS_CFG_TIMEOUT_RAWX	expects an integer as a number of seconds
OIOSDS_CFG_FLAG_SYNCATDOWNLOAD	expects an integer used for its boolean value
OIOSDS_CFG_FLAG_ADMIN	expects an integer used for its boolean value
OIOSDS_CFG_FLAG_NO_SHUFFLE	Disable the shuffling of chunks before reading, and instead sort them by score. Expects an integer used for its boolean value.
OIOSDS_CFG_FLAG_CHUNKSIZE	Define the chunk size in bytes. Expects an <int64_t>. If 0, use the default size.

enum oio_sds_content_key_e

Define a value to be reported by oio_sds_show_content(), via the oio_sds_info_reporter_f hook.

Enumerator
OIO_SDS_CONTENT_ID	Indicate the value reports the hexadecimal content ID.
OIO_SDS_CONTENT_VERSION	the value reports the version number in a textual decimal representation
OIO_SDS_CONTENT_HASH	The value represents the hexadecimal hash of the whole content.
OIO_SDS_CONTENT_SIZE	Reports the size of the content, as an integer in a decimal representation. Requires to manage 64bits-wide integers.
OIO_SDS_CONTENT_CHUNKMETHOD	Reports the textual chunk-method that generated the chunks.

enum oio_sds_dl_dst_type_e

Enumerator
OIO_DL_DST_HOOK_SEQUENTIAL
OIO_DL_DST_BUFFER
OIO_DL_DST_FILE

enum oio_sds_ul_src_type_e

Enumerator
OIO_UL_SRC_HOOK_SEQUENTIAL

enum oio_url_field_e

Enumerator
OIOURL_NS
OIOURL_ACCOUNT
OIOURL_USER
OIOURL_PATH
OIOURL_VERSION
OIOURL_WHOLE
OIOURL_HEXID
OIOURL_CONTENTID
OIOURL_FULLPATH

Function Documentation

int oio_error_code ( const struct oio_error_s * e )

Return an error code associated with the error structure.

Parameters

e	May be NULL

Returns: 0 is e is NULL, an integer otherwise

void oio_error_free ( struct oio_error_s * e )

Free an error pointed by the given argument.

Parameters

e	May be NULL

const char* oio_error_message ( const struct oio_error_s * e )

Returns a human-readable message describing the error.

Parameters

e	May be NULL

Returns: a pointer to a constant string

void oio_error_pfree ( struct oio_error_s ** pe )

Free the error whose pointer is pointed by pe

Parameters

pe	May be NULL or point to NULL

void oio_log_more ( void )

Increases the verbosity of the internal logging output. OpenIO's log levels are ERROR, WARNING, NOTICE, INFO, DEBUG, TRACE. The default level is WARNING. DEBUG: output the SDK behavior. TRACE: also outputs the licurl behavior.

void oio_log_nothing ( void )

As the name suggests, it turns off the log output from the OpenIO's SDK

void oio_log_to_stderr ( void )

Configures the GLib-2.0 to send the logging output to the standard error output.

The format follow an internal rules of OpeIO. If the walling app wants to another format, it is its responsibility.

void oio_log_to_syslog ( void )

Configures the GLib-2.0 to send the logging output to the syslog. This function does not call openlog()

int oio_sds_configure	(	struct oio_sds_s *	sds,
		enum oio_sds_config_e	what,
		void *	pv,
		unsigned int	vlen
	)

return 0 on success, or errno in case of error

struct oio_error_s* oio_sds_create	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url
	)

Links the meta2 then triggers container creation

struct oio_error_s* oio_sds_delete	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u
	)

Works with fully qualified urls (content)

struct oio_error_s* oio_sds_delete_container	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url
	)

struct oio_error_s* oio_sds_download	(	struct oio_sds_s *	sds,
		struct oio_sds_dl_src_s *	src,
		struct oio_sds_dl_dst_s *	dst
	)

struct oio_error_s* oio_sds_download_to_file	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u,
		const char *	local
	)

Downloads the whole file works with fully qualified urls (content) and local paths

struct oio_error_s* oio_sds_drain	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u
	)

Drain the content identified by u, a.k.a. make it remain in the directory but not point to valid contents.

Parameters

sds	a pointer to a valid sds client.
u	a pointer to a valid oio_url_s identifying the content.

Returns: NULL in case of success, a valid error pointer otherwise

void oio_sds_free ( struct oio_sds_s * sds )

struct oio_error_s* oio_sds_get_container_properties	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url,
		on_element_f	fct,
		void *	ctx
	)

Get properties of a container: fct function will be called for each k,v couple

struct oio_error_s* oio_sds_get_content_properties	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url,
		on_element_f	fct,
		void *	ctx
	)

Get properties of a file: fct function will be called for each k,v couple

struct oio_error_s* oio_sds_get_usage	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u,
		struct oio_sds_usage_s *	out
	)

Report the usage of the container identified by the oio_url_s u.

Parameters

sds	A pointer to a valid oio_sds_s.
u	A pointer to a valid oio_url_s.
out	output variable, filled with the stats upon success.

Returns: NULL if the requests succeeds, or an oio_error_s pointer otherwise, to be freed with oio_error_free().

struct oio_error_s* oio_sds_has	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url,
		int *	phas
	)

currently works with fully qualified urls (content)

struct oio_error_s* oio_sds_init	(	struct oio_sds_s **	out,
		const char *	ns
	)

Prepare an OpenIO SDS client.

Parameters

out	A placeholder for the
ns

Returns: NULL if an error occured, or a pointer to a valid OpenIO SDS client.

struct oio_error_s* oio_sds_list	(	struct oio_sds_s *	sds,
		struct oio_sds_list_param_s *	param,
		struct oio_sds_list_listener_s *	listener
	)

List the object present in the container.

Parameters

sds
param
listener

Returns

void oio_sds_pfree ( struct oio_sds_s ** psds )

Calls oio_sds_free() on *psds, then set it to NULL

struct oio_error_s* oio_sds_set_container_properties	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url,
		const char const	val
	)

Set properties of a file with the val values

struct oio_error_s* oio_sds_set_content_properties	(	struct oio_sds_s *	sds,
		struct oio_url_s *	url,
		const char const	val
	)

Set properties of a file with the val values

struct oio_error_s* oio_sds_show_content	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u,
		void *	cb_data,
		oio_sds_info_reporter_f	cb_info,
		oio_sds_metachunk_reporter_f	cb_metachunks,
		oio_sds_property_reporter_f	cb_props
	)

Tells how is the content internally split.

Helps applications to paginate the downloads, with pages aligned on chunks boundaries.

Parameters

cb_data	not even checked, implementation-dependant
cb_info	ignored if NULL
cb_metachunks	ignored if NULL
cb_props	ignored if NULL

struct oio_error_s* oio_sds_truncate	(	struct oio_sds_s *	sds,
		struct oio_url_s *	u,
		size_t	size
	)

Truncate a content to the specified size.

The size must be aligned on a metachunk boundary (you can use oio_sds_show_content() to find it). It is preferable to specify the content by its ID instead of its path.

struct oio_error_s* oio_sds_upload	(	struct oio_sds_s *	sds,
		struct oio_sds_ul_src_s *	src,
		struct oio_sds_ul_dst_s *	dst
	)

struct oio_error_s* oio_sds_upload_abort ( struct oio_sds_ul_s * ul )

void oio_sds_upload_clean ( struct oio_sds_ul_s * ul )

struct oio_error_s* oio_sds_upload_commit ( struct oio_sds_ul_s * ul )

int oio_sds_upload_done ( struct oio_sds_ul_s * ul )

Tells if the upload is ready to be (in)validated

struct oio_error_s* oio_sds_upload_feed	(	struct oio_sds_ul_s *	ul,
		const unsigned char *	buf,
		size_t	len
	)

struct oio_error_s* oio_sds_upload_from_buffer	(	struct oio_sds_s *	sds,
		struct oio_sds_ul_dst_s *	dst,
		void *	base,
		size_t	len
	)

Simply wraps oio_sds_upload() without the autocreation flag set.

struct oio_error_s* oio_sds_upload_from_file	(	struct oio_sds_s *	sds,
		struct oio_sds_ul_dst_s *	dst,
		const char *	local,
		size_t	off,
		size_t	len
	)

Simply wraps oio_sds_upload() without the autocreation flag set.

int oio_sds_upload_greedy ( struct oio_sds_ul_s * ul )

Tells if the upload is ready to accept data

struct oio_sds_ul_s* oio_sds_upload_init	(	struct oio_sds_s *	sds,
		struct oio_sds_ul_dst_s *	dst
	)

int oio_sds_upload_needs_ecd ( struct oio_sds_ul_s * ul )

Tells if the upload will need a data-daemon aside. TODO rename to be more generic (not only EC requires side daemon)

struct oio_error_s* oio_sds_upload_prepare	(	struct oio_sds_ul_s *	ul,
		size_t	size
	)

struct oio_error_s* oio_sds_upload_step ( struct oio_sds_ul_s * ul )

unsigned int oio_sds_version ( void )

Returns the integer version of the API. Compare the version returned to the version you know from the OIO_SDS_VERSION macro. If it differs, the only behavior to have is upgrading your header AND your library to the same level.

gboolean oio_url_check	(	const struct oio_url_s *	u,
		const char *	n,
		const gchar **	e
	)

Validate contains of oio_url

Parameters

u	the URL
n	the namespace (optional)
e	will contains faulty field

Returns: true if valid

void oio_url_clean ( struct oio_url_s * u )

void oio_url_cleanv ( struct oio_url_s ** tab )

struct oio_url_s* oio_url_dup ( const struct oio_url_s * u )

Duplicate a URL (deep copy)

struct oio_url_s* oio_url_empty ( void )

Builds an empty URL

const char* oio_url_get	(	struct oio_url_s *	u,
		enum oio_url_field_e	f
	)

Gets a part of a URL.

Parameters

u	the URL
f	the identifier of the part you wan't to get

Returns: the value of the field (do not free)

The return value of oio_url_get(url, OIOURL_WHOLE) can safely be used as input of oio_url_init(char *url).

const void* oio_url_get_id ( struct oio_url_s * u )

size_t oio_url_get_id_size ( struct oio_url_s * u )

int oio_url_has	(	const struct oio_url_s *	u,
		enum oio_url_field_e	f
	)

int oio_url_has_fq_container ( const struct oio_url_s * u )

Returns wether all the mandatory components for a container are present

int oio_url_has_fq_path ( const struct oio_url_s * u )

Returns wether all the mandatory components for a path are present

struct oio_url_s* oio_url_init ( const char * url )

Builds a URL object from a '/'-separated string. The parts are parsed in that order:

namespace name;
account name;
reference name (aka container);
service type (should be empty most of the time);
content name.

Each part should be URL encoded.

A safer alternative to using this function is calling oio_url_empty() followed by oio_url_set() for each part you need to set (does not require URL encoding).

struct oio_url_s* oio_url_init_raw ( const char * url )

Same as oio_url_init, except that the parts should not be URL encoded (therefore you can't use '/' inside the parts).

void oio_url_pclean ( struct oio_url_s ** pu )

struct oio_url_s* oio_url_set	(	struct oio_url_s *	u,
		enum oio_url_field_e	f,
		const char *	v
	)

Sets a part of a URL. Values do not need to be URL encoded.

Parameters

u	the URL
f	the identifier of the part you wan't to set
v	the value for the part (no need to URL encode)

Returns: the URL

Note that you cannot set OIOURL_WHOLE (see oio_url_init).

void oio_url_set_id	(	struct oio_url_s *	u,
		const void *	id
	)

Set the container id from its binary representation. Use oio_url_set(u, OIOURL_CONTENTID, id) to set it with an hexadecimal str.

Parameters

id	must be oio_url_get_id_size() bytes long

void oio_url_unset	(	struct oio_url_s *	u,
		enum oio_url_field_e	f
	)

Variable Documentation

volatile int oio_sds_default_autocreate

Should the call to oio_sds_upload() (and its family) try to autocreate the container.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation