iotcs_storage_object.h File Reference

Methods for storage object. More...

#include "iotcs.h"
#include "advanced/iotcs_messaging.h"

Go to the source code of this file.

Typedefs
typedef enum iotcs_storage_dispatcher_progress_state_t	iotcs_storage_dispatcher_progress_state
	Provides progress of sync.
typedef void(*	iotcs_storage_dispatcher_progress_callback )(iotcs_storage_object *storage_object, iotcs_storage_dispatcher_progress_state state, int64_t bytes_transfered, const char *fail_reason)
	Callback to receive the result of an upload or download.
Enumerations
enum	iotcs_storage_dispatcher_progress_state_t {   IOTCS_CANCELED = 0, IOTCS_COMPLETED = 1, IOTCS_FAILED = 2, IOTCS_IN_PROGRESS = 3,   IOTCS_INITIATED = 4, IOTCS_QUEUED = 5 }
Functions
iotcs_result	iotcs_create_storage_object (const char *name, const char *content_type, iotcs_storage_object **storage_object)
	Create a new #iotcs_storage_object wthat will have a name with the given object name prefixed with the device's endpoint ID and a directory separator.
iotcs_result	iotcs_storage_object_set_custom_metadata (iotcs_storage_object *storage_object, const char *name, const char *value)
	Sets the metadata for the StorageObject.
iotcs_result	iotcs_create_external_object (const char *uri, iotcs_external_object **external_object)
	Create a new #iotcs_external_object with the given URI.
iotcs_result	iotcs_create_storage_object_by_uri (const char *uri, iotcs_storage_object **storage_object)
	Create a new #iotcs_storage_object from the URI for a named object in storage_object.
void	iotcs_free_storage_object (iotcs_storage_object *storage_object)
	Release Storage Object created by library.
void	iotcs_free_external_object (iotcs_external_object *external_object)
	Release External Object created by library.
void	iotcs_storage_object_cancel (iotcs_storage_object *storage_object)
	Cancel syncronization of storage object.
const char *	iotcs_external_object_get_uri (const iotcs_external_object *external_object)
	Return resource URI.
iotcs_result	iotcs_storage_object_set_input_path (iotcs_storage_object *storage_object, const char *input_path)
	Set input file for content to be uploaded.
iotcs_result	iotcs_storage_object_set_output_path (iotcs_storage_object *storage_object, const char *output_path)
	Set output file for content to be downloaded.
const char *	iotcs_storage_object_get_input_path (const iotcs_storage_object *storage_object)
	Return input path if it was set.
const char *	iotcs_storage_object_get_output_path (const iotcs_storage_object *storage_object)
	Return output path if it was set.
const char *	iotcs_storage_object_get_name (const iotcs_storage_object *storage_object)
	Return name of storage object.
const char *	iotcs_storage_object_get_uri (const iotcs_storage_object *storage_object)
	Return resource URI.
iotcs_result	iotcs_storage_object_sync (iotcs_storage_object *storage_object)
	IoT CS secure file synchronous sync method.
long	iotcs_storage_object_get_length (const iotcs_storage_object *storage_object)
	Get the length of the content in bytes.
const char *	iotcs_storage_object_get_type (const iotcs_storage_object *storage_object)
	Get the mime-type of the content.
const char *	iotcs_storage_object_get_encoding (const iotcs_storage_object *storage_object)
	Get the encoding scheme of the content.
iotcs_date_time	iotcs_storage_object_get_date (const iotcs_storage_object *storage_object)
	Get the date and time the content was created or last modified in cloud storage.
iotcs_result	iotcs_storage_dispatcher_queue (iotcs_storage_object *storage_object)
	IoT CS secure file asynchronous sync method.
void	iotcs_storage_dispatcher_set_callback (iotcs_storage_dispatcher_progress_callback callback)
	Set a callback to be notified as the transfer progresses.

---

Detailed Description

Methods for storage object.

---

Typedef Documentation

iotcs_storage_dispatcher_progress_callback

Callback to receive the result of an upload or download.

Parameters:

storage	pointer to #iotcs_storage_object
current	dispathcer state iotcs_storage_dispatcher_progress_state
transfered_bytes	amount of bytes read or written
fail_reason	string with fail reason or null on success

---

Enumeration Type Documentation

enum iotcs_storage_dispatcher_progress_state_t

Enumerator:

IOTCS_CANCELED	Up/download was canceled before it completed.
IOTCS_COMPLETED	Up/download completed successfully.
IOTCS_FAILED	Up/download failed without completing.
IOTCS_IN_PROGRESS	Up/download is currently in progress.
IOTCS_INITIATED	Initial state after upload() or download() is called.
IOTCS_QUEUED	Up/download is queued and not yet started.

---

Function Documentation

iotcs_result iotcs_create_external_object	(	const char *	uri,
		iotcs_external_object **	external_object
	)

Create a new #iotcs_external_object with the given URI.

Parameters:

uri	Link.
external_object	pointer to receive a external_object. Users must release it by calling iotcs_free_external_object(external_object).

Return values:

IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_INVALID_ARGUMENT	if given uri is empty or NULL.
IOTCS_RESULT_OK	if succeeds.

iotcs_result iotcs_create_storage_object	(	const char *	name,
		const char *	content_type,
		iotcs_storage_object **	storage_object
	)

Create a new #iotcs_storage_object wthat will have a name with the given object name prefixed with the device's endpoint ID and a directory separator.

The prefix addition can be disabled by setting the DISABLE_STORAGE_OBJECT_PREFIX to true

Parameters:

name	Name of the attribute.
content_type	Type of the content.
storage_object_handle	pointer to receive a storage_object. The storage will be allocated . by the library and user must release it by calling iotcs_release_storage_object(storage). Some fields could be empty or null in case if they weren't set before and there is no default value.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if name is NULL.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_OK	if succeeds.

iotcs_result iotcs_create_storage_object_by_uri	(	const char *	uri,
		iotcs_storage_object **	storage_object
	)

Create a new #iotcs_storage_object from the URI for a named object in storage_object.

Parameters:

uri	the URI of the object in the storage cloud.
storage_object_handle	pointer to receive a storage_object. The storage will be allocated . by the library and use must release it by calling iotcs_release_storage_object(storage). Some fields could be empty or null in case if they weren't set before and there is no default value.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if uri is NULL or doesn't correct URI
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_OK	if succeeds.

const char* iotcs_external_object_get_uri

(

const iotcs_external_object *

external_object

)

Return resource URI.

Parameters:

external_object

Pointer to external object #iotcs_external_object

Return values:

URI	- link to an object
NULL,if	it was not set

void iotcs_free_external_object

(

iotcs_external_object *

external_object

)

Release External Object created by library.

Parameters:

external_object

Pointer to external object #iotcs_external_object

void iotcs_free_storage_object

(

iotcs_storage_object *

storage_object

)

Release Storage Object created by library.

Parameters:

storage

pointer to #iotcs_storage_object

iotcs_result iotcs_storage_dispatcher_queue

(

iotcs_storage_object *

storage_object

)

IoT CS secure file asynchronous sync method.

Synchronizes storage content with the storage cloud. E.g. uploading or downloading if required.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if storage_object is NULL.
IOTCS_RESULT_OK	if succeeds.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_FAIL	otherwise.

void iotcs_storage_dispatcher_set_callback

(

iotcs_storage_dispatcher_progress_callback

callback

)

Set a callback to be notified as the transfer progresses.

Parameters:

callback

- callback to invoke, if null, the existing callback will be removed iotcs_storage_dispatcher_progress_callback

void iotcs_storage_object_cancel

(

iotcs_storage_object *

storage_object

)

Cancel syncronization of storage object.

Parameters:

storage

pointer to #iotcs_storage_object

iotcs_date_time iotcs_storage_object_get_date

(

const iotcs_storage_object *

storage_object

)

Get the date and time the content was created or last modified in cloud storage.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

number	of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT)
0,if	it was not defined

const char* iotcs_storage_object_get_encoding

(

const iotcs_storage_object *

storage_object

)

Get the encoding scheme of the content.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Encoding
NULL,if	it was not set

const char* iotcs_storage_object_get_input_path

(

const iotcs_storage_object *

storage_object

)

Return input path if it was set.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Input	path
NULL,if	it was not set

long iotcs_storage_object_get_length

(

const iotcs_storage_object *

storage_object

)

Get the length of the content in bytes.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Size	in bytes
0,if	it was not gotten

const char* iotcs_storage_object_get_name

(

const iotcs_storage_object *

storage_object

)

Return name of storage object.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Name

const char* iotcs_storage_object_get_output_path

(

const iotcs_storage_object *

storage_object

)

Return output path if it was set.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Output	path
NULL,if	it was not set

const char* iotcs_storage_object_get_type

(

const iotcs_storage_object *

storage_object

)

Get the mime-type of the content.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

Type
application/octet-stream,if	it was not set

const char* iotcs_storage_object_get_uri

(

const iotcs_storage_object *

storage_object

)

Return resource URI.

Parameters:

storage

pointer to #iotcs_storage_object

Return values:

URI
NULL,if	it was not set

iotcs_result iotcs_storage_object_set_custom_metadata	(	iotcs_storage_object *	storage_object,
		const char *	name,
		const char *	value
	)

Sets the metadata for the StorageObject.

All metdata will be added to Storage Cloud Service as custom metadata with the "X-Object-Meta-KeyName" header.

Parameters:

object	pointer to receive a storage_object. The storage will be allocated . by the library and user must release it by calling iotcs_release_storage_object_handle(storage_object_handle). Some fields could be empty or null in case if they weren't set before and there is no default value.
key	The metadata key
value	The metadata value

Returns:

IOTCS_RESULT_INVALID_ARGUMENT if the key or value is empty

IOTCS_RESULT_INVALID_ARGUMENT if the key or value is

 NULL 

IOTCS_RESULT_OK if succeeds.

iotcs_result iotcs_storage_object_set_input_path	(	iotcs_storage_object *	storage_object,
		const char *	input_path
	)

Set input file for content to be uploaded.

Parameters:

storage	pointer to #iotcs_storage_object
input_path	Path to the file.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if given input_path or storage_object are NULL.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_OK	if succeeds.

iotcs_result iotcs_storage_object_set_output_path	(	iotcs_storage_object *	storage_object,
		const char *	output_path
	)

Set output file for content to be downloaded.

Parameters:

storage	pointer to #iotcs_storage_object
callback	Callback for notifications about synchronization

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if given output_path or storage_object are NULL.
IOTCS_RESULT_INVALID_ARGUMENT	if storage_object is syncing.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_OK	if succeeds.

iotcs_result iotcs_storage_object_sync

(

iotcs_storage_object *

storage_object

)

IoT CS secure file synchronous sync method.

Synchronizes storage content with the storage cloud. E.g. uploading or downloading if required.

Parameters:

storage

pointer to #iotcs_storage_object

Note:

This procedure should not be called from the callback implementation due to the possible deadlock on waiting for the message sending status from the current thread.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if storage_object is NULL.
IOTCS_RESULT_OK	if succeeds.
IOTCS_RESULT_CANNOT_AUTHORIZE	if there are problems with authorization.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_FAIL	otherwise.