/**
 * Appcelerator Platform SDK
 * Copyright (c) 2014 by Appcelerator, Inc. All Rights Reserved.
 * Proprietary and Confidential - This source code is not for redistribution
 */

#import <Foundation/Foundation.h>

// Base APS Classes
#import "APSResponse.h"

/**
 * Callback function to handle the server response of the request.
 * Will be called back on the same thread as the caller.
 * @param e Response received from the server, context is specific to the called method
 */
typedef void (^APSResponseHandler)(APSResponse *e);

/**
 * Callback function to handle the progress of the API call.
 * Will be called back on the same thread as the caller.
 * @param progress Value of the progress as a float (0-1.0)
 * @param upload Indicates if the progress is for an upload (true) or download (false.)
 */
typedef void (^APSProgressHandler)(float progress, BOOL upload);

/**
 * The APSCloud interface allows the application to configure the client and make generic
 * REST requests to the APS Cloud servers.
 *
 * After configuring your APS Cloud settings, call the sharedInstance method
 * to get the shared instance of the cloud client. Use this instance to make generic
 * REST API calls with the sendRequest methods.
 * <br/><br/>
 *
 * For information on getting started with Appcelerator Platform Services, see
 * [Appclerator Platform Services Native SDKs](http://bit.ly/1gBzl2s).
 *
 * <h3>Callbacks</h3>
 * <p>The Cloud API makes asychronous calls and relies on callbacks to handle the response.</p>
 * <p>Both the APSCloudObjects and APSClient methods take a server response handler and an optional
 * progress handler.</p>
 *
 * <h4>APSResponseHandler</h4>
 * <p>Callback function to handle the server response of the request.  Runs in a background thread.
 * To update the UI, switch to the main thread.</p>
 * <p><code>typedef void (^APSResponseHandler)(APSResponse *e)</code></p>
 * <p><b>Parameters</b>
 * <dl><dt>e</dt><dd>Response received from the server. See APSResponse.</dd></dl>
 *
 * <h4>APSProgressHandler</h4>
 * <p>Callback function to handle the progress of the API call.  Runs in a background thread.
 * To update the UI, switch to the main thread.</p>
 * <p><code>typedef void (^APSProgressHandler)(float progress, BOOL upload)</code></p>
 * <p><b>Parameters</b>
 * <dl>
 * <dt>progress</dt><dd>Value of the progress as a float (0 - 1.0)</dd>
 * <dt>upload</dt><dd>If true, the request is uploading data.</dd>
 * </dl>
 */

@interface APSCloud : NSObject

/** Timeout for REST requests in seconds */
@property (atomic, readwrite) NSTimeInterval timeout;

/**
 * Retrieves the share instance of the client
 * @return The shared instance of the client
 */
+ (instancetype)sharedInstance;

/**
 * Sends a generic REST request to the server specified by the APSCloud.baseURL setting
 * @param url The last fragment of request url
 * @param method It only can be one of "GET", "POST", "PUT", "DELETE".
 * @param data The name-value pairs which is ready to be sent to server.
 * Supported data types: NSString, NSNumber, NSArray(of supported data types), NSDictionary(of supported data types), NSData, NSURL(to a local file).
 * @param handler The block called when the request completes
 */
- (void)sendRequest:(NSString *)url
             method:(NSString *)method
               data:(NSDictionary *)data
            handler:(APSResponseHandler)handler;

/**
 * Sends a generic REST request to the server specified by the APSCloud.baseURL setting
 * @param url The last fragment of request url
 * @param method It only can be one of "GET", "POST", "PUT", "DELETE".
 * @param data The name-value pairs which is ready to be sent to server.
 * Supported data types: NSString, NSNumber, NSArray(of supported data types), NSDictionary(of supported data types), NSData, NSURL(to a local file).
 * @param handler The block called when the request completes
 * @param progressHandler The block called with progress updates for uploading data
 */
- (void)sendRequest:(NSString *)url
             method:(NSString *)method
               data:(NSDictionary *)data
            handler:(APSResponseHandler)handler
           progress:(APSProgressHandler)progressHandler;

@end