iotcs_storage_object.h File Reference

Methods for storage object handle. More...

#include <stdint.h>
#include "iotcs.h"
#include "advanced/iotcs_messaging.h"
#include "iotcs_virtual_device.h"

Go to the source code of this file.

Structures
struct	iotcs_storage_object_sync_event_t
Typedefs
typedef enum iotcs_storage_object_sync_status_t	iotcs_storage_object_sync_status
	Provides status of sync.
typedef struct iotcs_storage_object_sync_event_t	iotcs_storage_object_sync_event
	Typedef for iotcs_storage_object_sync_event_t structure.
typedef void(*	iotcs_storage_object_sync_callback )(iotcs_storage_object_sync_event *event)
Enumerations
enum	iotcs_storage_object_sync_status_t { IOTCS_IN_SYNC = 0, IOTCS_NOT_IN_SYNC = 1, IOTCS_SYNC_FAILED = 2, IOTCS_SYNC_PENDING = 3 }
Functions
iotcs_result	iotcs_create_storage_object_handle (const char *name, const char *content_type, iotcs_storage_object_handle *storage_object_handle)
	Create a new #iotcs_storage_object_handle that 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_handle storage_object_handle, const char *name, const char *value)
	Sets the metadata for the StorageObject.
iotcs_result	iotcs_create_external_object_handle (const char *uri, iotcs_external_object_handle *external_object_handle)
	Create a new #iotcs_external_object_handle with the given URI.
void	iotcs_free_storage_object_handle (iotcs_storage_object_handle storage_object_handle)
	Release Storage Object Attribute created by library.
void	iotcs_free_external_object_handle (iotcs_external_object_handle external_object_handle)
	Release External Object.
const char *	iotcs_external_object_get_uri (const iotcs_external_object_handle external_object_handle)
	Return resource URI.
iotcs_result	iotcs_storage_object_set_input_path (iotcs_storage_object_handle storage_object_handle, const char *input_path)
	Set input file for content to be uploaded.
iotcs_result	iotcs_storage_object_set_output_path (iotcs_storage_object_handle storage_object_handle, const char *output_path)
	Set output file for content to be downloaded.
iotcs_result	iotcs_storage_object_set_callback (iotcs_storage_object_handle storage_object_handle, iotcs_storage_object_sync_callback callback)
	Set a callback that is invoked when the content referred to by this #iotcs_storage_object_handle is synchronized.
iotcs_storage_object_sync_status	iotcs_storage_object_get_sync_status (const iotcs_storage_object_handle storage_object_handle)
	Return synchronization status for current storage object.
const char *	iotcs_storage_object_get_input_path (const iotcs_storage_object_handle storage_object_handle)
	Return input path if it was set.
const char *	iotcs_storage_object_get_output_path (const iotcs_storage_object_handle storage_object_handle)
	Return output path if it was set.
const char *	iotcs_storage_object_get_name (const iotcs_storage_object_handle storage_object_handle)
	Return name of storage object.
const char *	iotcs_storage_object_get_uri (const iotcs_storage_object_handle storage_object_handle)
	Return resource URI.
long	iotcs_storage_object_get_length (const iotcs_storage_object_handle storage_object_handle)
	Get the length of the content in bytes.
const char *	iotcs_storage_object_get_type (const iotcs_storage_object_handle storage_object_handle)
	Get the mime-type of the content.
const char *	iotcs_storage_object_get_encoding (const iotcs_storage_object_handle storage_object_handle)
	Get the encoding scheme of the content.
iotcs_date_time	iotcs_storage_object_get_date (const iotcs_storage_object_handle storage_object_handle)
	Get the date and time the content was created or last modified in cloud storage.
iotcs_result	iotcs_storage_object_sync (iotcs_storage_object_handle storage_object_handle)
	Notify the library to sync content with the storage cloud.

---

Detailed Description

Methods for storage object handle.

---

Enumeration Type Documentation

enum iotcs_storage_object_sync_status_t

Enumerator:

IOTCS_IN_SYNC	The content is in sync with the storage cloud.
IOTCS_NOT_IN_SYNC	The content is not in sync with the storage cloud.
IOTCS_SYNC_FAILED	The content is not in sync with the storage cloud because the upload or download failed.
IOTCS_SYNC_PENDING	The content is not in sync with the storage cloud, but sync is pending.

---

Function Documentation

iotcs_result iotcs_create_external_object_handle	(	const char *	uri,
		iotcs_external_object_handle *	external_object_handle
	)

Create a new #iotcs_external_object_handle 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_handle(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_handle	(	const char *	name,
		const char *	content_type,
		iotcs_storage_object_handle *	storage_object_handle
	)

Create a new #iotcs_storage_object_handle that 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_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.

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.

const char* iotcs_external_object_get_uri

(

const iotcs_external_object_handle

external_object_handle

)

Return resource URI.

Parameters:

external_object

External object handle #iotcs_external_object_handle

Return values:

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

void iotcs_free_external_object_handle

(

iotcs_external_object_handle

external_object_handle

)

Release External Object.

Parameters:

external_object

External object #iotcs_external_object_handle

void iotcs_free_storage_object_handle

(

iotcs_storage_object_handle

storage_object_handle

)

Release Storage Object Attribute created by library.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

iotcs_date_time iotcs_storage_object_get_date

(

const iotcs_storage_object_handle

storage_object_handle

)

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

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

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_handle

storage_object_handle

)

Get the encoding scheme of the content.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Encoding
NULL,if	it was not set

const char* iotcs_storage_object_get_input_path

(

const iotcs_storage_object_handle

storage_object_handle

)

Return input path if it was set.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Input	path
NULL,if	it was not set

long iotcs_storage_object_get_length

(

const iotcs_storage_object_handle

storage_object_handle

)

Get the length of the content in bytes.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Size	in bytes
0,if	it was not gotten

const char* iotcs_storage_object_get_name

(

const iotcs_storage_object_handle

storage_object_handle

)

Return name of storage object.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Name

const char* iotcs_storage_object_get_output_path

(

const iotcs_storage_object_handle

storage_object_handle

)

Return output path if it was set.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Output	path
NULL,if	it was not set

iotcs_storage_object_sync_status iotcs_storage_object_get_sync_status

(

const iotcs_storage_object_handle

storage_object_handle

)

Return synchronization status for current storage object.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

Synchronization	status
IOTCS_NOT_IN_SYNC	for illegal or NULL objects

const char* iotcs_storage_object_get_type

(

const iotcs_storage_object_handle

storage_object_handle

)

Get the mime-type of the content.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

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

const char* iotcs_storage_object_get_uri

(

const iotcs_storage_object_handle

storage_object_handle

)

Return resource URI.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

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

iotcs_result iotcs_storage_object_set_callback	(	iotcs_storage_object_handle	storage_object_handle,
		iotcs_storage_object_sync_callback	callback
	)

Set a callback that is invoked when the content referred to by this #iotcs_storage_object_handle is synchronized.

Parameters:

storage_object_handle	Storage object handle #iotcs_storage_object_handle
callback	Callback for notifications about synchronization

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if given output_path is NULL.
IOTCS_RESULT_OK	if succeeds.

iotcs_result iotcs_storage_object_set_custom_metadata	(	iotcs_storage_object_handle	storage_object_handle,
		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_handle	storage_object_handle,
		const char *	input_path
	)

Set input file for content to be uploaded.

Parameters:

storage_object_handle	storage object #iotcs_storage_object_handle
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_handle	storage_object_handle,
		const char *	output_path
	)

Set output file for content to be downloaded.

Parameters:

storage_object_handle	Storage object handle #iotcs_storage_object_handle
output_path	Path to the file.

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if given output_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_sync

(

iotcs_storage_object_handle

storage_object_handle

)

Notify the library to sync content with the storage cloud.

Parameters:

storage_object_handle

Storage object handle #iotcs_storage_object_handle

Return values:

IOTCS_RESULT_INVALID_ARGUMENT	if virtual_device_handle or attribute_name are NULL.
IOTCS_RESULT_OK	if succeeds.
IOTCS_RESULT_OUT_OF_MEMORY	if there is no memory available.
IOTCS_RESULT_FAIL	otherwise.