ax_storage.h File Reference

The AXStorage library is an Edge Storage interface which contains functions for accessing the Axis product's Edge storage. More...

Go to the source code of this file.

Typedefs
typedef typedefG_BEGIN_DECLS struct _AXStorage	AXStorage
	Opaque structure for the AXStorage.
typedef void(*	AXStorageSubscriptionCallback) (gchar *storage_id, gpointer user_data, GError *error)
typedef void(*	AXStorageSetupCallback) (AXStorage *storage, gpointer user_data, GError *error)
typedef void(*	AXStorageReleaseCallback) (gpointer user_data, GError *error)

Enumerations
enum	AXStorageStatusEventId {   AX_STORAGE_AVAILABLE_EVENT, AX_STORAGE_EXITING_EVENT, AX_STORAGE_WRITABLE_EVENT, AX_STORAGE_FULL_EVENT,   AX_STORAGE_STATUS_EVENT_ID_END }
enum	AXStorageType { LOCAL_TYPE, EXTERNAL_TYPE, UNKNOWN_TYPE }

Functions
GList *	ax_storage_list (GError **error)
	Lists all connected storage devices. The returned list and its members must be freed by the caller. Use g_free for the members and g_list_free for the list. More...
guint	ax_storage_subscribe (gchar *storage_id, AXStorageSubscriptionCallback callback, gpointer user_data, GError **error)
gboolean	ax_storage_unsubscribe (guint id, GError **error)
	Stop subscribing to storage events. More...
gboolean	ax_storage_setup_async (gchar *storage_id, AXStorageSetupCallback callback, gpointer user_data, GError **error)
gboolean	ax_storage_release_async (AXStorage *storage, AXStorageReleaseCallback callback, gpointer user_data, GError **error)
gchar *	ax_storage_get_path (AXStorage *storage, GError **error)
gboolean	ax_storage_get_status (gchar *storage_id, AXStorageStatusEventId event, GError **error)
gchar *	ax_storage_get_storage_id (AXStorage *storage, GError **error)
AXStorageType	ax_storage_get_type (AXStorage *storage, GError **error)

Detailed Description

The AXStorage library is an Edge Storage interface which contains functions for accessing the Axis product's Edge storage.

The error parameter of the methods can be NULL to ignore errors or non-NULL to get errors reported. The API sets the error parameters in case something went wrong and the error parameter is non-NULL.

Typedef Documentation

AXStorageSubscriptionCallback

typedef void(* AXStorageSubscriptionCallback) (gchar *storage_id, gpointer user_data, GError *error)

The callback for events from a subscribed storage. It will be called when events change status.

To get status of the different events, use the ax_storage_get_status method!

Note that it is not an error if this method gets called when it appears none of the (known) events have changed state!

Parameters

storage_id	The storage that triggered this callback.
user_data	User data from ax_storage_subscribe.
error	Return location for error, or NULL.

AXStorageSetupCallback

typedef void(* AXStorageSetupCallback) (AXStorage *storage, gpointer user_data, GError *error)

Callback for setup. When the storage is setup for use, an application specific directory has been created on the storage. The path can be retrieved by the ax_storage_get_path method, using the AXStorage that is received in this callback as input parameter.

The AXStorage that is received in this callback is the one to use in every method which takes an AXStorage pointer as input parameter.

Parameters

storage	The storage to use.
user_data	User data from ax_storage_setup_async.
error	Return location for error, or NULL.

AXStorageReleaseCallback

typedef void(* AXStorageReleaseCallback) (gpointer user_data, GError *error)

The callback for asynchronous release. The release is successful if error parameter is NULL.

Parameters

user_data	User data from ax_storage_release_async.
error	Return location for error, or NULL.

Enumeration Type Documentation

AXStorageStatusEventId

enum AXStorageStatusEventId

The list of events for AXStorage

Enumerator
AX_STORAGE_AVAILABLE_EVENT	Event for when storage becomes available and unavailable.
AX_STORAGE_EXITING_EVENT	Event for when storage is about to exit, that's when client must stop using storage.
AX_STORAGE_WRITABLE_EVENT	Event for when storage becomes writable or readonly.
AX_STORAGE_FULL_EVENT	Event for when storage becomes full and when there is free space again. When storage becomes full client must not write more data to it, it's only ok to remove data.
AX_STORAGE_STATUS_EVENT_ID_END	Placeholder, do not use

AXStorageType

enum AXStorageType

The type of storage

Function Documentation

ax_storage_list()

GList* ax_storage_list

(

GError **

error

)

Lists all connected storage devices. The returned list and its members must be freed by the caller. Use g_free for the members and g_list_free for the list.

Parameters

error

Return location for error, or NULL.

Returns

A GList of allocated storage_id strings representing the connected edge storage devices or NULL in case there were no storage connected or something went wrong.

Examples:

ax_storage_example.c.

ax_storage_subscribe()

guint ax_storage_subscribe	(	gchar *	storage_id,
		AXStorageSubscriptionCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Subscribe to storage events for the provided storage.

Parameters

storage_id	The specific storage to subscribe events for.
callback	The callback to call when event occur.
user_data	Custom data that will be passed to the AXStorageSubscriptionCallback. The caller is responsible for freeing this memory.
error	Return location for error, or NULL.

Returns

0 if there was an error, then error parameter is set, else subscription was successful and the returned id can be used in calls to ax_storage_unsubscribe to end the subscription.

Examples:

ax_storage_example.c.

ax_storage_unsubscribe()

gboolean ax_storage_unsubscribe	(	guint	id,
		GError **	error
	)

Stop subscribing to storage events.

Parameters

id	The identifier from a call to ax_storage_subscribe.
error	Return location for error, or NULL.

Returns

TRUE if unsubscription was successful. FALSE if there was an error, then error parameter is set.

Examples:

ax_storage_example.c.

ax_storage_setup_async()

gboolean ax_storage_setup_async	(	gchar *	storage_id,
		AXStorageSetupCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Setup storage for use asynchronously. This method must be called before the storage is to be used in any way (for instance read or write). When done using the storage, ax_storage_release_async must be called.

In other words: 1) Call ax_storage_setup_async, a pointer to the populated AXStorage is received in the setup callback. 2) Use the AXStorage pointer to get the path of where to read and write. 3) User regular c-file operations to read and write to the storage. 4) Call ax_storage_release_async.

Parameters

storage_id	The storage to use.
callback	The callback which will be called when the setup is done
user_data	Custom data that will be passed to the AXStorageSetupCallback. The caller is responsible for freeing this memory.
error	Return location for error, or NULL.

Returns

TRUE if setup was sucessful. FALSE if there was an error, then error parameter is set.

Examples:

ax_storage_example.c.

ax_storage_release_async()

gboolean ax_storage_release_async	(	AXStorage *	storage,
		AXStorageReleaseCallback	callback,
		gpointer	user_data,
		GError **	error
	)

Release the use of storage asynchronously. This method should be called when done using the storage, after a successful setup (ax_storage_setup_async).

Parameters

storage	The storage to release
callback	The callback which will be called when the release is done.
user_data	The user_data pointer provided to the AXStorageReleaseCallback. The caller is responsible for freeing this memory.
error	Return location for error, or NULL.

Returns

TRUE if call was successful. FALSE if there was an error, then error parameter is set. The actual result of the release will be available in the callback.

Examples:

ax_storage_example.c.

ax_storage_get_path()

gchar* ax_storage_get_path	(	AXStorage *	storage,
		GError **	error
	)

Returns the location on the storage where the client should save its files. Should only be used after a successful storage setup. Note that the returned string must be freed by the caller!

Parameters

storage	An AXStorage
error	Return location for error, or NULL.

Returns

A path to a directory on the storage where the app should save its files. This path must be freed by the caller, or NULL if failure, then error will be set.

Examples:

ax_storage_example.c.

ax_storage_get_status()

gboolean ax_storage_get_status	(	gchar *	storage_id,
		AXStorageStatusEventId	event,
		GError **	error
	)

Returns the status of the provided event.

Parameters

storage_id	The storage to get status for.
event	The event to get status for.
error	Return location for error, or NULL.

Returns

TRUE if the status of the provided event is TRUE. FALSE if it is false. If successful, error is NULL, otherwise a return location for a GError is provided.

Examples:

ax_storage_example.c.

ax_storage_get_storage_id()

gchar* ax_storage_get_storage_id	(	AXStorage *	storage,
		GError **	error
	)

After a successful storage setup, get the storage_id from the provided AXStorage. Note that this string must be freed by the caller.

Parameters

storage	The storage to get ID for.
error	Return location for error, or NULL.

Returns

Allocated storage_id string or NULL if failure. Then a location for a GError is also provided.

Examples:

ax_storage_example.c.

ax_storage_get_type()

AXStorageType ax_storage_get_type	(	AXStorage *	storage,
		GError **	error
	)

After a successful storage setup, get the storage type from the provided AXStorage.

Parameters

storage	The storage to get type for.
error	Return location for error, or NULL.

Returns

storage type or UNKNOWN_TYPE if failure. Then a location for a GError is also provided.

Examples:

ax_storage_example.c.