<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
<head><meta content="text/html;charset=&quot;utf-8&quot;" http-equiv="Content-type"/><link href="faldoc.css" rel="stylesheet" type="text/css"/><title> - Class Client</title></head><body class="faldoc"><ul class="navi_top"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="web_oauth.html">Up: Support for OAuth 1.0 protocol.</a></li>
<li class="prev"><a href="web_oauth.html">Previous: Support for OAuth 1.0 protocol.</a></li>
<li class="next"><a href="web_oauth_ProtoError.html">Next: Class ProtoError</a></li>
<li class="clear"></li>
</ul><div id="page_body"><h1><span class="toc_number">21.1</span>Class Client</h1><p class="brief">Interface to remote OAuth authentication process server. </p>
<pre class="prototype">Class Client( cust_id, cust_secret, [mode] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">cust_id</td><td class="content"> The consumer key identifying the requester on the remote OAuth server. </td></tr>
<tr class="param"><td class="name">cust_secret</td><td class="content"> The consumer secret used to sign OAuth requests. </td></tr>
<tr class="optparam"><td class="name">mode</td><td class="content"> One of the <a href="web_oauth_Via.html">Via</a> methods (Defaults to POST). </td></tr>
</tbody>
</table>
<p>This class acts as an authentication client connecting with a remote server. </p>
<table class="members">
<tbody><tr class="member_type"><td class="member_type" colspan="2">Properties</td></tr>
<tr><td colspan="2"><a href="#cust_id">cust_id</a></td></tr>
<tr><td colspan="2"><a href="#mode">mode</a></td></tr>
<tr><td colspan="2"><a href="#secret">secret</a></td></tr>
<tr><td colspan="2"><a href="#signature_method">signature_method</a></td></tr>
<tr><td><a href="#use_header">use_header</a></td><td>Should we use the header field? </td></tr>
<tr><td colspan="2"><a href="#version">version</a></td></tr>
</tbody>
<tbody><tr class="member_type"><td class="member_type" colspan="2">Methods</td></tr>
<tr><td><a href="#callAPI">callAPI</a></td><td>Call an API protected by OAuth. </td></tr>
<tr><td><a href="#getToken">getToken</a></td><td>Perform a token request. </td></tr>
<tr><td colspan="2"><a href="#makeOAuthHandler">makeOAuthHandler</a></td></tr>
<tr><td><a href="#makeSecret">makeSecret</a></td><td>Signature key-string generator. </td></tr>
<tr><td><a href="#parseQS">parseQS</a></td><td>Static utility to parse a query string into a dictionary of values. </td></tr>
</tbody>
</table>
<h2>Properties</h2><h3><a name="cust_id">cust_id</a></h3><h3><a name="mode">mode</a></h3><h3><a name="secret">secret</a></h3><h3><a name="signature_method">signature_method</a></h3><h3><a name="use_header">use_header</a></h3><p class="brief">Should we use the header field? </p>
<p>Should be one of the <a href="web_oauth_UseHeader.html">UseHeader</a> enumeration values. </p>
<p>If <b>UseHeader.NONE,</b> the Authorization header field is never sent. </p>
<p>If <b>UseHeader.ALTERN,</b> the OAuth fields are MOVED in the header, and the selected mode ("GET" or "POST") is used <b>only</b> to send the non-oauth parameters. </p>
<p>If <b>UseHeader.FULL,</b> the OAuth fields are copied in the Authorization header, but they are sent also via the POST or GET query string. </p>
<h3><a name="version">version</a></h3><h2>Methods</h2><h3><a name="callAPI">callAPI</a></h3><p class="brief">Call an API protected by OAuth. </p>
<pre class="prototype">callAPI( token, uri, [params] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">token</td><td class="content"> An instance of <a href="web_oauth_Token.html">Token</a>. </td></tr>
<tr class="param"><td class="name">uri</td><td class="content"> The URI of the remote OAuth protected Web API to be called. </td></tr>
<tr class="optparam"><td class="name">params</td><td class="content"> Optional parameters for the call. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The raw data returned by the remote OAuth procedure. </td></tr>
</tbody>
</table>
<p>Calls a remote web API and blocks until a result is available. </p>
<h3><a name="getToken">getToken</a></h3><p class="brief">Perform a token request. </p>
<pre class="prototype">getToken( address, [callback],[token] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">address</td><td class="content"> The address of the remote token provider. </td></tr>
<tr class="optparam"><td class="name">callback</td><td class="content"> Address to be called back by authenticator if the caller is of a web application. </td></tr>
<tr class="optparam"><td class="name">token</td><td class="content"> An instance of the Token class to be exchanged token exchange. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">A new <a href="web_oauth_Token.html">Token</a> created through this call. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><a href="web_oauth_ProtoError.html">ProtoError</a></td><td class="content"> if the remote side doesn't complain with the OAuth protocol. </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<p>This method requests a "Request token" or an "Access token" the remote OAuth service. </p>
<p>Initially, the caller must create a request token by calling this method; on success, a valid (but not yet authorized) request token is returned. </p>
<p>Once this token is authorized through other means (i.e. redirecting the user to the remote service site), it can be exchanged with an access token calling this method and passing the previously returned token. The request token is discarded and the parameter becomes an access token, that can then be used to access reserved resources (via the <a href="web_oauth_Client.html#callAPI">callAPI</a> method). </p>
<p>For example, a theoretic workflow may be </p>
<pre>
import from web.oauth in oauth
client = oauth.Client( "MyClientID", "MyClientSecret" )
req_token = client.getToken( "https://TheRemoteService/get_req_token" )
//...
// authorize the token
//...
access_token = client.getToken( "https://TheRemoteService/login", nil, req_token )
userData = client.callAPI( access_token,
"https://TheRemoteService/get_user",
["user_id"=> my_user_id] )
</pre><p class='note'><b>Note:</b> This method blocks until the remote side replies. </p>
<h3><a name="makeOAuthHandler">makeOAuthHandler</a></h3><pre class="prototype">makeOAuthHandler( address, tsecret, oauth_params, params )</pre>
<table class="prototype">
<tbody></tbody>
</table>
<h3><a name="makeSecret">makeSecret</a></h3><p class="brief">Signature key-string generator. </p>
<pre class="prototype">makeSecret( cust_secret, [token_secret] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">cust_secret</td><td class="content"> The customer signature part. </td></tr>
<tr class="optparam"><td class="name">token_secret</td><td class="content"> The part of the secret associated with a token. </td></tr>
</tbody>
</table>
<p>The OAuth protocol doesn't dictate exactly the way in which authorization strings must be signed, but in cases where counter-signature is required, it mandates that both the customer secret and the token secret must be used. </p>
<p>The most common way to counter-sign the authorization string is to concatenate them through a "&" character, which is what this method does. </p>
<p>In case different OAuth applications requires different conuter-signature strategies, this method can be overridden by subclasses. </p>
<h3><a name="parseQS">parseQS</a></h3><p class="brief">Static utility to parse a query string into a dictionary of values. </p>
<pre class="prototype">parseQS( data )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">data</td><td class="content"> A query string </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">a dictionary of values. </td></tr>
</tbody>
</table>
<p>Typically, the query string is a pair of "key=value" strings separated by "&" valeus, and encoded as URI encoded values. </p>
</div><ul class="navi_bottom"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="web_oauth.html">Up: Support for OAuth 1.0 protocol.</a></li>
<li class="prev"><a href="web_oauth.html">Previous: Support for OAuth 1.0 protocol.</a></li>
<li class="next"><a href="web_oauth_ProtoError.html">Next: Class ProtoError</a></li>
<li class="clear"></li>
</ul><div class="signature">Made with <a href="faldoc 3.0">http://www.falconpl.org</a></div></body></html>
