/**
 * 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 Photos API lets you upload, resize and manage photos for your application.
 * The REST object of this class contains the following fields:<ul>
 * <li>acls (NSString): Single-element array containing the ACLs associated with this photo object, if any.</li>
 * <li>collections (APSPhotoCollections[]): Single-element array containing the collection this photo is a part of, if any.</li>
 * <li>content_type (NSString): MIME content-type for this photo.</li>
 * <li>created_at (NSString): Creation date for this photo object.</li>
 * <li>custom_fields (NSDictionary): User defined fields. </li>
 * <li>filename (NSString): Filename of the original photo.</li>
 * <li>id (NSString): Generated ID for this photo.</li>
 * <li>md5 (NSString): MD5 hash of the original image data.</li>
 * <li>processed (NSBoolean): True if this photo has been processed and is available for download.</li>
 * <li>ratings_average (NSNumber): Average rating for this object. </li>
 * <li>ratings_count (NSNumber): Total number of reviews for this object that include a rating. </li>
 * <li>ratings_summary (NSDictionary): Breakdown of the number of reviews that specified a given rating value. </li>
 * <li>reviews (APSReviews[]): List of reviews for this object. </li>
 * <li>reviews_count (NSNumber): Total number of reviews for this object. </li>
 * <li>size (NSNumber): Original image size in bytes.</li>
 * <li>tags (NSString[]): List of tags for this photo.</li>
 * <li>title (NSString): Photo title, if specified.</li>
 * <li>updated_at (NSString): Last update time for this photo object.</li>
 * <li>urls (NSDictionary): A hash containing image URLs for the photo at different sizes. </li>
 * <li>user (APSUsers): User object for the photo's owner.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Photos).
 */

@interface APSPhotos : NSObject




/**
 * Create a photo using the given photo binary attachment. 
 *
 * 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/Photos-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo (NSURL/NSData): The attached binary file. (required)</li>
 * <li>title (NSString): Photo title.</li>
 * <li>collection_name (NSString): Name of the PhotoCollections to add this photo to.</li>
 * <li>collection_id (NSString): ID of the PhotoCollections to add this photo to.</li>
 * <li>tags (NSString): Comma separated list of tags to associate with this photo.</li>
 * <li>custom_fields (NSDictionary): User-defined fields to add to this photo.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this photo object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this photo object.</li>
 * <li>user_id (NSString): User ID to create the photo on behalf of.</li>
 * <li>photo_sizes (NSString/NSDictionary): User-defined photo sizes.</li>
 * <li>photo_sync_sizes[]: Synchronous photo sizes to upload.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): Single-element array containing the newly-created photo object.</li>
 * </ul>
 */

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


/**
 * Create a photo using the given photo binary attachment. 
 *
 * 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/Photos-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo (NSURL/NSData): The attached binary file. (required)</li>
 * <li>title (NSString): Photo title.</li>
 * <li>collection_name (NSString): Name of the PhotoCollections to add this photo to.</li>
 * <li>collection_id (NSString): ID of the PhotoCollections to add this photo to.</li>
 * <li>tags (NSString): Comma separated list of tags to associate with this photo.</li>
 * <li>custom_fields (NSDictionary): User-defined fields to add to this photo.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this photo object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this photo object.</li>
 * <li>user_id (NSString): User ID to create the photo on behalf of.</li>
 * <li>photo_sizes (NSString/NSDictionary): User-defined photo sizes.</li>
 * <li>photo_sync_sizes[]: Synchronous photo sizes to upload.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): Single-element array containing the newly-created photo object.</li>
 * </ul>
 * @param progressHandler Callback to handle the progress of the request. See the Callback section in APSClient.
 */

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




/**
 * Returns the information for the identified photo. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Photos-method-show).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo_id (NSString): ID of the photo to show. (required)</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response JSON.</li>
 * <li>show_user_like (NSBoolean): If set to true the Photo object in the response will include "current_user_liked: true" if the current user has liked the object.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): Single-element array containing the identified photo.</li>
 * </ul>
 */

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




/**
 * Searches for photos with sorting and paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Photos-method-search).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</li>
 * <li>limit (NSNumber): Instead of using page and per_page for pagination, you can use limit and skip to do your own pagination.</li>
 * <li>skip (NSNumber): Number of records to skip.</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response JSON.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): List of photos matching the search parameters.</li>
 * </ul>
 */

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




/**
 * Perform custom query of photos with sorting and paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Photos-method-query).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</li>
 * <li>limit (NSNumber): Instead of using page and per_page for pagination, you can use limit and skip to do your own pagination.</li>
 * <li>skip (NSNumber): Number of records to skip.</li>
 * <li>where (NSDictionary): Constraint values for fields.</li>
 * <li>order (NSString): Sort results by one or more fields.</li>
 * <li>sel (NSDictionary): Selects the object fields to display.</li>
 * <li>show_user_like (NSBoolean): If set to true, each Photo object in the response includes "current_user_liked: true"  if the current user has liked the object.</li>
 * <li>unsel (NSDictionary): Selects the object fields NOT to display.</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response json.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): List of photos matching the query parameters.</li>
 * </ul>
 */

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




/**
 * Updates the photo attachment, the collection that the photo belongs to, or other photo properties. 
 *
 * 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/Photos-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo_id (NSString): ID of the photo to update. (required)</li>
 * <li>photo (NSURL/NSData): New photo to associate with this object, attached as a binary file. (required)</li>
 * <li>title (NSString): Photo title.</li>
 * <li>collection_name (NSString): Name of the PhotoCollections to add this photo to.</li>
 * <li>collection_id (NSString): ID of the PhotoCollections to add this photo to.</li>
 * <li>tags (NSString): Comma separated list of tags to associate with this photo.</li>
 * <li>custom_fields (NSDictionary): User-defined fields to add to this photo.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this photo object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this photo object.</li>
 * <li>photo_sizes (NSString/NSDictionary): User-defined photo sizes.</li>
 * <li>photo_sync_sizes: Synchronous photo sizes to upload.</li>
 * <li>user_id (NSString): User ID to update the Photo object on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): Single-element array containing the updated  photo.</li>
 * </ul>
 */

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


/**
 * Updates the photo attachment, the collection that the photo belongs to, or other photo properties. 
 *
 * 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/Photos-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo_id (NSString): ID of the photo to update. (required)</li>
 * <li>photo (NSURL/NSData): New photo to associate with this object, attached as a binary file. (required)</li>
 * <li>title (NSString): Photo title.</li>
 * <li>collection_name (NSString): Name of the PhotoCollections to add this photo to.</li>
 * <li>collection_id (NSString): ID of the PhotoCollections to add this photo to.</li>
 * <li>tags (NSString): Comma separated list of tags to associate with this photo.</li>
 * <li>custom_fields (NSDictionary): User-defined fields to add to this photo.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this photo object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this photo object.</li>
 * <li>photo_sizes (NSString/NSDictionary): User-defined photo sizes.</li>
 * <li>photo_sync_sizes: Synchronous photo sizes to upload.</li>
 * <li>user_id (NSString): User ID to update the Photo object on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>photos (APSPhotos[]): Single-element array containing the updated  photo.</li>
 * </ul>
 * @param progressHandler Callback to handle the progress of the request. See the Callback section in APSClient.
 */

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




/**
 * Deletes a photo to which you have update access. 
 *
 * 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/Photos-method-delete).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>photo_id (NSString): ID of the photo to delete. (required)</li>
 * <li>user_id (NSString): User ID to delete the Photo object on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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



@end