s3eIOSiCloud.h

/*
 * Copyright (C) 2001-2011 Ideaworks3D Ltd.
 * All Rights Reserved.
 *
 * This document is protected by copyright, and contains information
 * proprietary to Ideaworks Labs.
 * This file consists of source code released by Ideaworks Labs under
 * the terms of the accompanying End User License Agreement (EULA).
 * Please do not use this program/source code before you have read the
 * EULA and have agreed to be bound by its terms.
 */
/*
 * WARNING: this is an autogenerated file and will be overwritten by
 * the extension interface script.
 */
#ifndef S3E_EXT_IOSICLOUD_H
#define S3E_EXT_IOSICLOUD_H

#include <s3eTypes.h>

/** iCloud event callbacks */
typedef enum s3eIOSiCloudCallback
{
	/**
	 * Received data to merge with (either regular read or conflicting version).
	 *
	 * System data stores a pointer to s3eIOSiCloudDataToMergeWith.
	 * Return 0 if data was processed successfully, 1 otherwise. Returned value is important
	 * for the conflict resolution to know if given file version has been successfully processed.
	 */
    S3E_IOSICLOUD_CALLBACK_MERGE,
    S3E_IOSICLOUD_CALLBACK_MAX
} s3eIOSiCloudCallback;

/** Data to merge application side data with */
typedef struct s3eIOSiCloudDataToMergeWith
{
	/** Data size in bytes */
	int32 m_DataSize;
	/** Data */
	const void* m_Data;
} s3eIOSiCloudDataToMergeWith;
// \cond HIDDEN_DEFINES
S3E_BEGIN_C_DECL
// \endcond

/**
 * Returns S3E_TRUE if the IOSiCloud extension is available.
 */
s3eBool s3eIOSiCloudAvailable();

/**
 * Registers a callback to be called for an operating system event.
 *
 * The available callback types are listed in @ref s3eIOSiCloudCallback.
 * @param cbid ID of the event for which to register.
 * @param fn callback function.
 * @param userdata Value to pass to the @e userdata parameter of @e NotifyFunc.
 * @return
 *  - @ref S3E_RESULT_SUCCESS if no error occurred.
 *  - @ref S3E_RESULT_ERROR if the operation failed.\n
 *
 * @see s3eIOSiCloudUnRegister
 * @note For more information on the system data passed as a parameter to the callback
 * registered using this function, see the @ref s3eIOSiCloudCallback enum.
 */
s3eResult s3eIOSiCloudRegister(s3eIOSiCloudCallback cbid, s3eCallback fn, void* userData);

/**
 * Unregister a callback for a given event.
 * @param cbid ID of the callback for which to register.
 * @param fn Callback Function.
 * @return
 * - @ref S3E_RESULT_SUCCESS if no error occurred.
 * - @ref S3E_RESULT_ERROR if the operation failed.\n
 * @note For more information on the systemData passed as a parameter to the callback
 * registered using this function, see the s3eIOSiCloudCallback enum.
 * @note It is not necessary to define a return value for any registered callback.
 * @see s3eIOSiCloudRegister
 */
s3eResult s3eIOSiCloudUnRegister(s3eIOSiCloudCallback cbid, s3eCallback fn);

/**
 * Starts iCloud servicing (read, write and conflict resolution) for a specific file.
 *
 * Reading operations and conflicts will be notified via S3E_IOSICLOUD_CALLBACK_MERGE callback.
 * If iCloud isn't available on the device, S3E_RESULT_ERROR is returned.
 */
s3eResult s3eIOSiCloudStart(const char* fileName, s3eBool supportConflictResolution);

/**
 * Stops iCloud servicing for a file for which s3eIOSiCloudStart was previously invoked
 */
void s3eIOSiCloudStop();

/**
 * Tick function; must be called regularly to enable read/write operations retry
 */
void s3eIOSiCloudTick();

/**
 * Starts writing out the data to file.
 *
 * The final result of writing to iCloud file isn't reported by any callback.
 * If other write operation was enqueued at the time of calling this function or if failed
 * to enqueue the data to write for any other reason, S3E_RESULT_ERROR is returned.
 */
s3eResult s3eIOSiCloudWrite(const void* data, int32 dataSize);

S3E_END_C_DECL

#endif /* !S3E_EXT_IOSICLOUD_H */