/**
 * 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>
#import "APSCloud.h"


/**
 * The KeyValues API provides methods to store and retrieve string or binary data up to 2MB.
 * The REST object of this class contains the following fields:<ul>
 * <li>id (NSString): Generated ID for this key-value pair.</li>
 * <li>name (NSString): Name (or key) for this key-value pair.</li>
 * <li>type (NSString): Value type: "string" or "binary". </li>
 * <li>value (NSString/NSURL/NSData): String or binary data.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues).
 */

@interface APSKeyValues : NSObject




/**
 * Sets a string or binary value referenced by the key name. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-set).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): The name, or key, for this key-value pair. (required)</li>
 * <li>type (NSString): Value type: "string" or "binary".</li>
 * <li>value (NSString/NSURL/NSData): Value to assoicate with the key. (required)</li>
 * <li>access_private (NSBoolean): Determines whether this key-value is publically readable, or stored in a private store.</li>
 * <li>user_id (NSString): User to create the key-value pair on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)set:(NSDictionary *)data withBlock:(APSResponseHandler)handler;


/**
 * Sets a string or binary value referenced by the key name. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-set).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): The name, or key, for this key-value pair. (required)</li>
 * <li>type (NSString): Value type: "string" or "binary".</li>
 * <li>value (NSString/NSURL/NSData): Value to assoicate with the key. (required)</li>
 * <li>access_private (NSBoolean): Determines whether this key-value is publically readable, or stored in a private store.</li>
 * <li>user_id (NSString): User to create the key-value pair on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * @param progressHandler Callback to handle the progress of the request. See the Callback section in APSClient.
 */

+ (void)set:(NSDictionary *)data withBlock:(APSResponseHandler)handler progressBlock:(APSProgressHandler)progressHandler;




/**
 * Gets the value of a key-value pair. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-get).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Name (or key) for the key-value pair to retrieve. (required)</li>
 * <li>access_private (NSBoolean): Determines whether to retrieve this key-value from the publically readable store or from the user's private store.</li>
 * <li>user_id (NSString): Retrieve a private key-value pair from the identified user's store.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)get:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Add the given value to end of the existing one. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-append).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Name (or key) for the key-value pair. (required)</li>
 * <li>value (NSString): Value to append to the current value. (required)</li>
 * <li>access_private (NSBoolean): Determines whether to update this key-value in the publically readable store or in the user's private store.</li>
 * <li>user_id (NSString): Update the key-value pair on behalf of the identified user.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)append:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Increment the value by the given integer value. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-incrby).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Name (or key) for the key-value pair. (required)</li>
 * <li>value (NSString/NSNumber): Integer value to add to the current value. (required)</li>
 * <li>access_private (NSBoolean): Determines whether to update this key-value in the publically readable store or in the user's private store.</li>
 * <li>user_id (NSString): Update the key-value pair on behalf of the identified user.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)increment:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Deletes a key-value pair 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/KeyValues-method-delete).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Name (or key) of the key-value pair to delete. (required)</li>
 * <li>access_private (NSBoolean): Determines whether to delete this key-value in the publically readable store or in the user's private store.</li>
 * <li>user_id (NSString): Delete the key-value pair on behalf of the identified user.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)remove:(NSDictionary *)data withBlock:(APSResponseHandler)handler;



@end