oio_sds.h

Go to the documentation of this file.

/*
OpenIO SDS core library
Copyright (C) 2015-2018 OpenIO SAS, as part of OpenIO SDS

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 3.0 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library.
*/

#ifndef OIO_SDS__sdk__oio_sds_h
#define OIO_SDS__sdk__oio_sds_h 1

#include <stdlib.h>
#include <core/oiourl.h>

#define OIO_SDS_VERSION 20180716

#ifdef __cplusplus
extern "C" {
#endif

struct oio_sds_s;
struct oio_error_s;

enum oio_sds_config_e
{
    OIOSDS_CFG_TIMEOUT_PROXY = 1,

    OIOSDS_CFG_TIMEOUT_RAWX,

    OIOSDS_CFG_FLAG_SYNCATDOWNLOAD,

    OIOSDS_CFG_FLAG_ADMIN,

    OIOSDS_CFG_FLAG_NO_SHUFFLE,

    OIOSDS_CFG_FLAG_CHUNKSIZE,
};

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,
};

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



/* API-global --------------------------------------------------------------- */

/* OpenIO SDK internally relies on GLib-2.0 logging features,
 * so this only sets a callback into GLib's system. The calling app
 * keeps the freedom to change this. */

extern volatile int oio_sds_default_autocreate;


void oio_log_to_syslog (void);

void oio_log_to_stderr (void);

void oio_log_nothing (void);

void oio_log_more (void);

#ifdef OIO_SDS_VERSION

unsigned int oio_sds_version (void);
#endif /* defined OIO_SDS_VERSION */


/* Error management --------------------------------------------------------- */

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



/* Client-related features -------------------------------------------------- */

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

/* destructor */
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);



/* Create / destroy --------------------------------------------------------- */

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



/* Download ----------------------------------------------------------------- */

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

enum oio_sds_dl_dst_type_e
{
    OIO_DL_DST_HOOK_SEQUENTIAL = 1,
    OIO_DL_DST_BUFFER,
    OIO_DL_DST_FILE,
};

struct oio_sds_dl_dst_s
{
    /* output variable: how many bytes have been read, at all */
    size_t out_size;

    enum oio_sds_dl_dst_type_e type;

    union {
        struct {
            const char *path;
        } file;
        struct {
            unsigned char *ptr;
            size_t length;
        } buffer;
        struct {
            oio_sds_dl_hook_f cb;
            void *ctx;

            /* set 'length' to ((size_t)-1) to mark it unset and allow the
             * whole content to be downloaded. If set, it must be coherent
             * with the ranges provided. */
            size_t length;
        } hook;
    } data;
};

struct oio_sds_dl_range_s
{
    size_t offset;
    size_t size;
};

struct oio_sds_dl_src_s
{
    struct oio_url_s *url;

    struct oio_sds_dl_range_s **ranges;
};

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



/* Upload ------------------------------------------------------------------- */

struct oio_sds_ul_dst_s
{
    struct oio_url_s *url;

    /* Should the container be autocreated */
    unsigned int autocreate : 1;

    /* Should the data be appended to the content in place. When set to 1,
     * `content_id` and `meta_pos` must be set. */
    unsigned int append : 1;

    /* Do a partial upload. When set to 1, `content_id` and `meta_pos` are
     * mandatory. */
    unsigned int partial : 1;

    /* output variable: how many bytes have been uploaded */
    size_t out_size;

    /* The unique content name.
     * Optional when both `partial` and `append` are set to 0.
     * When set, it MUST be an hexadecimal string (with an even number of
     * characters). */
    const char *content_id;

    /* NULL-terminated array of property keys and values.
     * Set to NULL when you have no property to set upon the upload. */
    const char * const * properties;

    /* Position of the first metachunk that is to be modified */
    int meta_pos;

    /* Offset of the first byte of the metachunk, relative to the
     * beginning of the content, used to check write alignment. */
    size_t offset;

    /* Size of the chunks we will send, in bytes.
     * If set to 0, the default will be used. */
    size_t chunk_size;
};

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

struct oio_sds_ul_s;

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

#define OIO_SDS_UL__ERROR  ((size_t)-2)
#define OIO_SDS_UL__DONE   ((size_t)-1)
#define OIO_SDS_UL__NODATA ((size_t)0)

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

enum oio_sds_ul_src_type_e
{
    OIO_UL_SRC_HOOK_SEQUENTIAL = 1,
    /*OIO_UL_SRC_HOOK_RANDOM, */ /* coming soon */
};

struct oio_sds_ul_src_s
{
    enum oio_sds_ul_src_type_e type;

    union {
        struct {
            oio_sds_ul_hook_f cb;
            void *ctx;
            size_t size;
        } hook;
    } data;
};

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

/* works with fully qualified urls (content) and local paths */
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);



/* List --------------------------------------------------------------------- */

struct oio_sds_list_param_s
{
    struct oio_url_s *url;
    const char *prefix;
    const char *marker;
    const char *end;

    /* 0 means not set */
    size_t max_items;

    /* 0 means no set */
    char delimiter;

    unsigned char flag_nodeleted : 1;
    unsigned char flag_allversions : 1;
    unsigned char flag_properties : 1;
};

struct oio_sds_list_item_s
{
    const char *name;
    const char *hash;
    size_t size;
    size_t version;
    const char * const *properties;
};

struct oio_sds_list_listener_s
{
    void *ctx;

    int (*on_item) (void *ctx, const struct oio_sds_list_item_s *item);

    int (*on_prefix) (void *ctx, const char *prefix);

    int (*on_bound) (void *ctx, const char *next_marker);

    size_t out_count;

    int out_truncated;
};

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

/* Quota -------------------------------------------------------------------- */

struct oio_sds_usage_s
{
    size_t used_bytes;

    size_t quota_bytes;

    int used_objects;
};

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



/* Misc. -------------------------------------------------------------------- */

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


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

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

#ifdef __cplusplus
}
#endif

#endif /*OIO_SDS__sdk__oio_sds_h*/