/*
 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. 
 */

//
//  MKFacebook.h
//  MKAbeFook
//
//  Created by Mike on 10/11/06.
//  Copyright 2006 Mike Kinney. All rights reserved.
//
//  Modified by Josh Wiseman (Facebook, Inc.) on 1/24/07
//

#import <Cocoa/Cocoa.h>

@class MKLoginWindow;

extern NSString* const MKErrorConnection;   // if the connection has a problem
extern NSString* const MKErrorCancelled;    // if the user cancelled the operation
extern NSString* const MKErrorMissingParam; // if the request is missing a required parameter
extern NSString* const MKErrorXMLParsing;   // if the response wasn't valid XML
extern NSString* const MKErrorAPISchema;    // if the response didn't match the API schema
extern NSString* const MKErrorAPIOperation; // if the response was an API error
extern NSString* const MKFacebookAPIVersion;
extern NSString* const MKLoginUrl;
extern NSString* const MKAPIServerURL;
extern NSString* const MKAPISecureServerURL;

/*!
	@class MKFacebook
	@abstract Handles Facebook login, generates URL requests, and returns XML.
	@discussion MKFacebook is used to login, prepare and make requests to the Facebook REST server.

*/
@interface MKFacebook : NSObject {
	
	NSString *defaultsName;
	
	MKLoginWindow *loginWindow;
	//MKLoginWindow *loginWindowForSheet;
	NSString *apiKey;
	NSString *secretKey;
	NSString *authToken;
	NSString *sessionKey;
	NSString *sessionSecret;
	NSString *uid;
	NSString *MD5;
	BOOL hasAuthToken;
	BOOL hasSessionKey;
	BOOL hasSessionSecret;
	BOOL hasUid;
	BOOL userCancelledLogin;
	
	// API connection state
	BOOL receiveFinished;
	BOOL requestCancelled;
	NSMutableData *receivedData;
	NSString *requestError;			// set to one of the above error strings, or nil
	NSString *errorMethod;		    // if we had MKErrorMissingParam
	NSData *errorData;			    // if we had MKErrorXMLParsing
	NSXMLDocument *errorXML;	    // if we had MKErrorAPISchema
	NSDictionary *errorDictionary; // if we had MKErrorAPIOperation
	BOOL debug;
}

/*!
	@method facebookWithAPIKey:withSecret
	@discussion Returned MKFacebook is autoreleased, needs to be retained upon creation.
 
	Example: MKFacebook *newFacebook = [[MKFacebook facebookWithAPIKey:yourKey 
															withSecret:yourSecret]retain];
	
	@param apiKey Unique API key provided by Facebook upon registration
	@param secretKey Unique Secret Key provided by Facebook upon registration
	@result Returns new MKFacebook prepared with appropriate API Key and Secret Key.
*/
+(MKFacebook *)facebookWithAPIKey:(NSString *)apiKey withSecret:(NSString *)secretKey withDefaultsName:(NSString *)name;

/*!
	@method initUsingAPIKey:apiKey:usingSecret
	@abstract Prepares MKFacebook for login.
	@param anAPI Unique API Key provided by Facebook upon registration.
	@param aSecret Unique Secret Key provided by Facebook upon registration.
	@result New instance of MKFacebook.
*/
-(MKFacebook *)initUsingAPIKey:(NSString *)anApi usingSecret:(NSString *)aSecret withDefaultsName:(NSString *)name;

//needed for generating url requests
/*!
     @method apiKey
	 @abstract Returns apiKey as specified when MKFacebook object is created.
	 @result NSString
 */
-(NSString *)apiKey;

-(BOOL)loadPersistentSession;
-(NSString *)sessionKey;
-(NSString *)generateSigWithParameters:(NSDictionary *)parameters;
-(NSString *)generateTimeStamp;

/*!
	@method uid
	 @abstract Returns uid of logged in user, empty string if no user is logged in.
	 @result NSString
*/
-(NSString *)uid;

/*!
	 @method userLoggedIn
	 @abstract Attempts to verify if a user is logged in.
	 @discussion Returns true if valid there is a valid authToken, sessionKey, sessionSecret, and uid.  This is not a guaranteed
     way to verify a user is logged in.  This method might return true if the users session has timed out.  Use sessionPing to verify
     the users session is still active.
	 @result BOOL
*/
-(BOOL)userLoggedIn;

/*!
	 @method resetFacebookConnection
	 @abstract Resets all instance variables indicating no user is logged in.
	 @discussion Use this before logging in a different user or if sessionPing returns 0 to safely prepare for a new login.
*/
-(void)resetFacebookConnection;


//Login Window
-(BOOL)getAuthSession:(NSNotification *)aNotification;
/*!
	@method showFacebookLoginWindow
	@abstract Attempts to display Facebook login window.
	@discussion Attempts to create an authToken and display login window.  If no authToken is successfully created
	a login window will not be displayed and no error message will be displayed.  The login window 
	will post a notification named UserLoggedIn when the window is closed. The application that called
	showFacebookLoginWindow must have a notification center set up to accept a message from UserLoggedIn.
	See example applications on how to handle logging in a user.
*/
-(void)showFacebookLoginBrowser;
-(void)showFacebookLoginWindow;

/*!
	@method showFacebookLoginWindowAsSheet
	@discussion Generates a Facebook login window intended to be attatched to a window as a sheet.  A close window button
    will automatically be added that will handle closing the sheet.
	@result Returns NSWindow that can be attached as a sheet.
*/
-(NSWindow *)showFacebookLoginWindowForSheet;






@end
