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
68
69
70
71
 
# File 'lib/dropbox/session.rb', line 59

def initialize(oauth_key, oauth_secret, options={})
  @ssl = options[:ssl].to_bool

  @proxy = options[:proxy] || ENV["HTTP_PROXY"] || ENV["http_proxy"]
  @proxy = nil if options[:noproxy].to_bool
  @consumer = OAuth::Consumer.new(oauth_key, oauth_secret,
                                  :site => (@ssl ? Dropbox::AUTH_SSL_HOST : Dropbox::AUTH_HOST),
                                  :proxy => @proxy,
                                  :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 unless options[:already_authorized]
end

Class Method Details

.deserialize(data) ⇒ Object

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

Raises:

  • (ArgumentError) 


128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/dropbox/session.rb', line 128

def self.deserialize(data)
  consumer_key, consumer_secret, authorized, token, token_secret, ssl, mode = 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, :already_authorized => authorized)
  if authorized then
    session.set_access_token token, token_secret
  else
    session.set_request_token token, token_secret
  end
  session.mode = mode if mode

  return session
end

Instance Method Details

#access_token ⇒ Object

Returns the OAuth access_token which allows access to token and secret.



110
111
112
 
# File 'lib/dropbox/session.rb', line 110

def access_token
  @access_token || raise(UnauthorizedError, "You need to authorize the Dropbox user before you can call API methods")
end

#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.



96
97
98
99
100
 
# File 'lib/dropbox/session.rb', line 96

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.



77
78
79
80
81
82
83
 
# File 'lib/dropbox/session.rb', line 77

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) 


104
105
106
 
# File 'lib/dropbox/session.rb', line 104

def authorized?
  @access_token.to_bool
end

#inspect ⇒ Object

:nodoc:



157
158
159
 
# File 'lib/dropbox/session.rb', line 157

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.



117
118
119
120
121
122
123
 
# File 'lib/dropbox/session.rb', line 117

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

#set_access_token(token, token_secret) ⇒ Object

Manually sets the OAuth access token. Use this method if you are doing your own OAuth elsewhere.



153
154
155
 
# File 'lib/dropbox/session.rb', line 153

def set_access_token(token, token_secret)
  @access_token = OAuth::AccessToken.new(@consumer, token, token_secret)
end

#set_request_token(token, token_secret) ⇒ Object

Manually sets the OAuth request token. Use this method if you are doing your own OAuth elsewhere.



146
147
148
 
# File 'lib/dropbox/session.rb', line 146

def set_request_token(token, token_secret)
  @request_token = OAuth::RequestToken.new(@consumer, token, token_secret)
end