/**
 * 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 Events API provides methods to create and manage events.
 * The REST object of this class contains the following fields:<ul>
 * <li>acls (APSACLs[]): Array of ACLs associated with this object.</li>
 * <li>created_at (NSString): Event creation timestamp.</li>
 * <li>custom_fields (NSDictionary): User defined fields. </li>
 * <li>details (NSString): Description of the event.</li>
 * <li>duration (NSNumber): Event duration, in seconds.</li>
 * <li>ical (NSString): Event time and recurrence in iCalendar (RFC 5545) format.</li>
 * <li>id (NSString): Generated unique ID for this event.</li>
 * <li>name (NSString): Event name.</li>
 * <li>photo (APSPhotos): Primary photo for the event.</li>
 * <li>place (APSPlaces): Event location.</li>
 * <li>recurring (NSString): Recurrence schedule. </li>
 * <li>recurring_count (NSNumber): Number of occurrences for the event.</li>
 * <li>recurring_until (NSString): Date of last recurrence.</li>
 * <li>start_time (NSString): Event start time.</li>
 * <li>tags (NSString[]): Array of tags associated with this event.</li>
 * <li>updated_at (NSString): Event modification timestamp.</li>
 * <li>user (APSUsers): Event owner.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events).
 */

@interface APSEvents : NSObject




/**
 * Create an event. 
 *
 * 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/Events-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Event name. (required)</li>
 * <li>start_time (NSString): Event start time. (required)</li>
 * <li>details (NSString): Description of the event.</li>
 * <li>duration (NSNumber): Event duration, in seconds.</li>
 * <li>ical (NSString): Event time and recurrance in iCalendar (RFC 5545) format.</li>
 * <li>recurring (NSString): Recurrance schedule.</li>
 * <li>recurring_count (NSNumber): Number of occurrences for the event.</li>
 * <li>recurring_until (NSString): Date of last recurrance.</li>
 * <li>user (APSUsers): Event owner.</li>
 * <li>place_id (NSString): ID for the Places where the event takes place.</li>
 * <li>photo (APSPhotos): New photo to attach as the primary photo for the event.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach as the primary photo for the event.</li>
 * <li>tags (NSString): Comma separated list of tags for this event.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this event.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this event.</li>
 * <li>tags (NSString): Comma-separated list of tags associated with this event.</li>
 * <li>user_id (NSString): User ID to create the event 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>events (APSEvents[]): Single-element array containing the newly-created event.</li>
 * </ul>
 */

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


/**
 * Create an event. 
 *
 * 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/Events-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Event name. (required)</li>
 * <li>start_time (NSString): Event start time. (required)</li>
 * <li>details (NSString): Description of the event.</li>
 * <li>duration (NSNumber): Event duration, in seconds.</li>
 * <li>ical (NSString): Event time and recurrance in iCalendar (RFC 5545) format.</li>
 * <li>recurring (NSString): Recurrance schedule.</li>
 * <li>recurring_count (NSNumber): Number of occurrences for the event.</li>
 * <li>recurring_until (NSString): Date of last recurrance.</li>
 * <li>user (APSUsers): Event owner.</li>
 * <li>place_id (NSString): ID for the Places where the event takes place.</li>
 * <li>photo (APSPhotos): New photo to attach as the primary photo for the event.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach as the primary photo for the event.</li>
 * <li>tags (NSString): Comma separated list of tags for this event.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this event.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this event.</li>
 * <li>tags (NSString): Comma-separated list of tags associated with this event.</li>
 * <li>user_id (NSString): User ID to create the event 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>events (APSEvents[]): Single-element array containing the newly-created event.</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;




/**
 * Show event(s) with the given IDs. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-method-show).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>event_id (NSString): ID of the event to delete.</li>
 * <li>event_ids (NSString): Comma-separated list of event IDs to show.</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 Event 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>events (APSEvents[]): List of events.</li>
 * </ul>
 */

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




/**
 * Show the event occurrences of an event with the given event_id. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-method-show_occurrences).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>event_id (NSString): ID of the event to show occurrences of. (required)</li>
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</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.
 */

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




/**
 * Perform custom query of events with sorting and paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-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 Event 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.
 */

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




/**
 * Perform custom query of event occurrences with sorting and paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-method-query_occurrences).
 * @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>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.
 */

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




/**
 * Full text search of events. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-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>place_id (NSString): Restrict search results to events located in the identified Places.</li>
 * <li>user_id (NSString): Restrict search results to events owned by the identified Users.</li>
 * <li>latitude (NSNumber): Latitude of the search starting point.</li>
 * <li>longitude (NSNumber): Longitude of the search starting point.</li>
 * <li>distance (NSNumber): Maximum distance in km from the starting point identified by longitude, latitude`.</li>
 * <li>start_time (NSString): Only return events that start on or after start_time.</li>
 * <li>q: Space-separated list of keywords, used to perform full text search on event name and tags.</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>events (APSEvents[]): List of events matching the search results.</li>
 * </ul>
 */

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




/**
 * Full text search of event occurrences. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Events-method-search_occurrences).
 * @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>place_id (NSString): Restrict search results to events located in the identified Places.</li>
 * <li>user_id (NSString): Restrict search results to events owned by the identified Users.</li>
 * <li>latitude (NSNumber): Latitude of the search starting point.</li>
 * <li>longitude (NSNumber): Longitude of the search starting point.</li>
 * <li>distance (NSNumber): Maximum distance in km from the starting point identified by longitude, latitude`.</li>
 * <li>start_time (NSString): Only return events that start on or after start_time.</li>
 * <li>end_time (NSString): Only return events that end on or before end_time.</li>
 * <li>q: Space-separated list of keywords, used to perform full text search on event name and tags.</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>events (APSEvents[]): List of events matching the search results.</li>
 * </ul>
 */

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




/**
 * Update the event with the given id. 
 *
 * 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/Events-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>event_id (NSString): ID of the event to update. (required)</li>
 * <li>name (NSString): Updated event name.</li>
 * <li>start_time (NSString): Updated event start time.</li>
 * <li>duration (NSNumber): Updated event duration, in seconds.</li>
 * <li>recurring (NSString): New recurrance schedule.</li>
 * <li>recurring_count (NSNumber): Updated number of occurrences for the event.</li>
 * <li>recurring_until (NSString): Updated date of last recurrance.</li>
 * <li>details (NSString): Updated description of the event.</li>
 * <li>place_id (APSPlaces): ID of the place where this event takes place.</li>
 * <li>photo (APSPhotos): New photo to assign as the event's primary photo.</li>
 * <li>photo_id (NSString): ID of an existing photo to use as the event's primary photo.</li>
 * <li>tags (NSString): Comma-separated list of tags associated with this event.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this checkin object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this checkin object.</li>
 * <li>user_id (NSString): User to update the Event 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>events (APSEvents[]): Single-element array containing the updated event object.</li>
 * </ul>
 */

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


/**
 * Update the event with the given id. 
 *
 * 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/Events-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>event_id (NSString): ID of the event to update. (required)</li>
 * <li>name (NSString): Updated event name.</li>
 * <li>start_time (NSString): Updated event start time.</li>
 * <li>duration (NSNumber): Updated event duration, in seconds.</li>
 * <li>recurring (NSString): New recurrance schedule.</li>
 * <li>recurring_count (NSNumber): Updated number of occurrences for the event.</li>
 * <li>recurring_until (NSString): Updated date of last recurrance.</li>
 * <li>details (NSString): Updated description of the event.</li>
 * <li>place_id (APSPlaces): ID of the place where this event takes place.</li>
 * <li>photo (APSPhotos): New photo to assign as the event's primary photo.</li>
 * <li>photo_id (NSString): ID of an existing photo to use as the event's primary photo.</li>
 * <li>tags (NSString): Comma-separated list of tags associated with this event.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this checkin object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this checkin object.</li>
 * <li>user_id (NSString): User to update the Event 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>events (APSEvents[]): Single-element array containing the updated event object.</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;




/**
 * Delete the event with the given id. 
 *
 * 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/Events-method-delete).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>event_id (NSString): ID of the event to delete. (required)</li>
 * <li>user_id (NSString): User to delete the Event 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