/*
 Copyright (c) 2006, Mike Kinney
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 
 following conditions are met:
 
 * Redistributions of source code must retain the above copyright notice, this list of conditions and the 
 following disclaimer.
 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the 
 following disclaimer in the documentation and/or other materials provided with the distribution.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 
 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
 */
//
//  MKFacebookMethods.m
//  MKAbeFook
//
//  Created by Mike on 11/27/06.
//  Copyright 2006 Mike Kinney. All rights reserved.
//
//  Modified by Josh Wiseman (Facebook, Inc.) on 1/24/07
//

#import "MKFacebook.h"
/*!
@category MKFacebook(MKFacebookMethods)
*/

@interface MKFacebook (MKFacebookMethods) 

//helper methods

-(NSXMLDocument *)XMLForArgString:(NSString *)argString useSecureServer:(BOOL)useSecureServer;
-(NSXMLDocument *)XMLForArgString:(NSString *)argString;
-(NSXMLDocument *)XMLForMethod:(NSString *)method arguments:(NSDictionary *)arguments;

	/*!
	@method requestError
	 @result Returns a string describing the last request error, or nil if no error has occurred.  See MKFacebook.h for the list of error strings.
	 */
-(NSString *)requestError;

	/*!
	@method errorMethod
	 @result If the last Facebook API request had a missing param, returns the method name.  Only valid if requestError is MKErrorMissingParam.
	 */
-(NSString *)errorMethod;

	/*!
	@method errorData
	 @result If the last Facebook API response couldn't be parsed into XML, returns the raw response data, otherwise returns nil.  Only valid if requestError is MKErrorXMLParsing.
	 */
-(NSData *)errorData;

	/*!
	@method errorXML
	 @result If the last Facebook API response didn't match the Facebook XML schema, returns the response in XML form, otherwise returns nil.  Only valid if requestError is MKErrorXMLSchema.
	 */
-(NSXMLDocument *)errorXML;

	/*!
	@method errorDictionary
	 @result If the last Facebook API response was an API error, returns the response as a parsed dictionary with the keys 'error_code' and 'error_msg' set, otherwise returns nil.  Only valid if requestError is MKErrorAPIOperation.
	 */
-(NSDictionary *)errorDictionary;

	/*!
	@method shouldDebug:
	 @param shouldDebug Whether to print to console the details of any request errors.
	 */
-(void)setDebug:(BOOL)shouldDebug;

	/*!
	@method printErrorData
	 @abstract Prints to console the details of the error that occurred during the last API request, if an error occurred.  Otherwise does nothing.
	 */
-(void)printErrorData;

	/*!
	@method setMissingParamError
	 @abstract Sets the error to MKErrorMissingParam for the given method
	 @param method The method name
	 */
-(void)setMissingParamError:(NSString *)method;

	/*!
	@method cancelRequest
	 @abstract Cancels an API request.
	 @discussion Cancels an API request.  Must be called from a separate thread than the one that intiated the request.  Note: Currently, this only works for photo upload requests.
	 */
-(void)cancelRequest;

// facebook methods

// events

	/*!
	@method facebookEventsGetXML:eids:startTime:endTime:
	 @abstract Returns all visible events according to the filters specified.
	 @param userID Filter by events associated with a user with this uid.  Can be nil.
	 @param eids Filter by this list of events ids.  Can be nil.
	 @param startTime Filter with this UTC as lower bound.  Can be 0 to ignore.
	 @param endTime Filter with this UTC as upper bound. Can be 0 to ignore.
	 @result Returns XML generated by Facebook method facebook.events.getInWindow
	 */
-(NSXMLDocument *)facebookEventsGetXML:(NSString *)userID eids:(NSArray *)eids startTime:(int)startTime endTime:(int)endTime;

	/*!
	@method facebookEventsGetMembers:
	 @abstract Returns membership list data associated with an event.
	 @param eid Event id
	 @result Returns XML generated by Facebook method facebook.events.getMembers
	 */
-(NSXMLDocument *)facebookEventsGetMembersXML:(NSString *)eid;

// friends

	/*!
	@method facebookFriendsAreFriendsXML:id1:id2
	 @abstract Returns whether or not each pair of specified users is friends with each other.
	 @param uids1 Array of identifiers
	 @param uids2 Array of identifiers
	 @result Returns XML generated by Facebook method facebook.friends.areFriends
	 */
-(NSXMLDocument *)facebookFriendsAreFriendsXML:(NSArray *)uids1 uids2:(NSArray *)uids2;

	/*!
	@method facebookFriendsGetXML
	 @abstract Returns the identifiers of the current user's Facebook friends.
	 @result Returns XML generated by Facebook method facebook.friends.get
	 */
-(NSXMLDocument *)facebookFriendsGetXML;

	/*!
	@method facebookFriendsGetAppUsersXML
	 @abstract Returns the identifiers of the current user's Facebook friends who are signed up for this application.
	 @result Returns XML generated by Facebook method facebook.friends.GetAppUsers
	 */
-(NSXMLDocument *)facebookFriendsGetAppUsersXML;

// groups

	/*!
	@method facebookGroupsGet:gids:
	 @abstract Returns all visible groups according to the filters specified.
	 @param userID Filter by groups associated with user id. Can be nil.
	 @param gids Filter by this list of group ids. Can be nil.
	 @result Returns XML generated by Facebook method facebook.groups.get
	 */
-(NSXMLDocument *)facebookGroupsGetXML:(NSString *)userID gids:(NSArray *)gids;

	/*!
	@method facebookGroupsGetMembers:
	 @abstract Returns membership list data associated with a group.
	 @param gid Group id
	 @result Returns XML generated by Facebook method facebook.groups.getMembers
	 */
-(NSXMLDocument *)facebookGroupsGetMembersXML:(NSString *)gid;

// notifications

	/*!
	@method facebookNotificationsGetXML
	 @abstract Returns information on outstanding Facebook notifications for current session user.
	 @result Returns XML generated by Facebook method facebook.notifications.get
	 */
-(NSXMLDocument *)facebookNotificationsGetXML;

// photos

	/*!
	@method facebookPhotosGetXML:aid:pids:
	 @abstract Returns all visible photos according to the filters specified.
	 @param subjID Filter by photos associated with this user.  Can be nil.
	 @param aid Filter by photos in this album.  Can be nil.
	 @param pids Filter by photos in this list.  Can be nil.
	 @result Returns XML generated by Facebook method facebook.photos.get
	 */
-(NSXMLDocument *)facebookPhotosGetXML:(NSString *)subjID aid:(NSString *)aid pids:(NSArray *)pids;

	/*!
	 @method facebookPhotosGetAlbumsXML:ID
	 @abstract Returns metadata about all of the photo albums uploaded by the specified user.
	 @param userID Return albums created by this user.  Can be nil.
	 @param pids Return albums with aids in this list.  Can be nil.
	 @result Returns XML generated by Facebook method facebook.photos.getAlbums
	 */
-(NSXMLDocument *)facebookPhotosGetAlbumsXML:(NSString *)userID pids:(NSArray *)pids;

	/*!
	@method facebookPhotosGetTagsXML
	 @abstract Returns the set of user tags of all photos specified.
	 @param pids The list of photos from which to extract photo tags.
	 @result Returns XML generated by Facebook method facebook.photos.getTags
	 */
-(NSXMLDocument *)facebookPhotosGetTagsXML:(NSArray *)pids;

// users

	/*!
	@method facebookUsersGetInfoXML:users:fields
	 @abstract Returns a wide array of user-specific information for each user id passed, limited by the view of the current user.
	 @param uids List of user ids.
	 @param fields List of desired fields in return.  See official Facebook documentation
	 for valid field names.
	 @result Returns XML generated by Facebook method facebook.users.getInfo
	 */
-(NSXMLDocument *)facebookUsersGetInfoXML:(NSArray *)uids fields:(NSArray *)fields;

	/*!
	@method facebookUsersGetLoggedInUserXML
	 @abstract Getes the user id associated with the current session.
	 @result Returns XML generated by Facebook method facebook.users.getLoggedInUser
	 */
-(NSXMLDocument *)facebookUsersGetLoggedInUserXML;

// upload
	 
	/*!
	@method facebookPhotosCreateAlbumXML:name:description:location
	 @abstract Creates a new Facebook album with the given information.
	 @param name Name of album
	 @param description Description of album. Can be nil.
	 @param location Location of album. Can be nil.
	 @result Return XML generated by Facebook method facebook.photos.createAlbum
	*/
-(NSXMLDocument *)facebookPhotosCreateAlbumXML:(NSString *)name description:(NSString *)desc location:(NSString *)location;

	/*!
	@method facebookPhotosAddTagXML:tagUID:tagText:x:y
	 @abstract Adds a tag with the given information to the photo with the given pid.
	 @param pid Picture ID
	 @param tagUID User ID of tagged friend (nil if just using text)
	 @param tagText Name of tagged friend
	 @param x Horizontal position of tagged friend (0-100% from left)
	 @param y Veritcal position of tagged friend (0-100% from top)
	 @result Returns XML generated by Facebook method facebook.photos.addTag
	*/
-(NSXMLDocument *)facebookPhotosAddTagXML:(NSString *)pid tagUID:(NSString *)tagUID tagText:(NSString *)tagText x:(NSString *)x y:(NSString *)y;

	/*!
	@method facebookPhotosUploadXML:fileName:aid:caption
	 @abstract Uploads the given data as a photo to the specified album.
	 @param data Raw data of file to upload
	 @param fileName File name to use when uploading
	 @param aid Album ID of target album
	 @param caption Caption for photo. Can be nil.
	 @result Returns XML generated by Facebook method facebook.photo.upload
	*/
-(NSXMLDocument *)facebookPhotosUploadXML:(NSData *)data fileName:(NSString *)fileName aid:(NSString *)aid caption:(NSString *)caption;


@end
