Class: Dropbox::Session

Inherits:
Object show all
Includes:
API
Defined in:
lib/dropbox/session.rb

Overview

This class is a portal to the Dropbox API and a façade over the Ruby OAuth gem allowing developers to authenticate their user’s Dropbox accounts.

Authenticating a user

You start by creating a new instance and providing your OAuth consumer key and secret. You then call the authorize_url method on your new instance to receive the authorization URL.

Once your user visits the URL, it will complete the authorization process on the server side. You should call the authorize method:

session = Dropbox::Session.new(my_key, my_secret)
puts "Now visit #{session.authorize_url}. Hit enter when you have completed authorization."
gets
session.authorize

The authorize method must be called on the same instance of Dropbox::Session that gave you the URL. If this is unfeasible (for instance, you are doing this in a stateless Rails application), you can serialize the Session for storage (e.g., in your Rails session):

def authorize
  if params[:oauth_token] then
    dropbox_session = Dropbox::Session.deserialize(session[:dropbox_session])
    dropbox_session.authorize(params)
    session[:dropbox_session] = dropbox_session.serialize # re-serialize the authenticated session

    redirect_to :action => 'upload'
  else
    dropbox_session = Dropbox::Session.new('your_consumer_key', 'your_consumer_secret')
    session[:dropbox_session] = dropbox_session.serialize
    redirect_to dropbox_session.authorize_url(:oauth_callback => root_url)
  end
end

Working with the API

This class includes the methods of the Dropbox::API module. See that module to learn how to continue using the API.

Constant Summary

Constants included from API

API::MODES

Class Method Summary collapse

Instance Method Summary collapse

Methods included from API

#account, #copy, #create_folder, #delete, #download, #entry, #event_content, #event_metadata, #link, #list, #metadata, #mode, #mode=, #move, #rename, #thumbnail, #upload

Methods included from Memoization

#cache_clear_proc=, #cache_proc=, #disable_memoization, #enable_memoization, included

Constructor Details

#initialize(oauth_key, oauth_secret, options = {}) ⇒ Session

Begins the authorization process. Provide the OAuth key and secret of your API account, assigned by Dropbox. This is the first step in the authorization process.

Options:

ssl

If true, uses SSL to connect to the Dropbox API server.



59
60
61
62
63
64
65
66
67
 
# File 'lib/dropbox/session.rb', line 59

def initialize(oauth_key, oauth_secret, options={})
  @ssl = options[:ssl].to_bool
  @consumer = OAuth::Consumer.new(oauth_key, oauth_secret,
                                  :site => (@ssl ? Dropbox::SSL_HOST : Dropbox::HOST),
                                  :request_token_path => "/#{Dropbox::VERSION}/oauth/request_token",
                                  :authorize_path => "/#{Dropbox::VERSION}/oauth/authorize",
                                  :access_token_path => "/#{Dropbox::VERSION}/oauth/access_token")
  @request_token = @consumer.get_request_token
end

Class Method Details

.deserialize(data) ⇒ Object

Deserializes an instance from a string created from the serialize method. Returns the recreated instance.

Raises:

  • (ArgumentError) 


118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/dropbox/session.rb', line 118

def self.deserialize(data)
  consumer_key, consumer_secret, authorized, token, token_secret, ssl = YAML.load(StringIO.new(data))
  raise ArgumentError, "Must provide a properly serialized #{self.to_s} instance" unless [ consumer_key, consumer_secret, token, token_secret ].all? and authorized == true or authorized == false

  session = self.new(consumer_key, consumer_secret, :ssl => ssl)
  if authorized then
    session.instance_variable_set :@access_token, OAuth::AccessToken.new(session.instance_variable_get(:@consumer), token, token_secret)
  else
    session.instance_variable_set :@request_token, OAuth::RequestToken.new(session.instance_variable_get(:@consumer), token, token_secret)
  end
  
  return session
end

Instance Method Details

#authorize(options = {}) ⇒ Object

Authorizes a user from the information returned by Dropbox. This is the third step in the authorization process, after sending the user to the authorize_url.

You can pass to this method a hash containing the keys and values of the OAuth parameters returned by Dropbox. An example in Rails:

session.authorize :oauth_verifier => params[:oauth_verifier]

Returns a boolean indicating if authentication was successful.



92
93
94
95
96
 
# File 'lib/dropbox/session.rb', line 92

def authorize(options={})
  @access_token = @request_token.get_access_token(options)
  @request_token = nil if @access_token
  return @access_token.to_bool
end

#authorize_url(*args) ⇒ Object

Returns a URL that is used to complete the authorization process. Visiting this URL is the second step in the authorization process, after creating the Session instance.



73
74
75
76
77
78
79
 
# File 'lib/dropbox/session.rb', line 73

def authorize_url(*args)
  if authorized? then
    raise AlreadyAuthorizedError, "You have already been authorized; no need to get an authorization URL."
  else
    return @request_token.authorize_url(*args)
  end
end

#authorized? ⇒ Boolean

Returns true if this session has been authorized.

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/dropbox/session.rb', line 100

def authorized?
  @access_token.to_bool
end

#inspect ⇒ Object

:nodoc:



132
133
134
 
# File 'lib/dropbox/session.rb', line 132

def inspect # :nodoc:
  "#<#{self.class.to_s} #{@consumer.key} (#{'un' unless authorized?}authorized)>"
end

#serialize ⇒ Object

Serializes this object into a string that can then be recreated with the Dropbox::Session.deserialize method.



107
108
109
110
111
112
113
 
# File 'lib/dropbox/session.rb', line 107

def serialize
  if authorized? then
    [ @consumer.key, @consumer.secret, authorized?, @access_token.token, @access_token.secret, @ssl ].to_yaml
  else
    [ @consumer.key, @consumer.secret, authorized?, @request_token.token, @request_token.secret, @ssl ].to_yaml
  end
end