RESTful API

Functions specific to RESTful API (S3, CDMI, sproxyd, SRWS, etc) More...

Functions
const char *	dpl_get_backend_name (dpl_ctx_t *ctx)
	return the name of the backend currently used More...
dpl_status_t	dpl_get_capabilities (dpl_ctx_t *ctx, dpl_capability_t *maskp)
	get the backend capabilities More...
dpl_status_t	dpl_login (dpl_ctx_t *ctx)
	login More...
dpl_status_t	dpl_list_all_my_buckets (dpl_ctx_t *ctx, dpl_vec_t **vecp)
	list all buckets More...
dpl_status_t	dpl_list_bucket (dpl_ctx_t *ctx, const char *bucket, const char *prefix, const char *delimiter, const int max_keys, dpl_vec_t **objectsp, dpl_vec_t **common_prefixesp)
	list bucket or directory More...
dpl_status_t	dpl_make_bucket (dpl_ctx_t *ctx, const char *bucket, dpl_location_constraint_t location_constraint, dpl_canned_acl_t canned_acl)
	make a bucket More...
dpl_status_t	dpl_delete_bucket (dpl_ctx_t *ctx, const char *bucket)
	delete a path More...
dpl_status_t	dpl_post (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, const dpl_range_t *range, const dpl_dict_t *metadata, const dpl_sysmd_t *sysmd, const char *data_buf, unsigned int data_len, const dpl_dict_t *query_params, dpl_sysmd_t *returned_sysmdp)
	create or post data into a path More...
dpl_status_t	dpl_put (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, const dpl_range_t *range, const dpl_dict_t *metadata, const dpl_sysmd_t *sysmd, const char *data_buf, unsigned int data_len)
	put a path More...
dpl_status_t	dpl_get (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, const dpl_range_t *range, char **data_bufp, unsigned int *data_lenp, dpl_dict_t **metadatap, dpl_sysmd_t *sysmdp)
	get a path with range More...
dpl_status_t	dpl_head (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, dpl_dict_t **metadatap, dpl_sysmd_t *sysmdp)
	get user and system metadata More...
dpl_status_t	dpl_head_raw (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, dpl_dict_t **metadatap)
	get raw metadata More...
dpl_status_t	dpl_delete (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition)
	delete a path More...
dpl_status_t	dpl_post_id (dpl_ctx_t *ctx, const char *bucket, const char *id, const dpl_option_t *option, dpl_ftype_t object_type, const dpl_condition_t *condition, const dpl_range_t *range, const dpl_dict_t *metadata, const dpl_sysmd_t *sysmd, const char *data_buf, unsigned int data_len, const dpl_dict_t *query_params, dpl_sysmd_t *returned_sysmdp)
	create or post data into a path More...
dpl_status_t	dpl_genurl (dpl_ctx_t *ctx, const char *bucket, const char *path, const dpl_option_t *option, time_t expires, char *buf, unsigned int len, unsigned int *lenp)
	generate a valid URL for sharing object More...
dpl_status_t	dpl_copy (dpl_ctx_t *ctx, const char *src_bucket, const char *src_path, const char *dst_bucket, const char *dst_path, const dpl_option_t *option, dpl_ftype_t object_type, dpl_copy_directive_t copy_directive, const dpl_dict_t *metadata, const dpl_sysmd_t *sysmd, const dpl_condition_t *condition)
	perform various flavors of server side copies More...

Detailed Description

This is the abstraction layer fo all backends (S3, CDMI, sproxyd, SRWS, etc). Mainly, this API is used for PUTting, GETting and DELETing objects, but also manipulating the object attributes. For backends that has bucket support, this API allows to create/list/destroy buckets,

Users are supposed to call these functions as opposed to using the backend functions directly.

Configuring the backend is done is the profile dictionnary or the profile configuration file (see dpl_ctx_new())

Function Documentation

dpl_status_t dpl_copy	(	dpl_ctx_t *	ctx,
		const char *	src_bucket,
		const char *	src_path,
		const char *	dst_bucket,
		const char *	dst_path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		dpl_copy_directive_t	copy_directive,
		const dpl_dict_t *	metadata,
		const dpl_sysmd_t *	sysmd,
		const dpl_condition_t *	condition
	)

Parameters

ctx	the droplet context
src_bucket	the optional source bucket
src_path	the mandat source path
dst_bucket	the optional destination bucket
dst_path	the optional destination path (if dst equals src)
option	unused
object_type	unused
copy_directive	DPL_COPY_DIRECTIVE_COPY server side copy
copy_directive	DPL_COPY_DIRECTIVE_METADATA_REPLACE setattr
copy_directive	DPL_COPY_DIRECTIVE_LINK hard link
copy_directive	DPL_COPY_DIRECTIVE_SYMLINK reference
copy_directive	DPL_COPY_DIRECTIVE_MOVE rename
copy_directive	DPL_COPY_DIRECTIVE_MKDENT create a directory entry
metadata	the optional user metadata
sysmd	the optional system metadata
condition	the optional condition

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_delete	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition
	)

Parameters

ctx	the droplet context
bucket	the optional bucket
path	the mandat path
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
condition	the optional condition

Returns

DPL_SUCCESS

DPL_FAILURE

DPL_ENOENT path does not exist

dpl_status_t dpl_delete_bucket	(	dpl_ctx_t *	ctx,
		const char *	bucket
	)

Parameters

ctx	the droplet context
bucket	can be NULL

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_genurl	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		time_t	expires,
		char *	buf,
		unsigned int	len,
		unsigned int *	lenp
	)

Parameters

ctx	the droplet context
bucket	the optional bucket
path	the mandat path
option	unused
expires	expire time of URL
buf	URL is created in this buffer
len	buffer length
lenp	real buffer returned

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_get	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		const dpl_range_t *	range,
		char **	data_bufp,
		unsigned int *	data_lenp,
		dpl_dict_t **	metadatap,
		dpl_sysmd_t *	sysmdp
	)

Parameters

ctx	the droplet context
bucket	the optional bucket
path	the mandat path
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
object_type	DPL_FTYPE_ANY get any type of path
condition	the optional condition
range	the optional range
data_bufp	the returned data buffer client shall free
data_lenp	the returned data length
metadatap	the returned user metadata client shall free
sysmdp	the returned system metadata passed through stack

Returns

DPL_SUCCESS

DPL_FAILURE

DPL_ENOENT path does not exist

const char* dpl_get_backend_name

(

dpl_ctx_t *

ctx

)

Parameters

ctx

Returns

the backend name

dpl_status_t dpl_get_capabilities	(	dpl_ctx_t *	ctx,
		dpl_capability_t *	maskp
	)

Parameters

	ctx	droplet context
[out]	maskp	a pointer to mask

dpl_status_t dpl_head	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		dpl_dict_t **	metadatap,
		dpl_sysmd_t *	sysmdp
	)

Parameters

ctx	the droplet context
bucket	the optional bucket
path	the mandat path
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
object_type	DPL_FTYPE_ANY get any type of path
condition	the optional condition
metadatap	the returned user metadata client shall free
sysmdp	the returned system metadata passed through stack

Returns

DPL_SUCCESS

DPL_FAILURE

DPL_ENOENT path does not exist

dpl_status_t dpl_head_raw	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		dpl_dict_t **	metadatap
	)

Parameters

ctx	the droplet context
bucket	the optional bucket
path	the mandat path
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
condition	the optional condition
metadatap	the returned metadata client shall free

Returns

DPL_SUCCESS

DPL_FAILURE

DPL_ENOENT

dpl_status_t dpl_list_all_my_buckets	(	dpl_ctx_t *	ctx,
		dpl_vec_t **	vecp
	)

Parameters

ctx	the droplect context
vecp	a vector of dpl_bucket_t *

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_list_bucket	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	prefix,
		const char *	delimiter,
		const int	max_keys,
		dpl_vec_t **	objectsp,
		dpl_vec_t **	common_prefixesp
	)

Parameters

ctx	the droplet context
bucket	can be NULL
prefix	directory can be NULL
delimiter	e.g. "/" can be NULL
max	number of keys we want to get (-1 for no limit)
objectsp	vector of dpl_object_t * (files)
prefixesp	vector of dpl_common_prefix_t * (directories)

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_login

(

dpl_ctx_t *

ctx

)

Parameters

ctx	droplet context

dpl_status_t dpl_make_bucket	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		dpl_location_constraint_t	location_constraint,
		dpl_canned_acl_t	canned_acl
	)

Parameters

ctx	the droplet context
bucket	can be NULL
location_constraint	geographic location
canned_acl	simplified ACL

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_post	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		const dpl_range_t *	range,
		const dpl_dict_t *	metadata,
		const dpl_sysmd_t *	sysmd,
		const char *	data_buf,
		unsigned int	data_len,
		const dpl_dict_t *	query_params,
		dpl_sysmd_t *	returned_sysmdp
	)

Note

this function is expected to return a newly created object

Parameters

ctx	the droplet context
bucket	can be NULL
path	can be NULL
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
object_type	DPL_FTYPE_REG create a file
metadata	the user metadata. optional
sysmd	the system metadata. optional
data_buf	the data buffer
data_len	the data length
query_params	can be NULL
returned_sysmdp	the returned system metadata passed through stack

Returns

DPL_SUCCESS

DPL_FAILURE

dpl_status_t dpl_post_id	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	id,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		const dpl_range_t *	range,
		const dpl_dict_t *	metadata,
		const dpl_sysmd_t *	sysmd,
		const char *	data_buf,
		unsigned int	data_len,
		const dpl_dict_t *	query_params,
		dpl_sysmd_t *	returned_sysmdp
	)

Note

this function is expected to return a newly created object

Parameters

ctx
bucket
path	can be NULL
object_type
metadata
canned_acl
data_buf
data_len
query_params	can be NULL
returned_sysmdp

Returns

dpl_status_t dpl_put	(	dpl_ctx_t *	ctx,
		const char *	bucket,
		const char *	path,
		const dpl_option_t *	option,
		dpl_ftype_t	object_type,
		const dpl_condition_t *	condition,
		const dpl_range_t *	range,
		const dpl_dict_t *	metadata,
		const dpl_sysmd_t *	sysmd,
		const char *	data_buf,
		unsigned int	data_len
	)

Parameters

ctx	the droplet context
bucket	optional
path	mandatory
option	DPL_OPTION_HTTP_COMPAT use if possible the HTTP compat mode
object_type	DPL_FTYPE_REG create a file
object_type	DPL_FTYPE_DIR create a directory
condition	the optional condition
range	optional range
metadata	the optional user metadata
sysmd	the optional system metadata
data_buf	the data buffer
data_len	the data length

Returns

DPL_SUCCESS

DPL_FAILURE

DPL_EEXIST