rfacebook 0.9.1 → 0.9.2

data/README

@@ -38,5 +38,4 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 
 Some code was inspired by techniques used in Alpha Chen's old client.
-Some code was ported from the official PHP5 client.
 

data/lib/facebook_desktop_session.rb

@@ -32,10 +32,35 @@ require "facebook_session"
 module RFacebook
 
 class FacebookDesktopSession < FacebookSession
+
+  ################################################################################################
+  ################################################################################################
+  # :section: Properties
+  ################################################################################################
+  
+  attr_reader :session_secret # you should need this for infinite desktop sessions
+  
+  ################################################################################################
+  ################################################################################################
+  # :section: Initialization
+  ################################################################################################
+  
+  # Function: initialize
+  #   Constructs a FacebookDesktopSession.  Also calls the API to grab an auth_token.
+  #
+  # Parameters:
+  #   api_key                   - your API key
+  #   api_secret                - your API secret
+  #   options.suppress_errors   - boolean, set to true if you don't want errors to be thrown (defaults to false)
+  def initialize(api_key, api_secret, suppress_errors = false)
+    super(api_key, api_secret, suppress_errors)
+    @desktop_auth_token = get_auth_token
+  end
   
-  # you'll need to access session_secret (in addition to the session_key) to be able to
-  # call "activate_with_previous_session" when using infinite sessions
-  attr_reader :session_secret
+  ################################################################################################
+  ################################################################################################
+  # :section: URL Accessors
+  ################################################################################################
   
   # Function: get_login_url
   #   Gets the authentication URL
@@ -62,22 +87,20 @@ class FacebookDesktopSession < FacebookSession
     return "http://#{WWW_SERVER_BASE_URL}#{WWW_PATH_LOGIN}?v=1.0&api_key=#{@api_key}&auth_token=#{@desktop_auth_token}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
   end
   
+  ################################################################################################
+  ################################################################################################
+  # :section: Session Activation
+  ################################################################################################
   
-  # Function: initialize
-  #   Constructs a FacebookSession
-  #
-  # Parameters:
-  #   api_key                       - your API key
-  #   api_secret                    - your API secret
-  #   desktop                       - boolean, whether this is a desktop client or not (defaults to false)
-  #   options.suppress_exceptions   - boolean, set to true if you don't want exceptions to be thrown (defaults to false)
-  def initialize(api_key, api_secret, suppress_exceptions = false)
-    super(api_key, api_secret, suppress_exceptions)
-    @desktop_auth_token = get_auth_token
-  end
-  
+  # Function: activate
+  #   Use the internal auth_token to activate
   def activate
-    activate_with_token(@desktop_auth_token)
+    result = call_method("auth.getSession", {:auth_token => @desktop_auth_token}, true)
+    if result != nil
+      @session_user_id = result.at("uid").inner_html
+      @session_key = result.at("session_key").inner_html
+      @session_secret = result.at("secret").inner_html
+    end
   end
   
   # Function: activate_with_previous_session
@@ -85,6 +108,7 @@ class FacebookDesktopSession < FacebookSession
   # 
   # Parameters:
   #   key    - the session key to use
+  #   secret - the session secret to use
   def activate_with_previous_session(key, secret)
     # set the session key and secret
     @session_key = key
@@ -95,50 +119,33 @@ class FacebookDesktopSession < FacebookSession
     @session_user_id = result.at("users_getLoggedInUser_response").inner_html
   end
   
-  def is_valid?
-    return (is_activated? and !session_expired?)
-  end
-  
-  def session_user_id
-    return @session_user_id
-  end
-  
-  def session_key
-    return @session_key
-  end
-  
   protected
   
-  def is_activated?
-    return (@session_key != nil and @session_secret != nil)
-  end
-  
-  # Function: activate_with_token
-  #   Gets the session information available after current user logs in.
-  # 
-  # Parameters:
-  #   auth_token    - string token returned by auth.createToken (see: <get_auth_token>)
-  def activate_with_token(auth_token)
-    result = call_method("auth.getSession", {:auth_token => auth_token}, true)
-    if result != nil
-      @session_user_id = result.at("uid").inner_html
-      @session_key = result.at("session_key").inner_html
-      @session_secret = result.at("secret").inner_html
-    end
-    return result
-  end
-  
   # Function: auth_createToken
   #   Returns a string auth_token
-  def get_auth_token
+  def get_auth_token # :nodoc:
     result = call_method("auth.createToken", {})
     result = result.at("auth_createToken_response").inner_html.to_s ||= result.at("auth_createToken_response").inner_html.to_s
     return result
   end
   
+  
+  ################################################################################################
+  ################################################################################################
+  # :section: Template Methods
+  ################################################################################################
+    
+  # Function: is_activated?
+  #   Returns true when we have activated ourselves somehow
+  def is_activated?
+    return (@session_key != nil and @session_secret != nil)
+  end
+  
   # Function: get_secret
-  #   Template method, used by super::signature to generate a signature
-  def get_secret(params)
+  #   Used by super::signature to generate a signature.
+  #   Desktop sessions should use their session_secret rather than the api_secret
+  #   for any calls other than the call to createToken and getSession
+  def get_secret(params) # :nodoc:
     
     if ( params[:method] != "facebook.auth.getSession" and params[:method] != "facebook.auth.createToken")
       return @session_secret

data/lib/facebook_session.rb

@@ -29,7 +29,6 @@
 
 #
 # Some code was inspired by techniques used in Alpha Chen's old client.
-# Some code was ported from the official PHP5 client.
 #
 
 require "digest/md5"
@@ -49,111 +48,123 @@ WWW_PATH_INSTALL          = "/install.php"
 
 class FacebookSession
   
-  # error handling accessors
-  attr_reader :last_call_was_successful, :last_error
-  attr_writer :suppress_exceptions
-  
-  # SECTION: StandardErrors
+  ################################################################################################
+  ################################################################################################
+  # :section: Errors
+  ################################################################################################
     
   class RemoteStandardError < StandardError; end
   class ExpiredSessionStandardError < StandardError; end
   class NotActivatedStandardError < StandardError; end
+    
+  ################################################################################################
+  ################################################################################################
+  # :section: Properties
+  ################################################################################################
+  
+  # Property: session_user_id
+  #   The user id of the user associated with this sesssion.
+  attr_reader :session_user_id
+  
+  # Property: session_key
+  #   The key for this session. You will need to save this for infinite sessions.
+  attr_reader :session_key
+  
+  # Property: session_expires
+  #   The expiration time of this session, as given from Facebook API login.
+  attr_reader :session_expires
+  
+  # Property: last_error_message
+  #   Contains a string message of the last error received from Facebook.
+  attr_reader :last_error_message
+  
+  # Property: last_error_code
+  #   Contains an integer code of the last error received from Facebook.
+  attr_reader :last_error_code
+  
+  # Property: suppress_errors
+  #   By default, RFacebook will throw exceptions when errors occur.
+  #   You can set suppress_errors=true to stop these exceptions
+  #   from being thrown.
+  attr_accessor :suppress_errors
+  
+  # Property: logger
+  #   Can be set to any valid logger (for example, RAIL_DEFAULT_LOGGER)
+  attr_accessor :logger
+  
+  # Function: is_activated?
+  #   Returns true when the session has been activated in some way
+  #   THIS IS AN ABSTRACT METHOD (the value is determined differently for Web and Desktop sessions)
+  def is_activated?
+    raise StandardError
+  end
+  
+  # Function: is_expired?
+  #   Returns true when the session has expired
+  def is_expired?
+    # TODO: this should look at the @session_expires as well
+    return (@session_expired == true)
+  end
+  
+  # Function: is_valid?
+  #   Returns true when the session is definitely prepared to make API calls
+  def is_valid?
+    return (is_activated? and !is_expired?)
+  end
   
-  # SECTION: Public Methods  
+  # Function: is_ready?
+  #   alias for is_valid?
+  def is_ready?
+    return is_valid?
+  end
+  
+  ################################################################################################
+  ################################################################################################
+  # :section: Initialization
+  ################################################################################################
   
   # Function: initialize
   #   Constructs a FacebookSession
   #
   # Parameters:
-  #   api_key                       - your API key
-  #   api_secret                    - your API secret
-  #   suppress_exceptions           - boolean, set to true if you don't want exceptions to be thrown (defaults to false)
-  def initialize(api_key, api_secret, suppress_exceptions = false)
+  #   api_key           - your API key
+  #   api_secret        - your API secret
+  #   suppress_errors   - boolean, set to true if you don't want exceptions to be thrown (defaults to false)
+  #
+  def initialize(api_key, api_secret, suppress_errors = false)
     
     # required parameters
     @api_key = api_key
     @api_secret = api_secret
-    
-    # calculated parameters
-    @api_server_base_url = API_SERVER_BASE_URL
-    @api_server_path = API_PATH_REST
         
     # optional parameters
-    @suppress_exceptions = suppress_exceptions
+    @suppress_errors = suppress_errors
     
     # initialize internal state
-    @last_call_was_successful = true
-    @last_error = nil
+    @last_error_message = nil
+    @last_error_code = nil
     @session_expired = false
     
     # cache object for API calls
     @callcache = {}
-    
-    # default to XML formatted responses
-    # @response_format = "XML"
-    
-  end
-  
-  def session_expired?
-    return (@session_expired == true)
-  end
-  
-  def logger
-    return @logger
-  end
-  
-  def logger=(externalLogger)
-    @logger = externalLogger
-  end
-
-  # SECTION: Public Abstract Interface
-
-  def is_valid?
-    raise StandardError
-  end
-  
-  def session_key
-    raise StandardError
-  end
-  
-  def session_user_id
-    raise StandardError
-  end
-  
-  def session_expires
-    raise StandardError
-  end
-  
-  def session_uid # deprecated
-    return session_user_id
+        
   end
-  
-  # def use_json
-  #   @response_format = "JSON"
-  # end
-  # 
-  # def use_xml
-  #   @response_format = "XML"
-  # end
-  
-  # SECTION: Protected Abstract Interface
+      
+  ################################################################################################
+  ################################################################################################
+  # :section: API Calls
+  ################################################################################################
   protected
-  
-  def get_secret(params)
-    raise StandardError
-  end
-  
-  def is_activated?
-    raise StandardError
-  end
-  
-  # SECTION: Protected Concrete Interface
-  
+    
   # Function: method_missing
   #   This allows *any* Facebook method to be called, using the Ruby
   #   mechanism for responding to unimplemented methods.  Basically,
   #   this converts a call to "auth_getSession" to "auth.getSession"
-  #   and does the proper API call using the parameter hash given.  
+  #   and does the proper API call using the parameter hash given.
+  #
+  #   This allows you to call an API method such as facebook.users.getInfo
+  #   by calling "fbsession.users_getInfo"
+  #
   def method_missing(methodSymbol, *params)
     tokens = methodSymbol.to_s.split("_")
     if tokens[0] == "cached"
@@ -163,23 +174,6 @@ class FacebookSession
       return call_method(tokens.join("."), params.first)
     end
   end
-  
-  def cached_call_method(method,params)
-    key = cache_key_for(method,params)
-    @logger.debug "** RFACEBOOK(GEM) - RFacebook::FacebookSession\#cached_call_method - #{method}(#{params.inspect}) - attempting to hit cache" if @logger
-    return @callcache[key] ||= call_method(method,params)
-  end
-  
-  def cache_key_for(method,params)
-    pairs = []
-    params.each do |k,v|
-      if v.is_a?(Array)
-        v = v.join(",")
-      end
-      pairs << "#{k}=#{v}"
-    end
-    return "#{method}(#{pairs.sort.join("...")})".to_sym
-  end
 
   
   # Function: call_method
@@ -189,7 +183,7 @@ class FacebookSession
   #   method              - i.e. "users.getInfo"
   #   params              - hash of key,value pairs for the parameters to this method
   #   use_ssl             - set to true if the call will be made over SSL
-  def call_method(method, params={}, use_ssl=false)
+  def call_method(method, params={}, use_ssl=false) # :nodoc:
 
     @logger.debug "** RFACEBOOK(GEM) - RFacebook::FacebookSession\#call_method - #{method}(#{params.inspect}) - making remote call" if @logger
 
@@ -202,7 +196,7 @@ class FacebookSession
     if (!params)
       params = {}
     end
-    params = params.dup # patch courtesy of Project Agape
+    params = params.dup
     
     # params[:format] ||= @response_format
     params[:method] = "facebook.#{method}"
@@ -220,33 +214,31 @@ class FacebookSession
     # set up the param_signature value in the params
     params[:sig] = param_signature(params)
     
-    # prepare internal state
-    @last_call_was_successful = true
-    
-    # do the request
-    xmlstring = post_request(@api_server_base_url, @api_server_path, method, params, use_ssl)
-    # @logger.debug "** RFACEBOOK(GEM) - RFacebook::FacebookSession\#call_method - #{method}(#{params.inspect}) - raw XML response: #{xmlstring}" if @logger
-    xml = Facepricot.new(xmlstring)
+    # make the remote call and contain the results in a Facepricot XML object
+    rawxml = post_request(params, use_ssl)
+    xml = Facepricot.new(rawxml)
 
     # error checking    
     if xml.at("error_response")
       
       @logger.debug "** RFACEBOOK(GEM) - RFacebook::FacebookSession\#call_method - #{method}(#{params.inspect}) - remote call failed" if @logger
       
-      @last_call_was_successful = false
-      code = xml.at("error_code").inner_html
+      code = xml.at("error_code").inner_html.to_i
       msg = xml.at("error_msg").inner_html
-      @last_error = "ERROR #{code}: #{msg} (#{method.inspect}, #{params.inspect})"
+      @last_error_message = "ERROR #{code}: #{msg} (#{method.inspect}, #{params.inspect})"
       @last_error_code = code
       
       # check to see if this error was an expired session error
-      if code.to_i == 102
+      if code == 102
         @session_expired = true
-        raise ExpiredSessionStandardError, @last_error unless @suppress_exceptions == true
+        raise ExpiredSessionStandardError, @last_error_message unless @suppress_errors == true
       end
       
+      # TODO: check for method not existing error (what code is it?)
+      #       and convert it to a Ruby "NoMethodError"
+      
       # otherwise, just throw a generic expired session
-      raise RemoteStandardError, @last_error unless @suppress_exceptions == true
+      raise RemoteStandardError, @last_error_message unless @suppress_errors == true
       
       return nil
     end
@@ -254,43 +246,99 @@ class FacebookSession
     return xml
   end
   
-  
-  private
-  
-  # SECTION: Private Concrete Interface
-  
   # Function: post_request
-  #   Does a post to the given server/path, using the params as formdata
+  #   Posts a request to the remote Facebook API servers, and returns the
+  #   raw body of the result
   #
   # Parameters:
-  #   api_server_base_url         - i.e. "api.facebook.com"
-  #   api_server_path             - i.e. "/restserver.php"
-  #   method                      - i.e. "facebook.users.getInfo"
-  #   params                      - hash of key/value pairs that get sent as form data to the server
-  #   use_ssl                     - set to true if you want to use SSL for this request
-  def post_request(api_server_base_url, api_server_path, method, params, use_ssl)
+  #   params  - a Hash of the post parameters to send to the REST API
+  #   use_ssl - defaults to false, set to true if you want to use SSL for the POST
+  def post_request(params, use_ssl=false)
+    
     # get a server handle
     port = (use_ssl == true) ? 443 : 80
-    http_server = Net::HTTP.new(@api_server_base_url, port)
+    http_server = Net::HTTP.new(API_SERVER_BASE_URL, port)
     http_server.use_ssl = use_ssl
     
     # build a request
-    http_request = Net::HTTP::Post.new(@api_server_path)
+    http_request = Net::HTTP::Post.new(API_PATH_REST)
     http_request.form_data = params
-    response = http_server.start{|http| http.request(http_request)}.body
     
-    # return the text of the body
-    return response
+    # get the response XML
+    return http_server.start{|http| http.request(http_request)}.body
   end
   
+  # Function: cached_call_method
+  #   Does the same thing as call_method, except that the response is cached for
+  #   the lifetime of the FacebookSession.
+  #
+  # Parameters:
+  #   method              - i.e. "users.getInfo"
+  #   params              - hash of key,value pairs for the parameters to this method
+  #   use_ssl             - set to true if the call will be made over SSL
+  def cached_call_method(method,params={},use_ssl=false) # :nodoc:
+    key = cache_key_for(method,params)
+    @logger.debug "** RFACEBOOK(GEM) - RFacebook::FacebookSession\#cached_call_method - #{method}(#{params.inspect}) - attempting to hit cache" if @logger
+    return @callcache[key] ||= call_method(method,params,use_ssl)
+  end
+  
+  # Function: cache_key_for
+  #   Key to use for cached method calls.
+  #
+  # Parameters:
+  #   method      - the API method being cached
+  #   params      - a Hash of the parameters being sent to the API
+  #
+  def cache_key_for(method,params) # :nodoc:
+    pairs = []
+    params.each do |k,v|
+      if v.is_a?(Array)
+        v = v.join(",")
+      end
+      pairs << "#{k}=#{v}"
+    end
+    return "#{method}(#{pairs.sort.join("...")})".to_sym
+  end
+  
+  ################################################################################################
+  ################################################################################################
+  # :section: Signature Generation
+  ################################################################################################
+
+  # Function: get_secret
+  #   Returns the proper secret to sign a set of parameters with.
+  #   A WebSession will always use the api_secret, but a DesktopSession
+  #   sometimes needs to use a session_secret.
+  #
+  #   THIS IS AN ABSTRACT METHOD
+  #
+  # Parameters:
+  #   params    - a Hash containing the parameters to sign
+  #
+  def get_secret(params) # :nodoc:
+    raise StandardError
+  end
+    
   # Function: param_signature
   #   Generates a param_signature for a call to the API, per the spec on Facebook
   #   see: <http://developers.facebook.com/documentation.php?v=1.0&doc=auth>
-  def param_signature(params)    
+  #
+  # Parameters:
+  #   params    - a Hash containing the parameters to sign
+  #
+  def param_signature(params)   # :nodoc:  
     return generate_signature(params, get_secret(params));
   end
   
-  def generate_signature(hash, secret)
+  # Function: generate_signature
+  #   Generates a Facebook signature.  Used for generating API calls, as well
+  #   as for checking the signature from a Canvas page
+  #
+  # Parameters:
+  #   hash    - a Hash containing the parameters to sign
+  #   secret  - the API or session secret to use to sign the parameters
+  #
+  def generate_signature(hash, secret) # :nodoc:
     args = []
     hash.each do |k,v|
       args << "#{k}=#{v}"
@@ -300,6 +348,43 @@ class FacebookSession
     return Digest::MD5.hexdigest("#{requestStr}#{secret}")
   end
 
+  ################################################################################################
+  ################################################################################################
+  # :section: Deprecated Methods
+  ################################################################################################
+  public
+  
+  # DEPRECATED in favor of session_user_id
+  def session_uid # :nodoc:
+    @logger.debug "** RFACEBOOK(GEM) - DEPRECATION NOTICE - fbsession.session_uid is deprecated in favor of fbsession.session_user_id" if @logger
+    return self.session_user_id
+  end
+  
+  # DEPRECATED in favor of last_error_message
+  def last_error # :nodoc:
+    @logger.debug "** RFACEBOOK(GEM) - DEPRECATION NOTICE - fbsession.last_error is deprecated in favor of fbsession.last_error_message" if @logger
+    return self.last_error_message
+  end
+  
+  # DEPRECATED in favor of suppress_errors
+  def suppress_exceptions # :nodoc:
+    @logger.debug "** RFACEBOOK(GEM) - DEPRECATION NOTICE - fbsession.suppress_exceptions is deprecated in favor of fbsession.suppress_errors" if @logger
+    return self.suppress_errors
+  end
+  
+  # DEPRECATED in favor of suppress_errors
+  def suppress_exceptions=(value) # :nodoc:
+    @logger.debug "** RFACEBOOK(GEM) - DEPRECATION NOTICE - fbsession.suppress_exceptions is deprecated in favor of fbsession.suppress_errors" if @logger
+    self.suppress_errors = value
+  end
+  
+  # DEPRECATED in favor of is_expired?
+  def session_expired?
+    @logger.debug "** RFACEBOOK(GEM) - DEPRECATION NOTICE - fbsession.session_expired? is deprecated in favor of fbsession.is_expired?" if @logger
+    return self.is_expired?
+  end
+
+
 end
 
 end